spAddSample

Create an SPSound for a Sample Item.

Synopsis

Err spAddSample (SPSound **resultSound, SPPlayer *player, Item sample)

Description

Creates an SPSound for the specified Sample Item and adds it to the specified player. This is useful for playing back sounds that are already in memory.

This function queries the sample item for its properties (e.g. number of channels, size of frame, number of frames, loop points, etc.). The sound is checked for sample frame formatting compatibility with the other SPSounds in the SPPlayer and for buffer size compatibility. A mismatch causes an error to be returned.

Once that is done, the following special SPMarkers are created for the new SPSound:

SP_MARKER_NAME_BEGIN - set to the beginning of the sample

SP_MARKER_NAME_END - set to the end of the sample

SP_MARKER_NAME_SUSTAIN_BEGIN - set to the beginning of the sustain loop if the sample has a sustain loop.

SP_MARKER_NAME_SUSTAIN_END - set to the end of the sustain loop if the sample has a sustain loop.

SP_MARKER_NAME_RELEASE_BEGIN - set to the beginning of the release loop if the sample has a release loop.

SP_MARKER_NAME_RELEASE_END - set to the end of the release loop if the sample has a release loop.

Since a Sample Item has no provision for storing any markers other than the loop points, an SPSound created from a sample item returned by LoadSample() will not have any of the markers from the AIFF file other than the ones listed above.

The length of the sample and all of its loop points must be DMA-aligned or else this function will return ML_ERR_BAD_SAMPLE_ALIGNMENT.

All SPSounds added to an SPPlayer are automatically disposed of when the SPPlayer is deleted with spDeletePlayer() (by calling spRemoveSound()). You can manually dispose of an SPSound with spRemoveSound().

Arguments

resultSound: Pointer to buffer to write resulting SPSound pointer. Must be supplied or else this function returns ML_ERR_BADPTR.

player: Pointer to an SPPlayer.

sample: Item number of a sample to add.

Return Value

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

Outputs

A pointer to an allocated SPSound is written to the buffer pointed to by resultSound on success. NULL is written to this buffer on failure.

Notes

Since all SPSounds belonging to an SPPlayer are played by the same sample player instrument, they must all have the same frame sample frame characteristics (width, number of channels, compression type, and compression ratio).

SPSound to SPSound cross verification is done: an error is returned if they don't match. However, there is no way to verify the correctness of sample frame characteristics for the instrument supplied to spCreatePlayer().

Caveats

There is no restriction on adding Sample Item class SPSounds while the SPPlayer is playing, but removing them while playing can be dangerous. See the Caveats section of spRemoveSound() for more details on this.

Note that this only applies to Sample Item class SPSounds (the kind made with this function). There is no restriction on adding _or_ removing AIFF Sound File class SPSounds while playing.

The sound player will not work correctly unless the sample frame size for the sample follows these rules:

If frame size (in bytes) < 4, then it must divide into 4 evenly.

If frame size (in bytes) > 4, then it must be a multiple of 4.

Implementation

Library call implemented in music.lib V24.

Associated Files

soundplayer.h, music.lib