IDirectMusicSegmentState8::GetObjectInPath

DirectMusic

previous page next page
Microsoft DirectX 9.0 SDK Update (Summer 2004)

IDirectMusicSegmentState8::GetObjectInPath

The GetObjectInPath method retrieves an interface for an object in the audiopath on which this segment state is playing.

Syntax

HRESULT GetObjectInPath(
  DWORD dwPChannel,
  DWORD dwStage,
  DWORD dwBuffer,
  REFGUID guidObject,
  DWORD dwIndex,
  REFGUID iidInterface,
  Void** ppObject
);

Parameters

dwPChannel

Performance channel to search, or DMUS_PCHANNEL_ALL to search all channels. The first channel is numbered 0. See Remarks.

dwStage

Stage in the path. Can be one of the values listed in the following table.

Value Description
DMUS_PATH_AUDIOPATH The audiopath on which the segment state is playing.
DMUS_PATH_AUDIOPATH_GRAPH The audiopath toolgraph. One is created if none exists.
DMUS_PATH_AUDIOPATH_TOOL A tool from the audiopath toolgraph.
DMUS_PATH_BUFFER A DirectSound buffer.
DMUS_PATH_BUFFER_DMO A DMO in the buffer.
DMUS_PATH_MIXIN_BUFFER A global mix-in buffer.
DMUS_PATH_MIXIN_BUFFER_DMO A DMO in a global mix-in buffer.
DMUS_PATH_PERFORMANCE The performance.
DMUS_PATH_PERFORMANCE_GRAPH The performance toolgraph. One is created if none exists.
DMUS_PATH_PERFORMANCE_TOOL A tool in the performance graph.
DMUS_PATH_PORT The synthesizer.
DMUS_PATH_PRIMARY_BUFFER The primary buffer.
DMUS_PATH_SEGMENT The segment that owns this segment state.
DMUS_PATH_SEGMENT_GRAPH The segment toolgraph. One is created if none exists. See Remarks.
DMUS_PATH_SEGMENT_TOOL A tool from the segment graph. See Remarks.
DMUS_PATH_SEGMENT_TRACK A track from the segment. See Remarks.

dwBuffer

If dwStage is DMUS_PATH_BUFFER_DMO or DMUS_PATH_MIXIN_BUFFER_DMO, the index of the buffer in which that DMO resides. If dwStage is DMUS_PATH_BUFFER or DMUS_PATH_MIXIN_BUFFER, the index of the buffer. Otherwise must be 0.

guidObject

Class identifier of the objector 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

Index of the object in the 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

Identifier of the desired interface, such as IID_IDirectMusicGraph.

ppObject

Address of a variable that receives a pointer to the requested interface.

Return Values

If the method succeeds, the return value is S_OK or DMUS_S_GARBAGE_COLLECTED. See Garbage Collection.

If it fails, the method can return one of the error values shown in the following table.

Return code
DMUS_E_NOT_FOUND
E_INVALIDARG
E_NOINTERFACE
E_OUTOFMEMORY

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:

Value
DMUS_PATH_AUDIOPATH_TOOL
DMUS_PATH_BUFFER
DMUS_PATH_BUFFER_DMO
DMUS_PATH_PERFORMANCE_TOOL
DMUS_PATH_PORT
DMUS_PATH_SEGMENT_TOOL

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

  1. dwStage.
  2. guidObject. If this value is not GUID_All_Objects, only objects whose class identifier equals guidObject are searched. However, this parameter is ignored when only a single class of object can exist at the specified stage.
  3. dwPChannel. If the stage is channel-specific and this value is not DMUS_PCHANNEL_ALL, only objects on the channel are searched.
  4. 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.
  5. dwIndex. Note that tracks in segments created by DirectMusic Producer are not necessarily in the same order as they were in that application. Do not rely on dwIndex alone to find a particular track at stage DMUS_PATH_SEGMENT_TRACK.

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

The object returned when DMUS_PATH_SEGMENT_GRAPH or DMUS_PATH_SEGMENT_TOOL is specified in dwStage might not be the same one returned for a different segment state based on the same segment. When a segment is played, its toolgraph is copied and any tools that support the IDirectMusicTool8::Clone method are also cloned.

Requirements

  Header: Declared in dmusici.h.

See Also

© 2004 Microsoft Corporation. All rights reserved.



previous page start next page