----------------------------------------------------------------------------- Digital Sound Interface Kit (DSIK) Version 2.00 -- Reference Guide -- Copyright (c) 1993-95 by Carlos Hasan. All Rights Reserved. ----------------------------------------------------------------------------- This file provides information about all the procedures and functions used to work with the sound system. 1. Procedures and Functions: dAutoDetect ----------------------------------------------------------------------------- Function: Soundcard autodetection routine. Prototype: int dAutoDetect(SoundCard *SC) Parameters: SC - soundcard structure Returns: Return zero on success. Description: This routine will try to detect a soundcard. It uses safe detection routines based on environment variables and system calls to soundcard drivers. This routine can't detect all the supported soundcards, so is highly recommended to use the SETUP.EXE utility and the dLoadSetup routine to get the soundcard parameters. See Also: dLoadSetup, dInit. dDone ----------------------------------------------------------------------------- Function: Deinitializes the sound system. Prototype: int dDone(void) Parameters: None. Returns: Returns zero on success. Description: This routine will deinitialize the sound system, must be called before leaving from your program. See Also: dInit. dDoneTimer ----------------------------------------------------------------------------- Function: Deinitializes the timer services. Prototype: void dDoneTimer(void) Parameters: None. Returns: None. Description: Shutdown the timer services routines, must be called before exiting from your program. See Also: dInitTimer. dFreeModule ----------------------------------------------------------------------------- Function: Releases memory used by a module. Prototype: void dFreeModule(DSM *MusicPtr) Parameters: MusicPtr - module address Returns: None. Description: Routine used to release all the memory used by a module. You cannot call this function while the sound system is playing the module. See Also: dLoadModule. dFreeSample ----------------------------------------------------------------------------- Function: Releases memory used by a sample. Prototype: void dFreeSample(Sample *SampPtr) Parameters: SampPtr - sample structure Returns: None. Description: Used to release the memory used by a sample. You cannot release a sample while it's being played by the system. See Also: dLoadSample, dImportSample. dGetDriverFlags ----------------------------------------------------------------------------- Function: Returns the current driver capabilities bit flags. Prototype: int dGetDriverFlags(void) Parameters: None. Returns: Driver capabilities flags. Description: This routine returns the capabilities bit flags of the current active sound driver. The following constants are defined: Constant Value Description ------------------------------------------------------- AF_8BITS 0x00 8-bits per sample AF_16BITS 0x01 16-bits per sample AF_MONO 0x00 mono output mode AF_STEREO 0x02 stereo output mode AF_NODRAM 0x00 samples stored in system memory AF_DRAM 0x04 samples stored in soundcard memory For example, if you want to know if the current driver is playing in 16-bit mode: if (dGetDriverFlags() & AF_16BITS) printf("16-bit output mode.\n"); However, drivers that support 16-bit and/or stereo output mode can be forced to use 8-bit and/or mono output mode. This function will return the output mode currently used by the sound system. See Also: dInit, dDone. dGetDriverStruc ----------------------------------------------------------------------------- Function: Return the driver structure for a given driver identifier. Prototype: Driver *dGetDriverStruc(int DriverId) Parameters: DriverId - driver identifier value Returns: Driver structure address or NULL if not found. Description: Returns the driver structure address for a specified driver identifier. The following driver identifiers are defined: Constant Description -------------------------------------- ID_NONE No sound ID_SB Sound Blaster ID_SB201 Sound Blaster 2.01 ID_SBPRO Sound Blaster Pro ID_SB16 Sound Blaster 16 ID_PAS Pro Audio Spectrum ID_PASPLUS Pro Audio Spectrum+ ID_PAS16 Pro Audio Spectrum 16 ID_WSS Windows Sound System ID_GUS Gravis UltraSound It will return NULL if the driver does not exists. Note that the sound system only knows the drivers that were already registered using dRegisterDriver. See Also: dRegisterDriver, dRegisterDrivers. dGetMusicStatus ----------------------------------------------------------------------------- Function: Returns the music player status. Prototype: int dGetMusicStatus(void) Parameters: None. Returns: PS_PLAYING - music is being played PS_STOPPED - music is stopped PS_PAUSED - music is paused Description: Returns the current state of the music player. See Also: dPlayMusic, dStopMusic, dPauseMusic, dResumeMusic. dGetMusicStruc ----------------------------------------------------------------------------- Function: Returns the internal music structure. Prototype: MHdr *dGetMusicStruc(void) Parameters: None. Returns: Music structure address. Description: Returns the address of an static structure used by the sound system to play the current music module. You can use this structure to synchronize your program with the music and/or sound effects. Important: If you are using the ID_NONE sound driver, the music player will be inactive and the music structure won't be updated. See Also: None. dGetVoicePos ----------------------------------------------------------------------------- Function: Return the voice's relative playing position. Prototype: long dGetVoicePos(int Voice) Parameters: Voice - voice number (0-31) Returns: Relative playing position. Description: This function returns the playing position of the sample that is being played on the specified voice. For soundcards that do not use onboard memory to store samples, you can use this routine to implement your own double-buffering sound player (it is useful if you want to play huge sample files). See Also: dPlayVoice, dStopVoice, dSetVoiceFreq, dSetVoiceVolume, dSetVoiceBalance, dGetVoiceStatus. dGetVoiceStatus ----------------------------------------------------------------------------- Function: Return the current status of a specified voice. Prototype: int dGetVoiceStatus(int Voice) Parameters: Voice - voice number (0-31) Returns: PS_PLAYING - sample is being played PS_STOPPED - sample is stopped Description: Return the status of the voice. Notice that voices playing looped samples will never stop. However, you can stop those voices using dStopVoice. See Also: dPlayVoice, dStopVoice, dSetVoiceFreq, dSetVoiceVolume, dSetVoiceBalance, dGetVoicePos. dImportModule ----------------------------------------------------------------------------- Function: Imports music module files. Prototype: DSM *dImportModule(char *Filename, int Form) Parameters: Filename - full path of the music module Form - music module format Returns: Music module structure address or NULL if error. Description: Used to import music modules. The following music module formats are supported: Constant Description ----------------------------------------------- FORM_DSM RIFF/DSMF module files FORM_MOD Protracker/FastTracker modules FORM_S3M Scream Tracker 3.0 modules FORM_MTM Multitracker 1.0 modules FORM_669 Composer 669 modules FORM_STM Scream Tracker 2.0 modules If something went wrong, the function returns NULL and the global variable dError is set with the error type. Is highly recommended to use dLoadModule and RIFF/DSMF module files in your programs. The M2DSM.EXE program used to convert other module formats will remove most of the problems that other formats may have. See Also: dLoadModule. dImportModuleFile ----------------------------------------------------------------------------- Function: Imports music module files. Prototype: DSM *dImportModuleFile(int Handle, long Length, int Form) Parameters: Handle - DOS file handle Length - module file length Form - module file format Returns: Music module structure address or NULL if error. Description: Used to import music modules. It is near equivalent to dImportModule but it uses a DOS file handle to load the module file. Useful when module files are stored into a single resource file. See Also: dLoadModule, dImportModule. dImportSample ----------------------------------------------------------------------------- Function: Imports sample files. Prototype: Sample *dImportSample(char *Filename, int Form) Parameters: Filename - full path of the sample file Form - sample file format Returns: Sample structure address or NULL if error. Description: Used to import sample files. The format parameter specifies the sample file format: Constant Description ------------------------------------------------- FORM_WAV Microsoft RIFF/WAVE sample files FORM_VOC Creative Labs VOICE sample files FORM_IFF Amiga IFF/8SVX sample files FORM_RAW 8-bit signed RAW sample files If something went wrong, the function returns NULL and the global variable dError is set with the error type. See Also: dLoadSample. dImportSampleFile ----------------------------------------------------------------------------- Function: Imports sample files. Prototype: Sample *dImportSampleFile(int Handle, long Length, int Form) Parameters: Handle - DOS file handle Length - sample file length Form - sample file format Returns: Sample structure address or NULL if error. Description: Used to import sample files. It is near equivalent to dImportSsample but it uses a DOS file handle to load the sample file. Useful when sample files are stored into a single resource file. See Also: dLoadSample, dImportSample. dInit ----------------------------------------------------------------------------- Function: Initializes the sound system. Prototype: int dInit(SoundCard *SC) Parameters: SC - soundcard structure Returns: Returns zero on success. Description: Initializes the sound system using the soundcard's hardware parameters specified in the structure. You must call dDone before exiting from your program to deinitialize the sound system. See Also: dDone, dRegisterDrivers. dInitTimer ----------------------------------------------------------------------------- Function: Initializes the timer services. Prototype: void dInitTimer(void) Parameters: None. Returns: None. Description: Initializes the timer interrupt services. You must call the dDoneTimer to deinitialize the timer services before leaving from your program. See Also: dDoneTimer. dLoadDriver ----------------------------------------------------------------------------- Function: Load a dynamic-link audio driver from disk. Prototype: Driver *dLoadDriver(SoundCard *SC) Parameters: SC - soundcard structure Returns: Audio driver address or NULL if error. Description: This routine is used to load dynamic-link audio drivers from disk. You must use dRegisterDriver to register the dynamic-link audio driver. You should not reference any of the static-link drivers in your programs, and you shouldn't use dRegisterDrivers to install the static-link audio drivers. Here is an example to initialize the sound system using dynamic-link audio drivers: dLoadSetup(&SC,"SETUP.CFG"); dRegisterDriver(dLoadDriver(&SC)); dInit(&SC); the above lines will initialize the sound system. You can use the MKDRV.BAT batch file to build the audio driver files (ie. SB.DRV, PAS.DRV, WSS.DRV, etc). See Also: dRegisterDriver, dRegisterDrivers. dLoadModule ----------------------------------------------------------------------------- Function: Load a RIFF/DSMF music module file. Prototype: DSM *dLoadModule(char *Filename) Parameters: Filename - full path of the music module Returns: Module structure address of NULL if error. Description: Used to load RIFF/DSMF modules. If an error occurs while loading the module, this function will return NULL and the global variable dError will be set to one of the following error values: Constant Description ---------------------------------------------- ERR_FORMAT Invalid file format ERR_NOFILE File does not exist ERR_FILEIO Error reading the module file ERR_NOMEM Not enough system memory ERR_NODRAM Not enough soundcard memory You can use the M2DSM.EXE program to convert other module formats to RIFF/DSMF music module files. Also, you can convert other modules formats from your programs, using the built-in import routines. If your program needs to use a lot of samples, you can pack all those samples into a big module file. You will need a tracker/composer to do it. See Also: dFreeModule, dImportModule, dLoadModuleFile. dLoadModuleFile ----------------------------------------------------------------------------- Function: Load a RIFF/DSMF music module file. Prototype: DSM *dLoadModuleFile(int Handle, dword Length) Parameters: Handle - DOS file handle Length - module file length Returns: Module structure address of NULL if error. Description: Used to load RIFF/DSMF modules. It is near equivalent to the dLoadModule routine. It is useful to load music modules from your own resource data files. See Also: dFreeModule, dImportModule, dLoadModule. dLoadSample ----------------------------------------------------------------------------- Function: Load RIFF/WAVE sample files. Prototype: Sample *dLoadSample(char *Filename) Parameters: Filename - full path of sample file Returns: Sample structure address or NULL if error. Description: This function load RIFF/WAVE sample files. You can use import routines to load other formatted sample files. If something went wrong, the function returns NULL and the global variable dError is set with the error type. See Also: dFreeSample, dImportSample, dLoadSampleFile. dLoadSampleFile ----------------------------------------------------------------------------- Function: Load RIFF/WAVE sample files. Prototype: Sample *dLoadSampleFile(int Handle, dword Length) Parameters: Handle - DOS file handle Length - sample file length Returns: Sample structure address or NULL if error. Description: Routine used to load RIFF/WAVE samples. It is similar to the dLoadSample routine. It is useful to load samples from your own resource data files. See Also: dFreeSample, dImportSample, dLoadSample. dMemAlloc ----------------------------------------------------------------------------- Function: Allocates and uploads samples to the soundcard memory. Prototype: long dMemAlloc(Sample *SampPtr) Parameters: SampPtr - sample structure address Returns: Sample address in the soundcard memory or NULL if error. Description: This routine allocates and upload samples to the soundcard memory (when applicable). You should not use this routine directly from your programs. See Also: dMemFree, dMemAvail. dMemAvail ----------------------------------------------------------------------------- Function: Returns the amount of free memory in the soundcard. Prototype: long dMemAvail(void) Parameters: None. Returns: Amount of free memory or zero if the soundcard does not have onboard memory. Description: Return the amount of free soundcard memory. You may use this routine to verify if the user has enough memory on his soundcard to upload your samples. See Also: dMemAlloc, dMemFree. dMemFree ----------------------------------------------------------------------------- Function: Releases memory allocated by dMemAlloc. Prototype: void dMemFree(Sample *SampPtr) Parameters: SampPtr - sample structure address Returns: None. Description: Used internally to release a block of memory allocated in the soundcard memory (when applicable). You should not use this routine directly from your programs. See Also: dMemAlloc, dMemAvail, dLoadSample, dFreeSample. dPauseMusic ----------------------------------------------------------------------------- Function: Pauses the current music module. Prototype: int dPauseMusic(void) Parameters: None. Returns: Return zero on success. Description: Pauses the current music module. You must call dResumeMusic to continue playing the current module. See Also: dStopMusic, dResumeMusic. dPlayMusic ----------------------------------------------------------------------------- Function: Start playing a music module. Prototype: int dPlayMusic(DSM *MusicPtr) Parameters: MusicPtr - module structure address Returns: Return zero on success. Description: This routine will start playing a music module. You must have enough active voices to play the music module. You can use the dPlayPatterns routine to play sequences or chunks of the music module. See Also: dStopMusic, dPauseMusic, dResumeMusic, dSetupVoices. dPlayPatterns ----------------------------------------------------------------------------- Function: Start playing a sequence of music patterns. Prototype: int dPlayPatterns(DSM *MusicPtr, int OrderPos, int OrderEnd) Parameters: MusicPtr - module structure address OrderPos - starting order position (0-127) OrderEnd - ending order position (0-127) Returns: Return zero on success. Description: This routine will start playing a sequence of patterns. You must specify the starting and ending positions of the order list to be played. The order list is an array of pattern numbers used to play the music patterns in a specified order or sequence. You can play chunks of the song using this routine. For example, you can use a single module to save multiple sequences of music and/or sound effects. See Also: dStopMusic, dPauseMusic, dResumeMusic, dSetupVoices. dPlayVoice ----------------------------------------------------------------------------- Function: Start playing a sample. Prototype: void dPlayVoice(int Voice, Sample *SampPtr) Parameters: Voice - voice number (0-31) SampPtr - sample structure Returns: None. Description: This routine is used to start playing a sample. You should only use sound effect channels to play samples. See Also: dStopVoice, dSetVoiceFreq, dSetVoiceVolume, dSetVoiceBalance, dGetVoicePos, dGetVoiceStatus. dPoll ----------------------------------------------------------------------------- Function: Updates the sound system output audio buffer. Prototype: void dPoll(void) Parameters: None. Returns: None. Description: This routine is used to update the output audio buffer and to poll your soundcard hardware. Must be called at least 50 times per second. You can use the timer interrupt services to call this routine periodically. If your program does not calls this routine enough times per second, the output audio will sound like a broken record. See Also: dInitTimer, dDoneTimer, dStartTimer, dStopTimer. dRegisterDriver ----------------------------------------------------------------------------- Function: Registers a lowlevel sound driver. Prototype: void dRegisterDriver(Driver *DriverPtr) Parameters: DriverPtr - lowlevel driver structure Returns: None. Description: This routine is used to register new lowlevel sound drivers into the sound system. You must register all the drivers you want to use for playback. The sound system only knows registered sound drivers. See Also: dRegisterDrivers, dGetDriverStruc, dInit. dRegisterDrivers ----------------------------------------------------------------------------- Function: Registers all the static-link sound drivers. Prototype: void dRegisterDrivers(void) Parameters: None. Returns: None. Description: This function will register all the static-link drivers. It uses the dRegisterDriver function to register every driver. If you want to use dynamic-link audio drivers, you should use dLoadDriver and dRegisterDriver to load and register the dynamic-link audio drivers. See Also: dRegisterDriver, dLoadDriver. dResumeMusic ----------------------------------------------------------------------------- Function: Resumes playing the current music module. Prototype: int dResumeMusic(void) Parameters: None. Returns: Return zero on success. Description: Resumes playing the current music module. See Also: dStopMusic, dPauseMusic. dSetMusicVolume ----------------------------------------------------------------------------- Function: Set the music global volume. Prototype: void dSetMusicVolume(int Volume) Parameters: Volume - master volume (0-255) Returns: None. Description: Used to change the global volume of the music. This routine does not changes the volume of the sound effect channels. See Also: dSetSoundVolume, dSetupVoices. dSetSoundVolume ----------------------------------------------------------------------------- Function: Set the sound effects global volume. Prototype: void dSetSoundVolume(int Volume) Parameters: Volume - sound effects volume (0-255) Returns: None. Description: Used to change the global volume of the sound effects. This routine does not changes the volume of the music. See Also: dSetMusicVolume, dSetupVoices. dSetTimerSpeed ----------------------------------------------------------------------------- Function: Changes the timer interrupt speed. Prototype: void dSetTimerSpeed(int Speed) Parameters: Speed - timer speed in ticks Returns: None. Description: This routine is used to change the speed of your timer interrupt service. The speed parameter is given in ticks. You can use the following formula to translate frequencies in hertz to ticks: Ticks = 1193182 / Hertz For example, if your timer service must be called 70 times per second: dSetTimerSpeed(1193182/70) Notice, that the old BIOS timer interrupt is always called at 18.2 hertz no matter the speed of your timer. If you call this function with a speed of zero, then your timer will be synchronized with the VGA vertical retrace. See Also: dStartTimer, dStopTimer. dSetVoiceBalance ----------------------------------------------------------------------------- Function: Changes the balance or pan position of a voice. Prototype: void dSetVoiceBalance(int Voice, int Balance) Parameters: Voice - voice number (0-31) Balance - balance (0-128) Returns: None. Description: Changes the balance of a specified voice. It only works for stereo soundcards. Also, you can choose to use stereo surround using the PAN_SURROUND value. You should only change the balance for sound effect channels. The following constants are defined to be used with this routine: Constant Value Description ---------------------------------------- PAN_LEFT 0x00 left balance PAN_RIGHT 0x80 right balance PAN_MIDDLE 0x40 middle balance PAN_SURROUND 0xA4 stereo surround You can interpolate these values to do smooth pannings. Notice that the stereo surround does not work for GUS soundcards. See Also: dPlayVoice, dStopVoice, dSetVoiceFreq, dSetVoiceVolume, dGetVoicePos, dGetVoiceStatus. dSetVoiceFreq ----------------------------------------------------------------------------- Function: Changes the playback frequency for a specified voice. Prototype: void dSetVoiceFreq(int Voice, int Freq) Parameters: Voice - voice number (0-31) Freq - frequency (in hertz) Returns: None. Description: Changes the playback frequency of a voice. You should only change the frequencies of sound effect channels. See Also: dPlayVoice, dStopVoice, dSetVoiceVolume, dSetVoiceBalance, dGetVoicePos, dGetVoiceStatus. dSetVoiceVolume ----------------------------------------------------------------------------- Function: Changes the volume for a specified voice. Prototype: void dSetVoiceVolume(int Voice, int Volume) Parameters: Voice - voice number (0-31) Volume - volume level (0-64) Returns: None. Description: Changes the volume for a specified voice. Notice that the volume level goes from 0 to 64. The real volume will be computed using the global volume level. You should only change the volume of sound effect channels. See Also: dPlayVoice, dStopVoice, dSetVoiceFreq, dSetVoiceBalance, dGetVoicePos, dGetVoiceStatus. dSetupVoices ----------------------------------------------------------------------------- Function: Setup the amount of active voices. Prototype: void dSetupVoices(int NumVoices, int MasterVolume) Parameters: NumVoices - number of active voices (1-32) MasterVolume - master volume (16-255) Returns: None. Description: The sound system supports 32 digital sound channels. This routine is used to set the number of active voices that your program need to play music and/or sound effects. You should always use the minimum amount of active voices possible to improve the sound quality and to reduce the amount of CPU time required by the sound system. The master volume (or amplification factor) is used in 8-bit output modes to boost the sound making it much more dynamic. The recommended value for this parameter is given by the following formula: MasterVolume = Min(255,768/NumVoices) The voices or channels are numbered from 0 to 31. When you start playing a music module the sound system uses the first N voices to play the music, where N is the number of tracks of the music module. If you want to play sounds and music simultanemously, you need to open more channels. You should not use the channels reserved for music to play your sounds. For example, if you are playing a 4-track music module and you need 2 channels for sound effects, you must have at least 6 active voices. The first voices 0-3 are used to play music, and voices 4-5 are used for sounds. Important: When you are going to change the amount of active voices, be sure to turn off the music and all the sound effect channels before calling this routine. See Also: dSetMusicVolume, dSetSoundVolume, dPlayMusic. dStartTimer ----------------------------------------------------------------------------- Function: Install a new timer service routine. Prototype: void dStartTimer(void (*Timer)(void), int Speed) Parameters: Timer - timer handler address Speed - timer speed in ticks Returns: None. Description: This routine will install your own handler to be called at a specified frequency. Usually you will need to use this routine to call dPoll enough times per second. See Also: dSetTimerSpeed, dStopTimer. dStopMusic ----------------------------------------------------------------------------- Function: Stop playing the current music module. Prototype: void dStopMusic(void) Parameters: None. Returns: None. Description: Stop playing the current music module. See Also: dPlayMusic, dPauseMusic, dResumeMusic. dStopTimer ----------------------------------------------------------------------------- Function: Deinstall the current timer handler. Prototype: void dStopTimer(void) Parameters: None. Returns: None. Description: This routine will deinstall the current timer handler. See Also: dStartTimer. dStopVoice ----------------------------------------------------------------------------- Function: Stop playing a sample. Prototype: void dStopVoice(int Voice) Parameters: Voice - voice number (0-31) Returns: None. Description: This routine is used to stop playing a sample. You should only stop samples that are being played on sound effect channels. See Also: dPlayVoice, dSetVoiceFreq, dSetVoiceVolume, dSetVoiceBalance, dGetVoicePos, dGetVoiceStatus. 2. Structures: Driver structure ----------------------------------------------------------------------------- Function: Lowlevel sound driver structure. Declaration: typedef struct { dword Magic; dword Next; byte ID; byte Modes; char Name[32]; word Port; byte IrqLine; byte DmaChannel; word MinRate; word MaxRate; word BufferLength; void *ProcTablePtr; void *DriverPtr; word *ParmTablePtr; } Driver; Description: This structure holds all the information related to any lowlevel sound driver. This structure is used to register sound drivers. Fields: ID - sound driver identifier Modes - sound driver capabilities Name - sound driver long name Port - default base I/O port address IrqLine - default IRQ interrupt line DmaChannel - default DMA output channel MinRate - minimum sample rate MaxRate - maximum sample rate ParmTablePtr - list of Port/IRQ/DMA parameters Here is the list of driver identifiers: Constant Description -------------------------------------- ID_NONE No Sound ID_SB Sound Blaster ID_SB201 Sound Blaster 2.01 ID_SBPRO Sound Blaster Pro ID_SB16 Sound Blaster 16 ID_PAS Pro Audio Spectrum ID_PASPLUS Pro Audio Spectrum+ ID_PAS16 Pro Audio Spectrum 16 ID_WSS Windows Sound System ID_GUS Gravis UltraSound The sound driver capabilities bit flags are: Constant Description --------------------------------------------------- AF_8BITS 8-bits per sample AF_16BITS 16-bits per sample AF_MONO mono output mode AF_STEREO stereo output mode AF_NODRAM samples stored in system memory AF_DRAM samples stored in soundcard memory See Also: dRegisterDriver, dGetDriverStruc. DSM structure ----------------------------------------------------------------------------- Function: Module information structure. Declaration: typedef struct { Song Header; Sample **Samples; Pattern **Patterns; } DSM; Description: This structure is used to hold all the information related to a music module file. It includes a header with global information about the module, the main music sequence, and a list of instruments and patterns structures. See Also: Song, Sample, Pattern structures. MHdr structure ----------------------------------------------------------------------------- Function: Internal music player structure. Declaration: typedef struct { dword MusicVolume; dword SoundVolume; MTrk Tracks[MAXVOICES]; byte NumTracks; byte NumVoices; byte OrderPos; byte OrderLen; byte ReStart; byte PattNum; byte PattRow; byte BreakFlag; byte Tempo; byte TempoCount; byte BPM; byte SyncMark; byte Status; byte DriverStatus; void *PattPtr; DSM *SongPtr; } MHdr; Description: The music player uses this structure while playing a music module file. It holds all the information required to keep track of the song while it's being played. Fields: MusicVolume - current music volume SoundVolume - current sound effects volume Tracks - array of track structures NumTracks - number of active tracks NumVoices - number of active voices OrderPos - current order positionm OrderLen - order list length ReStart - restart order position PattNum - current pattern number PattRow - current pattern row BreakFlag - break pattern flags Tempo - current tempo value TempoCount - tempo counter BPM - current BPM value SyncMark - last sync mark seen Status - music player status DriverStatus - sound driver status MTrk structure ----------------------------------------------------------------------------- Function: Internal playback music track information. Declaration: typedef struct { byte Note; byte Sample; byte Volume; byte Balance; word Effect; word Rate; byte VUMeter; byte Flags; byte Reserved[38]; } MTrk; Description: This structure is used by the music player to keep track of every track of the music. Fields: Note - note number (1=C-0,96=B-7) Sample - sample number Volume - volume level Balance - stereo balance Effect - protracker command Rate - middle-c frequency VUMeter - volume unit meter The balance is any value between PAN_LEFT and PAN_RIGHT, or the special value PAN_SURROUND for stereo surround. The Effect fields holds one of the following standard Protracker commands: Command Description ----------------------------------------------------- 0xy arpeggio 1xx portamento up 2xx portamento down 3xx tone portamento 4xy vibrato 5xx tone portamento and volume slide 6xx vibrato and volume slide 7xy tremolo 8xx set fine pan position 9xx sample offset Axy volume slide Bxx jump position Cxx set volume Dxx break pattern E0x set filter E1x fine portamento up E2x fine portamento down E3x glissando control E4x vibrato control E5x set finetune E6x pattern loop E7x tremolo control E8x set pan position E9x retrig note EAx fine volume up EBx fine volume down ECx note cut EDx note delay EEx pattern delay EFx invert loop Fxx set speed/tempo Some of the above commands are not suppported in the current version of the sound system. See Also; dGetMusicStruc, MHdr structure. Pattern structure ----------------------------------------------------------------------------- Function: Pattern sheet information. Declaration: typedef struct { word Length; byte Data[1]; } Pattern; Description: Used to store music patterns. See Also: DSM structure. RIFF structures ----------------------------------------------------------------------------- Function: RIFF file header and block structures. Declarations: typedef struct { dword ID; dword Length; dword Type; } RiffHeader; typedef struct { dword ID; dword Length; } RiffBlock; Description: These structures are used to parse RIFF files. The sound system module and sample file formats are RIFF-based. See Also: DSM, Song, Sample, Pattern structures. Sample structure ----------------------------------------------------------------------------- Function: Sample information structure. Declaration: typedef struct { char FileName[13]; word Flags; byte Volume; dword Length; dword LoopStart; dword LoopEnd; void *DataPtr; word Rate; word Voice; char SampleName[28]; } Sample; Description: This structure holds all the information related to a sample or instrument. All the samples and/or instruments are loaded in memory using this structure. Fields: FileName - DOS file name Flags - sample bit flags Volume - default volume Length - sample length LoopStart - loop start point LoopEnd - loop end point DataPtr - data address Rate - middle-C frequency SampleName - sample name The flags are used only when the module is loaded in memory. These are the bit flags you can use: Constant Description ---------------------------------------- SF_8BITS 8-bits per sample SF_16BITS 16-bits per sample SF_UNSIGNED unsigned samples SF_SIGNED signed samples SF_LOOPED forward looping enabled SF_DELTA delta packed samples Notice that 16-bit samples are not supported in the current version of the sound system. See Also: dLoadSample, dImportSample, DSM structure. Song structure ----------------------------------------------------------------------------- Function: Song information structure. Declaration: typedef struct { char ModuleName[28]; word FileVersion; word Flags; word OrderPos; word ReStart; word NumOrders; word NumSamples; word NumPatterns; word NumTracks; byte GlobalVolume; byte MasterVolume; byte InitTempo; byte InitBPM; byte ChanMap[MAXTRACKS]; byte Orders[MAXORDERS]; } Song; Description: This structure is used to hold information about the module file (number of samples, patterns, sequence list, etc). Fields: ModuleName - song or module name OrderPos - starting order position ReStart - restart order position NumOrders - number of orders NumSamples - number of samples NumPatterns - number of patterns NumTracks - number of tracks GlobalVolume - default global volume MasterVolume - default master volume InitTempo - initial tempo value InitBPM - initial BPM value ChanMap - tracks default balances Orders - order list This structure is used within a DSM module structure. See Also: DSM, Sample, Pattern structures. SoundCard structure ----------------------------------------------------------------------------- Function: Soundcard configuration structure. Declaration: typedef struct { byte ID; byte Modes; word Port; byte IrqLine; byte DmaChannel; word SampleRate; char DriverName[16]; } SoundCard; Description: This structure holds the current soundcard's configuration, it's used to initialize the sound system. Fields: ID - soundcard identifier Modes - output mode bit flags Port - base I/O port address IrqLine - IRQ interrupt line DmaChannel - DMA output channel SampleRate - sample rate See Also: dInit.