| Microsoft DirectX 9.0 SDK Update (Summer 2003) |
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.
Syntax
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 is NULL.
- dwFlags
- [in] Direct pass-through. This value is passed to the dwFlagsparameter when the call to IDirectSoundBuffer::Play is made. For more information, see IDirectSoundBuffer8::Play. This parameter must be 0 if lpdsSourceBuffer is NULL.
- lpUserBuffer
- [out] Pointer to memory where the reserved buffer is placed.
Return Value
Returns DV_OK if successful, or one of the following error values.
DVERR_ALREADYBUFFERED There is already a user buffer for the specified ID. DVERR_INVALIDOBJECT The DirectPlay object pointer is invalid. DVERR_INVALIDPARAM One or more of the parameters passed to the method are invalid. DVERR_INVALIDPOINTER The pointer specified is invalid. DVERR_NOTALLOWED The object does not have the permission to perform this operation. DVERR_NOTCONNECTED The DirectPlay Voice object is not connected. DVERR_NOTINITIALIZED The IDirectPlayVoiceClient::Initialize or IDirectPlayVoiceServer::Initialize method must be called before calling this method. DVERR_OUTOFMEMORY There is insufficient memory to perform the requested operation. DVERR_SESSIONLOST The transport has lost the connection to the session.
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.