Microsoft DirectX 8.0 (C++)

IDirectMusicSegmentState8::GetObjectInPath

Retrieves an interface for an object in the audiopath on which this segment state is playing.

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 following values.
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. For information on DMO interfaces, see IDirectSoundBuffer8::GetObjectInPath.
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 following error values.

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:

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

IDirectMusicAudioPath8::GetObjectInPath, Retrieving Objects from an Audiopath