DirectSound Module Version 1.21
Thanks for downloading this module. Before you begin using it please read through this document to understand all of the modules features.
Introduction
DirectX is Microsofts answer to the MS-DOS game market. With its powerful features Microsoft has married the best of both worlds. The pure performance of DOS and the hardware independence of Windows. With DirectSound you can incorporate a very powerful digital sound system into any application. With its mixing on the fly and integrated 3D sound features, playing multiple sounds in a 3D environment is easy and fast.
Until recently Visual Basic users could not incorporate any of the features of DirectX into their applications. Thanks to Patrice Scribe and his DirectX Type Libraries. It is now possible to incorporate the vast majority of DirectX functions into Visual Basic.
It is highly recommended that you read the DirectSound section of the DirectX SDK, especially for a description of the many concepts used in 3D sound.
System Requirements
Update History
Version 1.21 (12/09/98)
Version 1.2 (02/09/98)
Version 1.1 (30/08/98)
Getting Started
Before you start using this module in you application you must do the following:
Quick Start Guide
Once you have followed all the instruction in the Getting Started section, you can use the module in you application.
First before using any methods you MUST call the Init_InitializeDirectSound function. You must do this before any other function will work.
SPECIAL NOTE: | If the Init_InitializeDirectSound function fails all other functions will NOT cause an error message to appear. This module has been designed to prevent any errors from occurring in case of initialization failure. You do not have to do anything special in your application to handle a failure. The functions will simply exit in case of initialization failure. |
Once DirectSound is initialized you can call the General_LoadStaticSound or General_LoadStreamSound functions to create a new sound buffer. Make sure you always save the return value in a variable, NEVER assume you will get a specific sound buffer number from these functions.
Once the sound buffer is loaded, you can use the General_PlaySound, General_PauseSound and General_StopSound functions to control the sound buffer.
When you are finished using the sound buffer you can use the General_DeleteSound function to delete the sound buffer and free up the resources used by it.
OR
You can call Init_UninitializeDirectSound to clear the sound buffer and uninitialize DirectSound. Should you use Init_UninitializeDirectSound to uninitialize DirectSound, you will have to use Init_InitializeDirectSound again if you want to play another sound. When calling Init_UninitializeDirectSound you DO NOT have to delete all the sound buffers first, this will be done for you.
This is all that needs to be done to use the most basic functions of DirectSound. More elaborate features are also available.
Sample Program
The sample program was written to show the vast majority of the functions found in this module. You can see it's code for examples of how to use each function.
There are a few things the sample does not do.
First of all the filename you type into the text box in the top left must be a valid wav file. This sample does not check to see if you entered a correct filename.
Second you can only load one file at a time. Never click the Load button twice as this will load a second buffer and you will lose access to the first buffer.
Module Reference
Module Function Groups
This module has been divided into eight function groups. Each group of functions starts with a specific prefix:
Init | These functions are used to initialize and uninitialize DirectSound. |
DSound | These functions control DirectSound. |
Primary | These functions control the Primary Sound Buffer. |
General | These functions control basic sound buffer management. |
Listener | These functions control the listener in a 3D environment. |
Buffer2D | These functions control functions for a specific 2D sound buffer (as well as 2D functions for a specific 3D sound buffer). |
Buffer3D | These functions control functions for a specific 3D sound buffer. |
Private | These functions are used by the module internally and should not be used. |
These are two functions are used to initialize and uninitialize the DirectSound.
Init_InitializeDirectSound
Init_UninitializeDirectSound
Use first to initialize DirectSound. This must be called before any other functions.
Syntax:
Init_InitializeDirectSound(ThisForm as Form)As Boolean
ThisForm | This argument specifies a reference to a form. This form will be used as the keeper of the module. You must uninitialize DirectSound BEFORE unloading this form. |
Returns:
True | This value is returned if the function successfully initialized DirectSound and created the Primary Sound Buffer. |
False | This value is returned if the function was unable to initialize DirectSound or was unable to create a Primary Sound Buffer. This most likely means that the digital sound device is being used by another program. |
Remarks:
The form you pass MUST be loaded until you call Init_UninitializeDirectSound.
The simplest way to use this function is to call it in the Form Load event.
Example:
Dim Init As Boolean
Init = Init_InitializeDirectSound(Me)
Use to uninitialize DirectSound. This must always be called before the program shuts down.
Syntax:
Init_UninitializeDirectSound As Boolean
Returns:
True | This value is returned if the function successfully uninitialized DirectSound and destroyed the Primary Sound Buffer. |
False | This value is returned if the function was unable to uninitialize DirectSound or was unable to destroy the Primary Sound Buffer. |
Remarks:
This function MUST always be called before shutting down the program. The simplest way to do this is to call this function in the Form Unload event.
Failure to call this function will result in the program crashing.
If you have sound buffers loaded, you do not have to delete them first before calling this function. This function will delete any sound buffers that are still active.
Example:
Dim UnInit As Boolean
UnInit = Init_UninitializeDirectSound
These four functions are used to manage DirectSound.
Memory management | DSound_Compact |
Device capabilities | DSound_GetCaps |
Speaker configuration | DSound_GetSpeakerConfig DSound_SetSpeakerConfig |
Use this function to compact all on-board sound memory.
Syntax:
DSound_Compact()
Remarks:
This function moves the unused portions of on-board sound memory, if any, to a contiguous block so that the largest portion of free memory will be available. You shouldn't need to do this at all, since only static sound buffers are loaded into on-board sound memory and the General_LoadStaticSound method does this automatically.
The function will have no effect if any operations are in progress.
Example:
DSound_Compact
Use this function to get statistics about DirectSound.
Syntax:
DSound_GetCaps() As DSCAPS
Returns:
This function returns a DSCAPS structure with statistics about DirectSound.
Remarks:
This function ONLY works when you have at least one sound buffer loaded.
Information retrieved in the DSCAPS structure describes the maximum capabilities of the sound device and those currently available, such as the number of hardware mixing channels and the amount of on-board sound memory.
Because of resource-sharing requirements, the maximum capabilities in one area might be available only at the cost of another area. For example, the maximum number of hardware-mixed streaming sound buffers might be available only if there are no hardware static sound buffers.
Example:
Dim Params As DSCAPS
Params = DSound_GetCaps
Use this function to get the type of speaker system set for DirectSound.
Syntax:
DSound_GetSpeakerConfig() As Long
Returns:
The value returned by this function can be one of these.
DSSPEAKER_HEADPHONE = 1 | The audio is played through headphones. |
DSSPEAKER_MONO = 2 | The audio is played through a single speaker. |
DSSPEAKER_QUAD = 3 | The audio is played through quadraphonic speakers. |
DSSPEAKER_STEREO = 4 | The audio is played through stereo speakers (default value). |
DSSPEAKER_SURROUND = 5 | The audio is played through surround speakers. |
Remarks:
The value of this function only affects 3D sounds.
Example:
Dim SpeakerType As Long
SpeakerType = DSound_GetSpeakerConfig
Use this function to set the type of speaker configuration used to enhance 3D sounds.
Syntax:
DSound_SetSpeakerConfig(Speaker As Long)
Speaker | The Speaker argument can be one of the following.
|
Remarks:
The value of this function only affects 3D sounds.
Example:
Dim SpeakerType As Long
SpeakerType = DSSPEAKER_STEREO
DSound_SetSpeakerConfig(SpeakerType)
These three functions are used to control the Primary Sound Buffer.
Sound management | Primary_GetVolume Primary_SetVolume |
Information | Primary_SetFormat |
Use this function to get the volume of the Primary Sound Buffer.
Syntax:
Primary_GetVolume As Long
Returns:
This function returns the volume of the Primary Sound Buffer.
Remarks:
The volume is specified in hundredths of decibels (dB). Allowable values are between DSBVOLUME_MAX (no attenuation) and DSBVOLUME_MIN (silence). These values are currently defined as 0 and -10,000 respectively. The value DSBVOLUME_MAX represents the original, unadjusted volume of the stream. The value DSBVOLUME_MIN indicates an audio volume attenuated by 100 dB, which, for all practical purposes, is silence. Currently DirectSound does not support amplification.
Example:
Dim MainVolume As Long
MainVolume= Primary_GetVolume
Use this function to set the volume of the Primary Sound Buffer.
Syntax:
Primary_SetVolume(Volume As Long)
Volume | This argument specifies the volume to set for the Primary Sound Buffer. This volume affects the sound level of all sound buffers in the application. |
Remarks:
The volume is specified in hundredths of decibels (dB). Allowable values are between DSBVOLUME_MAX (no attenuation) and DSBVOLUME_MIN (silence). These values are currently defined as 0 and -10,000 respectively. The value DSBVOLUME_MAX represents the original, unadjusted volume of the stream. The value DSBVOLUME_MIN indicates an audio volume attenuated by 100 dB, which, for all practical purposes, is silence. Currently DirectSound does not support amplification.
Example:
Dim MainVolume As Long
MainVolume = DSBVOLUME_MAX
Primary_SetVolume(MainVolume)
Use this function to set the output format of the Primary Sound Buffer.
Syntax:
Primary_SetFormat(Frequency As Long, Bits As Byte, Channels As Byte)
Frequency | This argument specifies the frequency to use for the Primary Sound Buffer. The valid values are 44100, 22050 and 11025. |
Bits | This argument specifies the number of bits to use for the Primary Sound Buffer. The valid values are 1 for 8 bit and 2 for 16 bit. |
Channels | This argument specifies the number of channels to use for the Primary Sound Buffer. The valid values are 1 for Mono and 2 for Stereo. |
Remarks:
Although you can specify any values for the format these are the most common values supported by today's hardware. Therefore these are the only values accepted to prevent any problems.
Example:
Dim Hertz As Long, Bits As Byte, Channels As Byte
Hertz = 22050
Bits = 2
Channels = 2
Primary_SetFormat(Hertz, Bits, Channels)
These six functions are used for basic sound buffer management.
Memory management | General_LoadStaticBuffer General_LoadStreamBuffer General_DeleteSound |
Play management | General_PlaySound General_PauseSound General_StopSound |
Use this function to create a static sound buffer.
Syntax:
General_LoadStaticBuffer(FileName As String, Use3D As Boolean, Optional DataOffset As Variant, Optional DataLength As Variant) As Integer
FileName | This argument specifies the full path to the .wav file
being loaded into the new sound buffer. This function DOES NOT check to see if the file is
a valid .wav file. The program must also make sure the file exists and is accessible. NOTE: The file extension does not have to be .wav. You can make the file extension anything you want. |
Use3D | This argument specifies if you want the new sound buffer to be a 3D buffer. If you pass True, panning controls will be unavailable for this sound buffer, since pan control would interfere with the 3D effects. |
DataOffset | This optional argument specifies the byte offset to start searching for wav data from in the specified file. |
DataLength | This optional argument specifies the number of bytes to read from the specified file. |
Returns:
If the function was successful the returned value will be a reference number to the new sound buffer. You have to use this value for all future actions performed on this sound buffer.
If the function returned -1 then a new sound buffer was not created.
Remarks:
You can use the DataOffset and DataLength arguments to specify where to begin and how much data to load from the specified file. You do not have to use both values at the same time.
For example if the original wav file was inserted at byte 200000 in a larger file. The DataOffset argument must point to this value and not to the first byte of the wav data. The function will still need the header information to be present.
The DataLength argument must be the length of the wav file including the header information. The easiest way of finding this value is to specify the file size of the original wav file. It may be smaller than the wav file thereby cutting off the data.
Example:
Dim SoundFileName As String, Make3DBuffer As Boolean, SoundNumber As Integer
SoundFileName = FileNameBox.Text
Make3DBuffer = True
SoundNumber = General_LoadStaticSound(SoundFileName,
Make3DBuffer)
Use this function to create a streaming sound buffer.
Syntax:
General_LoadStaticBuffer(FileName As String, Use3D As Boolean, BufferTime As Long, Optional DataOffset As Variant, Optional DataLength As Variant) As Integer
FileName | This argument specifies the full path to the .wav file
being loaded into the new sound buffer. This function DOES NOT check to see if the file is
a valid .wav file. The program must also make sure the file exists and is accessible. NOTE: The file extension does not have to be .wav. You can make the file extension anything you want. |
Use3D | This argument specifies if you want the new sound buffer to be a 3D sound buffer. If you pass True, panning controls will be unavailable for this sound buffer, since pan control would interfere with the 3D effects. |
BufferTime | This argument specifies the number of seconds of the sound file to keep in the sound buffer at any one time. |
DataOffset | This optional argument specifies the byte offset to start searching for wav data from in the specified file. |
DataLength | This optional argument specifies the number of bytes to read from the specified file. |
Returns:
If the function was successful the returned value will be a reference number to the new sound buffer. You have to use this value for all future actions performed on this sound buffer.
If the function returned -1 then a new sound buffer was not created.
Remarks:
You can use the DataOffset and DataLength arguments to specify where to begin and how much data to load from the specified file. You do not have to use both values at the same time.
For example if the original wav file was inserted at byte 200000 in a larger file. The DataOffset argument must point to this value and not to the first byte of the wav data. The function will still need the header information to be present.
The DataLength argument must be the length of the wav file including the header information. The easiest way of finding this value is to specify the file size of the original wav file. It may be smaller than the wav file thereby cutting off the data.
Example:
Dim SoundFileName As String, Make3DBuffer As Boolean, TotalTime As Long, SoundNumber As
Integer
SoundFileName = FileNameBox.Text
Make3DBuffer = True
TotalTime = 2 'Two seconds
SoundNumber = General_LoadStreamSound(SoundFileName,
Make3DBuffer, TotalTime)
Use this function to delete a specific sound buffer and free up system resources.
Syntax:
General_DeleteSound(SoundNumber As Integer)
SoundNumber | This argument specifies the sound buffer to delete. |
Remarks:
Use this function when you are finished with a specific sound buffer. When you delete the sound buffer all resources used by it are released. If you are uninitializing DirectSound you do not need to delete each sound buffer separately.
Example:
Dim Sound As Integer
Sound = 1
General_DeleteSound(Sound)
Use this function to play a specific sound buffer.
Syntax:
General_PlaySound(SoundNumber As Integer, Looping As Boolean)
SoundNumber | This argument specifies the sound buffer to play. |
Looping | This argument specifies if the sound buffer is to be looped. If True is specified, once the end of the sound buffer is reached, play restarts at the beginning of the sound buffer. Play continues until explicitly stopped. |
Remarks:
If you call this function with looping set to True and then call it again with looping set False. The sound buffer will finish playing and than stop.
If you call this function with looping set to False and then call it again with looping set True. The sound buffer will continue playing looped.
This method will cause the sound buffer to be mixed into the Primary Sound Buffer and sent to the sound device.
Example:
Dim Sound As Integer
Dim MakeItLoop As Boolean
Sound = 1
MakeItLoop = True
General_PlaySound(Sound, MakeItLoop)
Use this function to pause a specific sound buffer.
Syntax:
General_PauseSound(SoundNumber As Integer)
SoundNumber | This argument specifies the sound buffer to pause. |
Example:
Dim Sound As Integer
Sound = 1
General_PauseSound(Sound)
Use this function to stop a specific sound buffer.
Syntax:
General_StopSound(SoundNumber As Integer)
SoundNumber | This argument specifies the sound buffer to stop. |
Remarks:
Unlike General_PauseSound, this function sets the sound buffer position to the beginning of the sound buffer.
Example:
Dim Sound As Integer
Sound = 1
General_StopSound(Sound)
These fifteen functions control the 3D listener for DirectSound.
Deferred settings | Listener_CommitDeferredSettings |
Batch parameters | Listener_GetAllParameters Listener_SetAllParameters |
Distance factor | Listener_GetDistanceFactor Listener_SetDistanceFactor |
Doppler factor | Listener_GetDopplerFactor Listener_SetDopplerFactor |
Orientation | Listener_GetOrientation Listener_SetOrientation |
Position | Listener_GetPosition Listener_SetPosition |
Rolloff factor | Listener_GetRolloffFactor Listener_SetRolloffFactor |
Velocity | Listener_GetVelocity Listener_SetVelocity |
Listener_CommitDeferredSettings
Use this function to force all deferred 3D settings to update.
Syntax:
Listener_CommitDeferredSettings()
Remarks:
Use this function to commit all 3D sound setting that were set using the Wait argument set to True. This is useful as it does not force DirectSound to recalculate all 3D buffers each time a parameter changes. Grouping all parameters with the Wait argument set to True and then calling this function saves considerably on recalculations and CPU cycles.
Example:
Listener_CommitDeferredSettings
Use this function to get all the parameters for the listener in one go.
Syntax:
Listener_GetAllParameters() As DS3DLISTENER
Returns:
This function returns a DS3DLISTENER structure with all the parameters for the listener.
Remarks:
You should use this function if you want to retrieve more than one setting for the listener. Calling each individual function would be wasteful, both in system resources and in the amount of coding that would be needed.
Example:
Dim Params As DS3DLISTENER
Params = Listener_GetAllParameters
Use this function to set all the parameters for the listener in one go.
Syntax:
Listener_SetAllParameters(Params As DS3DLISTENER, Wait As Boolean)
Params | This argument specifies a DS3DLISTENER structure to pass to the listener. You must initialize all the settings for it to work. |
Wait | This argument specifies if the settings are to be applied immediately (False) or if they are to be deferred until the Listener_CommitDeferredSettings function is called (True). |
Remarks:
You must set all the settings before calling this function.
Example:
Dim Params As DS3DLISTENER
'Set all values of Params here
Listener_SetAllParameters(Params, False)
Use this function to get the distance factor for the listener.
Syntax:
Listener_GetDistanceFactor() As Single
Returns:
This function returns the value for the distance factor for the listener.
Remarks:
The distance factor is used to create a custom distance to use in DirectSound. A value of 1 indicates 1 meter, any other value indicates a factor of a meter.
Example:
Dim Factor As Single
Factor = Listener_GetDistanceFactor
Use this function to set the distance factor for the listener.
Syntax:
Listener_SetDistanceFactor(Factor As Single, Wait As Boolean)
Factor | This argument specifies the distance factor to use for the listener. |
Wait | This argument specifies if the setting is to be applied immediately (False) or if it is to be deferred until the Listener_CommitDeferredSettings function is called (True). |
Example:
Dim Factor As Single
Factor = 0.8 '0.8 meters per 1 distance unit
Listener_SetDistanceFactor(Factor, True)
Use this function to get the Doppler factor for the listener.
Syntax:
Listener_GetDopplerFactor() As Single
Returns:
This function returns the value for the Doppler factor for the listener.
Remarks:
The Doppler factor has a range of DS3D_MINDOPPLERFACTOR (no Doppler effects or 0) to DS3D_MAXDOPPLERFACTOR (as currently defined, 10 times the Doppler effects found in the real world). The default value is DS3D_DEFAULTDOPPLERFACTOR (1.0).
Example:
Dim Factor As Single
Factor = Listener_GetDopplerFactor
Use this function to set the Doppler factor for the listener.
Syntax:
Listener_SetDopplerFactor(Factor As Single, Wait As Boolean)
Factor | This argument specifies the Doppler factor to use for the listener. |
Wait | This argument specifies if the setting is to be applied immediately (False) or if it is to be deferred until the Listener_CommitDeferredSettings function is called (True). |
Remarks:
The Doppler factor has a range of DS3D_MINDOPPLERFACTOR (no Doppler effects or 0) to DS3D_MAXDOPPLERFACTOR (as currently defined, 10 times the Doppler effects found in the real world). The default value is DS3D_DEFAULTDOPPLERFACTOR (1.0).
Example:
Dim Factor As Single
Factor = 1.5
Listener_SetDopplerFactor(Factor, True)
Use this function to get the orientation of the listener.
Syntax:
Listener_GetOrientation(ByRef FrontOrientation As D3DVECTOR, ByRef TopOrientation As D3DVECTOR)
FrontOrientation | This argument specifies a variable that will receive the front orientation vector. |
TopOrientation | This argument specifies a variable that will receive the top orientation vector. |
Returns:
This function set the values of the FrontOrientation D3DVECTOR argument and the TopOrientation D3DVECTOR argument to the current orientation of the listener.
Remarks:
The front vector points in the direction of the listener's nose, and the top vector points out the top of the listener's head. By default, the front vector is (0,0,1.0) and the top vector is (0,1.0,0).
The values returned are not necessarily the same as those set by using the Listener_SetOrientation function. DirectSound adjusts orientation vectors so that they are at right angles and have a magnitude of less than or equal to 1.0.
Example:
Dim Front As D3DVECTOR
Dim Top As D3DVECTOR
Listener_GetOrientation(Front, Top)
'The Front and Top variables now contain the orientation of the listener.
Use this function to set the orientation of the listener.
Syntax:
Listener_SetOrientation(XFront As Single, YFront As Single, ZFront As Single, XTop As Single, YTop As Single, ZTop As Single, Wait As Boolean)
XFront, YFront, ZFront | These three arguments specify the X, Y and Z values for the Front vector. |
XTop, YTop, ZTop | These three arguments specify the X, Y and z values for the Top vector. |
Wait | This argument specifies if the setting is to be applied immediately (False) or if it is to be deferred until the Listener_CommitDeferredSettings function is called (True). |
Remarks:
The front vector points in the direction of the listener's nose, and the top vector points out the top of the listener's head. By default, the front vector is (0,0,1.0) and the top vector is (0,1.0,0).
The top vector must be at right angles to the front vector. If necessary, DirectSound adjusts the front vector after setting the top vector.
Example:
Dim XF, YF, ZF, XT, YT, ZT As Single
XF = 0
YF = 0
ZF = 1
XT = 0
YT = 1
ZT = 0
Listener_SetOrientation(XF, YF, ZF, XT, YT,
ZT, True)
Use this function to get the position of the listener.
Syntax:
Listener_GetPosition() As D3DVECTOR
Returns:
This function returns a D3DVECTOR structure with the current position of the listener.
Example:
Dim Pos As D3DVECTOR
Pos = Listener_GetPosition
Use this function to set the position of the listener.
Syntax:
Listener_SetPosition(X As Single, Y As Single, Z As Single, Wait As Boolean)
X, Y, Z | These three arguments specify the X, Y and Z values for the position of the listener. |
Wait | This argument specifies if the setting is to be applied immediately (False) or if it is to be deferred until the Listener_CommitDeferredSettings function is called (True). |
Remarks:
Note that DirectSound may adjust the X, Y and Z values to prevent floating-point overflow.
Example:
Dim XVal, YVal, ZVal As Single
XVal = 1
YVal = 2
ZVal = 3
Listener_SetPosition(XVal, YVal, ZVal, True)
Use this function to get the rolloff factor for the listener.
Syntax:
Listener_GetRolloffFactor() As Single
Returns:
This function returns the rolloff factor for the listener.
Remarks:
The rolloff factor has a range of DS3D_MINROLLOFFFACTOR (no rolloff or 0) to DS3D_MAXROLLOFFFACTOR (as currently defined, 10 times the rolloff found in the real world). The default value is DS3D_DEFAULTROLLOFFFACTOR (1.0).
Example:
Dim Rolloff As Single
Rolloff = Listener_GetRolloffFactor
Use this function to set the rolloff factor for the listener.
Syntax:
Listener_SetRolloffFactor(Factor As Single, Wait As Boolean)
Factor | This argument specifies the rolloff factor to use for the listener. |
Wait | This argument specifies if the setting is to be applied immediately (False) or if it is to be deferred until the Listener_CommitDeferredSettings function is called (True). |
Remarks:
The rolloff factor has a range of DS3D_MINROLLOFFFACTOR (no rolloff or 0) to DS3D_MAXROLLOFFFACTOR (as currently defined, 10 times the rolloff found in the real world). The default value is DS3D_DEFAULTROLLOFFFACTOR (1.0).
Example:
Dim Factor As Single
Factor = 1
Listener_SetRolloffFactor(Factor, True)
Use this function to get the velocity of the listener.
Syntax:
Listener_GetVelocity() As D3DVECTOR
Returns:
This function returns a D3DVECTOR structure with the current velocity of the listener.
Remarks:
Velocity is used only for Doppler effects. It does not actually move the listener. To change the listener's position, use the Listener_SetPosition function. The default velocity is (0,0,0).
Example:
Dim Vel As D3DVECTOR
Vel = Listener_GetVelocity
Use this function to set the velocity of the listener.
Syntax:
Listener_SetVelocity(X As Single, Y As Single, Z As Single, Wait As Boolean)
X, Y, Z | These three arguments specify the X, Y and Z values for the velocity of the listener. |
Wait | This argument specifies if the setting is to be applied immediately (False) or if it is to be deferred until the Listener_CommitDeferredSettings function is called (True). |
Remarks:
Velocity is used only for Doppler effects. It does not actually move the listener. To change the listener's position, use the Listener_SetPosition function. The default velocity is (0,0,0).
Example:
Dim XVel, YVel, ZVel As Single
XVel = 1
YVel = 2
ZVel = 3
Listener_SetVelocity(XVel, YVel, ZVel, True)
These fifteen functions control all the 2D functions of a specific sound buffer.
Use this function to get the capabilities of a specific sound buffer.
Syntax:
Buffer2D_GetCaps(SoundNumber As Integer) As DSBCAPS
SoundNumber | This argument specifies the sound buffer to get the capabilities of. |
Returns:
This function returns a DSBCAPS structure with the capabilities of the specified sound buffer.
Remarks:
The information in DSBCAPS can include the sound buffer's location, either in hardware or software, and some cost measures. Examples of cost measures include the time it takes to download to a hardware sound buffer and the processing overhead required to mix and play the sound buffer when it is in the system memory.
The flags specified in the dwFlags member of the DSBCAPS structure are the same flags used to create the sound buffer. The only difference is that in the DSBCAPS structure, either DSBCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE will be specified according to the location of the sound buffer memory.
Example:
Dim Caps As DSBCAPS, Sound As Integer
Caps = Buffer2D_GetCaps(Sound)
Use this function to get the format of a specific sound buffer.
Syntax:
Buffer2D_GetFormat(SoundNumber As Integer) As WAVEFORMATEX
SoundNumber | This argument specifies the sound buffer to get the format of. |
Returns:
This function returns a WAVEFORMATEX structure with the format of the specified sound buffer.
Example:
Dim Format As WAVEFORMATEX, Sound As Integer
Format = Buffer2D_GetFormat(Sound)
Use this function to get the status of a specific sound buffer.
Syntax:
Buffer2D_GetStatus(SoundNumber As Integer) As Long
SoundNumber | This argument specifies the sound buffer to get the status of. |
Returns:
This function returns one of the following:
DSBSTATUS_PLAYING = 1 | The sound buffer is playing. If this value is not set, the sound buffer is stopped. |
DSBSTATUS_BUFFERLOST = 2 | The sound buffer is lost and must be restored before it can be played or locked. This will be done automatically for you if you play the sound buffer. |
DSBSTATUS_LOOPING = 4 | The sound buffer is being looped. If this value is not set, the sound buffer will stop when it reaches the end of the sound data. Note that if this value is set, the sound buffer must also be playing. |
Remarks:
If the sound buffer is reported as lost, you do not have to do anything special. The next time you play the sound buffer it will be automatically restored with the appropriate sound data.
Example:
Dim Stat As Long, Sound As Integer
Stat = Buffer2D_GetStatus(Sound)
Use this function to find out if a specific sound buffer is a static or steaming sound buffer.
Syntax:
Buffer2D_IsBufferStreaming(SoundNumber As Integer) As Boolean
SoundNumber | This argument specifies the sound buffer to find the type of. |
Returns:
This function returns one of the following:
True | The buffer is a streaming sound buffer |
False | The buffer is a static sound buffer. |
Example:
Dim Type As Boolean, Sound As Integer
Type = Buffer2D_IsBufferStreaming(Sound)
Use this function to get the play position in a specific sound buffer.
Syntax:
Buffer2D_GetPosition(SoundNumber As Integer) As Long
SoundNumber | This argument specifies the sound buffer to get the play position of. |
Returns:
This function returns the position of the specified sound buffer.
Remarks:
The play position returned is the actual play position in the sound buffer for static sound buffers and the last written to position in streaming sound buffers. Therefore the position in streaming sound buffers leads the actual position by about the length of the sound buffer.
NEW In version 1.1 the position returned for streaming buffers is now the actual position. The delay problem above only applies to version 1.0.
Example:
Dim Pos As Long, Sound As Integer
Pos = Buffer2D_GetPosition(Sound)
Use this function to set the play position of a specific sound buffer.
Syntax:
Buffer2D_SetPosition(SoundNumber As Integer, Position As Long)
SoundNumber | This argument specifies the sound buffer to set the play position of. |
Position | This argument specifies the play position to set the sound buffer to. |
Remarks:
The play position set is the actual play position in the sound buffer for static sound buffers and the next written position in streaming sound buffers. Therefore the set position in streaming sound buffers leads the actual position by about the length of the sound buffer. This will result in a delay of the length of the sound buffer before the new position takes over.
NEW In version 1.1 the position set for streaming buffers is now the actual immediate position. The delay problem above only applies to version 1.0.
Example:
Dim Pos As Long, Sound As Integer
Pos = 12345678
Buffer2D_SetPosition(Sound, Pos)
Buffer2D_GetStreamRestartPosition
Use this function to get the restart position of a specific streaming sound buffer.
Syntax:
Buffer2D_GetStreamRestartPosition(SoundNumber As Integer) As Long
SoundNumber | This argument specifies the streaming sound buffer to get the restart position of. |
Returns:
This function returns the restart position of the specified streaming sound buffer.
Remarks:
This function only applies to streaming sound buffers. The restart position is used to allow a long sound to loop back into a position inside the sound buffer. This can be used for things like a song that has a short intro that plays only once.
S--------------L--------------------------------------------E
S = This is the start of the song (position 0)
L = This is the restart position
E = This is the end of the song
Basically the buffer would be played looped. It would start from S and play until it reaches E. If the restart position is set then the song would loop from E to L instead of S. This would effectively skip whatever is between S and L.
Example:
Dim Pos As Long, Sound As Integer
Pos = Buffer2D_GetStreamRestartPosition(Sound)
Buffer2D_SetStreamRestartPosition
Use this function to set the restart position of a specific streaming sound buffer.
Syntax:
Buffer2D_SetStreamRestartPosition(SoundNumber As Integer, RestartPosition As Long)
SoundNumber | This argument specifies the streaming sound buffer to set the position of. |
RestartPosition | This argument specifies the restart position to set for the streaming sound buffer. |
Remarks:
This function only applies to streaming sound buffers. The restart position is used to allow a long sound to loop back into a position inside the sound buffer. This can be used for things like a song that has a short intro that plays only once.
S--------------L--------------------------------------------E
S = This is the start of the song (position 0)
L = This is the restart position
E = This is the end of the song
Basically the buffer would be played looped. It would start from S and play until it reaches E. If the restart position is set then the song would loop from E to L instead of S. This would effectively skip whatever is between S and L.
Example:
Dim Pos As Long, Sound As Integer
Pos = 3453673
Buffer2D_SetStreamRestartPosition(Sound, Pos)
Use this function to seek a specific sound buffer to the beginning.
Syntax:
Buffer2D_SeekBufferToStart(SoundNumber As Integer)
SoundNumber | This argument specifies the sound buffer to seek to the start. |
Remarks:
This function basically is the same as using the Buffer2D_SetPosition function with the position set to 0.
Example:
Dim Sound As Integer
Buffer2D_SeekBufferToStart(Sound)
Use this function to get the frequency of a specific sound buffer.
Syntax:
Buffer2D_GetFrequency(SoundNumber As Integer) As Long
SoundNumber | This argument specifies the sound buffer to get the frequency of. |
Returns:
This function returns the frequency of the specified sound buffer.
Remarks:
The frequency value will be in the range of DSBFREQUENCY_MIN to DSBFREQUENCY_MAX. These values are currently defined as 100 and 100,000 respectively.
Example:
Dim Freq As Long, Sound As Integer
Freq = Buffer2D_GetFrequency(Sound)
Use this function to set the frequency of a specific sound buffer.
Syntax:
Buffer2D_SetFrequency(SoundNumber As Integer, Frequency As Long)
SoundNumber | This argument specifies the sound buffer to set the frequency of. |
Frequency | This argument specifies the frequency to set for the sound buffer. |
Remarks:
The frequency value can be in the range of DSBFREQUENCY_MIN to DSBFREQUENCY_MAX. These values are currently defined as 100 and 100,000 respectively.
If the value is DSBFREQUENCY_ORIGINAL or 0, the frequency is reset to the default value in the current sound buffer format.
Increasing or decreasing the frequency changes the perceived pitch of the audio data. This method does not affect the format of the sound buffer.
Example:
Dim Freq As Long, Sound As Integer
Freq = 24567
Buffer2D_SetFrequency(Sound, Freq)
Use this function to get the pan of a specific 2D sound buffer.
Syntax:
Buffer2D_GetPan(SoundNumber As Integer) As Long
SoundNumber | This argument specifies the 2D sound buffer to get the pan of. |
Returns:
This function returns the pan of the specified 2D sound buffer.
Remarks:
This function ONLY applies to 2D sound buffers. Any sound buffer that was created as 3D will not be affected by this function.
The returned value is measured in hundredths of a decibel (dB), in the range of DSBPAN_LEFT to DSBPAN_RIGHT. These values are currently defined as -10,000 and 10,000 respectively. The value DSBPAN_LEFT means the right channel is attenuated by 100 dB. The value DSBPAN_RIGHT means the left channel is attenuated by 100 dB. The neutral value is DSBPAN_CENTER, defined as zero. This value of 0 means that both channels are at full volume (they are attenuated by 0 decibels). At any setting other than DSBPAN_CENTER, one of the channels is at full volume and the other is attenuated.
A pan of -2173 means that the left channel is at full volume and the right channel is attenuated by 21.73 dB. Similarly, a pan of 870 means that the left channel is attenuated by 8.7 dB and the right channel is at full volume. A pan of DSBPAN_LEFT means that the right channel is silent and the sound is all the way to the left, while a pan of DSBPAN_RIGHT means that the left channel is silent and the sound is all the way to the right.
The pan control acts cumulatively with the volume control.
Example:
Dim Pan As Long, Sound As Integer
Pan = Buffer2D_GetPan(Sound)
Use this function to set the pan of a specific 2D sound buffer.
Syntax:
Buffer2D_SetPan(SoundNumber As Integer, Pan As Long)
SoundNumber | This argument specifies the 2D sound buffer to set the pan of. |
Pan | This argument specifies the pan to set for the 2D sound buffer. |
Remarks:
This function ONLY applies to 2D sound buffers. Any sound buffer that was created as 3D will not be affected by this function.
The returned value is measured in hundredths of a decibel (dB), in the range of DSBPAN_LEFT to DSBPAN_RIGHT. These values are currently defined as -10,000 and 10,000 respectively. The value DSBPAN_LEFT means the right channel is attenuated by 100 dB. The value DSBPAN_RIGHT means the left channel is attenuated by 100 dB. The neutral value is DSBPAN_CENTER, defined as zero. This value of 0 means that both channels are at full volume (they are attenuated by 0 decibels). At any setting other than DSBPAN_CENTER, one of the channels is at full volume and the other is attenuated.
A pan of -2173 means that the left channel is at full volume and the right channel is attenuated by 21.73 dB. Similarly, a pan of 870 means that the left channel is attenuated by 8.7 dB and the right channel is at full volume. A pan of DSBPAN_LEFT means that the right channel is silent and the sound is all the way to the left, while a pan of DSBPAN_RIGHT means that the left channel is silent and the sound is all the way to the right.
The pan control acts cumulatively with the volume control.
Example:
Dim Pan As Long, Sound As Integer
Pan = -3565
Buffer2D_SetPan(Sound, Pan)
Use this function to get the volume of a specific sound buffer.
Syntax:
Buffer2D_GetVolume(SoundNumber As Integer) As Long
SoundNumber | This argument specifies the sound buffer to get the volume of. |
Returns:
This function returns the volume of the specified sound buffer.
Remarks:
The volume is specified in hundredths of decibels (dB). Allowable values are between DSBVOLUME_MAX (no attenuation) and DSBVOLUME_MIN (silence). These values are currently defined as 0 and -10,000 respectively. The value DSBVOLUME_MAX represents the original, unadjusted volume of the stream. The value DSBVOLUME_MIN indicates an audio volume attenuated by 100 dB, which, for all practical purposes, is silence. Currently DirectSound does not support amplification.
Example:
Dim Volume As Long, Sound As Integer
Volume = Buffer2D_GetVolume(Sound)
Use this function to set the volume of a specific sound buffer.
Syntax:
Buffer2D_SetVolume(SoundNumber As Integer, Volume As Long)
SoundNumber | This argument specifies the sound buffer to set the volume of. |
Pan | This argument specifies the volume to set for the sound buffer. |
Remarks:
The volume is specified in hundredths of decibels (dB). Allowable values are between DSBVOLUME_MAX (no attenuation) and DSBVOLUME_MIN (silence). These values are currently defined as 0 and -10,000 respectively. The value DSBVOLUME_MAX represents the original, unadjusted volume of the stream. The value DSBVOLUME_MIN indicates an audio volume attenuated by 100 dB, which, for all practical purposes, is silence. Currently DirectSound does not support amplification.
Example:
Dim Volume As Long, Sound As Integer
Volume = -2000
Buffer2D_SetVolume(Sound, Volume)
These eighteen functions control all the 3D functions of a specific 3D sound buffer. Please note that these functions are ONLY available on sound buffers that were created as 3D sound buffers, all other sound buffers will ignore these functions.
Batch parameter manipulation | Buffer3D_GetAllParameters Buffer3D_SetAllParameters |
Distance | Buffer3D_GetMaxDistance Buffer3D_SetMaxDistance Buffer3D_GetMinDistance Buffer3D_SetMinDistance |
Operation mode | Buffer3D_GetMode Buffer3D_SetMode |
Position | Buffer3D_GetPosition Buffer3D_SetPosition |
Sound projection cones | Buffer3D_GetConeAngles Buffer3D_SetConeAngles Buffer3D_GetConeOrientation Buffer3D_SetConeOrientation Buffer3D_GetConeOutsideVolume Buffer3D_SetConeOutsideVolume |
Velocity | Buffer3D_GetVelocity Buffer3D_SetVelocity |
Use this function to get all the parameters of a specific 3D sound buffer in one go.
Syntax:
Buffer3D_GetAllParameters(SoundNumber As Integer) As DS3DBUFFER
SoundNumber | This argument specifies the 3D sound buffer to get the parameters of. |
Returns:
This function returns a DS3DBUFFER structure with all the parameters of the specified 3D sound buffer.
Remarks:
You should use this function if you want to retrieve more than one setting for a specific 3D sound buffer. Calling each individual function would be wasteful, both in system resources and in the amount of coding that would be needed.
Example:
Dim Params As DS3DBUFFER, Sound As Integer
Params = Buffer3D_GetAllParameters(Sound)
Use this function to set all the parameters of a specific 3D sound buffer in one go.
Syntax:
Buffer3D_SetAllParameters(SoundNumber As Integer, Parameters As DS3DBUFFER, Wait As Boolean)
SoundNumber | This argument specifies the 3D sound buffer to set the parameters of. |
Parameters | This argument specifies a DS3DBUFFER structure to pass to the specific 3D sound buffer. You must initialize all the settings for it to work. |
Wait | This argument specifies if the settings are to be applied immediately (False) or if they are to be deferred until the Listener_CommitDeferredSettings function is called (True). |
Remarks:
You must set all the settings before calling this function.
Example:
Dim Params As DS3DBUFFER, Sound As Integer
'Set all values of Params here
Buffer3D_SetAllParameters(Sound, Params, True)
Use this function to get the maximum distance of a specific 3D sound buffer.
Syntax:
Buffer3D_GetMaxDistance(SoundNumber As Integer) As Single
SoundNumber | This argument specifies the 3D sound buffer to get the maximum distance of. |
Returns:
This function returns the maximum distance of the specified 3D sound buffer.
Remarks:
The default maximum distance is effectively infinite.
Example:
Dim Dist As Single, Sound As Integer
Dist = Buffer3D_GetMaxDistance(Sound)
Use this function to set the maximum distance of a specific 3D sound buffer.
Syntax:
Buffer3D_SetMaxDistance(SoundNumber As Integer, Distance As Single, Wait As Boolean)
SoundNumber | This argument specifies the 3D sound buffer to set the maximum distance of. |
Distance | This argument specifies the maximum distance for a specific 3D sound buffer. |
Wait | This argument specifies if the setting is to be applied immediately (False) or if it is be deferred until the Listener_CommitDeferredSettings function is called (True). |
Remarks:
The default maximum distance is effectively infinite.
Example:
Dim Dist As Single, Sound As Integer
Dist = 1200
Buffer3D_SetMaxDistance(Sound, Dist, True)
Use this function to get the minimum distance of a specific 3D sound buffer.
Syntax:
Buffer3D_GetMinDistance(SoundNumber As Integer) As Single
SoundNumber | This argument specifies the 3D sound buffer to get the minimum distance of. |
Returns:
This function returns the minimum distance of the specified 3D sound buffer.
Remarks:
By default, the minimum distance value is DS3D_DEFAULTMINDISTANCE, currently defined as 1.0 (corresponding to 1.0 meter at the default distance factor of 1.0 meters per unit).
Example:
Dim Dist As Single, Sound As Integer
Dist = Buffer3D_GetMinDistance(Sound)
Use this function to set the minimum distance of a specific 3D sound buffer.
Syntax:
Buffer3D_SetMinDistance(SoundNumber As Integer, Distance As Single, Wait As Boolean)
SoundNumber | This argument specifies the 3D sound buffer to set the minimum distance of. |
Distance | This argument specifies the minimum distance for a specific 3D sound buffer. |
Wait | This argument specifies if the setting is to be applied immediately (False) or if it is be deferred until the Listener_CommitDeferredSettings function is called (True). |
Remarks:
By default, the minimum distance value is DS3D_DEFAULTMINDISTANCE, currently defined as 1.0 (corresponding to 1.0 meter at the default distance factor of 1.0 meters per unit).
Example:
Dim Dist As Single, Sound As Integer
Dist = 100
Buffer3D_SetMinDistance(Sound, Dist, True)
Use this function to get the mode of a specific 3D sound buffer.
Syntax:
Buffer3D_GetMode(SoundNumber As Integer) As Long
SoundNumber | This argument specifies the 3D sound buffer to get the mode of. |
Returns:
This function returns one of the following:
DS3DMODE_NORMAL = 0 | Normal processing. This is the default mode. |
DS3DMODE_HEADRELATIVE = 1 | 3D sound buffer parameters (position, velocity, and orientation) are relative to the listener's parameters. In this mode, the absolute parameters of the sound buffer are updated automatically as the listener's parameters change, so that the relative parameters remain constant. |
DS3DMODE_DISABLE = 2 | Processing of 3D sound buffer is disabled. The sound buffer seems to originate from the center of the listener's head. |
Example:
Dim Mode As Long, Sound As Integer
Mode = Buffer3D_GetMode(Sound)
Use this function to set the mode of a specific 3D sound buffer.
Syntax:
Buffer3D_SetMode(SoundNumber As Integer, Mode As Long, Wait As Boolean)
SoundNumber | This argument specifies the 3D sound buffer to set the mode of. | ||||||
Mode | This argument specifies the mode for a specific 3D sound buffer. It can
be one of the following:
|
||||||
Wait | This argument specifies if the setting is to be applied immediately (False) or if it is be deferred until the Listener_CommitDeferredSettings function is called (True). |
Example:
Dim Mode As Long, Sound As Integer
Mode = 1
Buffer3D_SetMode(Sound, Mode, True)
Use this function to get the position of a specific 3D sound buffer.
Syntax:
Buffer3D_GetPosition(SoundNumber As Integer) As D3DVECTOR
SoundNumber | This argument specifies the 3D sound buffer to get the position of. |
Returns:
This function returns a D3DVECTOR structure with the position of the specified 3D sound buffer.
Example:
Dim Pos As D3DVECTOR, Sound As
Integer
Pos = Buffer3D_GetPosition(Sound)
Use this function to set the position of a specific 3D sound buffer.
Syntax:
Buffer3D_SetPosition(SoundNumber As Integer, X As Single, Y As Single, Z As Single, Wait As Boolean)
SoundNumber | This argument specifies the 3D sound buffer to set the position of. |
X, Y, Z | These arguments specify the X, Y and Z values for the position of a specific 3D sound buffer. Note that DirectSound may adjust these values to prevent floating-point overflow. |
Wait | This argument specifies if the setting is to be applied immediately (False) or if it is be deferred until the Listener_CommitDeferredSettings function is called (True). |
Example:
Dim XVal As Single, YVal As Single, ZVal As Single, Sound As
Integer
XVal = 12
YVal = 14.5
ZVal = 24
Buffer3D_SetPosition(Sound, XVal, YVal, ZVal, True)
Use this function to get the inside and outside angles of the sound projection cone of a specific 3D sound buffer.
Syntax:
Buffer3D_GetConeAngles(SoundNumber As Integer, ByRef InsideCone As Long, ByRef OutsideCone As Long)
SoundNumber | This argument specifies the 3D sound buffer to get the cone angles of. |
InsideCone | This argument specifies the variable that will receive the inside cone angle for the specified 3D sound buffer. |
OutsideCone | This argument specifies the variable that will receive the outside cone angle for the specified 3D sound buffer. |
Returns:
This function set the values of the InsideCone argument and the OutsideCone argument to the current cone angles of the specific 3D sound buffer.
Example:
Dim Inside As Long, Outside As Long, Sound As Integer
Buffer3D_GetConeAngles(Sound, Inside, Outside)
Use this function to set the inside and outside angles of the sound projection cone of a specific 3D sound buffer.
Syntax:
Buffer3D_SetConeAngles(SoundNumber As Integer, InsideCone As Long, OutsideCone As Long, Wait As Boolean)
SoundNumber | This argument specifies the 3D sound buffer to set the cone angles of. |
InsideCone | This argument specifies the inside cone angle for the specified 3D sound buffer. |
OutsideCone | This argument specifies the outside cone angle for the specified 3D sound buffer. |
Wait | This argument specifies if the setting is to be applied immediately (False) or if it is be deferred until the Listener_CommitDeferredSettings function is called (True). |
Remarks:
The minimum, maximum, and default cone angles are defined as DS3D_MINCONEANGLE (0), DS3D_MAXCONEANGLE (360), and DS3D_DEFAULTCONEANGLE (360). Each angle must be in the range of 0 degrees (no cone) to 360 degrees (the full sphere). The default value is 360.
The inside cone angle must be as large or smaller than the outside cone angle.
Example:
Dim Inside As Long, Outside As Long, Sound As Integer
Inside = 15
Outside = 30
Buffer3D_SetConeAngles(Sound, Inside, Outside, True)
Use this function to get the orientation of the sound projection cone of a specific 3D sound buffer.
Syntax:
Buffer3D_GetConeOrientation(SoundNumber As Integer) As D3DVECTOR
SoundNumber | This argument specifies the 3D sound buffer to get the cone orientation of. |
Returns:
This function returns a D3DVECTOR structure with the sound projection cone orientation of the specified 3D sound buffer.
Example:
Dim Orient As D3DVECTOR, Sound As
Integer
Orient = Buffer3D_GetConeOrientation(Sound)
Use this function to set the orientation of the sound projection cone of a specific 3D sound buffer.
Syntax:
Buffer3D_SetConeOrientation(SoundNumber As Integer, X As Single, Y As Single, Z As Single, Wait As Boolean)
SoundNumber | This argument specifies the 3D sound buffer to set the cone orientation of. |
X, Y, Z | These arguments specify the X, Y and Z values of the orientation of the sound projection cone for the specified 3D sound buffer. |
Wait | This argument specifies if the setting is to be applied immediately (False) or if it is be deferred until the Listener_CommitDeferredSettings function is called (True). |
Remarks:
This method has no effect unless the cone angle and cone volume factor have also been set.
Example:
Dim X As Single, Y As Single, Z As Single, Sound As Integer
X = 12
Y = 9
Z = 14
Buffer3D_SetConeOrientation(Sound, X, Y, Z, True)
Use this function to get the outside cone volume of a specific 3D sound buffer.
Syntax:
Buffer3D_GetConeOutsideVolume(SoundNumber As Integer) As Long
SoundNumber | This argument specifies the 3D sound buffer to get the outside cone volume of. |
Returns:
This function returns the outside cone volume of the specified 3D sound buffer.
Volume levels are represented by attenuation. Allowable values are between DSBVOLUME_MAX (no attenuation or 0) and DSBVOLUME_MIN (silence or -10000). The default value is DS3D_DEFAULTCONEOUTSIDEVOLUME (no attenuation or 0). Currently DirectSound does not support amplification.
Example:
Dim Vol As Long, Sound As Integer
Vol = Buffer3D_GetConeOutsideVolume(Sound)
Use this function to set the outside cone volume of a specific 3D sound buffer.
Syntax:
Buffer3D_SetConeOutsideVolume(SoundNumber As Integer, Volume As Long, Wait As Boolean)
SoundNumber | This argument specifies the 3D sound buffer to set the outside cone volume of. |
Volume | This argument specifies the outside cone volume for the specified 3D sound buffer. |
Wait | This argument specifies if the setting is to be applied immediately (False) or if it is be deferred until the Listener_CommitDeferredSettings function is called (True). |
Remarks:
Volume levels are represented by attenuation. Allowable values are between DSBVOLUME_MAX (no attenuation or 0) and DSBVOLUME_MIN (silence or -10000). The default value is DS3D_DEFAULTCONEOUTSIDEVOLUME (no attenuation or 0). Currently DirectSound does not support amplification.
Example:
Dim Vol As Long, Sound As Integer
Vol = -1000
Buffer3D_SetConeOutsideVolume(Sound, Vol, True)
Use this function to get the velocity of a specific 3D sound buffer.
Syntax:
Buffer3D_GetVelocity(SoundNumber As Integer) As D3DVECTOR
SoundNumber | This argument specifies the 3D sound buffer to get the velocity of. |
Returns:
This function returns a D3DVECTOR structure with the velocity of the specified 3D sound buffer.
Velocity is used for Doppler effects only. It does not actually move the 3D sound buffer.
Example:
Dim Vel As D3DVECTOR, Sound As
Integer
Vel = Buffer3D_GetVelocity(Sound)
Use this function to set the velocity of a specific 3D sound buffer.
Syntax:
Buffer3D_SetVelocity(SoundNumber As Integer, X As Single, Y As Single, Z As Single, Wait As Boolean)
SoundNumber | This argument specifies the 3D sound buffer to set the velocity of. |
X, Y, Z | These arguments specify the X, Y and Z values for the velocity for the specified 3D sound buffer. |
Wait | This argument specifies if the setting is to be applied immediately (False) or if it is be deferred until the Listener_CommitDeferredSettings function is called (True). |
Remarks:
Velocity is used for Doppler effects only. It does not actually move the sound buffer.
Example:
Dim XVal As Single, YVal As Single, ZVal As Single, Sound As
Integer
XVal = 12.5
YVal = 18.4
ZVal = 9.4
Buffer3D_SetVelocity(Sound, XVal, YVal, ZVal, True)
These functions are used by the module internally and should not be used. Normally these functions are not visible (except the Private_UpdateStreams function). These functions are described here only so you know what they do should you want to modify the module.
Buffer Management | Private_NextAvailableBuffer Private_RestoreStaticBuffer Private_RestoreStreamingBuffer Private_UpdateStreams |
This function returns the next available sound buffer.
Syntax:
Private_NextAvailableBuffer() As Integer
Returns:
This function returns the next available sound buffer. If there are no available sound buffers left then the function returns -1.
The maximum number of sound buffers is specified by the MaxBuffers constant.
Example:
Dim Buf As Integer
Buf = Private_NextAvailableBuffer
This function restores the specified static sound buffer.
Syntax:
Private_RestoreStaticBuffer(SoundNum As Integer) As Boolean
SoundNum | This argument specifies the static sound buffer to restore |
This function returns True if the buffer was successfully restored or False if it was not.
The restored sound buffer is ready to be played. This function also takes care of restoring the actual sound data.
Example:
Dim Buf As Integer, Restored As Boolean
Restored = Private_RestoreStaticBuffer(Buf)
Private_RestoreStreamingBuffer
This function restores the specified streaming sound buffer.
Syntax:
Private_RestoreStreamingBuffer(SoundNum As Integer) As Boolean
SoundNum | This argument specifies the streaming sound buffer to restore |
This function returns True if the buffer was successfully restored or False if it was not.
The restored buffer is ready to be played. This function also takes care of restoring the actual sound data.
Example:
Dim Buf As Integer, Restored As Boolean
Restored = Private_RestoreStreamingBuffer(Buf)
This function updates all playing streaming sound buffers with new data.
Syntax:
Private_UpdateStreams()
This function is called by a system timer with the interval specified in the UpdateInterval constant.
Example:
Private_UpdateStreams
Contacting the Author
If you find any mistakes in the module and/or the documentation or if you have suggestions for new features or how to improve old features, please feel free to email me at:
Jan Nawara
nawaraj@hotmail.com
If you happen to use this module in an actual program I would appreciate it if you would tell me about it (or send me a copy if you wish ). Tell me first if you wish to send me a copy of your program.
Windows NT Users
If you wish to use this module on a Windows NT 4 system you can do so with little modification. All you have to do is download and reference the DirectX 3 type library instead of the DirectX 6 type library. The target NT system must have service pack 3 installed in order for the necessary DirectX 3 runtime to be present.
DirectX Type Libraries
You can download the DirectX Type Library files (and the Win32 Type Library) from either of these two sites:
http://members.xoom.com/vba51
http://www.chez.com/scribe
If you have any questions regarding these type libraries contact:
Patrice Scribe
scribe@chez.com
Using a type library
A type library is just a description of COM objects (neutral language objects that are managed at the Operating System level). This description is used at compile time by Visual Basic to build the necessary calls into the final EXE file. To reference a type library :
Remember no matter which DirectX Type Library you use (DirectX 3, DirectX 5 or DirectX 6) you MUST still reference the Win32 Type Library.