Platform SDK: DirectX |
The IDirectSoundBuffer::Play method causes the sound buffer to play from the current position.
HRESULT Play( DWORD dwReserved1, DWORD dwPriority, DWORD dwFlags );
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:
DSERR_BUFFERLOST |
DSERR_HWUNAVAIL |
DSERR_INVALIDCALL |
DSERR_INVALIDPARAM |
DSERR_PRIOLEVELNEEDED |
If IDirectSound::SetCooperativeLevel has not been called, the method returns DS_OK, but no sound is produced until a cooperative level has been set.
If the buffer specified in the method is already playing, the call to the method succeeds and the buffer continues to play. However, the flags defined in the most recent call supersede flags defined in previous calls.
When called on the primary buffer, this method causes the buffer to start playing to the sound device. If the application has set the DSSCL_WRITEPRIMARY cooperative level, any audio data put in the primary buffer by the application is sent to the sound device. Under any other cooperative level, the primary buffer plays silence if no secondary buffers are playing. Primary buffers must be played with the DSBPLAY_LOOPING flag set. For more information, see Playing the Primary Buffer Continuously.
If the method is called with a voice allocation or voice management flag set on a buffer that was not created with the DSBCAPS_LOCDEFER flag, the call fails with DSERR_INVALIDPARAM.
DSBPLAY_TERMINATEBY_TIME and DSBPLAY_TERMINATEBY_DISTANCE cannot be combined, but either may be combined with DSBPLAY_TERMINATEBY_PRIORITY, in which case the DSBPLAY_TERMINATEBY_TIME or DSBPLAY_TERMINATEBY_DISTANCE flag is used to determine which buffer should be terminated in the event of a priority tie.
The following table shows the behavior of the method under various combinations of the voice allocation and voice management flags when no free hardware voices are available.
DSBPLAY_LOCHARDWARE | Neither DSBPLAY_LOCHARDWARE nor DSBPLAY_LOCSOFTWARE | DSBPLAY_LOCSOFTWARE | |
---|---|---|---|
DSBPLAY_TERMINATEBY_TIME | Sound with least time left to play is terminated and the new sound plays on the released voice. | Sound with least time left to play is terminated and the new sound plays on the released voice. | New sound plays in software. |
DSBPLAY_TERMINATEBY_DISTANCE | If any sounds currently playing in hardware are beyond their maximum distance and have the DSBCAPS_MUTE3DATMAXDISTANCE flag set, one of them is terminated and the new sound plays in hardware. Otherwise, the call fails. | If any sounds currently playing in hardware are beyond their maximum distance and have the DSBCAPS_MUTE3DATMAXDISTANCE flag set, one of them is terminated and the new sound plays in hardware. Otherwise, the new sound plays in software. | New sound plays in software. |
DSBPLAY_TERMINATEBY_PRIORITY | If the new sound's priority is higher than or equal to that of any sound currently playing in hardware, one of the lowest-priority sounds is terminated and the new sound plays in hardware. Otherwise, the call fails. | If the new sound's priority is higher than or equal to that of any sound currently playing in hardware, one of the lowest-priority sounds is terminated and the new sound plays in hardware. Otherwise, the new sound plays in software. | New sound plays in software. |
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.