DirectTransition3D Xtra Set I
DirectTransition3D Xtra Set II
DirectTransition3D Xtra Set III
Special Discounted Bundles
How To Order
Check for Upgrades
Change Your Profile
DirectSound Xtra™ Documentation
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.
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:
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 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
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.
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.
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 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.
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 :
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.
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.
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.
Stops the sound. If it is not playing, this has no effect.
Returns the total byte size of the sound data for the sound.
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.
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.
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.
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.
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.
Returns TRUE if the sound is currently playing. Returns FALSE if the sound has stopped or has never been started.
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.
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.
Close the DirectSound Xtra and return control to Director/Authorware sound system.
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].
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.
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.
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).
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).
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
Retrieves the current rolloff factor. The default value is 1.0
ds3DLSetRolloffFactor( float RolloffFactor )
Sets the rolloff factor. The default value is 1.0
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.
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.
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.
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.
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.
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.
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.
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: email@example.com
E-mail Technical Support: firstname.lastname@example.org
Copyright © 1996-2004 DirectXtras Inc. All Rights Reserved.