. DirectXtras Home
        Home

DirectCommunication Xtra
DirectConnection Xtra
DirectControl Xtra
DirectEmail Xtra
DirectFTP Xtra
DirectImage Xtra
DirectInteraction Xtra
DirectOS Xtra
DirectSMS Xtra
DirectSound Xtra
Documentation
License Agreement
Licensing Fees
Order Form
DirectTransition Xtra
DirectTransition3D Xtra Set I
DirectTransition3D Xtra Set II
DirectTransition3D Xtra Set III
DirectTTS Xtra
XtrAgent
DirectXport Xtra

SpeechPlugin

Special Discounted Bundles

The Gallery
How To Order
Order Form
Check for Upgrades

Sign in
Change Your Profile

Contact Us
















    .
DirectXtras
Xtra Power for Director & Authorware



DirectSound Xtra
 DirectSound Xtra

Authorware 4.x Compatible Authorware 5.x CompatibleAuthorware 6.x CompatibleAuthorware 7.x CompatibleDirector 5.x Compatible Director 6.x CompatibleDirector 7.x Compatible Director 8.x CompatibleDirector MX CompatibleDirector MX 2004 Compatible Director Shockwave Compatible and Safe     Windows Compatible   


DirectSound Xtra™ Documentation


 

Programmed by Tomer Berda, DirectXtras Inc.
Copyright 1996-2001.
Last updated: March 04, 2000.

Introduction

Harness the power of DirectSound to Director and Authorware.

DirectSound Xtra is a Scripting Xtra to enable Director and Authorware applications to use Microsoft's DirectSound API (part of the DirectX/Game SDK). The DirectSound API provides low-latency mixing, hardware acceleration, and direct access to sound devices.

Why Use DirectSound in Director and Authorware?

Director and Authorware for Windows is using the basic Windows API which only supports a single sound channel. The way this limitation has been worked around was by writing a custom code to handle sound mixing. However, sounds do not play immediately (there is some latency) and the mixing is CPU-intensive and is generally limited to a few sounds at a time. In addition, Director/Authorware only allows limited control of the sounds - essentially starting and stopping them and setting the volume.

The DirectSound API supports low-latency mixing and uses the PC sound hardware whereever possible (that is, when a DirectSound driver is available for the sound card). When the driver is available, DirectSound provides mixing with 20 milliseconds of latency or less. Also, sounds use memory on the sound card when available, using less of the computer's RAM.

In addition, DirectSound provides more control over sounds. You can get and set the sound position, volume, panning and frerquency. You can also control and manipulate 3D sounds.

Using the DirectSound Xtra

This Xtra is a Scripting Xtra, so to use DirectSound, you must create sounds in your scripts. All of this Xtra's methods begin with the letters "ds." The dsNewSound method returns an ID that must be passed to the other methods to interact with a particular sound. You may create as many sound as you wish (limited by the amount of memory), and manipulate them independently. You must keep track of the IDs.

All sounds must be stored as WAV files. Sound playback is asynchronous, so control is returned to Director/Authorware while the sound is playing.

Three-Dimensional Sound

DirectSound Xtra enables your movie to change the apparent position of a sound source, by using the ds3Dxxx methods (i.e. all the methods that starts with "ds3d"). Sound sources can be a point from which sounds radiate in all directions or a cone outside which sounds are attenuated. Applications can also modify sounds using Doppler shift. Although these effects are audible using standard loudspeakers, they are more obvious and compelling when the user wears headphones.

Perception of Sound Positions

In the real world, the perception of a sound's position in space is influenced by a number of factors, including the following:

Volume. The farther an object is from the listener, the quieter it sounds. This phenomenon is known as rolloff.

Arrival offset. A sound emitted by a source to the listener's right will arrive at the listener's right ear slightly before it arrives at the left ear. (The duration of this offset is approximately a millisecond.)

Muffling. The orientation of people's ears ensures that sounds coming from behind the listener are slightly muffled compared with sounds coming from in front of the listener. In addition, if a sound is coming from the listener's right, the sounds reaching the left ear will be muffled by the mass of the listener's head.

Although these are not the only cues people use to discern the position of sound, they are the main ones, and they are the factors that have been implemented in DirectSound's positioning system. When hardware that supports 3D sound becomes generally available, other positioning cues might be incorporated into the system, including the difference in how high- and low-frequency sounds are muffled by the mass of the listener's head and the reflections of sound off the listener's shoulders and external ear parts.

