MULTIMEDIA

Programming with DirectX : Sound in DirectX - XAudio2

7/6/2011 6:01:52 PM
Audio2 is the Direct Sound replacement for Windows developers and is an enhanced version of the XAudio API that Xbox developers have been enjoying for some time. In this article we will create a demo that will play a sound file once and then exit. This demo will show you how to get XAudio2 up and working to play sound inside any application.

XAudio2 does not have a way to detect and convert audio files between incompatible endian orders. This means that if you are working directly with XAudio2 on Xbox 360 and Windows, you must handle endian order carefully.


XAUDIO2 Demo

Like XACT3, XAudio2 has an interface that you create to use XAudio2. This interface is called IXAudio2, and it is created by calling the SDK function XAudio2Create(). On the Xbox 360 this is an actual API function, while on Windows, according to the DirectX documentation, it is a convenient inline function defined in XAudio2.h. XAudio2Create() has the following function prototype and takes as parameters the IXAudio2 object that will be created, creation flags (defaults to 0 or XAUDIO2_DEBUG_ENGINE for debug mode), and an audio processor that specifies which CPU XAudio2 should use, which has a default value of XAUDIO2_DEFAULT_PROCESSOR.

HRESULT XAudio2Create(
IXAudio2 **ppXAudio2,
UINT32 Flags = 0,
XAUDIO2_PROCESSOR XAudio2Processor = XAUDIO2_DEFAULT_PROCESSOR
);

On the Xbox 360, XAudio2 is implemented as a statically linked library, while on Windows it is a COM object implemented by a dynamic link library.


XAudio2 uses something known as voices to manipulate and control audio. There are three types of these voices in the XAudio2 API: source voices, submix voices, and mastering voices. A source voice is used to send sound data to the other types of voices, and it represents an audio stream of data. A submix voice is used to process audio data from a source voice to perform various effects (e.g., sample rate conversion) and can also be used as an input voice to another submix voice or to a mastering voice. A mastering voice is the voice that is audible, and it sends that data it receives from source and submix voices to the audio hardware. The mastering voice is the only voice that allows you to hear anything, so you must create this voice in XAudio2 to hear anything.

As far as the basics of XAudio2 are concerned this is essentially what you need to play audio in the API. In the XAudio2 demo’s main source file the function calls CoInitializeEx() because XAudio2 is a COM object in Windows. It creates the XAudio2 engine, and it creates the mastering voice that will play the actual sound. In the demo the loading and playing of the actual file are done in a function called PlayPCM(), which will be discussed later in this section.

The creation of the mastering voice is done with a call to CreateMasteringVoice(), which takes as parameters an address to an IXAudio2MasteringVoice object that will store the created voice object, the audio channels, the audio sample rate, flags for the voice (which must be set to 0), the output device index the voice will use, and an optional audio effects chain using the structure XAUDIO2_EFFECT_CHAIN. The audio channels are set to XAUDIO2_DEFAULT_CHANNELS and default to 5.1 surround on Xbox 360. In Windows, XAudio2 attempts to determine the speaker configuration.

The main() function in the XAudio2 demo is shown in Listing 1. To recap, the function initializes COM, creates the audio engine, creates the mastering voice, loads and plays the sound with a call to PlayPCM() that will be implemented next, and exits the application after releasing the audio engine and uninitializing COM.

