path: root/fpcsrc/packages/palmunits/src/soundmgr.pp

{$MACRO ON}
{$define Rsc := }
(******************************************************************************
 *
 * Copyright (c) 1995-2000 Palm, Inc. or its subsidiaries.
 * All rights reserved.
 *
 * File: SoundMgr.h
 *
 * Release: Palm OS SDK 4.0 (63220)
 *
 * Description:
 *    Include file for Sound Manager
 *
 * History:
 *    4/11/95  VMK - Created by Vitaly Kruglikov
 *
 *****************************************************************************)

unit soundmgr;

interface

uses palmos, coretraps, errorbase, preferences;

(************************************************************
 * Sound Manager constants
 *
 *************************************************************)

const
// Sound Manager max and default volume levels
  sndMaxAmp         = 64;
//sndVolumeMask     = $ff;
  sndDefaultAmp     = sndMaxAmp;

  sndMidiNameLength = 32; // MIDI track name length *including* NULL terminator

(************************************************************
 * Sound Manager data structures
 *
 *************************************************************)

//
// Command numbers for SndCommandType's cmd field
//
type
  SndCmdIDType = Enum;

const
  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 = Succ(sndCmdFreqDurationAmp); // 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 = Succ(sndCmdNoteOn);         // 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 = Succ(sndCmdFrqOn);          // stop current sound
                                            // param1 = 0
                                            // param2 = 0
                                            // param3 = 0

//
// SndCommandType: used by SndDoCmd()
//

type
  SndCommandType = record
    cmd: SndCmdIDType;             // command id
    reserved: UInt8;
    param1: Int32;                 // first parameter
    param2: UInt16;                // second parameter
    param3: UInt16;                // third parameter
  end;

  SndCommandPtr = ^SndCommandType;

//
// Beep numbers used by SndSysBeep()
//

type
  SndSysBeepType = Enum;

const
  sndInfo = 1;
  sndWarning = Succ(sndInfo);
  sndError = Succ(sndWarning);
  sndStartUp = Succ(sndError);
  sndAlarm = Succ(sndStartUp);
  sndConfirmation = Succ(sndAlarm);
  sndClick = Succ(sndConfirmation);

(************************************************************
 * 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).

const
  sndMidiRecSignature = Rsc('PMrc');

type
  SndMidiRecHdrType = record
    signature: UInt32;             // set to sndMidiRecSignature
    bDataOffset: UInt8;            // offset from the beginning of the record
                                   // to the Standard Midi File data stream
    reserved: UInt8;               // set to zero
  end;

  SndMidiRecType = record
    hdr: SndMidiRecHdrType;            // offset from the beginning of the record
                                       // to the Standard Midi File data stream
    name: array [0..2-1] of Char;      // 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.
  end;

// Midi records found by SndCreateMidiList.
  SndMidiListItemType = record
    name: array [0..sndMidiNameLength-1] of Char; // including NULL terminator
    uniqueRecID: UInt32;
    dbID: LocalID;
    cardNo: UInt16;
  end;

// Commands for SndPlaySmf
  SndSmfCmdEnum = Enum;

const
  sndSmfCmdPlay = 1;                       // play the selection
  sndSmfCmdDuration = Succ(sndSmfCmdPlay); // get the duration in milliseconds of the entire track

type
  SndComplFuncType = procedure(chanP: Pointer; dwUserData: UInt32);
  SndComplFuncPtr = SndComplFuncType;

// Return true to continue, false to abort
  SndBlockingFuncType = function(chanP: Pointer; dwUserData: UInt32; sysTicksAvailable: Int32): Boolean;
  SndBlockingFuncPtr = SndBlockingFuncType;

type
  SndCallbackInfoType = record
    funcP: MemPtr;          // pointer to the callback function (NULL = no function)
    dwUserData: UInt32;     // value to be passed in the dwUserData parameter of the callback function
  end;

  SndSmfCallbacksType = record
    completion: SndCallbackInfoType;     // completion callback function (see SndComplFuncType)
    blocking: SndCallbackInfoType;       // blocking hook callback function (see SndBlockingFuncType)
    reserved: SndCallbackInfoType;       // RESERVED -- SET ALL FIELDS TO ZERO BEFORE PASSING
  end;
  SndSmfCallbacksPtr = ^SndSmfCallbacksType;

const
  sndSmfPlayAllMilliSec = $FFFFFFFF;

