BWSB v1.02 Reference Guide Quick Reference ------------------------------------------------------------- AmigaHertz - Set the Amiga Clock speed (for period calculations) ChannelPan - Get or set a channel's pan position ChannelVol - Get or set a channel's volume setting ChannelVU - Get or set a channel's VU value FreeMSE - Remove MSE from memory GetChannelTable - Get information on a channel GetMainScope - Get the currently played sample for a scope GetSampleTable - Get information on a sample LoadGDM - Load a GDM module from disk LoadMSE - Load MSE file from disk MixForground - Mix sound in the foreground MixStatus - Get mix request flag MusicBPM - Get or set the BPM speed MusicLoop - Get times music has looped or set music loop enable flag MusicStatus - Find out if music processing is currently enabled MusicOrder - Get or set the music playing order number MusicPattern - Get or set the music playing pattern number MusicRow - Get the music playing row MusicTempo - Get or set the music Tempo MusicVolume - Get or set the global music volume PlaySample - Play a sound effect already loaded into MSE memory SetAutoMix - Select foreground mixing or background mixing StartMusic - Enable music processing StartOutput - Turn on sound mixing StopMusic - Disable music processing StopOutput - Turn off sound mixing UnloadModule - Free the loaded module from memory AmigaHertz ------------------------------------------------------------------- Purpose: Set the Amiga clock speed for music period calculations Syntax: AmigaHertz NewSpeed& Procedure AmigaHertz(NewSpeed : Longint); Remarks: none Calling: NewSpeed - New Amiga clock speed for period calculations. Some common values are: 3579545.25 (Amiga NTSC Machines, Default) 3546895 (Amiga PAL Machines) 3579264 (Scream Tracker) Returns: none See Also: none Source: QBX_MSE.ASM, TPX_MSE.ASM Example: none ChannelPan ------------------------------------------------------------------- Purpose: Get or set the specified channel's panning position Syntax: x% = ChannelPan%(Channel%, NewPos%) Function ChannelPan(Channel, NewPos : Byte) : Byte; Remarks: Setting all the channels to one side or the other may result in cracks and clicks in the output (except on the GUS). Try to keep the number of locations more or less balanced on left and right sides. Note also that positions between Left, Middle, and Right require additional CPU time (except on the GUS). Calling: Channel - Channel number to get or set pan on. (1..32) NewPos - New pan position. 0 is full left, 15 is full (FFh, 0..15) right, 8 is middle. Positions in between are varying degrees of Left and Right together. FFh does not affect pan position. Returns: ChannelPan - Current pan position in use. (0..15) See Also: ChannelVol Source: QBX_MSE.ASM, TPX_MSE.ASM Example: none ChannelVol ------------------------------------------------------------------- Purpose: Get or set the channel's volume setting Syntax: CurVol% = ChannelVol%(Channel%, NewVol%) Remarks: none Calling: Channel% - Channel number to get or set volume on. (1..32) NewVol% - New volume to play at. FFh does not change (FFh, 0..64) current volume. Returns: CurVol% - Current volume setting in use. (0..64) See Also: ChannelVU, ChannelPan Source: QBX_MSE.ASM, TPX_MSE.ASM Example: none ChannelVU -------------------------------------------------------------------- Purpose: Get or set the channel's VU meter setting Syntax: x% = ChannelVU%(Channel%, NewVU%) Function ChannelVU(Chan, NewVU : Byte) : Byte; Remarks: The VU values do not fall by themselves. They get set to the channel's output volume when the volume has been changed or a not has been struck. To make moving VU meters, you will have to set the VU value to a lower number each time you read it. Calling: Channel - Channel to work with. (1..32) NewVU - New VU value to use, FFh does not change value. (0..32) Returns: ChannelVU - Current VU value. (0..32) See Also: ChannelVol, ChannelVU Source: QBX_MSE.ASM, TPX_MSE.ASM Example: SETUP.BAS FreeMSE ---------------------------------------------------------------------- Purpose: Deallocate MSE memory and unload MSE file Syntax: FreeMSE Procedure FreeMSE; Remarks: This function is called to unload the current MSE so that you could either exit your program or possibly load a different MSE file (using LoadMSE%). It will disable sound output if needed, deallocate all MSE memory (including music and sound effects), and unload the MSE. After this is called, do *not* use any of the other MSE functions (except LoadMSE) because this will result in a system crash or reboot. Calling: none Returns: none See Also: LoadMSE Source: QBX_MSE.ASM, MSE_TP.PAS Example: MMP.BAS, SETUP.BAS, GDMPLAY.PAS, GDMSCOPE.PAS GetChannelTable -------------------------------------------------------------- Purpose: Get extended information on a digital sound or music channel Syntax: GetChannelTable Channel%, VARSEG(ChanTab), VARPTR(ChanTab) Procedure GetChannelTable(Channel : Byte; TSeg, TOff : Word); Remarks: This routine is more of a hack job than anything, in the future it will most likely be replaced by some more eloquent functions. Calling: Channel - Digital channel to get information on. (1..32) [QB/PDS] ChanTab - This is a user defined variable with the structure ChannelType defined in CHANTYPE.BI. More details on it can be found there. [TP] TSeg - Segment of 128 byte buffer to hold the channel information. Format of this is declared in CHANTYPE.BI. [TP] TOff - Offset of 128 byte buffer to hold channel information. Returns: ChanTab - Now filled with information on the desired channel. See Also: GetSampleTable Source: QBX_MSE.ASM, TPX_MSE.ASM Example: none GetMainScope ----------------------------------------------------------------- Purpose: Get currently played sample from the mixing buffer Syntax: GetMainScope Left%, Right% Procedure GetMainScope(Var Left, Right : Word); Remarks: Values from this are useful in creating a digital output scope (showing the sound's waveform). If the current sound device has one 8 bits output, the sample will be multiplied by 256 so that it fits in a 16 bit number. Calling: none Returns: Left - Currently played sample on left speaker. (0..FFFFh) Right - Currently played sample on right speaker. (0..FFFFh) See Also: none Source: QBX_MSE.ASM, TPX_MSE.ASM Example: GDMSCOPE.PAS GetSampleTable --------------------------------------------------------------- Purpose: Get extended information on a digital sample Syntax: GetSampleTable Channel%, VARSEG(SamTable), VARPTR(SamTable) Procedure GetSampleTable(Sample : Byte; TSeg, TOff : Word); Remarks: This routine is more of a hack job than anything, in the future it will most likely be replaced by some more eloquent functions. Calling: Sample - Digital sample number to get information on. (0..255) [QB/PDS] SamTable - This is a user defined variable with the structure ChannelType defined in GDMTYPE.BI. More details on it can be found there. [TP] TSeg - Segment of 64 byte buffer to hold the sample information. Format is declared in GDMTYPE.BI. [TP] TOff - Offset of 64 byte buffer to hold the sample information. Returns: SamTable - Now filled with information on the desired channel. See Also: GetChannelTable Source: QBX_MSE.ASM, TPX_MSE.ASM Example: none LoadGDM ---------------------------------------------------------------------- Purpose: Load a GDM module from disk into MSE memory Syntax: LoadGDM FILEATTR(Hnd%, 2),FOff&,Flg%,VARSEG(GDMHead),VARPTR(GDMHead) Function LoadGDM(Hnd : Word; FOff : Longint; Var Flg : Word; Var GDMHead) : Word; Remarks: GDMHead is a user defined variable of type GDMHeaderType, which is defined in the file GDMTYPE.BI. Before you can play music or any sound effects, you must load a module from disk. Use this routine to load GDMs (converted from another format with the 2GDM utility). Calling: Hnd - File handle number of a previously opened file (the GDM to load) in BINARY mode. In Turbo Pascal you must use the OpenFile and CloseFile routines defined in MSE_TP.PAS because TP uses FCBs instead of file handles like BWSB does. FOff - Offset into the file to start loading the module from (for playing modules within EXEs, etc). Flg - Loading flags. Currently only bit 0 is used. Bit: Purpose: 0 Load module into EMS [NO EFFECT ON GUS] 0-Load into base memory only 1-Load into EMS memory (must be present) Returns: GDMHead - Now filled with information from the module. Use this to find things like the module's title, etc. Flg - Module load error code: 0 - No errors, module loaded successfully. 1 - Module is corrupt 2 - Could not autodetect module type (N/A) 3 - Bad file format ID string 4 - Insufficient memory to load module 5 - Can not unpack samples 6 - AdLib instruments not supported If you get back any error code other than 0, do *not* enable music processing. If you do, you'll probably end up crashing the system. See Also: UnloadModule Source: QBX_MSE.ASM, TPX_MSE.ASM, MSE_TP.PAS, GDMTYPE.BI, FUNCODE.INC Example: MMP.BAS, SETUP.BAS, GDMSCOPE.PAS, GDMPLAY.PAS LoadMSE ---------------------------------------------------------------------- Purpose: Load and initialize the specified MSE file Syntax: x% = LoadMSE%(MSE$, OverRate%, BufferSize%, Addr%, IRQ%, DMA%) Function LoadMSE(MSE : String; OverRate, BufferSize : Word; Var Addr : Word; Var IRQ, DMA : Byte) : Word; Remarks: LoadMSE *must* be called before any of the other routines are used. Calling other routine MSE routines before using this one will result in a system crash or reboot. After LoadMSE is called, you can do any other MSE function calls that you want, however, sound output is not enabled until you call StartOutput. The reason for this is that having sound output enabled uses additional CPU time at all times to keep the output stream moving (except on GUS cards). By keeping these two functions separate, you can allow MSE calls and still use the full CPU power while doing such things as loading music files, etc, which do not need sound output to be enabled. Calling: MSE - File name and path of the MSE file you wish to use. OverRate - xxKHz oversampling rate you wish to use. Higher (4..48) oversampling rates provide higher sound fidelity, but uses up more CPU time to do so. This value is ignored on the GUS. BufferSize - This is the size of the mixing buffer you want to (256..32767) use for the MSE. Larger buffers take more memory and stops foreground execution for longer amounts of time, but causes less clicks and reverberation. Smaller buffers take less memory, but tend to use more CPU time overall and has a greater tendency to reverberate during CPU intensive things such as disk access, etc. Experiment and see what works best for your specific application. This value is ignored on the GUS. Addr - Base I/O address of the sound card in use. Use the value FFFFh for autodetection. IRQ - IRQ level of the sound card in use. Use value FFh for autodetection. DMA - DMA channel of sound card in use. Use value FFh for autodetection. Returns: MSE - Full 20 character name of the sound device. Addr - Actual base I/O address used (useful when using autodetection) IRQ - Actual IRQ level used. DMA - Actual DMA channel used. ErrCd - MSE installation error code: 0 - No error, MSE installation successful 1 - Base I/O address autodetection failure 2 - IRQ level autodetection failure 3 - DMA channel autodetection failure 4 - DMA channel not supported 5 - n/a 6 - Sound device does not respond 7 - Memory control blocks destroyed 8 - Insufficient memory for mixing buffers 9 - Insufficient memory for MSE file 10- MSE has invalid identification string 11- MSE disk read failure 12- MVSOUND.SYS not loaded See Also: FreeMSE Source: QBX_MSE.ASM, LOADMSE.BAS, MSE_TP.PAS, TPX_MSE.ASM Example: MMP.BAS, SETUP.BAS, GDMPLAY.PAS, GDMSCOPE.PAS MixForground ----------------------------------------------------------------- Purpose: Mix a new sound buffer when MixStatus <> 0 Syntax: MixForground Procedure MixForground; Remarks: This function should only be used when you have selected foreground mixing using the SetAutoMix routine. When the MixStatus function turns nonzero, you should call this routine ASAP so that sound output will remain smooth and unreverberated. This has no effect on the GUS. Calling: none Returns: none See Also: SetAutoMix, MixStatus Source: QBX_MSE.ASM, TPX_MSE.ASM Example: none MixStatus -------------------------------------------------------------------- Purpose: Get the current mixing demand flag Syntax: x% = MixStatus% Function MixStatus : Word; Remarks: This function is used in conjunction with the MixForground routine to do all sound mixing in the foreground instead of the background automatically. Before you can use this, you must disable background mixing using the SetAutoMix routine. This has no effect on the GUS. Calling: none Returns: MixStatus - Mix demand flag: 0 - No mixing currently needed 1 - Mixing needed, call MixForground See Also: SetAutoMix, MixForground Source: QBX_MSE.ASM, TPX_MSE.ASM Example: none MusicBPM --------------------------------------------------------------------- Purpose: Get or set the current music BPM (beats per minute) speed Syntax: x% = MusicBPM%(NewBPM%) Function MusicBPM(NewBPM : Byte) : Byte; Remarks: The default BPM speed for a MOD is 125. Calling: NewBPM - New BPM speed to use. Value of 0 does not change (0, 32..255) the current BPM. Returns: MusicBPM - The current BPM speed in use. (32..255) See Also: MusicTempo Source: QBX_MSE.ASM, TPX_MSE.ASM Example: PLAY.BAS MusicLoop -------------------------------------------------------------------- Purpose: Get times music has looped/Enable or disable music looping Syntax: x% = MusicLoop%(LoopEnable%) Function MusicLoop(LoopEnable : Byte) : Byte; Remarks: none Calling: LoopEnable - Enable/disable music looping: 0 - Music looping enabled. When last order number is finished, music will loop back to order zero. (DEFAULT) 1 - Music looping disabled. When last order is playing, music processing will be disabled. Use StartMusic to reenable. FFh- Don't set the loop enable/disable flag. Returns: MusicLoop - Number of times the music has looped so far. (0..255) See Also: StartMusic, MusicStatus, StopMusic Source: QBX_MSE.ASM, TPX_MSE.ASM Example: PLAY.BAS MusicStatus ------------------------------------------------------------------ Purpose: Get the current music enable status Syntax: x% = MusicStatus% Function MusicStatus : Word; Remarks: none Calling: none Returns: MusicStatus - Current music enabled flag: 0 - Music is disabled (StopMusic) 1 - Music is enabled (StartMusic was called earlier) See Also: StartMusic, StopMusic Source: QBX_MSE.ASM, TPX_MSE.ASM Example: PLAY.BAS MusicOrder ------------------------------------------------------------------- Purpose: Get or set the current playing order position Syntax: x% = MusicOrder%(NewOrder%) Function MusicOrder(NewOrder : Byte) : Byte; Remarks: This the routine you'll probably be wanting to use to move around in modules rather than MusicPattern. Calling: NewOrder - New order position to start playing from. FFh does (0..FFh) not change the order position. Trying to play an order number that does not exist will play pattern number 0. Returns: MusicOrder - Order position actually in use. See Also: MusicPattern, MusicRow Source: QBX_MSE.ASM, TPX_MSE.ASM Example: MMP.BAS, PLAY.BAS, GDMPLAY.PAS MusicPattern ----------------------------------------------------------------- Purpose: Get or set the current playing pattern number Syntax: x% = MusicPattern%(NewPattern%) Function MusicPattern(NewPattern : Byte) : Byte; Remarks: You will usually not use this function to set the pattern position, use MusicOrder instead. Calling: NewPattern - New pattern number to play. FFh does not (0..FFh) change pattern number (you will want that in most cases). Selecting a pattern that does not exist will most likely crash the system. Returns: MusicPattern- Current playing pattern number. See Also: MusicRow, MusicOrder Source: QBX_MSE.ASM, TPX_MSE.ASM Example: MMP.BAS, GDMPLAY.PAS MusicRow --------------------------------------------------------------------- Purpose: Get the current playing row number Syntax: x% = MusicRow% Function MusicRow : Byte; Remarks: There is currently no way to set the current playing row. Calling: none Returns: MusicRow - Current playing row number. See Also: MusicPattern, MusicOrder Source: QBX_MSE.ASM, TPX_MSE.ASM Example: MMP.BAS, PLAY.BAS, GDMPLAY.PAS MusicTempo ------------------------------------------------------------------- Purpose: Get or set the current music tempo Syntax: x% = MusicTempo%(NewTempo%) Function MusicTempo(NewTempo : Byte) : Byte; Remarks: The default tempo for a MOD is 6. Calling: NewTempo - New tempo value to use. Value of FFh does not (FFh, 0..254) change the current tempo. Returns: MusicTempo - Tempo setting actually in use. See Also: MusicBPM Source: QBX_MSE.ASM, TPX_MSE.ASM Example: PLAY.BAS MusicVolume ------------------------------------------------------------------ Purpose: Get or set the global music volume Syntax: x% = MusicVolume%(Vol%) Function MusicVolume(Vol : Byte) : Byte; Remarks: The global music volume is by default set to 64 by any of the module loading routines, except for GDMs and S3Ms, which are set to the default specified in the module. Calling: Vol - New global music volume to use. FFh does (FFh, 0..64) not change the global music volume. Returns: MusicVolume - The current global music volume. (0..64) See Also: none Source: QBX_MSE.ASM, TPX_MSE.ASM Example: PLAY.BAS PlaySample ------------------------------------------------------------------- Purpose: Play a sound effect already loaded into MSE memory Syntax: PlaySample Channel%, Sample%, Rate&, Vol%, Pan% Procedure PlaySample(Channel, Sample : Byte; Rate : Word; Vol, Pan : Byte); Remarks: This is for playing sound effects in your programs. It is a rather tedious routine to master, so consult the tutorial (BWSB.DOC) for more help. Calling: Channel - Sound channel to play the sound effect on. If you (1..32) play on a channel that is used by the music, you'll make the music sound like it is missing notes. Sample - This is the sample number in the loaded module to (0..255) play as your sound effect. Rate - The sampling rate to play the sample at (in Hertz). (4000..44000) Vol - Volume level to play the sample at. Normally you'll (0..64) use 64, unless you're doing a special effect like echoes, etc. Pan - Pan position between left and right speakers to (0..15, FFh) play sample at. Note that values other than 0, 8, and 15 require additional CPU time (except on GUS). 0 - Left Most 8 - Middle 15 - Right Most FFh - Use Old Position Returns: none See Also: none Source: QBX_MSE.ASM, TPX_MSE.ASM Example: none SetAutoMix ------------------------------------------------------------------- Purpose: Select automatic background mixing or manual foreground mixing Syntax SetAutoMix MixFlag% Procedure SetAutoMix(MixFlag : Byte); Remarks: In some cases it is more desirable to having mixing done in the foreground where it can be interrupted rather than in the background where it takes over the PC for the whole duration required to mix the next buffer (like under Windows, for example). In these cases, set the mixing to foreground and then keep a check on the mixing status (MixStatus) and do mixing (MixForground) whenever necessary. This has no effect on the GUS. Calling: MixFlag - 0 - Do mixing automatically in the background. 1 - Do mixing manually in the foreground. Returns: none See Also: MixForground, MixStatus Source: QBX_MSE.ASM, TPX_MSE.ASM Example: none StartMusic ------------------------------------------------------------------- Purpose: Enable music processing Syntax: StartMusic Procedure StartMusic; Remarks: When a module is loaded and sound output is enabled, so can start the module playback using this function. Until music is enabled, no music will be played. If you do not have a module loaded (or have a corrupted module loaded), enabling music playback will most likely crash the system because no safety checks are done on the music data. Calling: none Returns: none See Also: StopMusic, MusicStatus Source: QBX_MSE.ASM, TPX_MSE.ASM Example: MMP.BAS, PLAY.BAS, SETUP.BAS, GDMPLAY.PAS, GDMSCOPE.PAS StartOutput ------------------------------------------------------------------ Purpose: Initialize and enable the sound output routines Syntax: x& = StartOutput&(Channels%, Amplify%) Function StartOutput(Channels, Amplify : ShortInt) : Word; Remarks: No sound will be playable until sound output is enabled with this routine. When sound output is enabled, a small amount of CPU time is used to keep the output stream flowing, so try to keep sound output enabled *only* when you need to have sound/music playing. If sound output is already enabled, this routine has no effect. Calling: Channels - Total number of output channels to enable. More (1..32) output channels require more CPU time and diminish overall sound quality, so use as few as possible. Amplify - Amplification level. Too high a value will cause (0..9) clicks and cracks in the output. Under normal use, use amplification 0. If you know that an value great than that won't cause clicks, by all means use it because that will increase sound fidelity. This value is ignored on the GUS. Returns: StartOutput - Actual oversampling rate (in Hz) used. See Also: StopOutput Source: QBX_MSE.ASM, TPX_MSE.ASM Example: MMP.BAS, PLAY.BAS, SETUP.BAS, GDMPLAY.PAS, GDMSCOPE.PAS StopMusic -------------------------------------------------------------------- Purpose: Disable music processing Syntax: StopMusic Procedure StopMusic; Remarks: Stopping the music also saves a tiny amount of CPU time. This routine does *not* turn off all music channels so after this call there will possibly be some samples still playing if any looped samples were being played. Note, you *must* disable music processing before unloading the current module (UnloadModule). Not doing so will probably end up in a system crash at some point later on when music data is overwritten. Calling: none Returns: none See Also: StartMusic, MusicStatus Source: QBX_MSE.ASM, TPX_MSE.ASM Example: MMP.BAS, PLAY.BAS StopOutput ------------------------------------------------------------------- Purpose: Turns off all sound output processing Syntax: StopOutput Procedure StopOutput; Remarks: Once this is called, no more sound can be played until StartOutput is called again. It is generally used to shut off all output while more data is transferred to or from the disk since disk transferring is generally quite a bit slower when sound output is running. If sound output is already off, this routine has no effect. Calling: none Returns: none See Also: StartOutput Source: QBX_MSE.ASM, TPX_MSE.ASM Example: MMP.BAS, PLAY.BAS, SETUP.BAS, GDMPLAY.PAS, GDMSCOPE.PAS UnloadModule ----------------------------------------------------------------- Purpose: Free all memory used by the current music file Syntax: UnloadModule Procedure UnloadModule; Remarks: This routine must be called before loading a new music file. Once it is called, do not enable music processing, for the music data may get overwritten after this call. In that case, the invalid music data would probably cause a system crash. Calling: none Returns: none See Also: LoadGDM Source: QBX_MSE.ASM, TPX_MSE.ASM Example: MMP.BAS, PLAY.BAS, GDMPLAY.PAS, GDMSCOPE.PAS