| Platform SDK: DirectX |
As a segment is played, the performance makes repeated calls to the segment's tracks, causing them to generate messages for the supplied time range, which is some fraction of a second. These messages are then placed in the queue behind those that were generated in previous calls. By default, about a second's worth of messages are in the queue at any given time.
For an illustration, see Latency and Bumper Time.
The queue is like a gas tank that is constantly being topped off by calls to IDirectMusicTrack::Play. Each time the performance calls Play, it calculates the end time for that call by adding the prepare time to the current time. If the current time is 10,000 milliseconds (or the equivalent in REFERENCE_TIME units) and the prepare time is the default 1000 ms, the end time is 11,000—that is, all new messages that are to play up to time 11,000 must be prepared and placed in the queue.
The size of the queue can be changed by calling the IDirectMusicPerformance::SetPrepareTime method, and the current size can be retrieved by using IDirectMusicPerformance::GetPrepareTime.
Most applications do not need to change the default prepare time, and the process just described is not visible to the application. However, it is helpful to understand the concept of prepare time because of the DMUS_SEGF_AFTERPREPARETIME flag, which the application can pass to IDirectMusicPerformance::PlaySegment.
The queue is like a gas tank that is constantly being topped off. Each time the performance calls on the segment to send messages, it calculates the end time for that call by adding the prepare time to the current time. If the current time is 10,000 milliseconds and the prepare time is the default 1000 ms, the end time is 11,000—that is, all new messages that are to play up to time 11,000 must be prepared and placed in the queue.
The size of the queue can be changed by calling the DirectMusicPerformance.SetPrepareTime method, and the current size can be retrieved by using DirectMusicPerformance.GetPrepareTime.
Most applications do not need to change the default prepare time, and the process just described is not visible to the application. However, it is helpful to understand the concept of prepare time because of the DMUS_SEGF_AFTERPREPARETIME flag, which the application can pass to DirectMusicPerformance.PlaySegment.
Normally, if you set a start time of "now" for the segment, the performance invalidates any messages currently in the queue. Any tracks that are still valid at this point (for example, tracks of secondary segments that continue to play despite the introduction of a new primary segment) then have to resend their messages, taking into account any changes made to the musical environment by the new segment. To avoid unnecessary processing and to ensure continuity (for example, to ensure that a long note or nonmusical DLS sound is not cut short), you can use the DMUS_SEGF_AFTERPREPARETIME flag to specify that the segment is not to start playing until all messages currently in the queue have been processed and passed to the port buffer. So, for example, if messages up to time 10,000 are in the queue and the current time is 9,000, a segment cued to play immediately starts playing just after the 10,000 ms mark.
For more information, see Segment Timing.