type
  SndSmfOptionsType = record
    // dwStartMilliSec and dwEndMilliSec are used as inputs to the function for sndSmfCmdPlay and as
    // outputs for sndSmfCmdDuration
    dwStartMilliSec: UInt32;                // 0 = "start from the beginning"
    dwEndMilliSec: UInt32;                  // 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
    amplitude: UInt16;                      // 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

    interruptible: Boolean;                 // 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

    reserved1: UInt8;
    reserved: UInt32;                       // RESERVED! -- MUST SET TO ZERO BEFORE PASSING
  end;
  SndSmfOptionsPtr = ^SndSmfOptionsType;

  SndSmfChanRangeType = record
    bFirstChan: UInt8;                         // first MIDI channel (0-15 decimal)
    bLastChan: UInt8;                          // last MIDI channel (0-15 decimal)
  end;
  SndSmfChanRangePtr = ^SndSmfChanRangeType;

(************************************************************
 * Sound Manager result codes
 * (sndErrorClass is defined in SystemMgr.h)
 *************************************************************)

const
  sndErrBadParam    = sndErrorClass or 1;
  sndErrBadChannel  = sndErrorClass or 2;
  sndErrMemory      = sndErrorClass or 3;
  sndErrOpen        = sndErrorClass or 4;
  sndErrQFull       = sndErrorClass or 5;
  sndErrQEmpty      = sndErrorClass or 6; // internal
  sndErrFormat      = sndErrorClass or 7; // unsupported data format
  sndErrBadStream   = sndErrorClass or 8; // invalid data stream
  sndErrInterrupted = sndErrorClass or 9; // play was interrupted

(********************************************************************
 * Sound Manager Routines
 * These are define as syscall calls only under emulation mode or
 *  under native mode from the module that actually installs the trap
 *  vectors
 ********************************************************************)

//-------------------------------------------------------------------
// Initialization
//-------------------------------------------------------------------

// Initializes the Sound Manager.  Should only be called by
// Pilot initialization code.
function SndInit: Err; syscall sysTrapSndInit;

// Frees the Sound Manager.
//procedure SndFree; syscall sysTrapSndFree;

//-------------------------------------------------------------------
// API
//-------------------------------------------------------------------

// Sets default sound volume levels
//
// Any parameter may be passed as NULL
procedure SndSetDefaultVolume(var alarmAmpP, sysAmpP, defAmpP: UInt16); syscall sysTrapSndSetDefaultVolume;

// Gets default sound volume levels
//
// Any parameter may be passed as NULL
procedure SndGetDefaultVolume(var alarmAmpP, sysAmpP, masterAmpP: UInt16); syscall sysTrapSndGetDefaultVolume;

// Executes a sound command on the given sound channel (pass
// channelP = 0 to use the shared channel).
function SndDoCmd({SndChanPtr} channelP: Pointer; cmdP: SndCommandPtr; noWait: Boolean): Err; syscall sysTrapSndDoCmd;

// Plays one of several defined system beeps/sounds (see sndSysBeep...
// constants).
procedure SndPlaySystemSound(beepID: SndSysBeepType); syscall sysTrapSndPlaySystemSound;

// NEW FOR v3.0
// Performs an operation on a Standard MIDI File (SMF) Format #0
function SndPlaySmf(chanP: Pointer; cmd: SndSmfCmdEnum; var smfP: UInt8; selP: SndSmfOptionsPtr;
                    chanRangeP: SndSmfChanRangePtr; callbacksP: SndSmfCallbacksPtr;
                    bNoWait: Boolean): Err; syscall sysTrapSndPlaySmf;

// NEW FOR v3.0
// Creates a list of all midi records.  Useful for displaying in lists.
// For creator wildcard, pass creator=0;
function SndCreateMidiList(creator: UInt32; multipleDBs: Boolean; var wCountP: UInt16; var entHP: MemHandle): Boolean; syscall sysTrapSndCreateMidiList;

// NEW FOR v3.2
// Plays a MIDI sound which is read out of an open resource database
function SndPlaySmfResource(resType: UInt32; resID: Int16; volumeSelector: SystemPreferencesChoice): Err; syscall sysTrapSndPlaySmfResource;


// NEW FOR v4.0
// Plays MIDI sounds regardless of the how the interruptible flag is set
function SndPlaySmfIrregardless(chanP: Pointer; cmd: SndSmfCmdEnum; var smfP: UInt8;
                                var selP: SndSmfOptionsType; var chanRangeP: SndSmfChanRangeType;
                                var callbacksP: SndSmfCallbacksType; bNoWait: Boolean): Err; syscall sysTrapSndPlaySmfIrregardless;

function SndPlaySmfResourceIrregardless(resType: UInt32; resID: Int16; volumeSelector: SystemPreferencesChoice): Err; syscall sysTrapSndPlaySmfResourceIrregardless;

function SndInterruptSmfIrregardless: Err; syscall sysTrapSndInterruptSmfIrregardless;

(************************************************************
 * Sound Manager Macros
 *
 *************************************************************)

implementation

end.