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 Microsoft’s 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:

  1. You must add the file DSModule.bas to you project.
  2. You must reference both the DirectX 6 type library and the Win32 type library. (See Appendix for instructions.)
  3. If you wish, change the UpdateInterval constant in the module to the number of milliseconds to pass between streaming buffer updates. This value should be about ¼ the length of the shortest buffer.
    E.g. For a 2 second buffer set this to 500 milliseconds.
  4. If you wish, change the MaxBuffers constant in the module to the maximum number of sound buffers you want to allow. This should not be larger than 128 buffers.

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.

Init Functions

These are two functions are used to initialize and uninitialize the DirectSound.

Init_InitializeDirectSound
Init_UninitializeDirectSound


Init_InitializeDirectSound

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)


Init_UninitializeDirectSound

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


DSound Functions

These four functions are used to manage DirectSound.

Memory management  DSound_Compact
Device capabilities  DSound_GetCaps
Speaker configuration  DSound_GetSpeakerConfig
DSound_SetSpeakerConfig

DSound_Compact

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


DSound_GetCaps

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


DSound_GetSpeakerConfig

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


DSound_SetSpeakerConfig

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.
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 = DSSPEAKER_STEREO

DSound_SetSpeakerConfig(SpeakerType)


Primary Functions

These three functions are used to control the Primary Sound Buffer.

Sound management Primary_GetVolume
Primary_SetVolume
Information Primary_SetFormat

Primary_GetVolume

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


Primary_SetVolume

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)


Primary_SetFormat

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)


General Functions

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

General_LoadStaticBuffer

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)


General_LoadStreamBuffer

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)


General_DeleteSound

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)


General_PlaySound

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)


General_PauseSound

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)


General_StopSound

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)


Listener Functions

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


Listener_GetAllParameters

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


Listener_SetAllParameters

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)


Listener_GetDistanceFactor

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


Listener_SetDistanceFactor

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)


Listener_GetDopplerFactor

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


Listener_SetDopplerFactor

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)


Listener_GetOrientation

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.


Listener_SetOrientation

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)


Listener_GetPosition

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


Listener_SetPosition

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)


Listener_GetRolloffFactor

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


Listener_SetRolloffFactor

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)


Listener_GetVelocity

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


Listener_SetVelocity

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)


Buffer2D Functions

These fifteen functions control all the 2D functions of a specific sound buffer.

Information Buffer2D_GetCaps
Buffer2D_GetFormat
Buffer2D_GetStatus
Buffer2D_IsBufferStreaming
Play management Buffer2D_GetPosition
Buffer2D_SetPosition
Buffer2D_GetStreamRestartPosition
Buffer2D_SetStreamRestartPosition
Buffer2D_SeekBufferToStart
Sound management Buffer2D_GetFrequency
Buffer2D_SetFrequency
Buffer2D_GetPan
Buffer2D_SetPan
Buffer2D_GetVolume
Buffer2D_SetVolume

Buffer2D_GetCaps

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)


Buffer2D_GetFormat

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)


Buffer2D_GetStatus

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)


Buffer2D_IsBufferStreaming

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)


Buffer2D_GetPosition

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)


Buffer2D_SetPosition

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)


Buffer2D_SeekBufferToStart

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)


Buffer2D_GetFrequency

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)


Buffer2D_SetFrequency

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)


Buffer2D_GetPan

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)


Buffer2D_SetPan

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)


Buffer2D_GetVolume

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)


Buffer2D_SetVolume

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)


Buffer3D Functions

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

Buffer3D_GetAllParameters

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)


Buffer3D_SetAllParameters

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)


Buffer3D_GetMaxDistance

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)


Buffer3D_SetMaxDistance

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)


Buffer3D_GetMinDistance

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)


Buffer3D_SetMinDistance

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)


Buffer3D_GetMode

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)


Buffer3D_SetMode

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:
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.
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)


Buffer3D_GetPosition

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)


Buffer3D_SetPosition

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)


Buffer3D_GetConeAngles

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)


Buffer3D_SetConeAngles

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)


Buffer3D_GetConeOrientation

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)


Buffer3D_SetConeOrientation

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)


Buffer3D_GetConeOutsideVolume

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.

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 = Buffer3D_GetConeOutsideVolume(Sound)


Buffer3D_SetConeOutsideVolume

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)


Buffer3D_GetVelocity

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.

Remarks:

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)


Buffer3D_SetVelocity

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)


Private Functions

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

Private_NextAvailableBuffer

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.

Remarks:

The maximum number of sound buffers is specified by the MaxBuffers constant.

Example:

Dim Buf As Integer

Buf = Private_NextAvailableBuffer


Private_RestoreStaticBuffer

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

Returns:

This function returns True if the buffer was successfully restored or False if it was not.

Remarks:

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

Returns:

This function returns True if the buffer was successfully restored or False if it was not.

Remarks:

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)


Private_UpdateStreams

This function updates all playing streaming sound buffers with new data.

Syntax:

Private_UpdateStreams()

Remarks:

This function is called by a system timer with the interval specified in the UpdateInterval constant.

Example:

Private_UpdateStreams


Appendix

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 :

  1. Copy the appropriate TLB file(s) into the Windows\System folder.
  2. Choose References under the Project menu and check the appropriate library (for the first time use the browse button to register the 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.