Windows apps
Collapse the table of content
Expand the table of content

Composition batch processing

[ Updated for UWP apps on Windows 10. For Windows 8.x articles, see the archive ]

Composition batches allow monitoring for the completion of a group of active animations or effects and trigger a callback when all members of the group have completed.

There are two types of composition batches, commit batches represented by CompositionCommitBatch, and scoped batches represented by CompositionScopedBatch.

Commit batches

A commit batch is a batch that is implicitly created during the commit cycle. The current Commit batch can be retrieved by calling Compositor.GetCommitBatch at any time during the commit cycle. The commit cycle is defined as the time between updates from the compositor. Updates are queued until the system is ready to process the changes and draw bits to the screen. Titles do not control when commits happen. The Commit batch will aggregate all objects within the commit cycle, those before and after GetCommitBatch was called.

The Commit batch is implicitly created on the composition thread, the thread which the compositor is created on. There can only be one compositor per thread hence one Commit batch per thread. A Commit batch must be retrieved in order declare the completed event. A Commit batch will be implicitly closed at the end of each commit cycle and cannot be suspended or resumed, this will result in an error if attempted.

The following example shows using a commit batch to recieve notification that an animation has completed.



private void UsingCommitBatch()
{
  //Create Scoped batch for animations
  CompositionCommitBatch batch =  Compositor.GetCommitBatch(CompositionBatchTypes.Animation);
 
  //Setup completion event 
  batch.Completed += CommitBatchCompleted;
 
  //Setup animations
  Animation1(_target);
}
 
// Creates and defines the Keyframe animation 
private void Animation1(Visual targetVisual)
{
  var animation1 = _compositor.CreateVector3KeyFrameAnimation();
 
  animation1.InsertKeyFrame(0.0f, new Vector3(100.00f, 100.00f, 0.00f));
  animation1.InsertKeyFrame(0.5f, new Vector3(300.00f, 100.00f, 0.00f));
  animation1.InsertKeyFrame(1.0f, new Vector3(500.00f, 100.00f, 0.00f));
 
  animation1.Duration = TimeSpan.FromMilliseconds(2000);
  targetVisual.StartAnimation("Offset", animation1);
}
 
public void CommitBatchCompleted(object sender, CompositionBatchCompletedEventArgs args)
{
  _root.Children.Remove(_target);
}      
          

Scoped batches

A scoped batch is explicitly created using Compositor.CreateScopedBatch and is used to designate specific objects to be included in a single batch. A Scoped batch can be created on any thread and is not tied to the composition thread. Scoped batches will only aggregate objects within the thread it is created.

 

CompositionScopedBatch may be explicitly paused with Suspend() in order to exclude objects from that batch. When a batch is suspended it can be reopened by calling Resume.

 

A CompositionScopedBatch must be explicitly closed using End. Once it has been closed it cannot be suspended or resumed again.

 

Multiple CompositionScopedBatch instances can be created and can span across commit cycles. This means a CompositionScopedBatch can be created in one commit cycle and suspended/resumed/end in a later commit cycle. When a CompositionScopedBatch is open and actively collecting objects it is possible to overlap with several other batches. Batch finish events are orthogonal to one another and are not chained.

The following example shows using multiple scoped batchs to recieve notifications when different groups of animations have completed.



private void CreateVisuals_Click(object sender, RoutedEventArgs e)
{
        
    _target = _compositor.CreateSpriteVisual();
    childvisual.Brush = _compositor.CreateColorBrush( Windows.UI.Colors.Orange );
    childVisual.Size = new Vector2(250, 20);

        
    //Create Scoped batch1 for animations
    _batch1 = _compositor.CreateScopedBatch(CompositionBatchTypes.Animation);
 
    //Create Scoped batch2 for animations
    _batch2 = _compositor.CreateScopedBatch(CompositionBatchTypes.Animation);
 
    //batch1 completion event
    _batch1.Completed += OnBatchCompleted1;
 
    //Add animation to batch1 & batch2
    Animation1(_target);
 
    //Stop aggregating for batch1
    _batch1.Suspend();
            
    //Add an animation to batch2
    Animation2(_target);
 
    //Reopen batch1
    _batch1.Resume();
 
    //Add another animation to batch1 & batch2
    Animation3(_target);
 
    //batch2 completion event
    _batch2.Completed += OnBatchCompleted2;
 
    //Close batch2 and event should fire
    _batch2.End();
 
    //Add an animation to batch1
    Animation4(_target);
 
    //Close batch1 and event should fire
    _batch1.End();
 
}
 
private void OnBatchCompleted2(object sender, CompositionBatchCompletedEventArgs args)
{
 
    ((SpriteVisual)_target).Brush.Color = Colors.Red;
}
 
public void OnBatchCompleted1(object sender, CompositionBatchCompletedEventArgs args)
{
    _root.Children.Remove(_target);
}
        
private void Animation1(SpriteVisual targetVisual)
{
    var animation1 = _compositor.CreateVector3KeyFrameAnimation();
 
    animation1.InsertKeyFrame(0.0f, new Vector3(100.00f, 100.00f, 0.00f));
    animation1.InsertKeyFrame(0.5f, new Vector3(300.00f, 100.00f, 0.00f));
    animation1.InsertKeyFrame(1.0f, new Vector3(500.00f, 100.00f, 0.00f));
            
    animation1.Duration = TimeSpan.FromMilliseconds(2000);
            
    targetVisual.StartAnimation("Offset", animation1);
}
        
private void Animation2(SpriteVisual targetVisual)
{
  ...
}
private void Animation3(SpriteVisual targetVisual)
{
  ...
}
        
private void Animation4(SpriteVisual targetVisual)
{
  ...
}
      
          

 

 

Show:
© 2018 Microsoft