SPDecisionFunction

Typedef for decision callback functions

Synopsis

typedef Err (*SPDecisionFunction) (SPAction *resultAction, void *decisionData, SPSound *sound, const char *markerName)

Description

Client-supplied callback functions of this form may be installed in each marker and/or as a default for an SPPlayer.

A marker's action is processed when the sound data for that marker's position is read by the player when any of the following is true:

there is a default decision function for the marker's SPPlayer.
the marker has a marker decision function
the marker specifies a non-trivial action (branch or stop)
the marker is at the end of a sound

Normally, disc I/O is performed based on the size of each buffer. When one of the above conditions is true for a marker, the player will split up disc I/O at that marker in order to prepare for a possible branch. This impacts disc I/O efficiency. It is important to avoid having so many markers with non-trivial actions as to cripple the players ability to produce smooth sounding output. Since default decision functions affect every marker, it is necessary to insure that the marker spacing is such that smooth playback can still be produced. This is unfortunately one of those things that requires a bit of trial and error.

The following steps are used in determining what action the SPPlayer will take when processing a marker's action:

If the marker has a decision function, call it. If the marker's decision function sets its resultAction (e.g. by a call to spSetBranchAction() or spSetStopAction()), then take that action.
Otherwise, if the there is a default decision function, call it. If the default decision function sets its resultAction (e.g. by a call to spSetBranchAction() or spSetStopAction()), then take that action.
Otherwise, if the marker specifies some static action (branch or stop), take that action.
Otherwise, if the marker is at the end of a sound, stop reading.
Otherwise continue reading the sound after the marker.

A decision function MAY do almost anything to the SPPlayer that owns this marker including adding new sounds or markers, changing the static action for this or any other marker, changing the default or marker decision functions for this or any other marker, deleting this or any other marker or sound (with the below caveats in mind).

A decision function MUST NOT do any of the following:

call any function that changes the player state (e.g. spDeletePlayer(), spStop(), spStartReading(), spStartPlaying(), spService(), etc.) for the current SPMarker's SPPlayer.
delete the current SPMarker's SPSound since this has the side effect of calling spStop().
delete the current marker without setting up resultAction to stop or branch to another marker.
take a long time to execute.

Arguments

resultAction: SPAction to optionally be filled out by decision function. If it isn't filled out, the sound player ignores the call to the decision function and continues as if the decision function hadn't been installed.

decisionData: Pointer to client data passed to spSetMarkerDecisionFunction() or spSetDefaultDecisionFunction().

sound: Pointer to SPSound containing marker for which the player is requesting a playback decision.

markerName: Name of marker for which the player is requesting a playback decision.

Return Value

Client should return a non-negative value for success, or a negative error code on failure. An error code returned to the sound player causes the sound player to stop reading and return that error code back to the caller.

Outputs

Decision function can set the SPAction by calling one of the following:

spSetBranchAction() - specifies a marker to branch to as the result of this decision function.

spSetStopAction() - specifies that reader should stop as the result of this decision function.

If the decision does note set the SPAction, the sound player ignores the decision function (acts as if decision function hadn't been installed).

Examples

Err mydecision (SPAction *resultAction, int32 *remaining,
                SPSound *sound, const char *markerName)
{
        // stop when remaining count reaches zero
    if ((*remaining)-- <= 0) {
        return spSetStopAction (resultAction);
    }
        // do nothing (take default action) otherwise
    return 0;
}

Implementation

Typedef for callback function defined in soundplayer.h V24.

Associated Files

soundplayer.h, music.lib