Prepare Time

^{Prepare Time}

As a segment is played, the performance makes repeated calls to the segment's tracks, causing them to generate messages for a specified time range, which is a 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 time.

Each time it calls on a track to play messages, the performance calculates the end time for that call by adding the prepare time to the current time. For example, if the current time is 10,000 milliseconds (or the equivalent in reference time units) and the prepare time is the default 1000 milliseconds, the end time is at 11,000. The result is that all new messages that are to be played up to time 11,000 must be prepared and placed in the queue.

Most applications don't 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 IDirectMusicPerformance8::PlaySegment or IDirectMusicPerformance8::PlaySegmentEx.

If you set a start time of "now" for the segment without specifying DMUS_SEGF_AFTERPREPARETIME, the performance invalidates any messages currently in the queue. Any tracks that are still valid at this point (for example, tracks of secondary segments, which continue to play) then have to resend their messages, taking into account any changes made to the environment by the new segment. This causes extra processing and might also lead to undesired results.

You can use the DMUS_SEGF_AFTERPREPARETIME flag to specify that the segment isn't to start playing until all messages currently in the queue have been processed and passed to the port buffer. If messages up to time 10,000 are in the queue and the current time is 9,000, a segment cued to play immediately, but flagged DMUS_SEGF_AFTERPREPARETIME, starts playing just after the 10,000 mark.

See Also

• IDirectMusicPerformance8::GetPrepareTime
• IDirectMusicPerformance8::SetPrepareTime
• Latency and Bumper Time
• Segment Timing.