This topic pertains only to applications written in C++.

When you set or retrieve a parameter by using IDirectMusicTrack::SetParam or IDirectMusicTrack::GetParam, the parameter is associated with the track on which the method is called. However, when you call IDirectMusicPerformance::SetParam, IDirectMusicPerformance::GetParam, IDirectMusicSegment::SetParam, or IDirectMusicSegment::GetParam, DirectMusic needs to find the appropriate track.

Normally, you can let DirectMusic determine which track contains the desired parameter. To do this, set dwGroupBits to 0xFFFFFFFF and dwIndex to 0. For example, the following call to IDirectMusicSegment::SetParam turns off the tempo track so that looping a segment does not reset the tempo:

pIDMSegment->SetParam(GUID_DisableTempo, 0xFFFFFFFF, 0, 0, NULL);

There are times, however, when you need to identify a track. Typically, this would be the case when a segment contains multiple tracks of the same type. To set or retrieve the parameter on the desired track, you must identify it by group and index value.

Every track belongs to one or more groups, each group being represented by a bit in the dwGroupBits parameter of one of the methods under discussion. (The track is assigned to a group or groups when it is inserted in the performance. See IDirectMusicSegment::InsertTrack. In the case of segments loaded from a file, track groups are assigned by the author of the segment.)

A track is identified by a zero-based index value within each of the groups that it belongs to. The index value is determined by the order in which the tracks were inserted.

Suppose a segment contains the following tracks:

Group 1 contains tracks A, C, and D, and group 2 contains tracks B and D. If you call GetParam or SetParam with a value of 1 in dwGroupBits and a value of 0 in dwIndex, the parameter is retrieved from track A, which is the first track in group 1. If dwIndex is 1, the parameter is retrieved from track C, the second track in the group. Track D belongs to two groups, 1 and 2, so it can be identified as either dwGroupBits = 1 and dwIndex =2, or dwGroupBits = 2 and dwIndex = 1.

If you set more than 1 bit in dwGroupBits, the parameter is retrieved from the nth track containing any of those bits, where n is the value in dwIndex.