Microsoft DirectX 8.1 (Visual Basic)

DirectSoundSecondaryBuffer8.Play

The Play method causes the sound buffer to play from the play cursor.

Syntax

object.Play(flags As CONST_DSBPLAYFLAGS)

Parts

object

Resolves to a DirectSoundSecondaryBuffer8 object.

flags

One or more of the constants of the CONST_DSBPLAYFLAGS enumeration.

Error Codes

If the method fails, an error is raised and Err.Number may be set to one of the following error codes.

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

Remarks

Before this method can be used the first time, the application must call the DirectSound8.SetCooperativeLevel method.

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

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 can 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 Nonlooping sound with least time left to play is terminated and the new sound plays on the released voice. Nonlooping 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.

See Also