Microsoft DirectX 8.1 (C++)

IDirectMusicPerformance8

The IDirectMusicPerformance8 interface is the overall manager of music 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 music 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 obey separate tempo maps, and so play completely asynchronously, whereas all segments within one performance play in lock step.

IDirectMusicPerformance8 supersedes the IDirectMusicPerformance interface and adds new methods.

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

Audiopaths

Method Description
CreateAudioPath Creates an audiopath object that represents the stages in data flow from the performance to DirectSound buffers.
CreateStandardAudioPath Creates an object that represents the stages in data flow from the performance to DirectSound buffers.
GetDefaultAudioPath Retrieves the default audiopath.
SetDefaultAudioPath Sets and activates the default audiopath for the performance.

Messages

Method Description
AllocPMsg Allocates a performance message.
ClonePMsg Makes a copy of a performance message.
FreePMsg Frees 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 (created by the Microsoft Win32 CreateEvent function) 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.

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 Determines whether a particular segment or segment state is currently being heard from the speakers.
PlaySegment Begins playback of a segment.
PlaySegmentEx Begins playback of a segment with more options than PlaySegment.
Stop Stops playback of a segment or segment state.
StopEx Stops playback of an object.

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 amount of time 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 current latency time.
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 amount of time to buffer ahead of the port's latency for messages to be sent to the port for rendering.
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 data for an instrument 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.