Microsoft DirectX 9.0 SDK Update (October 2004)

Track Configuration

Using the IDirectMusicSegment8::SetTrackConfig and IDirectMusicSegmentState8::SetTrackConfig methods, an application can modify the behavior of any track in a segment. Configuration options include the following:

Enable or disable playback.
Enable or disable parameter calls on a track in a control segment.
Enable or disable notifications.
Override notifications in a primary segment with notifications from a secondary control segment.
Enable or disable track composition.
Control the start point of track data used in composing transitions.

For a list of the track configuration flags and a table of the flags valid on standard tracks, see IDirectMusicSegmentState8::SetTrackConfig.

Two of the configuration flags, DMUS_TRACKCONFIG_CONTROL_PLAY and DMUS_TRACKCONFIG_CONTROL_NOTIFICATION, extend the powers of secondary control segments. Normally, a secondary control segment manages only parameters that are obtained by the performance through calls to IDirectMusicTrack8::GetParam. Like any segment, the control segment can also make changes to the performance by sending messages. For example, it might change the volume of the performance. Such changes might appear to be overriding parameters in the primary segment, but they differ from true control changes in two ways:

They are valid only until a similar change is made by another segment. Control segment parameters cannot be overridden by other segments.
As long as they are not overridden, they remain valid even after the sending segment has finished playing. Control segment parameters are valid only until another segment becomes the control segment.

When the DMUS_TRACKCONFIG_CONTROL_PLAY or DMUS_TRACKCONFIG_CONTROL_NOTIFICATION flag is set on a track, the equivalent track on the primary segment is disabled. It is enabled again when the controlling segment stops.

The SetTrackConfig method is available on the IDirectMusicSegmentState8 interface as well as on IDirectMusicSegment8. The parameters are identical, but the effect differs as follows:

If you change a flag on a segment, subsequent instances of playing segment states inherit the changed flags. However, segment states that are already playing do not change their behavior.
If you change a flag on a segment state, the behavior changes only for that segment state. To ensure that the behavior changes immediately rather than after prepare time, you can call IDirectMusicPerformance8::Invalidate.

The following example code disables a chord progression track in the segment addressed by pSegment. Chord progressions are broadcast as control segment parameters, so the track is disabled by turning off the DMUS_TRACKCONFIG_CONTROL_ENABLED flag.

HRESULT hr = pSegment->SetTrackConfig(CLSID_DirectMusicChordTrack,
    -1, DMUS_SEG_ALLTRACKS, 0, DMUS_TRACKCONFIG_CONTROL_ENABLED);

The next example does the opposite, enabling all chord tracks to play:

hr = pSegment->SetTrackConfig(CLSID_DirectMusicChordTrack, 
    -1, DMUS_SEG_ALLTRACKS, DMUS_TRACKCONFIG_CONTROL_ENABLED, 0);

See Also