[This is preliminary documentation and subject to change.]
Merging enhancement streams causes the two streams to be interleaved by event time. For example, if you have a stream with events A and B occurring at 15 and 30 seconds after start, and a second stream with events C and D occurring at 20 and 45 seconds after start, the merged stream has events in the order A, C, B, and then D.
This functionality can be useful if your application needs to combine events from different stream files. For example, if one stream contains only announcement events and the other only trigger events, you can merge the two streams to create a stream that contained both types of events.
Merging enhancement streams is different from including one stream in another. When you include an enhancement stream in another, the timing of the events in the included stream is relative to the time of the event that includes the stream. When you merge a stream into a pre-existing stream, the timing of events in the merged stream is relative to the starting time of the pre-existing stream.
To merge an enhancement stream into the current stream, call the EnhEvents.Load method and specify the file name of the stream that you want to merge into the current stream. The events in the new stream are merged with the events specified in the EnhEvents collection for the current stream. The following example demonstrates this functionality.
Dim evs As IEnhEvents
Set evs = New EnhEvents
'Load the first stream
'This example loads a pre-existing stream to simplify the code.
'You can also create a new stream and add events to it.
evs.Load("Stream1.str")
'merge Stream2 with Stream1
evs.Load("Stream2.str")
If you want the timing of the events in the merged stream to be relative to a time other than the starting time of the pre-existing or newly created stream, you can set the timing offset in the EnhEvents.LoadBias property. The following example merges a third stream into the previous example. The timing of events in the third stream is relative to the thirtieth minute of the show.
evs.LoadBias = evs.ParseTime("30:00.0")
evs.Load("Stream3")
The preceding example uses EnhEvents.ParseTime method to convert the time, formatted as a string, to a Double value. You can alternately specify the offset time in seconds. The following example performs processing identical to that of the preceding.
evs.LoadBias = 1800
evs.Load("Stream3")
Set LoadBias back to zero when you no longer require an offset, otherwise, all subsequently loaded streams will be offset by LoadBias seconds.
If you wish to load a second stream without merging it into the current stream, you can call EnhEvents.Clear to empty the stream of events before you load the second stream. This causes the second stream to replace the previously-loaded stream instead of merging with it.