One of the most important sound-positioning cues is the apparent visual position of the sound source. If a projectile appears as a dot in the distance and grows to the size of an intercontinental missile before it roars past the viewer's head, for example, the sound will appear to have gone by the listener without much help from subtle cues.

Listeners

Listeners experience an identical sonic effect when an object moves in a 90-degree arc around them or if they move their heads 90 degrees relative to the object. Programmatically, however, it is often much simpler to change the position or orientation of the listener than to change to positions of every other object in a scene. DirectSound Xtra exposes this capability through the ds3DLxxx methods

Sound Cones

A sound with a position but no orientation is a point source; the farther the listener is from the sound, in any direction, the quieter the sound. A sound with a position and an orientation is a sound cone.

In DirectSound Xtra, sound cones include an inside cone and an outside cone. Within the inside cone, the volume is at the maximum level for that sound source. (Because DirectSound does not support amplification, the maximum volume level is zero; all other volume levels are negative values that represent an attenuation of the maximum volume.) Outside the outside cone, the volume is the specified outside volume added to the inside volume. If your movie sets the outside volume to -10,000, for example, the sound source will be inaudible outside the outside cone. Between the outside and inside cones, the volume changes gradually from one level to the other. The concept of sound cones is shown in the following illustration:

Technically, every 3D sound created by ds3DNewSound() method is a sound cone, but often these sound cones behave like omnidirectional sound sources. For example, the default value for the volume outside the sound cone is zero; unless the application changes this value, the volume will be the same inside and outside the cone, and sound will not have any apparent orientation. Additionally, you could make the sound-cone angles as wide as you want, effectively making the sound cone a sphere.

Designing sound cones properly can add dramatic effects to your movies. For example, imagine that you want to use the sound of a ghostly voice. Instead of simply playing the sound, you could create additional suspense in your application by using ds3Dxxx methods. Position the sound source in the center of a room, setting its orientation toward a door. Then, focus the sound cones to the width of the door and set the outside cone volume to -10,000 (inaudible). These characteristics, when combined, make it seem that the voice is emanating from a room that the user passes by.

Minimum and Maximum Distances

As a listener approaches a sound source, the sound gets louder. Past a certain point, however, it isn't reasonable for the volume to continue to increase; either the maximum (zero) has been reached, or the nature of the sound source imposes a logical limit. This is the minimum distance for the sound source. Similarly, the maximum distance for a sound source is the distance beyond which the sound does not get any quieter.

