IDirectPlayVoiceClient::Create3DSoundBuffer

Retrieves a 3-D sound buffer for a player or group. You can use the methods of the 3-D sound buffer object to change the virtual 3-D position of incoming voice transmissions from the specified group or player.

HRESULT Create3DSoundBuffer(
DVID dvID,
LPDIRECTSOUNDBUFFER lpdsSourceBuffer,
DWORD dwPriority,
DWORD dwFlags,
LPDIRECTSOUND3DBUFFER* lpUserBuffer
);

Parameters

dvID

[in] Variable of type DVID that specifies the identification of the player or group that the user wants to reserve a buffer for. You can also specify DVID_REMAINING to create a 3-D user buffer for all players or groups that do not have a user buffer. If DVID_REMAINING is specified, the lpdsSourceBuffer parameter must be set to NULL and the dwPriority and dwFlags parameters must be set to 0.

lpdsSourceBuffer

[in] Pointer to an IDirectSoundBuffer interface, which is used to create the Microsoft® DirectPlay® Voice main buffer. This can be either NULL or a user-created Microsoft DirectSound® buffer. If this member is set to NULL, then DirectPlay Voice creates a buffer for you.

dwPriority

[in] Direct pass-through. This value is passed in the dwPriority parameter when the call to IDirectSoundBuffer::Play is made. For more information, see IDirectSoundBuffer8::Play. This parameter must be 0 if lpdsSourceBuffer parameter is set to NULL.

dwFlags

[in] Direct pass-through. This value is passed to the dwFlags parameter when the call to IDirectSoundBuffer::Play is made. For more information, see IDirectSoundBuffer8::Play. This parameter must be 0 if lpdsSourceBuffer is set to NULL.

lpUserBuffer

[in] Pointer to memory where the reserved buffer is placed.

Return Values

Returns DV_OK if successful, or one of the following error values.

Remarks

If the DirectPlay voice session is a mixing server session, this method fails and returns DVERR_NOTALLOWED.

Although you can access all the member functions of the 3-D sound buffer object, because the DirectPlay voice client uses the buffer to stream incoming audio, do not use the Lock, UnLock, or Play methods of the DirectSound3DBuffer object.

If the user specifies a buffer, DirectPlay uses that buffer for the player's or group's buffer. User-created buffers have the following restrictions.

• The buffer must be 22 kilohertz, 16-bit, Mono format.
• The buffer must be at least 1 second in length.
• The buffer must have been created with the DSBCAPS_GETCURRENTPOSITION2 and DSBCAPS_CTRL3D flags.
• The buffer must not be a primary buffer.
• The buffer must not be playing when it is passed to DirectPlay.

If the buffer is not the right format, the method will return DVERR_INVALIDBUFFER.

The buffer must not be locked when you pass it to DirectPlay. When the buffer for the individual user is no longer required or when a player leaves the voice session, it is important to call IDirectPlayVoiceClient::Delete3DSoundBuffer to free up resources.

If the buffer or a portion of the buffer is locked when DirectPlay Voice attempts to write to it, the method will return DVERR_INVALIDBUFFER. If you lock the buffer after the method has returned, you will receive a DVMSGID_SESSIONLOST message. The hResult member of the associated structure will be set to DVERR_LOCKEDBUFFER. Subsequent method calls will return a DVERR_NOTCONNECTED error code.

Requirements

  Windows NT/2000/XP: Available as a redistributable for Windows 2000 and later.
  Windows 98/Me: Available as a redistributable for Windows 98 and later.
  Header: Declared in Dvoice.h.