CompositionSurfaceBrush CompositionSurfaceBrush CompositionSurfaceBrush CompositionSurfaceBrush Class

Definition

Paints a SpriteVisual with pixels from an ICompositionSurface.

public : sealed class CompositionSurfaceBrush : CompositionBrush
struct winrt::Windows::UI::Composition::CompositionSurfaceBrush : CompositionBrush
public sealed class CompositionSurfaceBrush : CompositionBrush
Public NotInheritable Class CompositionSurfaceBrush Inherits CompositionBrush
Inheritance
CompositionSurfaceBrushCompositionSurfaceBrushCompositionSurfaceBrushCompositionSurfaceBrush
Attributes

Windows 10 requirements

Device family
Windows 10 (introduced v10.0.10586.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v2)

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 AnchorPoint AnchorPoint 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 BitmapInterpolationMode BitmapInterpolationMode 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 CenterPoint CenterPoint CenterPoint

The point about which the brush is rotated and scaled.

Comment Comment Comment Comment

A string to associate with the CompositionObject.

(Inherited from CompositionObject)
Compositor Compositor Compositor Compositor

The Compositor used to create this CompositionObject.

(Inherited from CompositionObject)
Dispatcher Dispatcher Dispatcher Dispatcher

The dispatcher for the CompositionObject.

(Inherited from CompositionObject)
DispatcherQueue DispatcherQueue DispatcherQueue DispatcherQueue

Gets the DispatcherQueue for the CompostionObject.

(Inherited from CompositionObject)
HorizontalAlignmentRatio HorizontalAlignmentRatio HorizontalAlignmentRatio 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. By default this is set to 0.0f.

ImplicitAnimations ImplicitAnimations ImplicitAnimations ImplicitAnimations

The collection of implicit animations attached to this object.

(Inherited from CompositionObject)
Offset Offset Offset Offset

The offset of the brush relative to its SpriteVisual.

Properties Properties Properties Properties

The collection of properties associated with the CompositionObject.

(Inherited from CompositionObject)
RotationAngle RotationAngle RotationAngle RotationAngle

The rotation angle, in radians, of the brush.

RotationAngleInDegrees RotationAngleInDegrees RotationAngleInDegrees RotationAngleInDegrees

The rotation angle, in degrees, of the brush.

Scale Scale Scale Scale

The scale to apply to the brush.

SnapToPixels SnapToPixels SnapToPixels SnapToPixels

Gets or sets a value that indicates whether the surface brush aligns with pixels.

Stretch Stretch Stretch 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 Surface Surface Surface

The ICompositionSurface associated with the CompositionSurfaceBrush.

TransformMatrix TransformMatrix TransformMatrix TransformMatrix

The transformation matrix to apply to the brush.

VerticalAlignmentRatio VerticalAlignmentRatio VerticalAlignmentRatio 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 Close Close Close

Closes the CompositionObject and releases system resources.

(Inherited from CompositionObject)
PopulatePropertyInfo(String,AnimationPropertyInfo) PopulatePropertyInfo(String,AnimationPropertyInfo) PopulatePropertyInfo(String,AnimationPropertyInfo) PopulatePropertyInfo(String,AnimationPropertyInfo)

Defines a property that can be animated.

(Inherited from CompositionObject)
StartAnimation(String,CompositionAnimation) StartAnimation(String,CompositionAnimation) StartAnimation(String,CompositionAnimation) StartAnimation(String,CompositionAnimation)

Connects an animation with the specified property of the object and starts the animation.

(Inherited from CompositionObject)
StartAnimationGroup(ICompositionAnimationBase) StartAnimationGroup(ICompositionAnimationBase) StartAnimationGroup(ICompositionAnimationBase) 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)
StartAnimationGroupWithIAnimationObject(IAnimationObject,ICompositionAnimationBase) StartAnimationGroupWithIAnimationObject(IAnimationObject,ICompositionAnimationBase) StartAnimationGroupWithIAnimationObject(IAnimationObject,ICompositionAnimationBase) StartAnimationGroupWithIAnimationObject(IAnimationObject,ICompositionAnimationBase)

Starts an animation group on the specified target.

(Inherited from CompositionObject)
StartAnimationWithIAnimationObject(IAnimationObject,String,CompositionAnimation) StartAnimationWithIAnimationObject(IAnimationObject,String,CompositionAnimation) StartAnimationWithIAnimationObject(IAnimationObject,String,CompositionAnimation) StartAnimationWithIAnimationObject(IAnimationObject,String,CompositionAnimation)

Connects an animation with the specified property of the target object and starts the animation.

(Inherited from CompositionObject)
StopAnimation(String) StopAnimation(String) StopAnimation(String) StopAnimation(String)

Disconnects an animation from the specified property and stops the animation.

(Inherited from CompositionObject)
StopAnimationGroup(ICompositionAnimationBase) StopAnimationGroup(ICompositionAnimationBase) StopAnimationGroup(ICompositionAnimationBase) StopAnimationGroup(ICompositionAnimationBase)

Stops an animation group.

(Inherited from CompositionObject)
TryGetAnimationController(String) TryGetAnimationController(String) TryGetAnimationController(String) TryGetAnimationController(String)

Returns an AnimationController for the animation running on the specified property.

(Inherited from CompositionObject)

See also