C3DSegment

C3DSegment

Purpose: Handles high level 3D segments. These segments contain a CAudioPath object and inherit from CSegment, C3DBuffer and C3DListener objects
Remark: The returns values are based on the DirectX9 constants except DM_FAILED
The functions raise a CDMusicException exception type with the error data.
Member functions:

Function: GetAudioPath
Declaration: CAudioPath& C3DSegment::GetAudioPath()
Purpose: Returns a reference to the internal audiopath
Parameters: none

Returns:

CAudioPath

A reference to an audiopath object

Top Index

Function: GetObjectPath
Declaration: HRESULT C3DSegment::GetObjectInPath(DWORD dwPChannel, DWORD dwStage, DWORD dwBuffer, REFGUID
guidObject,DWORD dwIndex,REFGUID iidInterface,void **ppObject)
Purpose: Retrieves an interface for an object in the audiopath
Parameters:

dwPChannel [in]: Performance channel to search, or DMUS_PCHANNEL_ALL to search all channels. The first channel is numbered 0. (See Remarks.)
dwStage [in]: Stage in the audiopath. Can be one of the values in the following table

Value	Description
DMUS_PATH_AUDIOPATH_GRAPH	Get the audiopath toolgraph. One is created if none exists.
DMUS_PATH_AUDIOPATH_TOOL	Get a tool from the audiopath toolgraph.
DMUS_PATH_BUFFER	Get a DirectSound buffer.
DMUS_PATH_BUFFER_DMO	Get a DMO in a buffer.
DMUS_PATH_MIXIN_BUFFER	Get a global mix-in buffer.
DMUS_PATH_MIXIN_BUFFER_DMO	Get a DMO in a global mix-in buffer.
DMUS_PATH_PERFORMANCE	Get the performance.
DMUS_PATH_PERFORMANCE_GRAPH	Get the performance toolgraph. One is created if none exists.
DMUS_PATH_PERFORMANCE_TOOL	Get a tool from the performance toolgraph.
DMUS_PATH_PORT	Get the synthesizer.
DMUS_PATH_PRIMARY_BUFFER	Get the primary buffer.

