CompositionSurfaceBrush Class

Definition

Namespace:

Windows.UI.Composition

Paints a SpriteVisual with pixels from an ICompositionSurface.

public ref class CompositionSurfaceBrush sealed : CompositionBrush

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 131072)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class CompositionSurfaceBrush final : CompositionBrush

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 131072)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class CompositionSurfaceBrush : CompositionBrush

Public NotInheritable Class CompositionSurfaceBrush
Inherits CompositionBrush

Inheritance

Object Platform::Object IInspectable CompositionObject CompositionBrush CompositionSurfaceBrush

Attributes

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows requirements

Device family	Windows 10 (introduced in 10.0.10586.0)
API contract	Windows.Foundation.UniversalApiContract (introduced in v2.0)

Examples

Draw an image asset onto a SpriteVisual

private SpriteVisual CreateImageVisual(ICompositionSurface imageSurface)
{
  SpriteVisual imageVisual = _compositor.CreateSpriteVisual();
  imageVisual.Size = new Vector2(300, 200);

  CompositionSurfaceBrush imageBrush = _compositor.CreateSurfaceBrush();
  imageBrush.Surface = imageSurface;

  // specify CompositionStretch on SurfaceBrush and horizontal/vertical alignment
  imageBrush.Stretch = CompositionStretch.UniformToFill;
  imageBrush.HorizontalAlignmentRatio = 0.5f;
  imageBrush.VerticalAlignmentRatio = 0.5f;

  imageVisual.Brush = imageBrush;
  return imageVisual;
}

Apply a custom scale transformation animation to a CompositionSurfaceBrush

private void AnimateBrushScale(SpriteVisual imageVisual)
{
  CompositionSurfaceBrush imageBrush = (CompositionSurfaceBrush)imageVisual.Brush;

  // set brush CenterPoint at the center of the content painted onto imageVisual 
  imageBrush.CenterPoint = imageVisual.Size / 2;

  // set up scale keyframe animation
  CompositionScopedBatch batch = _compositor.CreateScopedBatch(CompositionBatchTypes.Animation);
  Vector2KeyFrameAnimation scaleAnimation = _compositor.CreateVector2KeyFrameAnimation();
  scaleAnimation.InsertKeyFrame(1.0f, new Vector2(1.5f));
  scaleAnimation.Duration = TimeSpan.FromMilliseconds(500);

  // start animation on CompositionSurfaceBrush.Scale
  imageBrush.StartAnimation("Scale", scaleAnimation);

  // end animation batch and fire completion event
  batch.End();
  batch.Completed += ScaleAnimationBatch_Completed;
} 

Remarks

The Stretch property, in conjunction with the HorizontalAlignmentRatio and VerticalAlignmentRatio properties, is used to specify the scale and positioning of the CompositionSurfaceBrush’s contents when painted onto a SpriteVisual.

CompositionSurfaceBrush also has the following properties that enable custom transformations:

• AnchorPoint
• CenterPoint
• Offset
• RotationAngle
• RotationAngleInDegrees
• Scale
• TransformMatrix

The order of transformation operations on a CompositionSurfaceBrush is as follows:

1. The content of the CompositionSurfaceBrush is stretched and aligned onto the SpriteVisual (see Stretch, HorizontalAlignmentRatio, and VerticalAlignmentRatio properties).

2. Any other transformation properties set on the CompositionSurfaceBrush are applied.

   Custom transformations applied to a CompositionSurfaceBrush are therefore evaluated in the coordinate space of the SpriteVisual that the brush is painted onto. For example, setting an Offset of Vector2(100, 0) offsets the brush’s stretched and aligned contents by 100 units to the right relative to the left edge of the SpriteVisual it is painted onto.

Version history

Windows version	SDK version	Value added
1607	14393	AnchorPoint
1607	14393	CenterPoint
1607	14393	Offset
1607	14393	RotationAngle
1607	14393	RotationAngleInDegrees
1607	14393	Scale
1607	14393	TransformMatrix
1903	18362	SnapToPixels

Properties

AnchorPoint	The point on the brush to be positioned at the brush's offset. Value is normalized with respect to the size of the SpriteVisual.
BitmapInterpolationMode	Specifies the algorithm used for interpolating pixels from ICompositionSurface when they do not form a one-to-one mapping to pixels on SpriteVisual (as can happen under stretch, scale, rotation, and other transformations).
CenterPoint	The point about which the brush is rotated and scaled.
Comment	A string to associate with the CompositionObject. (Inherited from CompositionObject)
Compositor	The Compositor used to create this CompositionObject. (Inherited from CompositionObject)
Dispatcher	The dispatcher for the CompositionObject. (Inherited from CompositionObject)
DispatcherQueue	Gets the DispatcherQueue for the CompostionObject. (Inherited from CompositionObject)
HorizontalAlignmentRatio	Controls the positioning of the vertical axis of content with respect to the vertical axis of the SpriteVisual. The value is clamped from 0.0f to 1.0f with 0.0f representing the left vertical edge and 1.0f representing the right vertical edge of the SpriteVisual.
ImplicitAnimations	The collection of implicit animations attached to this object. (Inherited from CompositionObject)
Offset	The offset of the brush relative to its SpriteVisual.
Properties	The collection of properties associated with the CompositionObject. (Inherited from CompositionObject)
RotationAngle	The rotation angle, in radians, of the brush.
RotationAngleInDegrees	The rotation angle, in degrees, of the brush.
Scale	The scale to apply to the brush.
SnapToPixels	Gets or sets a value that indicates whether the surface brush aligns with pixels.
Stretch	Controls the scaling that is applied to the contents the ICompositionSurface with respect to the size of the SpriteVisual that is being painted.
Surface	The ICompositionSurface associated with the CompositionSurfaceBrush.
TransformMatrix	The transformation matrix to apply to the brush.
VerticalAlignmentRatio	Controls the positioning of the horizontal axis of content with respect to the horizontal axis of the SpriteVisual. The value is clamped from 0.0f to 1.0f with 0.0f representing the top horizontal edge and 1.0f representing the bottom horizontal edge of the SpriteVisual. The default value is 0.5f.

Methods

Close()	Closes the CompositionObject and releases system resources. (Inherited from CompositionObject)
ConnectAnimation(String, CompositionAnimation)	Connects and animation. (Inherited from CompositionObject)
DisconnectAnimation(String)	Disconnects an animation. (Inherited from CompositionObject)
Dispose()	Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. (Inherited from CompositionObject)
PopulatePropertyInfo(String, AnimationPropertyInfo)	Defines a property that can be animated. (Inherited from CompositionObject)
StartAnimation(String, CompositionAnimation, AnimationController)	Connects an animation with the specified property of the object and starts the animation. (Inherited from CompositionObject)
StartAnimation(String, CompositionAnimation)	Connects an animation with the specified property of the object and starts the animation. (Inherited from CompositionObject)
StartAnimationGroup(ICompositionAnimationBase)	Starts an animation group. The StartAnimationGroup method on CompositionObject lets you start CompositionAnimationGroup. All the animations in the group will be started at the same time on the object. (Inherited from CompositionObject)
StopAnimation(String)	Disconnects an animation from the specified property and stops the animation. (Inherited from CompositionObject)
StopAnimationGroup(ICompositionAnimationBase)	Stops an animation group. (Inherited from CompositionObject)
TryGetAnimationController(String)	Returns an AnimationController for the animation running on the specified property. (Inherited from CompositionObject)

See also

• CompositionBrush
• IClosable