spStartReading

Start SPPlayer reading from an SPSound.

Synopsis

Err spStartReading (SPSound *startSound, const char *startMarkerName)

Description

This function begins the process of spooling data for an SPPlayer, processing marker actions along the way. It completely fills the spooler buffers belonging to the SPPlayer in preparation for playback, which can take an unpredictable amount of time. Therefore, the actual function to begin playback, spStartPlaying(), is a separate call so that starting the actual sound playback may be synchronized to some user event.

Normally this function is called while the player's SP_STATUS_F_READING status flag is cleared (see spGetPlayerStatus()), in which case it merely begins reading at the specified location. The SP_STATUS_F_READING flag is then set. If the entire sound data to be played fits completely into the buffers, this flag is cleared again before this function returns.

This function can also be called while the SP_STATUS_F_READING flag is set in order to force the playback to a different location without waiting for a marker branch or decision function. This abnormal method of relocating sound playback will almost certainly produce unpleasant sound output, but there may be times when it is necessary. Note that this merely causes reading to begin at a new location. It does not does not flush the spooler. Anything buffered already will continue play.

Arguments

startSound: Pointer to SPSound to start reading from.

startMarkerName: Name of marker in startSound to start reading from.

Return Value

Non-negative value on success; negative error code on failure.

Implementation

Library call implemented in music.lib V24.

Examples

// error checking omitted for brevity
{
    const int32 playersigs = spGetPlayerSignalMask (player);
        // read from beginning of one of the sounds
    spStartReading (player, sound1, SP_MARKER_NAME_BEGIN);
        // could wait for some event to trigger playback here
        // begin playback
    spStartPlayingVA (player,
                      AF_TAG_AMPLITUDE, 0x7fff,
                      TAG_END);
        // service player until it's done
    while (spGetPlayerStatus(player) & SP_STATUS_F_BUFFER_ACTIVE) {
        const int32 sigs = WaitSignal (playersigs);
        spService (player, playersigs);
    }
}

Associated Files

soundplayer.h, music.lib