dwBuffer [in]: Index of the buffer (if dwStage is DMUS_PATH_BUFFER or DMUS_PATH_MIXIN_BUFFER), or index of the buffer in which the DMO resides (if dwStage is DMUS_PATH_BUFFER_DMO or DMUS_PATH_MIXIN_BUFFER_DMO
guidObject [in]: Class identifier of the object, or GUID_All_Objects to search for an object of any class. This parameter is ignored if only a single class of object can exist at the stage specified by dwStage, and can be set to GUID_NULL
dwIndex [in]: Index of the object within a list of matching objects. Set to 0 to find the first matching object. If dwStage is DMUS_PATH_BUFFER or DMUS_PATH_MIXIN_BUFFER, this parameter is ignored, and the buffer index is specified by dwBuffer
iidInterface [in]: Identifier of the desired interface, such as IID_IDirectMusicTool
ppObject [out]: Address of a variable that receives a pointer to the requested interface

Remarks

The value in dwPChannel must be 0 for any stage that is not channel-specific. Objects in the following stages are channel-specific and can be retrieved by setting a channel number or DMUS_PCHANNEL_ALL in dwPChannel:

DMUS_PATH_AUDIOPATH_TOOL
DMUS_PATH_BUFFER
DMUS_PATH_BUFFER_DMO
DMUS_PATH_PERFORMANCE_TOOL
DMUS_PATH_PORT

The precedence of the parameters in filtering out unwanted objects is as follows:

dwStage.
guidObject. If this value is not GUID_All_Objects, only objects whose class identifier equals guidObject are searched. However, this parameter is ignored for stages where only a single class of object can exist, such as DMUS_PATH_AUDIOPATH_GRAPH.
dwPChannel. If the stage is channel-specific and this value is not DMUS_PCHANNEL_ALL, only objects on the channel are searched.
dwBuffer. This is used only if dwStage is DMUS_PATH_BUFFER, DMUS_PATH_MIXIN_BUFFER, DMUS_PATH_BUFFER_DMO, or DMUS_PATH_MIXIN_BUFFER_DMO.
dwIndex.

If a matching object is found but the interface specified by iidInterface cannot be obtained, the method fails

Returns:

S_OK

Succeeds

Throws:

E_POINTER	An invalid pointer, usually NULL, was passed as a parameter
E_NOINTERFACE	No object interface is available
E_OUTOFMEMORY	Insufficient memory to complete the task
E_INVALIDARG	Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
DMUS_E_NOT_FOUND	The requested item is not contained by the object
DM_FAILED	Error, see DirectMidi causes

Top Index

Function: Initialize
Declaration: HRESULT C3DSegment::Initialize(CAPathPerformance &pPerformance,DWORD dwType,DWORD dwPChannelCount)
Purpose: Initializes the C3DSegment object
Parameters:

pPerformance [in]: Reference to an audiopath performance
dwType [in]: Type of internal audiopath:

Value	Description
DMUS_APATH_DYNAMIC_3D	One bus to a 3-D buffer. Does not send to environmental reverb.
DMUS_APATH_DYNAMIC_MONO	One bus to a mono buffer.
DMUS_APATH_DYNAMIC_STEREO	Two buses to a stereo buffer.
DMUS_APATH_SHARED_STEREOPLUSREVERB	Ordinary music setup

dwPChannelCount [in]: Number of performance channels in the path

Returns:

S_OK

Succeeds

Throws:

DMUS_E_NOT_INIT	A required object is not initialized or failed to initialize
DSERR_BUFFERLOST	The buffer memory has been lost and must be restored
E_INVALIDARG	Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
DM_FAILED	Error, see DirectMidi causes
E_POINTER	An invalid pointer, usually NULL, was passed as a parameter
E_NOINTERFACE	No object interface is available
DMUS_E_NOT_FOUND	The requested item is not contained by the object
E_OUTOFMEMORY	Insufficient memory to complete the task

Top Index

Function: Initialize
Declaration: HRESULT C3DSegment::Initialize(CAudioPath &Path)
Purpose: Initializes the C3DSegment object given an external shared audiopath. This audiopath is not released by the C3DSegment object destructor
Parameters:

Path [in]: Reference to an audiopath

Returns:

S_OK

Succeeds

Throws:

E_POINTER	An invalid pointer, usually NULL, was passed as a parameter
E_NOINTERFACE	No object interface is available
E_OUTOFMEMORY	Insufficient memory to complete the task
E_INVALIDARG	Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
DMUS_E_NOT_FOUND	The requested item is not contained by the object
DM_FAILED	Error, see DirectMidi causes

Top Index

Function: operator = (CSegment &Segment)
Declaration: C3DSegment::operator = (const CSegment &Segment)
Purpose: Clones a Segment to a C3DSegment object
Parameters:

CSegment [in]: Reference to a CSegment object

Returns:

C3DSegment

A cloned C3DSement. Important: It must be initialized before using 3D and audiopaths

Throws:

DM_FAILED	Error, see DirectMidi causes
E_POINTER	An invalid pointer, usually NULL, was passed as a parameter
E_OUTOFMEMORY	Insufficient memory to complete the task

Top Index

Function: operator = (C3DSegment &Segment)
Declaration: C3DSegment& C3DSegment::operator = (const C3DSegment &Segment)
Purpose: Clones a C3DSegment to another C3DSegment object
Parameters:

C3DSegment [in]: Reference to a C3DSegment object

Returns:

C3DSegment

A cloned C3DSement. Important: It must be initialized before using 3D and audiopaths

Throws:

DM_FAILED	Error, see DirectMidi causes
E_POINTER	An invalid pointer, usually NULL, was passed as a parameter
E_OUTOFMEMORY	Insufficient memory to complete the task

Top Index

Function: ReleaseSegment
Declaration: HRESULT C3DSegment::ReleaseSegment()
Purpose: Releases a 3D segment. Releases all internal objects
Parameters: none

Returns:

S_OK

Succeeds

Top Index

Function: SetVolume
Declaration: HRESULT C3DSegment::SetVolume(long lVolume,DWORD dwDuration)
Purpose: Sets the volume for the internal audiopath
Parameters:

lVolume [in]: Value that specifies the attenuation, in hundredths of a decibel. This value must be in the range from -9600 to 0. Zero is full volume
dwDuration [in]: Value that specifies the time, in milliseconds, over which the volume change takes place. A value of 0 ensures maximum efficiency

Returns:

S_OK

Succeeds

Throws:

DM_FAILED	Error, see DirectMidi causes
DMUS_E_NOT_INIT	A required object is not initialized or failed to initialize
E_INVALIDARG	Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method

Top Index