480 lines
17 KiB
C
Executable File
480 lines
17 KiB
C
Executable File
/******************************************************************************
|
|
*
|
|
* Copyright (c) 1995-2004 PalmSource, Inc. All rights reserved.
|
|
*
|
|
* File: SoundMgr.h
|
|
*
|
|
* Release: eclipse 5 SDK (68K) R4.
|
|
*
|
|
* Description:
|
|
* Include file for Sound Manager
|
|
*
|
|
*****************************************************************************/
|
|
|
|
#ifndef __SOUNDMGR_H__
|
|
#define __SOUNDMGR_H__
|
|
|
|
|
|
// Include elementary types
|
|
#include <PalmTypes.h>
|
|
#include <CoreTraps.h> // Trap Numbers.
|
|
|
|
#include <Preferences.h>
|
|
|
|
|
|
/************************************************************
|
|
* Sound Manager constants
|
|
*
|
|
*************************************************************/
|
|
|
|
// Sound Manager max and default volume levels
|
|
#define sndMaxAmp 64
|
|
//#define sndVolumeMask 0x0ff
|
|
#define sndDefaultAmp sndMaxAmp
|
|
|
|
#define sndMidiNameLength 32 // MIDI track name length *including* NULL terminator
|
|
|
|
|
|
/************************************************************
|
|
* Sound Manager data structures
|
|
*
|
|
*************************************************************/
|
|
|
|
//
|
|
// Command numbers for SndCommandType's cmd field
|
|
//
|
|
enum SndCmdIDTag {
|
|
|
|
sndCmdFreqDurationAmp = 1, // play a sound, blocking for the entire duration (except for zero amplitude)
|
|
// param1 = frequency in Hz
|
|
// param2 = duration in milliseconds
|
|
// param3 = amplitude (0 - sndMaxAmp); if 0, will return immediately
|
|
|
|
// Commands added in PilotOS v3.0
|
|
// ***IMPORTANT***
|
|
// Please note that SndDoCmd() in PilotOS before v3.0 will Fatal Error on unknown
|
|
// commands (anything other than sndCmdFreqDurationAmp). For this reason,
|
|
// applications wishing to take advantage of these new commands while staying
|
|
// compatible with the earlier version of the OS, _must_ avoid using these commands
|
|
// when running on OS versions less thatn v3.0 (see sysFtrNumROMVersion in SystemMgr.h).
|
|
// Beginning with v3.0, SndDoCmd has been fixed to return sndErrBadParam when an
|
|
// unknown command is passed.
|
|
//
|
|
sndCmdNoteOn, // start a sound given its MIDI key index, max duration and velocity;
|
|
// the call will not wait for the sound to complete, returning imeediately;
|
|
// any other sound play request made before this one completes will interrupt it.
|
|
// param1 = MIDI key index (0-127)
|
|
// param2 = maximum duration in milliseconds
|
|
// param3 = velocity (0 - 127) (will be interpolated as amplitude)
|
|
|
|
sndCmdFrqOn, // start a sound given its frequency in Hz, max duration and amplitude;
|
|
// the call will not wait for the sound to complete, returning imeediately;
|
|
// any other sound play request made before this one completes will interrupt it.
|
|
// param1 = frequency in Hz
|
|
// param2 = maximum duration in milliseconds
|
|
// param3 = amplitude (0 - sndMaxAmp)
|
|
|
|
sndCmdQuiet // stop current sound
|
|
// param1 = 0
|
|
// param2 = 0
|
|
// param3 = 0
|
|
|
|
};
|
|
|
|
typedef UInt8 SndCmdIDType;
|
|
|
|
|
|
|
|
//
|
|
// SndCommandType: used by SndDoCmd()
|
|
//
|
|
|
|
typedef struct SndCommandType {
|
|
SndCmdIDType cmd; // command id
|
|
UInt8 reserved;
|
|
Int32 param1; // first parameter
|
|
UInt16 param2; // second parameter
|
|
UInt16 param3; // third parameter
|
|
} SndCommandType;
|
|
|
|
typedef SndCommandType* SndCommandPtr;
|
|
|
|
|
|
//
|
|
// Beep numbers used by SndSysBeep()
|
|
//
|
|
|
|
enum SndSysBeepTag {
|
|
sndInfo = 1,
|
|
sndWarning,
|
|
sndError,
|
|
sndStartUp,
|
|
sndAlarm,
|
|
sndConfirmation,
|
|
sndClick
|
|
};
|
|
|
|
typedef UInt8 SndSysBeepType;
|
|
|
|
/************************************************************
|
|
* Standard MIDI File (SMF) support structures
|
|
*************************************************************/
|
|
|
|
|
|
// Structure of records in the MIDI sound database:
|
|
//
|
|
// Each MIDI record consists of a record header followed immediately by the
|
|
// Standard MIDI File (SMF) data stream. Only SMF format #0 is presently supported.
|
|
// The first byte of the record header is the byte offset from the beginning of the record
|
|
// to the SMF data stream. The name of the record follows the byte offset
|
|
// field. sndMidiNameLength is the limit on name size (including NULL).
|
|
#define sndMidiRecSignature 'PMrc'
|
|
typedef struct SndMidiRecHdrType {
|
|
UInt32 signature; // set to sndMidiRecSignature
|
|
UInt8 bDataOffset; // offset from the beginning of the record
|
|
// to the Standard Midi File data stream
|
|
UInt8 reserved; // set to zero
|
|
} SndMidiRecHdrType;
|
|
|
|
typedef struct SndMidiRecType {
|
|
SndMidiRecHdrType hdr; // offset from the beginning of the record
|
|
// to the Standard Midi File data stream
|
|
Char name[2]; // Track name: 1 or more chars including NULL terminator.
|
|
// If a track has no name, the NULL character must still
|
|
// be provided.
|
|
// Set to 2 to pad the structure out to a word boundary.
|
|
} SndMidiRecType;
|
|
|
|
|
|
// Midi records found by SndCreateMidiList.
|
|
typedef struct SndMidiListItemType
|
|
{
|
|
Char name[sndMidiNameLength]; // including NULL terminator
|
|
UInt32 uniqueRecID;
|
|
LocalID dbID;
|
|
UInt16 cardNo;
|
|
} SndMidiListItemType;
|
|
|
|
|
|
// Commands for SndPlaySmf
|
|
enum SndSmfCmdEnumTag {
|
|
sndSmfCmdPlay = 1, // play the selection
|
|
sndSmfCmdDuration // get the duration in milliseconds of the entire track
|
|
};
|
|
|
|
typedef UInt8 SndSmfCmdEnum;
|
|
|
|
typedef void SndComplFuncType(void *chanP, UInt32 dwUserData);
|
|
typedef SndComplFuncType *SndComplFuncPtr;
|
|
|
|
|
|
// Return true to continue, false to abort
|
|
typedef Boolean SndBlockingFuncType(void *chanP, UInt32 dwUserData, Int32 sysTicksAvailable);
|
|
typedef SndBlockingFuncType *SndBlockingFuncPtr;
|
|
|
|
typedef struct SndCallbackInfoType {
|
|
MemPtr funcP; // pointer to the callback function (NULL = no function)
|
|
UInt32 dwUserData; // value to be passed in the dwUserData parameter of the callback function
|
|
} SndCallbackInfoType;
|
|
|
|
|
|
typedef struct SndSmfCallbacksType {
|
|
SndCallbackInfoType completion; // completion callback function (see SndComplFuncType)
|
|
SndCallbackInfoType blocking; // blocking hook callback function (see SndBlockingFuncType)
|
|
SndCallbackInfoType reserved; // RESERVED -- SET ALL FIELDS TO ZERO BEFORE PASSING
|
|
} SndSmfCallbacksType;
|
|
|
|
|
|
#define sndSmfPlayAllMilliSec 0xFFFFFFFFUL
|
|
|
|
typedef struct SndSmfOptionsType {
|
|
// dwStartMilliSec and dwEndMilliSec are used as inputs to the function for sndSmfCmdPlay and as
|
|
// outputs for sndSmfCmdDuration
|
|
UInt32 dwStartMilliSec; // 0 = "start from the beginning"
|
|
UInt32 dwEndMilliSec; // sndSmfPlayAllMilliSec = "play the entire track";
|
|
// the default is "play entire track" if this structure
|
|
// is not passed in
|
|
|
|
// The amplitude and interruptible fields are used only for sndSmfCmdPlay
|
|
UInt16 amplitude; // relative volume: 0 - sndMaxAmp, inclusively; the default is
|
|
// sndMaxAmp if this structure is not passed in; if 0, the play will
|
|
// be skipped and the call will return immediately
|
|
|
|
Boolean interruptible; // if true, sound play will be interrupted if
|
|
// user interacts with the controls (digitizer, buttons, etc.);
|
|
// if false, the paly will not be interrupted; the default behavior
|
|
// is "interruptible" if this structure is not passed in
|
|
|
|
UInt8 reserved1;
|
|
UInt32 reserved; // RESERVED! -- MUST SET TO ZERO BEFORE PASSING
|
|
} SndSmfOptionsType;
|
|
|
|
|
|
typedef struct SndSmfChanRangeType {
|
|
UInt8 bFirstChan; // first MIDI channel (0-15 decimal)
|
|
UInt8 bLastChan; // last MIDI channel (0-15 decimal)
|
|
} SndSmfChanRangeType;
|
|
|
|
|
|
|
|
|
|
/************************************************************
|
|
* Sound Manager result codes
|
|
* (sndErrorClass is defined in SystemMgr.h)
|
|
*************************************************************/
|
|
#define sndErrBadParam (sndErrorClass | 1)
|
|
#define sndErrBadChannel (sndErrorClass | 2)
|
|
#define sndErrMemory (sndErrorClass | 3)
|
|
#define sndErrOpen (sndErrorClass | 4)
|
|
#define sndErrQFull (sndErrorClass | 5)
|
|
#define sndErrQEmpty (sndErrorClass | 6) // internal
|
|
#define sndErrFormat (sndErrorClass | 7) // unsupported data format
|
|
#define sndErrBadStream (sndErrorClass | 8) // invalid data stream
|
|
#define sndErrInterrupted (sndErrorClass | 9) // play was interrupted
|
|
#define sndErrNotImpl (sndErrorClass |10) // function not implemented
|
|
#define sndErrInvalidStream (sndErrorClass |11) // invalid stream-identifier
|
|
|
|
|
|
|
|
/********************************************************************
|
|
* Sound Manager Routines
|
|
* These are define as external calls only under emulation mode or
|
|
* under native mode from the module that actually installs the trap
|
|
* vectors
|
|
********************************************************************/
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
|
|
//-------------------------------------------------------------------
|
|
// Initialization
|
|
//-------------------------------------------------------------------
|
|
|
|
// Initializes the Sound Manager. Should only be called by
|
|
// Pilot initialization code.
|
|
Err SndInit(void) SYS_TRAP(sysTrapSndInit);
|
|
|
|
// Frees the Sound Manager.
|
|
//void SndFree(void) SYS_TRAP(sysTrapSndFree);
|
|
|
|
|
|
//-------------------------------------------------------------------
|
|
// API
|
|
//-------------------------------------------------------------------
|
|
|
|
// Sets default sound volume levels
|
|
//
|
|
// Any parameter may be passed as NULL
|
|
extern void SndSetDefaultVolume(UInt16 *alarmAmpP, UInt16 *sysAmpP, UInt16 *defAmpP)
|
|
SYS_TRAP(sysTrapSndSetDefaultVolume);
|
|
|
|
// Gets default sound volume levels
|
|
//
|
|
// Any parameter may be passed as NULL
|
|
extern void SndGetDefaultVolume(UInt16 *alarmAmpP, UInt16 *sysAmpP, UInt16 *masterAmpP)
|
|
SYS_TRAP(sysTrapSndGetDefaultVolume);
|
|
|
|
// Executes a sound command on the given sound channel (pass
|
|
// channelP = 0 to use the shared channel).
|
|
extern Err SndDoCmd(void * /*SndChanPtr*/ channelP, SndCommandPtr cmdP, Boolean noWait)
|
|
SYS_TRAP(sysTrapSndDoCmd);
|
|
|
|
// Plays one of several defined system beeps/sounds (see sndSysBeep...
|
|
// constants).
|
|
extern void SndPlaySystemSound(SndSysBeepType beepID)
|
|
SYS_TRAP(sysTrapSndPlaySystemSound);
|
|
|
|
|
|
// NEW FOR v3.0
|
|
// Performs an operation on a Standard MIDI File (SMF) Format #0
|
|
extern Err SndPlaySmf(void *chanP, SndSmfCmdEnum cmd, UInt8 *smfP, SndSmfOptionsType *selP,
|
|
SndSmfChanRangeType *chanRangeP, SndSmfCallbacksType *callbacksP,
|
|
Boolean bNoWait)
|
|
SYS_TRAP(sysTrapSndPlaySmf);
|
|
|
|
// NEW FOR v3.0
|
|
// Creates a list of all midi records. Useful for displaying in lists.
|
|
// For creator wildcard, pass creator=0;
|
|
extern Boolean SndCreateMidiList(UInt32 creator, Boolean multipleDBs, UInt16 *wCountP, MemHandle *entHP)
|
|
SYS_TRAP(sysTrapSndCreateMidiList);
|
|
|
|
// NEW FOR v3.2
|
|
// Plays a MIDI sound which is read out of an open resource database
|
|
extern Err SndPlaySmfResource(UInt32 resType, Int16 resID, SystemPreferencesChoice volumeSelector)
|
|
SYS_TRAP(sysTrapSndPlaySmfResource);
|
|
|
|
|
|
// NEW FOR v4.0
|
|
// Plays MIDI sounds regardless of the how the interruptible flag is set
|
|
extern Err SndPlaySmfIrregardless(void *chanP, SndSmfCmdEnum cmd, UInt8 *smfP, SndSmfOptionsType *selP,
|
|
SndSmfChanRangeType *chanRangeP, SndSmfCallbacksType *callbacksP,
|
|
Boolean bNoWait)
|
|
SYS_TRAP(sysTrapSndPlaySmfIrregardless);
|
|
|
|
extern Err SndPlaySmfResourceIrregardless(UInt32 resType, Int16 resID, SystemPreferencesChoice volumeSelector)
|
|
SYS_TRAP(sysTrapSndPlaySmfResourceIrregardless);
|
|
|
|
|
|
extern Err SndInterruptSmfIrregardless(void)
|
|
SYS_TRAP(sysTrapSndInterruptSmfIrregardless);
|
|
|
|
|
|
//
|
|
// Sound streams API. New for v5
|
|
//
|
|
|
|
#define sndFtrIDVersion 0 // ID of feature containing (new) sound manager version
|
|
// Check for existence of this feature to determine if
|
|
// the Sound streams APIs are available
|
|
#define sndMgrVersionNum (100) // The current version (1.00)
|
|
|
|
typedef UInt32 SndStreamRef;
|
|
|
|
enum SndStreamModeTag {
|
|
sndInput,
|
|
sndOutput
|
|
};
|
|
|
|
typedef Int8 SndStreamMode;
|
|
|
|
enum SndStreamWidthTag {
|
|
sndMono,
|
|
sndStereo
|
|
};
|
|
typedef Int8 SndStreamWidth;
|
|
|
|
/*
|
|
* special 'cookie' values that can be used instead of a real volume setting
|
|
* */
|
|
enum
|
|
{
|
|
sndSystemVolume = -1,
|
|
sndGameVolume = -2,
|
|
sndAlarmVolume = -3
|
|
};
|
|
|
|
/*
|
|
* the lower 4 bits of the sampletype indicate the size in bytes of a single
|
|
* sample.
|
|
*/
|
|
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, // native-endian
|
|
sndInt16Opposite= sndInt16Little, // opposite of native-endian
|
|
sndInt32 = sndInt32Big,
|
|
sndInt32Opposite= sndInt32Little,
|
|
sndFloat = sndFloatBig,
|
|
sndFloatOpposite= sndFloatLittle
|
|
#else
|
|
sndInt16 = sndInt16Little,
|
|
sndInt16Opposite= sndInt16Big,
|
|
sndInt32 = sndInt32Little,
|
|
sndInt32Opposite= sndInt32Big,
|
|
sndFloat = sndFloatLittle,
|
|
sndFloatOpposite= sndFloatBig
|
|
#endif
|
|
};
|
|
typedef Int16 SndSampleType;
|
|
|
|
|
|
// Flags to be used with SndPlayResource
|
|
#define sndFlagSync 0x00000000
|
|
#define sndFlagAsync 0x00000001
|
|
#define sndFlagNormal sndFlagSync
|
|
|
|
// Special Panning values
|
|
#define sndPanCenter (0)
|
|
#define sndPanFullLeft (-1024)
|
|
#define sndPanFullRight (1024)
|
|
|
|
typedef void *SndPtr;
|
|
|
|
typedef Err (*SndStreamBufferCallback)(void *userdata,
|
|
SndStreamRef channel, void *buffer, UInt32 numberofframes);
|
|
|
|
extern Err SndStreamCreate(SndStreamRef *channel, /* channel-ID is stored here */
|
|
SndStreamMode mode, /* input/output, enum */
|
|
UInt32 samplerate, /* in frames/second, e.g. 44100, 48000 */
|
|
SndSampleType type, /* enum, e.g. sndInt16 */
|
|
SndStreamWidth width, /* enum, e.g. sndMono */
|
|
SndStreamBufferCallback func, /* function that gets called to fill a buffer */
|
|
void *userdata, /* gets passed in to the above function */
|
|
UInt32 buffsize, /* preferred buffersize in frames, not guaranteed, use 0 for default */
|
|
Boolean armNative) /* true if callback is arm native */
|
|
SYS_TRAP(sysTrapSndStreamCreate);
|
|
|
|
extern Err SndStreamDelete(SndStreamRef channel)
|
|
SYS_TRAP(sysTrapSndStreamDelete);
|
|
|
|
extern Err SndStreamStart(SndStreamRef channel)
|
|
SYS_TRAP(sysTrapSndStreamStart);
|
|
|
|
extern Err SndStreamPause(SndStreamRef channel, Boolean pause)
|
|
SYS_TRAP(sysTrapSndStreamPause);
|
|
|
|
extern Err SndStreamStop(SndStreamRef channel)
|
|
SYS_TRAP(sysTrapSndStreamStop);
|
|
|
|
extern Err SndStreamSetVolume(SndStreamRef channel, Int32 volume)
|
|
SYS_TRAP(sysTrapSndStreamSetVolume);
|
|
|
|
extern Err SndStreamGetVolume(SndStreamRef channel, Int32 *volume)
|
|
SYS_TRAP(sysTrapSndStreamGetVolume);
|
|
|
|
extern Err SndPlayResource(SndPtr sndP, Int32 volume, UInt32 flags)
|
|
SYS_TRAP(sysTrapSndPlayResource);
|
|
|
|
extern Err SndStreamSetPan(SndStreamRef channel, Int32 panposition)
|
|
SYS_TRAP(sysTrapSndStreamSetPan);
|
|
|
|
extern Err SndStreamGetPan(SndStreamRef channel, Int32 *panposition)
|
|
SYS_TRAP(sysTrapSndStreamGetPan);
|
|
|
|
|
|
typedef Err (*SndStreamVariableBufferCallback)(void *userdata,
|
|
SndStreamRef channel, void *buffer, UInt32 *bufferSizeP);
|
|
|
|
enum SndFormatTag {
|
|
sndFormatPCM = 0, // Raw PCM (Pulse Code Modulation), (attributes defined by type parameter)
|
|
sndFormatIMA_ADPCM = 'APCM', // IMA ADPCM (Interactive Multimedia Association Adaptive Differential PCM)
|
|
sndFormatDVI_ADPCM = 'DPCM', // Intel/MS/DVI ADPCM
|
|
sndFormatMP3 = 'MPG3', // Moving Picture Experts Group, Audio Layer III (MPEG-1 and MPEG-2 depending on bit-rate)
|
|
sndFormatAAC = 'DAAC', // Dolby Advanced Audio Coding
|
|
sndFormatOGG = 'OGGV' // Ogg Vorbis
|
|
};
|
|
|
|
typedef UInt32 SndFormatType;
|
|
|
|
extern Err SndStreamCreateExtended(
|
|
SndStreamRef *channel, /* channel-ID is stored here */
|
|
SndStreamMode mode, /* input/output, enum */
|
|
SndFormatType format, /* enum, e.g., sndFormatMP3 */
|
|
UInt32 samplerate, /* in frames/second, e.g. 44100, 48000 */
|
|
SndSampleType type, /* enum, e.g. sndInt16, if applicable, or 0 otherwise */
|
|
SndStreamWidth width, /* enum, e.g. sndMono */
|
|
SndStreamVariableBufferCallback func, /* function that gets called to fill a buffer */
|
|
void *userdata, /* gets passed in to the above function */
|
|
UInt32 buffsize, /* preferred buffersize, use 0 for default */
|
|
Boolean armNative) /* true if callback is arm native */
|
|
SYS_TRAP(sysTrapSndStreamCreateExtended);
|
|
|
|
extern Err SndStreamDeviceControl( SndStreamRef channel, Int32 cmd, void* param, Int32 size)
|
|
SYS_TRAP(sysTrapSndStreamDeviceControl);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
|
|
#endif // __SOUND_MGR_H__
|