The minimum distance is especially useful when you must compensate for the difference in absolute volume levels of different sounds. Although a jet engine is much louder than a bee, for example, for practical reasons these sounds must be recorded at similar absolute volumes (16-bit audio doesn't have enough room to accommodate such different volume levels). An application might use a minimum distance of 100 meters for the jet engine and 2 centimeters for the bee. With these settings, the jet engine would be at half volume when the listener was 200 meters away, but the bee would be at half volume when the listener was 4 centimeters away. This concept is shown in the following illustration:


Position Versus Velocity

Every 3D sound and 3D listener has both a position and a velocity. From a graphics and animation standpoint, these characteristics seem quite similar. As one would expect, the position of a 3D sound or listener represents its location in 3D space. However, the velocity of that sound or listener does not represent how fast the object is moving in space. Rather, DirectSound uses the velocity of a given sound or listener to calculate Doppler-shift effects.

Velocity adjustments can be useful if you would like to exaggerate the Doppler shift of an object. For example, imagine that you want the sound of an oncoming race car to seem as though it is screaming past the listener. If you exaggerate the effects of Doppler shift for the listener, the exaggeration will affect all sound buffers that the listener hears. To exaggerate the effect for the race car alone, you could increase the velocity setting for the car's 3D sound.

The system handles cumulative Doppler-shift effects for you. If your movie's listener and the sound source have velocities, the system automatically calculates the relationship between the velocities and adjusts the Doppler effect accordingly.

Mono and Stereo Sources

Stereo sound sources are not particularly useful in 3D sound environments. In effect, a stereo signal consists of two separate monaural tracks played simultaneously on different speakers.

You should supply monaural sound sources when using DirectSound's 3D capabilities. Although the system can convert a stereo source into mono, there is no reason to supply stereo, and the conversion step wastes time.

Doppler Factor

DirectSound Xtra applies Doppler-shift effects to sounds, based on the listener's velocity in relation to one or more 3D sounds. DirectSound can apply to a sound up to 10 times the Doppler shift experienced in the real world by setting a Doppler factor. To set this factor, use the ds3DLSetDopplerFactor method. The Doppler factor can range from 0 to 10. A value of 0 means no Doppler shift is applied to a sound. Every other value represents a multiple of the Doppler shift experienced in the real world. In other words, a value of 1 means the Doppler shift experienced in the real world is applied to the sound; a value of 2 means two times the Doppler shift experienced in the real world, and so on. To retrieve the Doppler factor set for a 3D listener, use the ds3DLGetDopplerFactor method.

Listener Position and Velocity

You can set and retrieve a listener's position in 3D space by using the ds3DLSetPosition

and ds3DLGetPosition methods.

To set or retrieve the velocity value that DirectSound uses to calculate Doppler-shift effects for a listener, use the ds3DLSetVelocity and ds3DLGetVelocity methods. A listener's position is not affected by its velocity.

Listener Orientation

The listener's orientation plays a strong role in 3D effects processing. DirectSound approximates sound cues to provide the illusion that a sound is generated at a particular point in space. For more information about these cues, see Perception of Sound Positions.

Listener orientation is defined by the relationship between two vectors that share an origin: the top and front vectors. The top vector originates from the center of the listener's head and points straight up through the top of the head. The front vector also originates from the center of the listener's head, but it points at a right angle to the top vector, forward through the listener's face. The following illustration shows the directions of these vectors:

You can set and retrieve the listener's orientation by using the ds3DLSetOrientation and ds3DLGetOrientation methods. By default, the front vector is (0,0,1.0), and the top

vector is (0,1.0,0).

Rolloff Factor

Rolloff is the amount of attenuation that is applied to sounds, based on the listener's distance from the sound source. DirectSound can apply to a sound up to 10 times the rolloff experienced in the real world by setting a rolloff factor. To set this factor, use the ds3DLSetRolloffFactor method. The rolloff factor can range from 0 to 10. A value of 0 means no rolloff is applied to a sound. Every other value represents a multiple of the rolloff experienced in the real world. In other words, a value of 1 means the rolloff experienced in the real world is applied to the sound; a value of 2 means two times the rolloff experienced in the real world, and so on. To retrieve the rolloff factor, use the ds3DLGetRolloffFactor method.

Method Reference

dsOpen()

Intiate the DirectSound Xtra.

Since Microsoft's DirectSound does not support the previous Windows sound system it cannot coexsit within the Director and Authorware sound system. Use this method to intiate the DirectSound Xtra and the dsClose() method to return control to Director and Authorware origrinal sound system.

In most cases, you will have to close the Xtra just for playing a video.

Important Note : If you want to control 3D sounds, use ds3DOpen() method instead.

Returns 0 if an error occurs (DirectSound drivers not installed or DirectSound already opened).

dsNewSound(string fileName, int Mode)

Creates a new DirectSound and returns an ID. Returns 0 if an error occurs (usually not enough memory or the file cannot be found or opened).

The file specified should be a WAV file. This method uses Director's path resolution algorithm to find files, so you may specify a file in the current directory by its name. You can also specify the full path.

The second parameter Mode, can be one of the following :

0 - Indicates that the sound will be static. The entire sound will be read into memory.
-3 - Indicates that the sound will be static, and will support 3D control.

You can use all the ds3Dxxx methods only on sounds created that way.

Important Note : If you are not going to use 3D control on that sound, pass 0 as the second parameter to improve performance.

dsDelSound(int id)

Frees memory associated with the sound. The sound will stop playing if it is currently playing. It's important to free memory associated with unused sounds. Without enough memory, dsNewSound method will fail.

All memory is also freed if the Xtra itself is closed using dsClose method, so you don't have to delete every sound before closing the Xtra.

dsPlay(int id)

Begins playback of the sound. Playback should occur within 20 milliseconds of this call. This has no effect if the sound is already playing. To play back a sound which is already playing (that is, to mix it with itself), first duplicate the sound with dsDupSound, then play back the duplicate sound.

dsStop(int id)

Stops the sound. If it is not playing, this has no effect.

dsGetSize(int id)

Returns the total byte size of the sound data for the sound.

dsDupSound(int id)

Creates a duplicate instance of a sound and returns a unique ID.

This instance of the sound does not duplicate the sound data (so it does not use much memory), but it does allow for independent manipulation and playback of the sound. This is required if you want to play back the same sound more than once at the same time, possibly offset, and mix them together.

dsGetFreq(int id)

Returns the frequency of the sound, in samples per second. This value will be in the range of 100-100,000. (100hz - 100Khz).

dsSetFreq(int id, int frequency)

Sets the frequency of the sound, in samples per second. This value must be in the range of 100-100,000. If the value is zero, the frequency is reset to the current sound format.

dsGetVolume(int id)

Returns the volume of the sound, in hundredths of a dB. 0 is the loudest value, and -10000 (-100dB) is the minimum value (essentially silence). The scale is logarithmic, so a value which is 20 dB less than another is half as loud.

dsSetVolume(int id, int volume)

Sets the volume of the sound, in hundredths of a dB. 0 is the loudest value, and -10000 (-100 dB) is the minimum value (essentially silence). The scale is logarithmic, so a value which is 20 dB less than another is half as loud.

dsGetPan(int id)

Returns the pan value of the sound, in hundredths of a decibel (dB).

Zero is the neutral value for lPan and indicates that both channels are at full volume (that is, they are attenuated by zero decibels). At any other setting, one of the channels is at full volume and the other is attenuated. For example, 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 -10,000 means that the right channel is silent (the sound is "all the way to the left"), and a pan of 10,000 means that the left channel is silent (the sound is "all the way to the right").

The pan control is cumulative with volume control.

dsSetPan(int id, int pan)

Sets the pan value of the sound, in hundredths of a decibel (dB). See dsGetPan for more description.

dsGetPosition(int id)

Returns the current byte position of the playback head within the sound's data. This can be called both when the sound is playing or when it is stopped.

dsSetPosition(int id, int position)

Sets the position of the playback head. This can be called both when the sound is playing or when it is stopped.

dsIsPlaying(int id)

Returns TRUE if the sound is currently playing. Returns FALSE if the sound has stopped or has never been started.

dsGetLoop(int id)

Returns the value of the looping flag of the sound. TRUE means that the sound is (or will) loop, FALSE means that it will stop after playing once.

dsSetLoop(int id, int loopflag)

Sets the the looping flag of the sound. TRUE means that the sound is (or will) loop, FALSE means that it will stop after playing once.

dsGetCaps()

Retrieves the capabilities of the hardware device that is represented by DirectSound. The result value is a list that contain the capabilities of the sound device. Information retrieved in the list describes the maximum capabilities of the sound device and those currently available, such as the amount of onboard memory. You can use this information to fine-tune and optimize performance.

The resultValue = [ TotalHwMem, MaxHwMixingStatic, EmulDriver, CpuOverhead ]

TotalHwMem - Size, In bytes, of the amount of memory on the sound card that stores static sounds.

MaxHwMixingStatic - Specifies the maximum number of hardware static sounds.

EmulDriver - FALSE if the device does not have a DirectSound driver installed, so it is being emulated through the waveform audio functions. Performance degradation should be expected.

CpuOverhead - Description of the processing overhead, as a percentage of the central processing unit, needed to mix software sounds (those located in main system memory). This varies according to the bus type, the processor type, and the clock speed.

The play processing overhead for hardware sounds is 0 because the mixing is done by the sound device.

dsClose()

Close the DirectSound Xtra and return control to Director/Authorware sound system.

3D Sounds

Since functions can return only one value, the result value of the 3D functions that returns vectors are represented by a list with 3 values [X,Y,Z].

ds3DOpen()

Same as dsOpen() method except that opening DirectSound Xtra this way will let you control 3D sounds using ds3Dxxx() methods.

ds3DOpen() will fail if there is no DirectX drivers version 3 or later installed, while dsOpen() will work with all the versions of DirectX without the 3D sounds control.

ds3DLGetPosition()

Retrieves the listener's current position in meters. The result value is a vector.

ds3DLSetPosition( float X, float Y, float Z )

Sets the listener's current position in meters.

ds3DLGetOrientation()

Retrieves the listener's current orientation in vectors: a front vector and a top vector. The result value is a list with 6 values. The first 3 values are the front vector and the last three values are the top vector. 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).

ds3DLSetOrientation( float XFront, float YFront, float ZFront, float XTop, float YTop, float ZTop )

Sets the listener's current orientation in terms of two vectors: a front vector and a top vector. The result value is a list with 6 values. The first 3 values are the front vector and the last three values are the top vector. 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).

ds3DLGetVelocity()

Retrieves the listener's current velocity. The result value is a vector. Velocity is used only for Doppler effects. It does not actually move the listener. To change the listener's position, use ds3DLSetPosition. The default value is (0,0,0).

ds3DLSetVelocity( float X, float Y, float Z )

Sets the listener's velocity. Velocity is used only for Doppler effects. It does not actually move the listener. To change the listener's position, use ds3DLSetPosition. The default value is (0,0,0).

ds3DLGetDopplerFactor()

Retrieves the current Doppler effect factor. The Doppler factor has a range of 0 (no Doppler effects) to 10.0 (10 times the Doppler effects found in the physical world). The default value is 1.0

ds3DLSetDopplerFactor( float DopplerFactor )

Sets the current Doppler effect factor. The Doppler factor has a range of 0 (no Doppler effects) to 10.0 (10 times the Doppler effects found in the physical world). The default value is 1.0

ds3DLGetRolloffFactor()

Retrieves the current rolloff factor. The default value is 1.0

ds3DLSetRolloffFactor( float RolloffFactor )

Sets the rolloff factor. The default value is 1.0

ds3DGetPosition(int id)

Retrieves the sound's current position in meters. The result value is a vector.

ds3DSetPosition( int id, float X, float Y, float Z )

Sets the sound's current position in meters.

ds3DGetOrientation(int id)

Retrieves the orientation of the sound projection cone. The result value is a vector. The vector information represents the center of the sound cone. This method has no effect unless the cone angle and cone volume factor have also been set. The default value is (0,0,1.0)

ds3DSetOrientation( int id, float X, float Y, float Z )

Sets the orientation of the sound projection cone. This method has no effect unless the cone angle and cone volume factor have also been set.

ds3DGetVelocity(int id)

Retrieves the current velocity. Velocity is used for Doppler effects only. It does not actually move the sound.

ds3DSetVelocity( int id, float X, float Y, float Z )

Sets the sound buffer's current velocity. Velocity is used for Doppler effects only. It does not actually move the sound.

ds3DGetOutsideVolume(int id)

Retrieves the current cone outside volume.

ds3DSetOutsideVolume( int id, int Volume )

Sets the current cone outside volume, in hunderdths of decibels. Volume levels are represented by attenuation. Allowable values are between 0 (no attenuation) and -10,000 (silence). Amplification is not currently supported by DirectSound.

ds3DGetAngles(int id)

Retrieves the inside and outside angles of the sound projection cone. The result value is a list. The first value in the list is the inside cone angle, and the second value is the outside cone angle.

ds3DSetAngles( int id, int Inside, int Outside )

Sets the inside and outside angles of the sound projection cone. Each angle must be in the range of 0 degrees (no cone) to 360 degrees (the full sphere). The default value is 360.

ds3DGetMaxDistance(int id)

Retrieves the current maximum distance in meters. By default, the maximum distance value is infinite.

ds3DSetMaxDistance( int id, float MaxDistance )

Sets the current maximum distance in meters. By default, the maximum distance value is infinite.

ds3DGetMinDistance(int id)

Retrieves the current minimum distance in meters. By default, the minimum distance value is 1.0 meter.

ds3DSetMinDistance( int id, float MinDistance )

Sets the current minimum distance in meters. By default, the minimum distance value is 1.0 meter.



DirectXtras Inc.
P.O Box 2645, Menlo Park, CA, 94026, U.S.A
Voice: +1-415-5058249, Fax: +1-801-8585841
Toll Free: 1-800-4453093
E-mail General Information: info@directxtras.com
E-mail Technical Support: support@directxtras.com

Copyright © 1996-2004 DirectXtras Inc. All Rights Reserved.
WebMaster: tamar@directxtras.com
Last Updated: 10/2/2001 3:47:19 PM.