NNS_SndArcPlayerStartSeq*

C Specification

#include <nnsys/snd.h>
BOOL NNS_SndArcPlayerStartSeq( NNSSndHandle* handle, int seqNo );
        NNSSndHandle* handle,
        int playerNo,
        int bankNo,
        int playerPrio,
        int seqNo );

Arguments

handle The sound handle pointer.
seqNo Sequence number.
playerNo The Player number.
bankNo Bank number.
playerPrio This is the player priority. The values is in the range of 0-127; a greater value indicates higher priority.

Return Values

If playback succeeds TRUE. If it fails FALSE.

Description

Plays sequence.

With NNS_SndArcPlayerStartSeq, the player number and other parameters are read from the sound data. With NNS_SndArcPlayerStartSeqEx, the program can specify the player number, bank number and player priority. If any of these parameters (playerNo, bankNo, and playerPrio) are set to -1, it will be configured based on the sound data.

The sound archive must first be initialized with NNS_SndArcInit or NNS_SndArcInitOnMemory.

The sound handle (handle) must be initialized once with NNS_SndHandleInit. When this function is called, the sequence already bound to the sound handle will be unbound (but not stopped). If playback is successful, the sequence will be bound to the sound handle.

This function calls NNS_SndArcGetFileAddress to determine if the required sound data is loaded into memory. If the data is not there, it attempts to load it into the player heap. If there is no player heap or the player heap is not large enough, the playback will fail.

The function internally calls NNS_SndPlayerSetSeqNo so that you can later use NNS_SndPlayerStopSeqBySeqNo to stop playback by sequence number.

If you want to reset the channel priority and volume settings specified by the sound data, you can call NNS_SndPlayerSetChannelPriority or NNS_SndPlayerSetInitialVolume immediately after starting the sequence.

Playback failure may be the result of the following factors:

  • Sequence archive number is invalid
  • Priority is lower than the sequence already playing
  • Data is not in memory or cannot be loaded

See Also

NNS_SndArcInit, NNS_SndArcInitOnMemory, NNS_SndHandleInit, NNS_SndArcGetFileAddress, NNS_SndPlayerStopSeqBySeqNo, NNS_SndPlayerSetSeqNo, NNS_SndPlayerSetChannelPriority, NNS_SndPlayerSetInitialVolume

Revision History

2004/11/30 Corrected erroneous return value type.

2004/06/01 Expanded NNS_SndArcPlayerStartSeqWithPlayerNo and NNS_SndArcPlayerStartSeqEx was modified. Explanation of player heap was added.

2004/04/19 Manuals for NNS_SndArcPlayerStartSeq and NNS_SndArcPlayerStartSeqWithPlayerNo were combined.

2004/04/01 Initial version.


CONFIDENTIAL