Listing 1. The XAudio2 Demo’s main() Source File
int main(int args, char* argc[])
{
cout << "XAudio2 Demo: Playing clip.wav" << endl << endl;
cout << "Demo will end when the sound is done." << endl << endl;

if(FAILED(CoInitializeEx(NULL, COINIT_MULTITHREADED)))
return 0;

IXAudio2* xAudio2Engine = NULL;

UINT32 flags = 0;
#ifdef _DEBUG
flags |= XAUDIO2_DEBUG_ENGINE;
#endif

if(FAILED(XAudio2Create(&xAudio2Engine)))
{
cout << "XAudio2 engine was not created!" << endl;
CoUninitialize();
return 0;
}

IXAudio2MasteringVoice *masterVoice = NULL;

if(FAILED(xAudio2Engine->CreateMasteringVoice(&masterVoice,
XAUDIO2_DEFAULT_CHANNELS, XAUDIO2_DEFAULT_SAMPLERATE,
0, 0, NULL)))
{
cout << "Master voice was not created!" << endl;

if(xAudio2Engine != NULL)
xAudio2Engine->Release()

CoUninitialize();
return 0;
}

if(PlayPCM(xAudio2Engine, "clip.wav") == false)
{
cout << "clip.wav failed to load!" << endl;

if(xAudio2Engine != NULL)
xAudio2Engine->Release()

CoUninitialize();
return 0;
}

if(xAudio2Engine != NULL)
xAudio2Engine->Release()

CoUninitialize();

return 1;
}


An audio file is loaded and played with a call to PlayPCM(). This function is a modified version of the PlayPCM() function offered in the Microsoft DirectX SDK sample XAudio2BasicSound. To load and play sounds we will use this function as well as the files SDKwavefile.h and SDKwavefile.cpp. The SDKwavefile files are part of the DirectX Utility (DXUT) library and can be found in any of the DXUT samples in the DirectX SDK. Since these files are part of DirectX, we will use them instead of writing some very long and complicated code for loading audio files. Since the files use DXUT, they have been slightly altered so that the use of the SDKwavefile files does not require any of the other DXUT headers or source files.

The PlayPCM() function uses the CWaveFile class defined in SDKwavefile.h to open the audio file. The file is read by calling the Read() function, which takes as parameters a buffer to read into, the size to read in bytes, and an out pointer to the size of bytes read by the function.

Once the file is loaded, the source voice is created. Keep in mind that the source voice represents a stream of audio data. To create the source voice, which has an interface of IXAudio2SourceVoice, we call the CreateSourceVoice() function of the XAudio2 engine object. This function takes the source voice that will be created, the format of the audio (using the WAVEFORMATEX structure provided by Windows), behavior flags, the maximum frequency ratio, a callback interface function, a send list of source voices for the destination of the audio date (optional), and an audio effect chain. The behavior flags can have one of the following values:

  • XAUDIO2_VOICE_NOPITCH for no pitch control

  • XAUDIO2_VOICE_NOSRC for no sample rate conversion

  • XAUDIO2_VOICE_USEFILTER to enable filter effects on the sound

  • XAUDIO2_VOICE_MUSIC to state that the voice is used to play background music

Once the source voice is created, an audio buffer using the XAudio2 structure XAUDIO2_BUFFER is created. This buffer will take the sound data and submit it to the sound voice, which can only happen after a valid sound voice has been created by CreateSoundVoice(). The audio buffer has the audio data assigned to the pAudioData variable, the audio flags to the Flags variable, and the size of the audio to the AudioBytes variable. The flag of XAUDIO2_END_OF_STREAM tells XAudio2 that there is no more data to follow after the sound has played.

To submit the data to the source voice, you call SubmitSourceBuffer() on the source voice object, which takes as a parameter the XAUDIO_BUFFER object. If all is successful, you can start processing the sound by calling Start() on the source voice. The Start() function takes as parameters behavior flags that must be set to 0 and an operation set. The operation set can be XAUDIO2_COMMIT_NOW to apply the operation immediately or XAUDIO2_COMMIT_ALL to apply all pending operations.

When a source voice is processing, it is being played. You can test the state of the sound by calling the GetState() function on the source voice object. This will return an XAUDIO2_VOICE_STATE object that you can test for various states. To test if the sound is still playing you can test if the BuffersQueued variable is greater than 0.

Once you are done with a source voice, you free it by calling DestroyVoice(). The entire PlayPCM() function is shown in Listing 2 with all the code we’ve just discussed in the previous few paragraphs. This function essentially loads a sound, plays it, and then frees it from memory. As a bonus exercise you should separate the loading and playing code into their own functions and allow the sound to be played multiple times before it is freed.

