CompositionSurfaceBrush Class

Definition

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

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)

Applies to

See also