IDirectSoundBuffer::Play

The IDirectSoundBuffer::Play method causes the sound buffer to play from the current position.

HRESULT Play(
  DWORD dwReserved1,  
  DWORD dwPriority,   
  DWORD dwFlags       
);

Parameters

dwReserved1

This parameter is reserved. Its value must be 0.

dwPriority

The priority for the sound. May be used by the voice manager to determine the priority of the sound when assigning hardware mixing resources. If the buffer was not created with LOC_DEFER flag, this value must be 0. The priority level is a DWORD with a range from 0 to ffffffff, with 0 being the lowest priory.

dwFlags

Flags specifying how to play the buffer. The following flag is defined:

DSBPLAY_LOOPING

Once the end of the audio buffer is reached, play restarts at the beginning of the buffer. Play continues until explicitly stopped. This flag must be set when playing primary sound buffers.

Voice Allocation flags

DSBPLAY_LOCHARDWARE

For buffers created with the DSBCAPS_LOCDEFER flag set, play this voice in a hardware buffer only. If the hardware has no available voices and no DSBPLAY_TERMINATEBY_xxx flags are set, the Play will fail. If neither DBSPLAY_LOCHARDWARE nor DBSPLAY_LOCSOFTWARE is set, the sound may be played in either software or hardware, depending on the availability of resources at the time the Play is issued. Note: This flag will only affect buffers that have been created with the DSBCAPS_LOCDEFER flag. This flag is incompatible with DSBPLAY_LOCSOFTWARE.

DSBPLAY_LOCSOFTWARE

For buffers created with the LOC_DEFER flag set, play this voice in a software buffer only. If neither DBSPLAY_LOCHARDWARE nor DBSPLAY_LOCSOFTWARE is set, the sound may be played in either software or hardware, depending on the availability of resources at the time the Play is issued. Note: This flag will only affect buffers that have been created with the DSBCAPS_LOCDEFER flag and if DSBPLAY_LOCSOFTWARE is set, no DSBPLAY_TERMINATEBY flags are allowed. This flag is incompatible with DSBPLAY_LOCHARDWARE.

Voice Management flags

DSBPLAY_TERMINATEBY_TIME

Enables hardware resource stealing. When used, it is guaranteed that the voice will play in hardware and the software HEL will not be used. If the hardware has no available voices, a currently playing buffer will be stopped to make room for the new buffer. The buffer to be prematurely terminated will be the one with the least time left to play. Note: Only buffers that have been created with the DSBCAPS_LOCDEFER flag are candidates for premature termination.

DSBPLAY_TERMINATEBY_DISTANCE

For 3-D buffers only. Enables hardware resource stealing. When used, it is guaranteed that the voice will play in hardware and the software HEL will not be used. If the hardware has no available voices, a currently playing buffer will be stopped to make room for the new buffer. The buffer to be prematurely terminated will be selected from buffers that are beyond their maximum distance, and have the buffer's DSBCAPS_ MUTE3DBYDISTANCE flag set. If there are no buffers beyond their maximum distances with MUTE3DBYDISTANCE flags set, the play will fail. Note: Only buffers that have been created with the DSBCAPS_LOCDEFER flag are candidates for premature termination.

DSBPLAY_TERMINATEBY_PRIORITY

Enables hardware resource stealing. When used, it is guaranteed that the voice will play in hardware and the software HEL will not be used. If the hardware has no available voices, a currently playing buffer will be stopped to make room for the new buffer. The buffer to be prematurely terminated will be the one with the lowest priority as set by the IDirectSoundBuffer::Play priority argument. DSBPLAY_TERMINATEBY_PRIORITY may not co-exist with DSBPLAY_TERMINATEBY_DISTANCE. Note: Only buffers that have been created with the DSBCAPS_LOCDEFER flag are candidates for premature termination.

Return Values

If the method succeeds, the return value is DS_OK.

If the method fails, the return value may be one of the following error values:

Remarks

This method will cause a secondary sound buffer to be mixed into the primary buffer and sent to the sound device. If this is the first buffer to play, it will implicitly create a primary buffer and start playing that buffer; the application need not explicitly direct the primary buffer to play.

If the buffer specified in the method is already playing, the call to the method will succeed and the buffer will continue to play. However, the flags defined in the most recent call supersede flags defined in previous calls.

Primary buffers must be played with the DSBPLAY_LOOPING flag set.

This method will cause primary sound buffers to start playing to the sound device. If the application is set to the DSSCL_WRITEPRIMARY cooperative level, this will cause the audio data in the primary buffer to be sent to the sound device. However, if the application is set to any other cooperative level, this method will ensure that the primary buffer is playing even when no secondary buffers are playing; in that case, silence will be played. This can reduce processing overhead when sounds are started and stopped in sequence, because the primary buffer will be playing continuously rather than stopping and starting between secondary buffers.

Voice allocation and voice management flags apply only to buffers created with the DSBCAPS_LOCDEFER flag set. If an IDirectSoundBuffer::Play is called with a voice allocation or voice management flag set on a buffer that was not created with the DSBCAPS_LOCDEFER flag set, the call will fail DSERR_INVALIDPARAM. DSBPLAY_TERMINATEBY_TIME and DSBPLAY_TERMINATEBY_DISTANCE cannot co-exist, but either may co-exist with DSBPLAY_TERMINATEBY_PRIORITY. In this case, the TIME or DISTANCE flag is used to determine which buffer should be terminated in the event of a priority tie.

Voice management flags summary. The following chart shows the behavior if the hardware has no free voices when a new Play is issued, assuming the buffer has been created with the DSBCAPS_LOCDEFER flag set:

Note  Before this method can be called on any sound buffer, the application should call the IDirectSound::SetCooperativeLevel method and specify a cooperative level, typically DSSCL_NORMAL. If IDirectSound::SetCooperativeLevel has not been called, the IDirectSoundBuffer::Play method returns with DS_OK, but no sound will be produced until IDirectSound::SetCooperativeLevel is called.

DSBPLAY_LOCHARDWARE and DSBPLAY_LOCSOFTWARE may not co-exist.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dsound.h.
  Import Library: Use dsound.lib.

See Also

IDirectSoundBuffer, IDirectSound::SetCooperativeLevel