Identifying the Track
When you set or retrieve a parameter by using IDirectMusicTrack8::SetParamEx or IDirectMusicTrack8::GetParamEx, the parameter is associated with the track on which the method is called. However, when you call IDirectMusicPerformance8::SetParam, IDirectMusicPerformance8::GetParam, IDirectMusicSegment8::SetParam, or IDirectMusicSegment8::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 DMUS_SEG_ANYTRACK or DMUS_SEG_ALLTRACKS. For example, the following call to IDirectMusicSegment8::SetParam turns off the tempo track so that looping a segment does not reset the tempo:
HRESULT hr = pIDMSegment->SetParam(GUID_DisableTempo, 0xFFFFFFFF,
DMUS_SEG_ALLTRACKS, 0, NULL);
There are times, however, when you need to specify 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. 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 it belongs to. The index value is determined by the order in which the tracks were inserted.
Suppose a segment contains the tracks shown in the following table.
| Track | Group bits |
| A | 0x1 |
| B | 0x2 |
| C | 0x1 |
| D | 0x3 |
Group 1 contains tracks A, C, and D, and group 2 contains tracks B and D. If you call GetParam 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 one bit in dwGroupBits, the parameter is retrieved from the nth track containing any of those bits, where n is the value in dwIndex.
See Also