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

• Microsoft Windows 95 or 98 (NT users see the Appendix for additional information.)
• Microsoft DirectX 6 Runtimes
• At least one digital sound device.
• Microsoft Visual Basic 5 or up (Preferably with Service Pack 3 installed)
• Both the DirectX 6 and Win32 type libraries available from Patrice’s web site. (See Appendix for locations.)

Update History

Version 1.21 (12/09/98)

• Fixed an acuracy error that occured with Buffer2D_GetPosition and streaming buffers that are played looped. The function would return a negative value or would return a missaligned value once the buffer got near the end. This problem has now been fixed and all looping streaming buffers will report the value correctly for all positions. This problem did not occur with streaming buffers that were not looped. Also, any streaming buffer that had the General_StopSound function called on it or had just been created, reported the position equaling the size of the buffer. This has been fixed now.
• Complete rewrite of Private_UpdateStreams was done in order to fix several bugs that crept in as a result of the updates done in Version 1.2. Streaming buffers now play properly with byte offsets and byte lengths set. Also the Buffer2D_SetPosition function has been updated acordingly.
• The Private_RestoreStaticBuffer and Private_RestoreStreamingBuffer have been updated to work with byte offsets and byte lengths.

Version 1.2 (02/09/98)

• The General_LoadStaticBuffer and General_LoadStreamBuffer functions have been updated. They now optionally accept a byte offset and a byte length for the sound filename. You can use these two values to specify the byte offset and length of the wave data if the data is stored inside another file. Using these two arguments you can easily access files that have multiple sounds stored in them.

Version 1.1 (30/08/98)

• Fixed the timing issue for the Buffer2D_GetPosition, Buffer2D_SetPosition and Buffer2D_SeekBufferToStart functions and streaming buffers. The position that is set or returned is the actual position and the delay experienced in version 1.0 no longer exists. One note about the Buffer2D_SetPosition function, if you use this function in rapid succession you may experience a popping sound. This occurs because the buffer is stopped and played again each time the position is set. You should avoid setting the position in rapid succession.

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.

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 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

Returns:

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:

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.

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.

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)

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.

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)

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)

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.

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

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

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)

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)

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)

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)

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.

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)

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)

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)

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)

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)

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)

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)

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)

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.

Buffer2D_GetCaps

Use this function to get the capabilities of a specific sound buffer.

Syntax:

Buffer2D_GetCaps(SoundNumber As Integer) As DSBCAPS

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

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

Returns:

This function returns one of the following:

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

Returns:

This function returns one of the following:

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

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)

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

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)

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)

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

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)

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

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)

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

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)

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.

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

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)

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

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)

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

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)

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

Returns:

This function returns one of the following:

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)

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

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)

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)

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)

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

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)

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

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)

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

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)

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.

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

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

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.