//-----------------------------------------------------------------------------
//
// Sample Name: StreamData Sample
//
// Copyright (c) 1999-2001 Microsoft Corporation. All rights reserved.
//
//-----------------------------------------------------------------------------
Description
===========
The StreamData sample shows how to stream a wave file through a DirectSound
secondary buffer. It is similar to the PlaySound sample, but adds support
for streaming.
Path
====
Source: DXSDK\Samples\Multimedia\DSound\StreamData
Executable: DXSDK\Samples\Multimedia\DSound\Bin
User's Guide
============
Load a wave file by clicking Sound File. Select Loop Sound if you want it
to play repeatedly. Click Play.
Programming Notes
=================
For details on how to setup a non-streaming DirectSound buffer, see the
PlaySound sample.
The basic tasks to stream data from a wav file to a DirectSound buffer are
as follows:
* Set up DirectSound:
1. Call DirectSoundCreate to create a IDirectSound object
2. Call IDirectSound::SetCooperativeLevel to set the cooperative level.
3. Set the primary buffer format. This sample calls
DSUtil_SetPrimaryBufferFormat() to do just this.
* Create a DirectSound buffer and set up the notifications:
1. Read the wav file to get the wav file size, and the wav format
in the format a WAVEFORMATEX structure.
2. Choose a DirectSound buffer size. This is the amount of data that
DirectSound stores at once. You re-fill this buffer as sound plays
from this buffer. This is best for large sounds files that are not
possible to load all at once. For this sample, the buffer size is
~3 seconds of data.
3. Create a DirectSound buffer using the buffer size, and the wav file's
format. Also pass in DSBCAPS_CTRLPOSITIONNOTIFY flag. This allows the
buffer to send notification events to tell us whenever sound has finished
playing. However, using this flags limits the buffer to software only,
since hardware can not signal position notifications.
4. Set up the notifications on the buffer by calling
IDirectSoundBuffer::SetNotificationPositions. See InitDSoundNotification()
for an example of how this is done. When DirectSound plays past a
notification position it signals an Win32 event. When this event is signaled,
it is safe to fill that segment of data in the buffer with a new piece of
sound.
* Play the DirectSound buffer:
1. Call IDirectSoundBuffer::Restore on the buffer if the buffer was lost.
2. Next, fill the DirectSound buffer will the maximum amount of sound data.
Since all the sound can not fit into this buffer will be filled with new
sound data as this sound plays.
3. Call IDirectSoundBuffer::Play with the DSBPLAY_LOOPING flag set to
start the buffer playing. The looping flag needs to be set since the
buffer will need to continue playing after the end of the buffer is
reached since typically more sound needs to be played.
* Check to see if a notification is signaled:
1. Typically in the message pump check to see if the event was signaled.
The event tells us that a segment of data has been played so this
piece need to be filled. MsgWaitForMultipleObjects() works well as
the message pump for this purpose.
2. If the event has been signaled, then lock the section of the buffer
than has just been played and fill it with the next segment of wav
data. See HandleNotification() for how this works.
* When the entire sound has played:
When handling the event notification, keep track of how much data has
been put in the buffer. When the entire wav file has been put into the
buffer, and after DirectSound has played it all it is necessary to manually
stop the buffer since the buffer will continuously loop otherwise.
* Free DirectSound:
Simply call Release() on all the DirectSound objects that were created.
LGram16
e067522598