Listing 2. The PlayPCM() Function
bool PlayPCM(IXAudio2* xAudio2Engine, char *filename)
{
CWaveFile wav;

if(FAILED(wav.Open(filename, NULL, WAVEFILE_READ)))
return false;
WAVEFORMATEX *format = wav.GetFormat();
unsigned long wavSize = wav.GetSize();
unsigned char *wavData = new unsigned char[wavSize];

if(FAILED(wav.Read(wavData, wavSize, &wavSize)))
{
if(wavData)
delete[] wavData;

return false;
}


IXAudio2SourceVoice *srcVoice;

if(FAILED(xAudio2Engine->CreateSourceVoice(&srcVoice, format,
Other  
  •  Programming with DirectX : Sound in DirectX - XACT3 (part 2) - XACT3 Demo
  •  Programming with DirectX : Sound in DirectX - XACT3 (part 1) - XACT3 Tools
  •  iPhone 3D Programming : Image-Processing Example: Bloom
  •  iPhone 3D Programming : Anisotropic Filtering: Textures on Steroids
  •  iPhone 3D Programming : Reflections with Cube Maps
  •  Silverlight Recipes : Networking and Web Service Integration - Accessing Resources over HTTP
  •  Silverlight Recipes : Networking and Web Service Integration - Using JSON Serialization over HTTP
  •  Microsoft XNA Game Studio 3.0 : Displaying Images - Using Resources in a Game (part 4) - Filling the Screen
  •  Microsoft XNA Game Studio 3.0 : Displaying Images - Using Resources in a Game (part 3) - Sprite Drawing with SpriteBatch
  •  Microsoft XNA Game Studio 3.0 : Displaying Images - Using Resources in a Game (part 2) - Positioning Your Game Sprite on the Screen
  •  
    Most View
    Tips And Tricks To Set You Apart From The Tech Crowd (Part 5)
    Data For Eternity (Part 1)
    Windows 8 : Customizing the Appearance of Windows - Personalizing the Lock Screen Background - Choose a Lock Screen Image
    How To Tidy The Windows 8 UI (Part 2)
    Sharepoint 2010 : Using an External Data Column, Building a Composite Application
    Group Test - Monitors Under $300 (Part 2) : Liyama ProLite E2473HS, HannsG HL249DPB, BenQ GW2750HM
    Micro ATX Motherboard Gigabyte F2A88XM DS2
    iphone SDK 3 : Working with Databases - Basic Database Operations
    The Cowon EM1 Earphones - Musically Yours
    Synology 4-Bay NAS: Three Models Review (Part 3)
    Top 10
    Windows Phone 8 : Microsoft Office Mobile - Excel (part 10) - Entering Formulas,AutoSum
    Windows Phone 8 : Microsoft Office Mobile - Excel (part 9) - Sharing a Spreadsheet, Fitting and Hiding Text
    Windows Phone 8 : Microsoft Office Mobile - Excel (part 8) - Accessing Charts and Sheets, Saving a Spreadsheet
    Windows Phone 8 : Microsoft Office Mobile - Excel (part 7) - Undo and Redo, Charting
    Windows Phone 8 : Microsoft Office Mobile - Excel (part 6) - Sorting a Column, Filtering
    Windows Phone 8 : Microsoft Office Mobile - Excel (part 5) - Freezing a Pane, Applying Formatting Options
    Windows Phone 8 : Microsoft Office Mobile - Excel (part 4) - Selecting Multiple Cells, Viewing Cell Text
    Windows Phone 8 : Microsoft Office Mobile - Excel (part 3) - Viewing and Navigating Comments,Searching a Spreadsheet
    Windows Phone 8 : Microsoft Office Mobile - Excel (part 2) - Adding a Comment to a Cell, Changing the Comment Author
    Windows Phone 8 : Microsoft Office Mobile - Excel (part 1) - Creating a New Spreadsheet, Working with the Excel Interface