This chapter describes the API that's defined by the Sound Manager. You use this API to make and record sounds.
The Sound Manager controls two independent sound facilities:
- "Simple" sound: single voice, monophonic, square-wave sound synthesis, useful for system beeps. This is the traditional (pre-Palm OS® Garnet) sound.
- "Sampled" sound: stereo, multi-format, sampled data recording and playback (new in Palm OS Garnet).
The organization of this chapter reflects this division:
- Simple Sound Data Structures
- Simple Sound Constants
- Simple Sound Functions
- Simple Sound Application-Defined Functions
- Sampled Sound Data Structures
- Sampled Sound Constants
- Sampled Sound Functions
- Sampled Sound Application-Defined Functions
All elements described here are declared in SoundMgr.h
.
For more information on the Sound Manager, see the section "Sound" in the Palm OS Programmer's Companion, vol. I.
Simple Sound Data Structures
SndCallbackInfoType Struct
Purpose
The SndCallbackInfoType
structure encapsulates a callback function and its argument data. SndCallbackInfoType
is used by the SndSmfCallbacksType
structure, which is used to list the callback functions that are called during SMF playback.
Prototype
typedef struct SndCallbackInfoType { MemPtr funcP; UInt32 dwUserData; } SndCallbackInfoType;
Fields
-
funcP
- A pointer to the callback function.
-
dwUserData
- Data that's passed as an argument to the function.
SndCommandType Struct
Purpose
The SndCommandType
structure encapsulates a sound synthesis operation and its associated parameters. It is used by the SndDoCmd()
function.
Prototype
typedef struct SndCommandType { SndCmdIDType cmd; UInt8 reserved; Int32 param1; UInt16 param2; UInt16 param3; } SndCommandType;
typedef SndCommandType *SndCommandPtr;
Fields
-
cmd
- Constant that represents a sound operation. The operations are listed and described in
SndDoCmd()
. -
reserved
- Reserved for future use.
-
param1
,param2
,param3
- Operation-specific parameters. The parameters' meanings are described in
SndDoCmd()
.
Compatibility
The reserved
field was introduced in the Palm OS 3.5 SDK. Consequently, when using a later SDK the compiler will complain when it encounters code that depends upon the presence or absence of this field. Code like this, for instance:
static SndCommandType onCmd = {sndCmdNoteOn,60,2200,127};
Instead of doing the above, set each of the structure's fields explicitly, like this:
SndCommandType onCmd; [...] onCmd.cmd = sndCmdNoteOn; onCmd.param1 = 60; onCmd.param2 = 2200; onCmd.param3 = 127;
SndCmdIDType Typedef
Purpose
Type used to specify a sound operation to SndDoCmd()
The constants that can be assigned to this type are documented under "SndCmdIDTag."
Prototype
typedef UInt8 SndCmdIDType;
SndMidiListItemType Struct
Purpose
A structure that locates a MIDI file. This structure is used by the SndCreateMidiList()
function.
Prototype
typedef struct SndMidiListItemType{ Char name[sndMidiNameLength]; UInt32 uniqueRecID; LocalID dbID; UInt16 cardNo; } SndMidiListItemType;
Fields
-
name
- The null-terminated name of the MIDI file.
-
uniqueRecID
- The ID of the record that holds the MIDI file.
-
dbID
- Database ID of the database that holds the record.
-
cardNo
- Card number on which the database that holds the record resides.
SndMidiRecHdrType Struct
Purpose
A structure that encapsulates the header of a MIDI record.
Prototype
typedef struct SndMidiRecHdrType { UInt32 signature; UInt8 bDataOffset; UInt8 reserved; } SndMidiRecHdrType;
Fields
-
signature
- The MIDI record signature. Always set this field to
sndMidiRecSignature
. -
bDataOffset
- Offset, in bytes, from the beginning of the record to the first byte of the MIDI data.
-
reserved
- Reserved for future use. Always set this field to 0.
SndMidiRecType Struct
Purpose
The SndMidiRecType
structure encapsulates the MIDI record header and the beginning of the human-readable name of the MIDI data.
Prototype
typedef struct SndMidiRecType { SndMidiRecHdrType header; Char name[2]; } SndMidiRecType
Fields
-
header
- The MIDI record header.
-
name
- The human-readable name of the MIDI data. The MIDI track name is a
null
-terminated string, even if it's empty. Contrary to the declaration, its length (including the null-terminator) varies; it's at least one byte and at mostsndMidiNameLength
bytes long.
SndSmfCallbacksType Struct
Purpose
A structure that contains a set of application-defined functions that are called during MIDI playback. To register your callback functions, call SndPlaySmf()
.
Prototype
typedef struct SndSmfCallbacksType { SndCallbackInfoType completion; SndCallbackInfoType blocking; SndCallbackInfoType reserved; } SndSmfCallbacksType;
Fields
-
completion
- Completion function; see
SndComplFuncType()
. -
blocking
- Blocking function; see
SndBlockingFuncType()
. -
reserved
- Reserved. Set this field to 0.
SndSmfChanRangeType Struct
Purpose
A structure that defines the range of enabled MIDI channels. Events on MIDI channels outside the enabled range are ignored. By default, no channels are enabled.
Prototype
typedef struct SndSmfChanRangeType { UInt8 bFirstChan; UInt8 bLastChan; } SndSmfChanRangeType;
Fields
-
bFirstChan
- The first enabled channel in the range [0, 15].
-
bLastChan
- The last enabled channel in the range [0, 15].
WARNING! The SndSmfChanRangeType structure expects MIDI channels to be in the range [0, 15]; real MIDI channel values are in the range [1, 16]. Thus, PalmSource MIDI channel 0 is real MIDI channel 1, PalmSource MIDI channel 1 is real MIDI channel 2, and so on.
SndSmfCmdEnum Typedef
Purpose
Type used to specify a command to SndPlaySmf()
. See "SndPlaySmf Commands" for the set of values that this type can contain.
Prototype
typedef UInt8 SndSmfCmdEnum;
SndSmfOptionsType Struct
Purpose
The SndSmfOptionsType
structure establishes MIDI performance parameters. This structure is used with the SndPlaySmf()
function to establish new parameter settings or to return the currently set values, depending on how the function is called. In the case where the structure returns values, only the "performance marker" fields (dwStartMilliSec
and dwEndMilliSec
) are valid.
Prototype
typedef struct SndSmfOptionsType { UInt32 dwStartMilliSec; UInt32 dwEndMilliSec; UInt16 amplitude; Boolean interruptible; UInt8 reserved1; UInt32 reserved; } SndSmfOptionsType;
Fields
-
dwStartMilliSec
- The "beginning of performance" marker, measured in milliseconds from the beginning of the track. A value of 0 plays the track from the beginning. The time difference between
dwStartMilliSec
and the performance time of the first subsequent MIDI event is respected. For example, ifdwStartMilliSec
is 2000 and the first (subsequent) note-on event is at 3000, there will be a 1000 millisecond "pause" before the note is played. -
dwEndMilliSec
- The "end of performance" marker, measured in milliseconds from the beginning of the track. To play to the end of the track, set this to
sndSmfPlayAllMilliSec
. -
amplitude
- The volume of the track, in the range [0,
sndMaxAmp
].sndMaxAmp
. If set to 0, the MIDI file isn't played. -
interruptible
- If
true
(the default), MIDI playback is interrupted if the user interacts with the controls (digitizer, buttons, etc.), even if the interaction doesn't generate a sound command. Iffalse
, playback is not interrupted. -
reserved1
- Reserved.
-
reserved
- Reserved. Set this field to 0.
SndSysBeepType Typedef
Purpose
Type that specifies a system beep sound. This type is used by SndPlaySystemSound()
. See "System Beeps" for the set of values that this type can contain.
Prototype
typedef UInt8 SndSysBeepType;
Simple Sound Constants
SndCmdIDTag Enum
Purpose
The SndCmdIDTag
enumeration contains constants that represent specific sound operations used in simple sound playback with SndDoCmd()
.
Prototype
typedef enum SndCmdIDTag { sndCmdFreqDurationAmp = 1, sndCmdNoteOn, sndCmdFrqOn, sndCmdQuiet }
Constants
-
sndCmdFreqDurationAmp
- Play a tone.
SndDoCmd
blocks until the tone has finished. -
sndCmdFrqOn
- Initiate a tone.
SndDoCmd
returns immediately while the tone plays in the background. Subsequent sound playback requests interrupt the tone. -
sndCmdNoteOn
- Initiate a MIDI-defined tone.
SndDoCmd
returns immediately while the tone plays in the background. Subsequent sound playback requests interrupt the tone. -
sndCmdQuiet
- Stop the playback of the currently generated tone.
Simple Sound Amplitudes
These constants can be supplied to the simple sound functions (such as SndDoCmd()
) when an amplitude value is required. Note that these values are not compatible with the sampled sound amplitude range and thus shouldn't be used with the sampled sound functions.
sndMidiNameLength
Constant that defines the maximum string length, including the null terminator, for the name of a MIDI file or MIDI track.
sndMidiRecSignature
Constant that's used to tag a MIDI record. It is used as the value of the signature
field of the SndMidiRecHdrType
structure.
SndPlaySmf Commands Enum
Purpose
This enumeration defines a set of commands that tell SndPlaySmf()
whether it should play the file or simply return the duration of the file in milliseconds.
Prototype
enum SndSmfCmdEnumTag { sndSmfCmdPlay = 1, sndSmfCmdDuration, }
Constants
-
sndSmfCmdPlay
- Play the specified Standard MIDI File.
-
sndSmfCmdDuration
- Return the duration, in milliseconds, of the specified Standard MIDI File.
sndSmfPlayAllMilliSec
Represents the (temporal) far end of a MIDI file. You can use this constant as the value of the dwEndMilliSec
field of the SndSmfOptionsType
structure before passing the structure to SndPlaySmf()
. This setting tells the function to play the entire file.
System Beeps Enum
Purpose
This enumeration declares a set of constants that represent pre-defined system beeps. In order to play one of these sounds, pass the corresponding value to SndPlaySystemSound()
.
Prototype
typedef enum SndSysBeepTag { sndInfo = 1, sndWarning, sndError, sndStartUp, sndAlarm, sndConfirmation, sndClick }
Constants
-
sndInfo
- Heralds non-crucial information.
-
sndWarning
- Grabs the user's attention
-
sndError
- Indicates an illegal operation.
-
sndStartUp
- Played at device start up time.
-
sndAlarm
- Generic alarm sound; note that this is not the Datebook's alarm sound.
-
sndConfirmation
- Indicates approval or acceptance.
-
sndClick
- The button click sound.
Simple Sound Functions
SndCreateMidiList Function
Purpose
Generate a list of MIDI records.
Declared In
SoundMgr.h
Prototype
Boolean SndCreateMidiList ( UInt32 creator, Boolean multipleDBs, UInt16 *recordCount, MemHandle *recordList )
Parameters
-
→
creator
- Creator ID of the database in which the function looks for MIDI records. Pass
0
to search all databases. -
→
multipleDBs
- Pass
true
to search multiple databases for MIDI records. Passfalse
to search only in the first database that meets the search criteria. -
←
recordCount
- Returns the number of MIDI records that were found.
-
←
recordList
- Returns a pointer to an array of
SndMidiListItemType
structures, one structure for each record that was found.
Returns
Returns true
if records were found, false
otherwise.
Compatibility
Implemented in Palm OS 3.0 and later.
SndDoCmd Function
Purpose
Ask the Sound Manager to perform a simple sound synthesis operation.
Declared In
SoundMgr.h
Prototype
Err SndDoCmd ( void *channelP, SndCommandPtr commandP, Boolean noWait )
Parameters
-
→
channelP
- Pointer to the sound channel on which you want to perform the operation. Pass
NULL
for the "shared" sound channel.
IMPORTANT: The Sound Manager only supports one channel of sound synthesis: You must pass NULL as the value of
channelP
.
-
→
commandP
- Pointer to a
SndCommandType
structure that describes the operation and contains any associated parameters. See the Comments section, below, for the set of sound commands and their associated parameters. -
→
noWait
- Sets the function to be asynchronous (
true
) or synchronous (false
) with respect to the caller.
Returns
Returns errNone
if the operation completed successfully, or one of the following if an error occurred:
-
sndErrBadParam
- Invalid parameter.
-
sndErrBadChannel
- Invalid channel pointer.
-
sndErrQFull
- The sound queue is full.
Comments
The sound operations that are performed by SndDoCmd
are encapsulated in the SndCommandType
structure. The cmd
field represents the operation, while the param
fields are data that's passed to the operation. The operations and data that SndDoCmd
supports are described in the following table.
Table 50.1 SndDoCmd commands and parameters
Compatibility
Commands other than sndCmdFreqDurationAmp
are implemented in Palm OS 3.0 and later. In OS versions earlier than 3.0, SndDoCmd
will crash with a fatal error if you pass a command other than sndCmdFreqDurationAmp
.
See Also
SndGetDefaultVolume Function
Purpose
Return volume levels cached by the Sound Manager.
Declared In
SoundMgr.h
Prototype
void SndGetDefaultVolume ( UInt16 *alarmAmpP, UInt16 *sysAmpP, UInt16 *masterAmpP )
Parameters
-
← alarmAmpP
- Pointer to the alarm amplitude.
-
← sysAmpP
- Pointer to the system sound amplitude.
-
← masterAmpP
- Pointer to the master amplitude.
Comments
Pass NULL
for those settings that you don't care about.
Compatibility
Never call this function in Palm OS Garnet. To retrieve default volume levels, you should ask for the user's preferences settings.
See Also
SndInterruptSmfIrregardless Function
Purpose
Stop the currently playing MIDI file, even if the performance was declared to be intolerant of interruptions.
Declared In
SoundMgr.h
Prototype
Err SndInterruptSmfIrregardless ( void )
Returns
Compatibility
Implemented only if 4.0 New Feature Set is present. However, if Palm OS Cobalt Feature Set is present this function is unimplemented.
See Also
SndPlaySmf()
, SndPlaySmfResourceIrregardless()
SndPlaySmf Function
Purpose
Perform a Standard MIDI File, or returns the duration of the file.
Declared In
SoundMgr.h
Prototype
Err SndPlaySmf ( void *channelP, SndSmfCmdEnum command, UInt8 *midiDataP, SndSmfOptionsType *optionsP, SndSmfChanRangeType *channelRangeP, SndSmfCallbacksType *callbacksP, Boolean noWait )
Parameters
-
→
channelP
- A pointer to the sound channel on which you want to perform the MIDI file. Pass
NULL
for the "shared" sound channel.
IMPORTANT: The Sound Manager only supports one channel of sound synthesis: You must pass NULL as the value of
channel
.
-
→
command
- One of the SndPlaySmf Commands: either
SndSmfCmdPlay
(play the file) orSndSmfCmdDuration
(return the duration of the file in milliseconds). -
→
midiDataP
- The MIDI data; this can point to an
SndMidiRecHdrType
structure, or it can point directly to the actual MIDI data bytes in memory. -
→
optionsP
-
A
pointer to aSndSmfOptionsType
structure that defines performance parameters, such as volume, starting offset, and interruption tolerance. For default behavior, passNULL
. For more information, including default settings, seeSndSmfOptionsType
. -
→
channelRangeP
-
A
pointer to aSndSmfChanRangeType
structure that specifies the range of MIDI channels (in the SMF data) to use during playback. To play all channels, passNULL
. -
→
callbacksP
-
A
pointer to aSndSmfCallbacksType
structure that holds your callback functions. PassNULL
if you don't want any callbacks. -
n
oWait
- This value is ignored. This function always finishes playing the SMF selection before returning (but see the Comments section, below).
Returns
Returns errNone
if the operation completed successfully, or one of the following if there was an error:
-
sndErrBadParam
- Invalid value passed to this function.
-
sndErrBadChannel
- Invalid sound channel.
-
sndErrMemory
- Insufficient memory.
-
sndErrOpen
- Tried to open channel that's already open.
-
sndErrQFull
- Can't accept more notes.
-
sndErrFormat
- Unsupported data format.
-
sndErrBadStream
- Invalid data stream.
-
sndErrInterrupted
- Play was interrupted.
Comments
Although this call is always synchronous, you can register a "blocking" function that's called periodically as the MIDI file is playing. See SndBlockingFuncType()
for more information.
Normally, playback is halted by events generated by user interaction with the screen, digitizer, or hardware-based buttons. You can override this behavior by setting the interruptible
field of the optionsP
argument to false
.
This function waits until any currently-playing simple sound has finished before starting playback of the requested MIDI data. A similar function, SndPlaySmfIrregardless()
, doesn't wait: it interrupts the current performance and immediately begins playback of the requested data.
Compatibility
Implemented in Palm OS 3.0 and later.
SndPlaySmfIrregardless Function
Purpose
Like SndPlaySmf()
, but interrupts any currently playing simple sound, regardless of that sound's declared interruption tolerance.
Declared In
SoundMgr.h
Prototype
Err SndPlaySmfIrregardless ( void *channelP, SndSmfCmdEnum command, UInt8 *midiDataP, SndSmfOptionsType *optionsP, SndSmfChanRangeType *channelRangeP, SndSmfCallbacksType *callbacksP, Boolean noWait )
Parameters
-
→
channelP
- A pointer to the sound channel on which you want to perform the MIDI file. Pass
NULL
for the "shared" sound channel.
IMPORTANT: The Sound Manager only supports one channel of sound synthesis: You must pass NULL as the value of
channel
.
-
→
command
- One of the SndPlaySmf Commands: either
SndSmfCmdPlay
(play the file) orSndSmfCmdDuration
(return the duration of the file in milliseconds). -
→
midiDataP
- The MIDI data; this can point to an
SndMidiRecHdrType
structure, or it can point directly to the actual MIDI data bytes in memory. -
→
optionsP
-
A
pointer to aSndSmfOptionsType
structure that defines performance parameters, such as volume, starting offset, and interruption tolerance. For default behavior, passNULL
. For more information, including default settings, seeSndSmfOptionsType
. -
→
channelRangeP
-
A
pointer to aSndSmfChanRangeType
structure that specifies the range of MIDI channels (in the SMF data) to use during playback. To play all channels, passNULL
. -
→
callbacksP
-
A
pointer to aSndSmfCallbacksType
structure that holds your callback functions. PassNULL
if you don't want any callbacks. -
n
oWait
- This value is ignored. This function always finishes playing the SMF selection before returning.
Returns
Returns errNone
if the operation completed successfully, or one of the following if there was an error:
-
sndErrBadParam
- Invalid value passed to this function.
-
sndErrBadChannel
- Invalid sound channel.
-
sndErrMemory
- Insufficient memory.
-
sndErrOpen
- Tried to open channel that's already open.
-
sndErrQFull
- Can't accept more notes.
-
sndErrFormat
- Unsupported data format.
-
sndErrBadStream
- Invalid data stream.
-
sndErrInterrupted
- Play was interrupted.
Comments
Although this call is always synchronous, you can register a "blocking" function that's called periodically as the MIDI file is playing. See SndBlockingFuncType()
for more information.
Normally, playback is halted by events generated by user interaction with the screen, digitizer, or hardware-based buttons. You can override this behavior by setting the interruptible
field of the optionsP
argument to false
.
This function doesn't wait for any currently-playing simple sound to finish before starting playback of the requested MIDI data: it interrupts the current performance and immediately begins playback of the requested data. A similar function, SndPlaySmf()
, waits for any currently-playing simple sound to finish before starting playback of the requested MIDI data.
Compatibility
Implemented only if 4.0 New Feature Set is present. However, if Palm OS Cobalt Feature Set is present this function is unimplemented.
SndPlaySmfResource Function
Purpose
Play a MIDI track read out of an open resource database.
Declared In
SoundMgr.h
Prototype
Err SndPlaySmfResource ( UInt32 resType, Int16 resID, SystemPreferencesChoice volume )
Parameters
-
→
resType
- SMF resource type.
-
→
resID
- SMF resource ID.
-
→
volume
- Volume setting; one of
prefSysSoundVolume
,prefGameSoundVolume
, orprefAlarmSoundVolume
(all defined inPreferences.h
).
Returns
Returns errNone
if the track was played successfully, or one of the following if an error occurred:
-
sndErrBadParam
- The
volumeSelector
parameter is invalid or the SMF resource has invalid data. -
dmErrCantFind
- The specified resource doesn't exist.
-
other values
- See
SndPlaySmf()
Comments
This function plays the entire MIDI file using all MIDI channels. Playback is interrupted by a key down or digitizer event. No callbacks are specified.
This function waits until any currently playing simple sound has finished before starting playback of the requested MIDI data. A similar function, SndPlaySmfResourceIrregardless()
, doesn't wait: It interrupts the current performance and immediately begins playback of the requested data.
Compatibility
Implemented in Palm OS 3.2 and later.
SndPlaySmfResourceIrregardless Function
Purpose
Like SndPlaySmfResource()
, but interrupts any currently playing simple sound, regardless of that sound's declared tolerance for interruption.
Declared In
SoundMgr.h
Prototype
Err SndPlaySmfResourceIrregardless ( UInt32 resType, Int16 resID, SystemPreferencesChoice volumeSelector )
Parameters
-
→
resType
- SMF resource type.
-
→
resID
- SMF resource ID.
-
→
volume
- Volume setting; one of
prefSysSoundVolume
,prefGameSoundVolume
, orprefAlarmSoundVolume
.
Returns
Returns errNone
if the track was played successfully, or one of the following if an error occurred:
-
sndErrBadParam
- The
volumeSelector
parameter is invalid or the SMF resource has invalid data. -
dmErrCantFind
- The specified resource doesn't exist.
-
other values
- See
SndPlaySmf()
Comments
This function plays the entire MIDI file using all MIDI channels. Playback is interrupted by a key down or digitizer event. No callbacks are specified.
This function doesn't wait for any currently playing simple sound to finish before starting playback of the requested MIDI data: it interrupts the current performance and immediately begins playback of the requested data. A similar function, SndPlaySmfResource()
, does wait.
Compatibility
Implemented only if 4.0 New Feature Set is present. However, if Palm OS Cobalt Feature Set is present this function is unimplemented.
SndPlaySystemSound Function
Purpose
Play a pre-defined (simple) system sound.
Declared In
SoundMgr.h
Prototype
void SndPlaySystemSound ( SndSysBeepType beepID )
Parameters
-
→
beepID
- One of the system beep sound constants defined in the
System Beeps
enum.
Comments
If you're playing an alarm (sndAlarm
), the user's alarm volume preference setting is used. For all other system sounds, the system volume preference is used.
Alarm sounds (sndAlarm
) are played synchronously: SndPlaySystemSound
blocks until the sound has been played. All other sounds are played asynchronously.
SndSetDefaultVolume Function
Purpose
Set the default sound volume levels cached by the Sound Manager.
Declared In
SoundMgr.h
Prototype
void SndSetDefaultVolume ( UInt16 *alarmAmpP, UInt16 *sysAmpP, UInt16 *masterAmpP )
Parameters
-
→ alarmAmpP
- Pointer to the alarm amplitude.
-
→ sysAmpP
- Pointer to the system sound amplitude.
-
→ masterAmpP
- Pointer to the master amplitude.
Returns
Comments
Any of the arguments may be NULL
. In that case, the corresponding setting is not altered.
NOTE: It is usually not appropriate for an application to be setting the default sound volume levels. Accordingly this function is rarely used by applications.
See Also
Simple Sound Application-Defined Functions
SndBlockingFuncType Function
Purpose
A callback funtion that is invoked periodically during SMF playback.
Declared In
SoundMgr.h
Prototype
Boolean SndBlockingFuncType ( void *channelP, UInt32 userData, Int32 time )
Parameters
-
→
channelP
- A pointer to the sound channel on which the file is being played. Currently always
NULL
. -
→
userData
- Application-defined data that's specified when the callback function is registered.
-
→
time
- The amount of time, in milliseconds, available for completion of this function.
Returns
Return true
from your callback if playback is to continue. Return false
if playback is to be aborted.
Comments
Your application's blocking callback is called whenever the MIDI parser is "between notes." Your application can do whatever it wants during this period, as long as it doesn't take more than time
milliseconds.
Specify your blocking callback function using the blocking
field of the SndSmfCallbacksType
structure that you pass to SndPlaySmf()
. Note that the blocking
field is a SndCallbackInfoType
structure; it contains a pointer to your callback function and a 32-bit value that is passed, as-is, to your callback.
See Also
SndComplFuncType Function
Purpose
A callback function that is invoked immediately after a MIDI file (SMF) finishes playing.
Declared In
SoundMgr.h
Prototype
void SndComplFuncType ( void *channelP, UInt32 userData )
Parameters
-
→
channelP
- A pointer to the sound channel on which the file was played; currently always
NULL
. -
→
userData
- Application-defined data that's specified when the callback function is registered.
Comments
Specify your blocking callback function using the completion
field of the SndSmfCallbacksType
structure that you pass to SndPlaySmf()
. Note that the completion
field is a SndCallbackInfoType
structure; it contains a pointer to your callback function and a 32-bit value that is passed, as-is, to your callback.
Sampled Sound Data Structures
SndFormatType Typedef
Purpose
Data type used to contain the encoding format of the data that you propose to pour through the stream with SndStreamCreateExtended()
. See "Sound Data Encoding Formats" for the set of values that this type can contain.
Prototype
typedef UInt32 SndFormatType;
SndPtr Typedef
Purpose
Type used to cast a pointer to the sound data used by SndPlayResource()
.
Prototype
typedef void *SndPtr;
Compatibility
Implemented if Sound Stream Feature Set is present.
SndSampleType Typedef
Purpose
Data type used to specify the sample format (size, data type, endianness) of a sampled sound stream. Used by SndStreamCreate()
. See "SndSampleTag" for the set of values that this type can contain.
Prototype
typedef Enum16 SndSampleType;
Compatibility
Implemented if Sound Stream Feature Set is present.
SndStreamMode Typedef
Purpose
Data type used to specify the "direction" (input or output) of a sampled sound stream. Used by the SndStreamCreate()
function. See "SndStreamModeTag" for the set of values that this type can contain.
Prototype
typedef Enum8 SndStreamMode;
Compatibility
Implemented if Sound Stream Feature Set is present.
SndStreamRef Typedef
Purpose
Data type that represents a sampled stream. You create an SndStreamRef
with SndStreamCreate()
.
Prototype
typedef UInt32 SndStreamRef;
Compatibility
Implemented if Sound Stream Feature Set is present.
SndStreamWidth Typedef
Purpose
Data type that specifies whether a sampled data stream is in stereo or mono. This data type is used by the SndStreamCreate()
function. See "SndStreamWidthTag" for the set of values that this type can contain.
Prototype
typedef Enum8 SndStreamWidth;
Compatibility
Implemented if Sound Stream Feature Set is present.
Sampled Sound Constants
Sound Stream Feature Constants
To detect the presence of the Sound Stream Feature Set you check for the Sound Manager's version number feature. If the Sound Manager's version feature is defined, the Sound Stream feature set is supported.
The feature number to supply to |
||
Sound Data Encoding Formats Enum
Purpose
The SndFormatTag
enum defines a set of constants that represent various sound data encoding formats. Pass one of these constants as the encodingFormat
argument to SndStreamCreateExtended()
.
Prototype
enum SndFormatTag { sndFormatPCM = 0, sndFormatIMA_ADPCM = 'APCM', sndFormatDVI_ADPCM = 'DPCM', sndFormatMP3 = 'MPG3', sndFormatAAC = 'DAAC', sndFormatOGG = 'OGGV' }
Constants
-
sndFormatPCM
- Pulse Code Modulation format. This is the "no encoding" format; the data is a series of samples that are linear with regard to amplitude quantization and regular with regard to sampling rate.
-
sndFormatIMA_ADPCM
- The Interactive Multimedia Association's implementation of "adaptive delta" encoding. The sampling rate is constant, but the quantization is non-linear.
-
sndFormatDVI_ADPCM
- Microsoft's adaptive delta implementation. This is the same as IMA ADPCM.
-
sndFormatMP3
- Motion Picture Group Audio Layer III.
-
sndFormatAAC
- Dolby Advanced Audio Coding.
-
sndFormatOGG
- OGG Vorbis encoding.
Compatibility
Implemented if Sound Stream Feature Set is present. The Palm OS Garnet implementation of SndStreamCreateExtended()
supports sndFormatPCM
data only. To play ADPCM data, use SndPlayResource()
.
SndSampleTag Enum
Purpose
The SndSampleTag
enum defines a set of constants that represent the sample format (size, data type, endianness) of a sampled sound stream. These constant values are used with SndStreamCreate()
.
The lower four bits of these constants gives the size (in bytes) of a single sample, as shown here:
UInt8 byteSize = formatConstant & 0x0f
Prototype
enum SndSampleTag { sndInt8 = 0x01, sndUInt8 = 0x11, sndInt16Big = 0x02, sndInt16Little = 0x12, sndInt32Big = 0x04, sndInt32Little = 0x14, sndFloatBig = 0x24, sndFloatLittle = 0x34, #if CPU_ENDIAN == CPU_ENDIAN_BIG sndInt16 = sndInt16Big, sndInt16Opposite = sndInt16Little, sndInt32 = sndInt32Big, sndInt32Opposite = sndInt32Little, sndFloat = sndFloatBig, sndFloatOpposite= sndFloatLittle #else sndInt16 = sndInt16Little, sndInt16Opposite = sndInt16Big, sndInt32 = sndInt32Little, sndInt32Opposite= sndInt32Big, sndFloat = sndFloatLittle, sndFloatOpposite= sndFloatBig #endif }
Constants
-
sndFloat
- Signed floating-point data in the device's native endianness.
-
sndFloatBig
- Signed floating-point data in big-endian format.
-
sndFloatLittle
- Signed floating-point data in little-endian format.
-
sndFloatOpposite
- Signed floating-point data in the endianness opposite to that of the device.
-
sndInt16
- Signed 16-bit integer data in the device's native endianness.
-
sndInt16Big
- Signed 16-bit integer data in big-endian format.
-
sndInt16Little
- Signed 16-bit integer data in little-endian format.
-
sndInt16Opposite
- Signed 16-bit integer data in the endianness opposite to that of the device.
-
sndInt32
- Signed 32-bit integer data in the device's native endianness.
-
sndInt32Big
- Signed 32-bit integer data in big-endian format.
-
sndInt32Little
- Signed 32-bit integer data in little-endian format.
-
sndInt32Opposite
- Signed 32-bit integer data in the endianness opposite to that of the device.
-
sndInt8
- Signed 8-bit data.
-
sndUInt8
- Unsigned 8-bit data.
Compatibility
Implemented if Sound Stream Feature Set is present. In Palm OS Garnet, the 32-bit and floating point formats aren't supported.
SndStreamModeTag Enum
Purpose
The SndStreamModeTag
enum defines constants that represent the "direction" (input or output) of a sampled sound stream. Use these constants with the SndStreamCreate()
function.
Prototype
enum SndStreamModeTag { sndInput, sndOutput }
Constants
Compatibility
Implemented if Sound Stream Feature Set is present.
SndStreamWidthTag Enum
Purpose
The SndStreamWidthTag
defines constants that represent mono and stereo sampled data streams. Use these constants with the SndStreamCreate()
function.
Prototype
enum SndStreamWidthTag { sndMono, sndStereo }
Constants
Compatibility
Implemented if Sound Stream Feature Set is present.
Sound Resource Playback Flags
Use these flags when calling SndPlayResource()
to specify various settings. Currently, the only setting is function synchronization.
Compatibility
Implemented if Sound Stream Feature Set is present.
Stereo Pan Constants
These constants define the extremes and the midpoint when altering the stream's stereo balance with SndStreamSetPan()
. SndStreamSetPan
allows you to set the balance to one of these values, or any integral value between sndPanFullLeft
and sndPanFullRight
.
Compatibility
Implemented if Sound Stream Feature Set is present.
Volume Constants Enum
Purpose
Use the volume constants defined in this enum with SndStreamSetVolume()
and SndPlayResource()
. The constants tell the functions to retrieve the named sound volume preference (as set by the user) and apply it as a volume setting.
Prototype
enum { sndSystemVolume = -1, sndGameVolume = -2, sndAlarmVolume = -3 }
Constants
-
sndSystemVolume
- The user's system sound preference.
-
sndGameVolume
- The user's game sound preference.
-
sndAlarmVolume
- The uer's alarm sound preference.
Compatibility
Implemented if Sound Stream Feature Set is present.
Sampled Sound Functions
SndPlayResource Function
Purpose
Play formatted sound data read from a resource or file.
Declared In
SoundMgr.h
Prototype
Err SndPlayResource ( SndPtr soundP, Int32 volume, UInt32 flags )
Parameters
-
→
soundP
- A pointer to the beginning of the formatted sound (including the header). Currently, only WAVE data is recognized (see the Comments section, below); in this case,
soundP
must point to the "RIFF" ID (byte 0 in a simple.wav
file). -
→
volume
- Amplitude scalar, in the range [0, 32k]. See
SndStreamSetVolume()
for information on how amplitude scalar values are applied. -
→
flags
- One of the "Sound Resource Playback Flags." Currently, the only setting is function synchronization: use
sndFlagSync
to have the function wait until all sound data has been fed to the DAC before returning , orsndFlagAsync
flag to have the function return immediately while playback continues in a separate thread.
Returns
Returns errNone
if the operation completed successfully, or one of the following if there was an error:
-
sndErrBadParam
- The specified resource or file contains no data.
-
sndErrFormat
- The data is in an unsupported format.
-
sndErrMemory
- The function couldn't allocate sufficient memory.
-
other errors
- The device couldn't allocate system resources for the sound.
Comments
The supported WAVE parameters are:
- Uncompressed (PCM) or IMA 4-bit adaptive differential (IMA ADPCM). The ADPCM type is also known as DVI ADPCM; in a WAVE file, it's known as format 0x11.
- One or two-channels
- All normal sampling rates (8k, 11k, 22.05k, 44.1k, 48, 96k).
You can't interrupt or abort a resource playback once it's been initiated. The resource always plays to the end of the data.
Example
The following code excerpt shows how to use this function to play a sound resource.
SndPtr soundP; MemHandle recordH; recordH = DmGet1Resource(sysResTSound,TestWaveSound); soundP = (SndPtr) MemHandleLock(recordH); SndPlayResource(soundP,1024,sndFlagSync); // 1024 is 0dB // (unity) gain MemHandleUnlock(recordH);
The above code first gets the resource from the last opened database. (You can use DmGetResource()
instead if you have more than one database open.) It then locks the memory associated with the resource and converts the result to a pointer to a sournd resource.
The call to the SndPlayResource()
function plays the sound. The second parameter is the sound level, which varies from 0 to 32767. A value of 1024 specifies unity gain. Higher values indicate higher gain. The third parameter specifies whether the function returns immediately or waits until after the sound has finished playing. You should avoid using sndFlagAsync
, which causes the function to return immediately without waiting for the sound to finish, if you use this code because you'll unlock the sound resource before the system finishes with it. In fact, you should always specify sndFlagSync
unless you can guarantee two things:
- Your resource memory remains locked for the duration of the sound
- Your application does not exit for the duration of the sound
Remember that you cannot stop a sound played with SndPlayResource()
.
Compatibility
Implemented if Sound Stream Feature Set is present.
SndStreamCreate Function
Purpose
Create a new audio data stream that can be used to record or play back uncompressed, sampled audio data.
Declared In
SoundMgr.h
Prototype
Err SndStreamCreate ( SndStreamRef *streamP, SndStreamMode mode, UInt32 sampleRate, SndSampleType type, SndStreamWidth width, SndStreamBufferCallback callback, void *callbackArgP, UInt32 bufferSize, Boolean callbackIsARM )
Parameters
-
←
streamP
- Token that represents the newly created stream.
-
→
mode
- One of the SndStreamModeTag constants that represents the "direction" of the data stream. Either
sndInput
(for recording), orsndOutput
(for playback). -
→
sampleRate
- Sampling rate, in frames-per-second. Specify the native rate of the data, such as 22050, 44100, or 48000. The maximum rate is 96000.
-
→
type
- Sample quantization and endianness (but see the section on "Data Formats," below). Supply one of the values documented under "SndSampleTag."
-
→
width
- One of the constants documented under "SndStreamWidthTag" that represents the number of channels of data in the stream.
-
→ callback
- A callback function that gets called when another buffer is needed. See
SndStreamBufferCallback()
for a description of the callback function that you must implement. -
→ callbackArgP
- Caller-defined data that gets passed to callback.
-
→
bufferSize
- Preferred size (in frames) for the buffers that are passed to
callback
. Note that the actual buffer size (as allocated by the Sound Manager) may be different from this request. -
→
callbackIsARM
- Pass
true
if the callback function is written in ARM-native code, orfalse
if it is written in 68k code.
Returns
Returns errNone
if the operation completed successfully, or one of the following if there was an error:
-
sndErrBadParam
-
streamP
is invalid,callback
isNULL
, the sampling rate is too high (greater than 96000), or the device doesn't like some other sound parameter value. -
sndErrorMemory
- All streams are being used (there is a maximum of 16), or memory for this stream couldn't otherwise be allocated.
-
other errors
- The device couldn't allocate system resources for the stream.
Comments
This function creates a new audio stream into which you can write (playback) or from which you can read (record) buffers of uncompressed, sampled audio data. The stream's "direction"—whether it will be used for recording or playback—is described by the mode
argument.
You can create one input stream and as many as 15 output streams. The "active" end of a stream is hardwired to read from or write to the device's sound driver. This means you can't "redirect" an input stream to read from a file (for example), nor can you connect one output stream to another output stream in an attempt to create a filter chain. You can, however, collect data from the input stream, manipulate it, and then write it to an output stream.
Data Formats
The format of the data that flows through the stream is described by the sampleRate
, type
, and width
arguments. If you're using an "extended" stream (see SndStreamCreateExtended()
), you can also declare the data's encoding.
If you look at the SndSampleTag constants, you'll see four flavors for each quantization type: a big-endian version, a little-endian version, a native-endian version (defined as one of the other two), and an "opposite" version, which has endianness opposite that of the native version. In general, you should use the native-endian version when choosing a value for the type
parameter. The one exception to this (in Palm OS Garnet) is if your application is written for 68k, but uses an ARM callback
function (that is, callbackIsARM == true
). In this case you should use one of the little-endian formats as the type
value when you create your stream.
Running the Stream
The new stream starts running when you pass the stream
token returned by this function to the SndStreamStart()
function. This initiates a series of calls to your callback function, which is where the action is: Each callback invocation is passed a buffer into which you write or from which you read a chunk of audio data. The callback
function is also passed the callbackArg that you supply here. See SndStreamBufferCallback()
for more information on the callback function.
Buffering and Latency
Currently, audio streams are double-buffered. With regard to playback, this means that while one buffer (buffer A) is being played, your callback function is placing data in the other buffer (B). When A is "empty," the Sound Manager seamlessly starts playing buffer B, and passes buffer A back to your callback; when B is empty, it starts playing A, and passes back B, and so on. It's important that your callback function fills the data buffers as quickly as possible—certainly no longer than it takes to play a buffer of data. This same double-buffer scheme is also applied to sound recording although, of course, for recording you're emptying each buffer (and doing something with the data) in your callback function.
Regarding latency, you can use the bufferSize
argument to suggest a buffer size and thereby increase or decrease latency, but you can't change the number of buffers. Keep in mind that the actual buffer size that's used may not be the same as the size you suggest; hardware and memory limitations may enforce a maximum or minimum buffer size. Also keep in mind that the bufferSize
is measures in frames (not bytes).
See Also
SndStreamStart()
, SndStreamDelete()
, SndStreamBufferCallback()
Compatibility
Implemented if Sound Stream Feature Set is present.
SndStreamCreateExtended Function
Purpose
Create a new audio data stream that can be used to record or play back audio data.
Declared In
SoundMgr.h
Prototype
Err SndStreamCreate ( SndStreamRef *streamP, SndStreamMode mode, SndFormatType encodingFormat, UInt32 sampleRate, SndSampleType type, SndStreamWidth width, SndStreamVariableBufferCallback callback, void *callbackArgP, UInt32 bufferSize, Boolean callbackIsARM )
Parameters
-
←
streamP
- Token that represents the newly created stream.
-
→
mode
- One of the SndStreamModeTag constants that represents the "direction" of the data stream. Either
sndInput
(for recording), orsndOutput
(for playback). -
→
encodingFormat
- Constant that represents the encoding format of the data that you propose to pour through the stream. See
SndFormatType
for a list of elligible values. Currently, onlysndFormatPCM
is supported. -
→
sampleRate
- Sampling rate, in frames-per-second. Specify the native rate of the data, such as 22050, 44100, or 48000. The maximum rate is 96000.
-
→
type
- Sample quantization and endianness (see "Data Formats" for advice on choosing this value). Supply one of the values documented under "SndSampleTag."
-
→
width
- One of the constants documented under "SndStreamWidthTag" that represents the number of channels of data in the stream.
-
→
callback
- A callback function that gets called when another buffer of data is needed. As implied by the name of the data type, the function accepts variable-sized buffers. See
SndStreamVariableBufferCallback()
for a description of the callback function that you must implement. -
→ callbackArgP
- Caller-defined data that gets passed to callback.
-
→
bufferSize
- Preferred size (in frames) for the buffers that are passed to
callback
. Note that the actual buffer size (as allocated by the Sound Manager) may be different from this request. -
→
callbackIsARM
- Pass
true
if the callback function is written in ARM-native code, orfalse
if it is written in 68k code.
Returns
Returns errNone
if the operation completed successfully, or one of the following if there was an error:
-
sndErrBadParam
-
streamP
is invalid,callback
isNULL
, the sampling rate is too high (greater than 96000), or the device doesn't like some other sound parameter value. -
sndErrorMemory
- All streams are being used (there is a maximum of 16), or memory for this stream couldn't otherwise be allocated.
-
other errors
- The device couldn't allocate system resources for the stream.
Comments
With a few minor exceptions, this function is equivalent to SndStreamCreate()
; see that function's Comments section for a description of how the stream creation functions generally work.
One difference between standard and extended streams: If you're using an extended stream, you can also declare the data's encoding. When selecting that encoding, be aware of the following:
- The data format that you specify for an input stream must match the data that's produced by the audio hardware.
- For an output stream, you can specify any of the formats that the Sound Manager supports; the data is automatically converted to the output hardware's native audio format. Whether your stream's format setting actually affects the hardware is undefined. For example, if you set an output stream to use a 48k sampling rate, that doesn't mean that the DAC will be set to 48k.
- Currently, only
sndFormatPCM
is supported.
Extended streams also allow for variable-sized buffers, as opposed to the fixed-sized buffers used by SndStreamCreate
.This enables support for variable-length encoded data (such as MP3). To accommodate the variable-sized buffer, the callback function's prototype changes slightly for an extended stream: see SndStreamVariableBufferCallback()
for a full description of the callback function you use with SndStreamCreateExtended
.
SndStreamDelete Function
Purpose
Stop the stream and destroy it.
Declared In
SoundMgr.h
Prototype
Err SndStreamDelete ( SndStreamRef stream )
Parameters
-
→
stream
- Stream token, as returned from
SndStreamCreate()
orSndStreamCreateExtended()
.
Returns
Returns errNone
if the operation completed successfully. Returns sndErrBadParam
if the stream
argument is invalid.
Comments
SndStreamDelete
calls SndStreamStop()
before destroying the stream. You should never call SndStreamDelete
from within your callback function.
Compatibility
Implemented if Sound Stream Feature Set is present.
SndStreamGetPan Function
Purpose
Retrieve a stream's stereo balance.
Declared In
SoundMgr.h
Prototype
Err SndStreamGetPan ( SndStreamRef stream, Int32 *panP )
Parameters
-
→
stream
- Stream token, as returned from
SndStreamCreate()
orSndStreamCreateExtended()
. -
←
panP
- Pan value in the range [-1024 (hard left), 1024 (hard right)]. Center balance is 0.
Returns
Returns errNone
if the operation completed successfully. Returns sndErrBadParam
if stream
is invalid or panP
is NULL
.
Compatibility
Implemented if Sound Stream Feature Set is present.
See Also
SndStreamGetVolume Function
Purpose
Retrieve the amplitude scalar for a sound stream.
Declared In
SoundMgr.h
Prototype
Err SndStreamGetVolume ( SndStreamRef stream, Int32 *volumeP )
Parameters
-
→
stream
- Stream token, as returned from
SndStreamCreate()
orSndStreamCreateExtended()
. -
←
volumeP
- Amplitude scalar, in the range [0, 32k]. See
SndStreamSetVolume()
for more information.
Returns
Returns errNone
if the operation completed successfully. Returns sndErrBadParam
if stream
is invalid or volumeP
is NULL
.
See Also
Compatibility
Implemented if Sound Stream Feature Set is present.
SndStreamPause Function
Purpose
Pause or resume a sample stream.
Declared In
SoundMgr.h
Prototype
Err SndStreamPause ( SndStreamRef stream, Boolean pause )
Parameters
-
→
stream
- Stream token, as returned from
SndStreamCreate()
orSndStreamCreateExtended()
. -
→
pause
- If
true
, the function pauses the stream; iffalse
, it resumes the stream
Returns
Returns errNone
if the operation completed successfully (which includes the situation where the stream is already in the requested state). Returns sndErrBadParam
if stream
is invalid.
Comments
Currently, SndStreamPause
simply calls SndStreamStop()
(if pause
is true
) or SndStreamStart()
(if pause
is false
). See those functions for details about "pausing" and "resuming" a sound stream.
You can't nest pauses; a single resume request is effective, regardless of the number of times the stream has been told to pause.
Compatibility
Implemented if Sound Stream Feature Set is present.
SndStreamSetPan Function
Purpose
Sets a stream's stereo balance.
Declared In
SoundMgr.h
Prototype
Err SndStreamSetPan ( SndStreamRef stream, Int32 pan )
Parameters
-
→
stream
- Stream token, as returned from
SndStreamCreate()
orSndStreamCreateExtended()
. -
→
pan
- Pan value in the range [-1024 (full left), 1024 (full right)]. Center balance is 0. As a convenience, you can use the values described in "Stereo Pan Constants." Note that values outside of the valid range may yield unexpected results (but don't generate an error).
Returns
Returns errNone
if the operation completed successfully. Returns sndErrBadParam
if stream
is invalid.
Comments
The pan value is used as a scalar on a channel's volume such that a channel increases from 0 (inaudible) to full volume as the pan value moves from an extreme to 0. Graphically, it looks like this:

Compatibility
Implemented if Sound Stream Feature Set is present.
See Also
SndStreamSetVolume Function
Purpose
Sets the amplitude scalar for a sound stream.
Declared In
SoundMgr.h
Prototype
Err SndStreamSetVolume ( SndStreamRef stream, Int32 volume )
Parameters
-
→
stream
- Stream token, as returned from
SndStreamCreate()
orSndStreamCreateExtended()
. -
→
volume
- Amplitude scalar in the range [0, 32k]. Values less than 0 are converted to 1024 (unity gain).
Returns
Returns errNone
if the operation completed successfully. Returns sndErrBadParam
if stream
is invalid.
Comments
The volume
value is applied as an amplitude scalar on the samples that this stream's callback function produces. The scalar is in the range [0, 32k], where 1024 is unity gain (i.e. the samples are multiplied by 1.0). The mapping of volume
to a scalar is linear; thus a volume
of 512 scales the samples by ~.5, 2048 scales by ~2.0, and so on.
To specify a user preference volume setting, supply one of the constants documented under "Volume Constants." These values are guaranteed to be less than unity gain.
If the stream is stereo, both channels are scaled by the same amplitude scalar. To adjust the balance between the channels, use SndStreamSetPan()
.
Compatibility
Implemented if Sound Stream Feature Set is present.
SndStreamStart Function
Purpose
Start a sample stream running.
Declared In
SoundMgr.h
Prototype
Err SndStreamStart ( SndStreamRef stream )
Parameters
-
→
stream
- Stream token, as returned from
SndStreamCreate()
orSndStreamCreateExtended()
.
Returns
Returns errNone
if the operation completed successfully (errNone
is returned even if the stream is already running). Returns sndErrBadParam
if stream
is invalid.
Comments
If the stream is already running, SndStreamStart
returns immediately (with errNone
). If it isn't running, the function starts the stream by initiating invocations of its callback function. If the stream is paused (through SndStreamPause()
), the stream is resumed.
You can call this function from within another stream's callback function. This allows one stream to tell another stream to start playing.
Compatibility
Implemented if Sound Stream Feature Set is present.
SndStreamStop Function
Purpose
Stop a sample stream from running.
Declared In
SoundMgr.h
Prototype
Err SndStreamStop ( SndStreamRef stream )
Parameters
-
→
stream
- Stream token, as returned from
SndStreamCreate()
orSndStreamCreateExtended()
.
Returns
Returns errNone
if the operation completed successfully (errNone
is returned even if the stream is already stopped). Returns sndErrBadParam
if stream
is invalid.
Comments
Stops a running sound stream by neglecting to call the stream's callback function. The stream remains in this suspended state until you call SndStreamStart()
.
You can call this function from the stream's own callback function. In other words, a stream can stop itself.
Compatibility
Implemented if Sound Stream Feature Set is present.
Sampled Sound Application-Defined Functions
SndStreamBufferCallback Function
Purpose
In input mode, delivers a data buffer to your application. In output mode, allows your application to supply the next buffer's worth of data.
Declared In
SoundMgr.h
Prototype
Err ( *SndStreamBufferCallback ) ( void *userDataP, SndStreamRef stream, void *bufferP, UInt32 frameCount )
Parameters
-
→
userDataP
- Caller-defined data, as provided in the
callbackArg
parameter toSndStreamCreate()
. -
→
stream
- Token that represents the stream to which this buffer belongs.
-
→
bufferP
- The data buffer.
-
→
frameCount
- Number of sample frames the buffer contains.
Returns
Currently, the return value is ignored.
Comments
The SndStreamBufferCallback
function that you create is invoked in input (recording) mode when the Sound Manager wants to deliver a new buffer of sound data to your application. In output (playback) mode, it is invoked when the Sound Manager needs another buffer of sound data. You associate your callback function with a given stream when you call SndStreamCreate()
.
In input mode, your callback function should read the data from the data buffer. In output mode, your callback function should write data into the data buffer (and it must fill the entire buffer with data).In either case, you want to do this as quickly as possible to avoid data underflow.
Note that the arguments passed to your callback function tell you nothing about the format of the data. You can use the userDataP
argument to pass this information into the function.
The callback function is executed in a task that's created and managed by the Sound Manager. Because of this, the function doesn't have access to the symbols that you create in your application. Again, use the userDataP
argument if you need to pass pointers to your symbols.
Compatibility
Implemented if Sound Stream Feature Set is present.
See Also
SndStreamCreate()
, SndStreamVariableBufferCallback()
SndStreamVariableBufferCallback Function
Purpose
In input mode, delivers a variable-length data buffer to your application. In output mode, allows your application to supply the next buffer's worth of data.
Declared In
SoundMgr.h
Prototype
Err ( *SndStreamVariableBufferCallback ) ( void *userDataP, SndStreamRef stream, void *bufferP, UInt32 *bufferSizeP )
Parameters
-
→
userDataP
- Caller-defined data, as provided by the
callbackArg
parameter toSndStreamCreateExtended()
. -
→
stream
- Token that represents the stream that this buffer belongs to.
-
→
bufferP
- The data buffer.
-
↔
bufferSizeP
- Size of the buffer, in bytes.
Returns
Currently, the return value is ignored.
Comments
The SndStreamVariableBufferCallback
function that you create is invoked in input (recording) mode when the Sound Manager wants to deliver a new buffer of sound data to your application. In output (playback) mode, it is invoked when the Sound Manager needs another buffer of sound data. You associate your callback function with a given stream when you call SndStreamCreateExtended()
.
In input mode, your callback function should read the data from the data buffer. In output mode, your callback function should write data into the data buffer and then reset *bufferSizeP
to the amount of data that was actually written. Unlike SndStreamBufferCallback()
, your callback function is not required to fill the entire buffer with data. Moreover, the data that it writes to the buffer doesn't have to meet any other threshold or requirement—for example, the buffer doesn't have to represent a certain amount of playback time. This flexibility is provided in order to support variable-length encoded data (such as MP3).
Whether your callback is reading from the buffer or writing to it, it should do this as quickly as possible to avoid data underflow.
Note that the arguments passed to your callback function tell you nothing about the format of the data. You can use the userDataP
argument to pass this information into the function.
The callback function is executed in a task that's created and managed by the Sound Manager. Because of this, the function doesn't have access to the symbols that you create in your application. Again, use the userDataP
argument if you need to pass pointers to your symbols.
Compatibility
Implemented if Sound Stream Feature Set is present.
See Also
SndStreamCreateExtended()
, SndStreamBufferCallback()