Search Tips Advanced Search |
| Delphi Graphics and Game Programming Exposed with DirectX 7.0 by John Ayres Wordware Publishing, Inc. ISBN: 1556226373 Pub Date: 12/01/99
Search this book:
Previous | Table of Contents | Next
Buffer Memory Format The memory in a DirectSound sound buffer is conceptually circular. Basically, this means that when DirectSound comes to the end of a buffer, it automatically goes back to the beginning. Think of sound buffer memory like the surface of a cylinder, as illustrated by Figure 9-2. Each buffer contains a play and write pointer into the memory containing the audio data. The current play position indicates the offset of the next byte that will be sent to the mixer. The current write position is located beyond the current play position and indicates the first byte in the buffer at which it is safe to write new data. The data located between the play and write positions is queued for playback and should never be altered. The write position maintains a distance of approximately 15 milliseconds of play time ahead of the play position. Nevertheless, applications should be writing data to the buffer well ahead of the current write position to allow for any delays in moving the data into the buffer. This information is typically useful only when dealing with streaming buffers, as the application must track the point at which it is safe to stream more audio data into the buffer. Figure 9-2 Sound buffer memory is conceptually circular Audible Focus The final important concept when dealing with sound buffers is that of audible focus. When a sound buffer is created, the developer can determine if the sound will continue to be heard when another application receives focus. By default, sounds will not be heard when the application loses focus (although they continue to play silently). A sound buffer can be given Global focus upon creation, indicating that the sound will always be audible unless another application receives focus and obtains exclusive access to the audio hardware (it will continue to play when the application is in the background). Alternatively, a sound buffer can have Sticky focus, indicating that it will be audible unless another application using DirectSound receives focus. Initialization As with DirectDraw, there are several steps the developer must follow to set up DirectSound before loading and playing sound buffers. Some of these steps are somewhat optional, but in general, DirectSound is instantiated by performing the following: • Enumerating audio devices • Creating the DirectSound object • Setting the cooperative level • Retrieving audio device capabilities • Setting the format of the primary buffer Enumerating Audio Devices DirectSound provides a function that returns information for every audio output device with an installed hardware driver detected in the system. As a general rule, it is unnecessary for most applications to enumerate all audio output devices. The user can select a preferred audio output device through the Multimedia control panel applet, and DirectSound should be created using this selection unless there is good reason to do otherwise. However, if the developer wants the application to check all available audio drivers for certain capabilities, or just wishes to provide the user with a list of available audio drivers to choose from, the DirectSoundEnumerate function is used. The DirectSoundEnumerate function is defined as:
    function DirectSoundEnumerate(

    lpDSEnumCallback: TDSEnumCallback;        // a pointer to the callback function

    lpContext: Pointer                        // an application-defined value

    ): HResult;                               // returns a DirectX error code
The first parameter is a pointer to a user-defined callback function. DirectSoundEnumerate prepares a list of every installed audio driver and sends information about each one, one at a time, to this user-defined callback function. This information includes the GUID for the device, the description of the device, and the module name of the DirectSound driver for the device. The other parameter is a 32-bit user-defined value (this is defined as a pointer but is intended for application-specific use and is ignored by the function). The TDSEnumCallback callback function itself is defined as:
    function TDSEnumCallback(

    lpGuid: PGUID;                    // the audio device GUID

    lpstrDescription: PAnsiChar;      // a description of the device

    lpstrModule: PAnsiChar;           // the module name

    lpContext: Pointer                // the user-defined value

    ): BOOL;                          // returns TRUE or FALSE
The first parameter is the GUID for the enumerated audio device. The second and third parameters contain textual information describing the audio device. The final parameter contains the user-defined value passed to the original DirectSoundEnumerate function. Every time the callback function is called, it should return a value of TRUE to continue the enumeration or FALSE if no other driver information is required. The first device enumerated by this function is always the preferred audio output device selected by the user, as described above. This device is known as the primary sound driver.
| primary sound driver: The audio output device selected by the user on the Audio tab of the Multimedia control panel applet.
Actually, this is not a true device enumeration, as no GUID will be returned for this device and the callback function will only receive a description string of “Primary Sound Driver” for the purpose of displaying it in a list. Once the primary sound driver has been enumerated, the callback function is called once for every available sound card.
| Note: On any system with a sound card, the callback function will be called at least twice: once for the primary sound driver and once for the actual sound card hardware. A GUID will be received on the second and subsequent calls.
The following example demonstrates the use of the DirectSoundEnumerate function to retrieve the names of all available audio drivers installed on the system.
Previous | Table of Contents | Next

Products | Contact Us | About Us | Privacy | Ad Info | Home Use of this site is subject to certain Terms & Conditions, Copyright © 1996-2000 EarthWeb Inc. All rights reserved. Reproduction whole or in part in any form or medium without express written permission of EarthWeb is prohibited. Read EarthWeb's privacy statement.