Microsoft DirectX 9.0 SDK Update (Summer 2004)

^{IDirectMusicPerformance8 Interface}

The IDirectMusicPerformance8 interface is the overall manager of playback. It is used for adding and removing ports, mapping performance channels to ports, playing segments, dispatching messages and routing them through tools, requesting and receiving event notification, and setting and retrieving various parameters. It also has several methods for getting information about timing and for converting time and music values from one system to another.

If an application needs two complete sets of music playing at the same time, it can do so by creating more than one performance. Separate performances have separate tempos, whereas all segments within one performance must play at the same tempo.

IDirectMusicPerformance8 supersedes the IDirectMusicPerformance interface and adds new methods.

In addition to the methods inherited from IUnknown, the IDirectMusicPerformance8 interface exposes the following methods, arranged by category.

Audiopaths

Method	Description
CreateAudioPath	Creates an audiopath from a configuration object.
CreateStandardAudioPath	Creates an audiopath with a standard configuration.
GetDefaultAudioPath	Retrieves the default audiopath.
SetDefaultAudioPath	Sets and activates the default audiopath for the performance.

Messages

Method	Description
AllocPMsg	Allocates memory for a performance message.
ClonePMsg	Makes a copy of a performance message.
FreePMsg	Frees memory allocated for a performance message.
SendPMsg	Sends a performance message.

MIDI conversion

Method	Description
MIDIToMusic	Converts a MIDI note value to a DirectMusic music value, using a supplied chord, subchord level, and play mode.
MusicToMIDI	Converts a DirectMusic music value to a MIDI note value.

Notifications

Method	Description
AddNotificationType	Adds a notification type to the performance.
GetNotificationPMsg	Retrieves a pending notification message.
RemoveNotificationType	Removes a previously added notification type from the performance.
SetNotificationHandle	Sets the event handle for notifications.

Parameters

Method	Description
GetGlobalParam	Retrieves global values from the performance.
GetParam	Retrieves data from a track.
GetParamEx	Retrieves data from a track, with support for self-controlling segments.
SetGlobalParam	Sets global values for the performance.
SetParam	Sets data on a track in the control segment.

Performance channels

Method	Description
AssignPChannel	Assigns a single performance channel to the performance and maps it to a port, group, and MIDI channel.
AssignPChannelBlock	Assigns a block of 16 performance channels to the performance and maps them to a port and a channel group.
PChannelInfo	Retrieves the port, group, and MIDI channel for a given performance channel.

Playback

Method	Description
GetSegmentState	Retrieves the currently playing primary segment state or the primary segment state that is playing at a given time.
IsPlaying	Ascertains whether a specified segment or segment state is currently being heard from the speakers.
PlaySegment	Begins playback of a segment.
PlaySegmentEx	Begins playback of a segment, with options for transition and audiopath.
Stop	Stops playback of a segment or segment state.
StopEx	Stops playback of a segment, segment state, or audiopath.

Ports

Method	Description
AddPort	Assigns a port to the performance.
RemovePort	Removes a port from the performance.

Timing

Method	Description
AdjustTime	Adjusts the internal performance time forward or backward.
GetBumperLength	Retrieves the interval between the time at which messages are placed in the port buffer and the time at which they begin to be processed by the port.
GetLatencyTime	Retrieves the latency time, which is the performance time being heard from the speakers plus the time required to queue and render messages.
GetPrepareTime	Retrieves the interval between the time when messages are sent by tracks and the time when the sound is heard.
GetQueueTime	Retrieves the earliest time in the queue at which messages can be flushed.
GetResolvedTime	Resolves a given time to a given boundary.
GetTime	Retrieves the current time of the performance.
MusicToReferenceTime	Converts a performance time in MUSIC_TIME format to performance time in REFERENCE_TIME format.
ReferenceToMusicTime	Converts a performance time in REFERENCE_TIME format to a performance time in MUSIC_TIME format.
RhythmToTime	Converts rhythm time to music time.
SetBumperLength	Sets the interval between the time at which messages are placed in the port buffer and the time at which they begin to be processed by the port.
SetPrepareTime	Sets the interval between the time when messages are sent by tracks and the time when the sound is heard.
TimeToRhythm	Converts music time to rhythm time.

Toolgraphs

Method	Description
GetGraph	Retrieves the toolgraph of a performance.
SetGraph	Replaces the performance's toolgraph.

Miscellaneous

Method	Description
CloseDown	Closes down the performance object.
DownloadInstrument	Downloads DLS instrument data to a port.
InitAudio	Initializes the performance and optionally sets up a default audiopath.
Invalidate	Flushes all queued messages from the supplied time forward and causes all tracks of all segments to resend their data from the given time forward.

Requirements

  Header: Declared in dmusici.h.

See Also

• DirectMusic Interfaces

---

© 2004 Microsoft Corporation. All rights reserved.