CanvasSpriteBatch Class

[Win10_10586] Efficiently draws multiple bitmaps.

Inheritance Hierarchy

SystemObject
Microsoft.Graphics.CanvasCanvasSpriteBatch

Namespace: Microsoft.Graphics.Canvas
Assembly: Microsoft.Graphics.Canvas (in Microsoft.Graphics.Canvas.dll) Version: 0.0.0.0

Syntax

Copy

public sealed class CanvasSpriteBatch : IDisposable, 
	ICanvasResourceCreatorWithDpi, ICanvasResourceCreator

The CanvasSpriteBatch type exposes the following members.

Properties

	Name	Description
	Device	[Win10_10586] Gets the device associated with this sprite batch.
	Dpi	[Win10_10586] Gets the dots-per-inch (DPI) of this sprite batch.

Top

Methods

	Name	Description
	ConvertDipsToPixels	[Win10_10586] Converts units from device independent pixels (DIPs) to physical pixels based on the DPI of this sprite batch.
	ConvertPixelsToDips	[Win10_10586] Converts units from physical pixels to device independent pixels (DIPs) based on the DPI of this sprite batch.
	Dispose	[Win10_10586] Finalizes the sprite batch and submits it to the CanvasDrawingSession.
	Draw(CanvasBitmap, Matrix3x2)	[Win10_10586] Adds a sprite to the sprite batch, drawn using a specific transform.
	Draw(CanvasBitmap, Vector2)	[Win10_10586] Adds a sprite to the sprite batch, drawn at a specified offset.
	Draw(CanvasBitmap, Rect)	[Win10_10586] Adds a sprite to the sprite batch, scaled to fill a rectangle.
	Draw(CanvasBitmap, Matrix3x2, Vector4)	[Win10_10586] Adds a sprite to the sprite batch, drawn using a specific transform and tinted
	Draw(CanvasBitmap, Vector2, Vector4)	[Win10_10586] Adds a sprite to the sprite batch, drawn at a specified offset and tinted.
	Draw(CanvasBitmap, Rect, Vector4)	[Win10_10586] Adds a sprite to the sprite batch, scaled to fill a rectangle and tinted.
	Draw(CanvasBitmap, Matrix3x2, Vector4, CanvasSpriteFlip)	[Win10_10586] Adds a sprite to the sprite batch, drawn using a specific transform, tinted and optionally flipped.
	Draw(CanvasBitmap, Rect, Vector4, CanvasSpriteFlip)	[Win10_10586] Adds a sprite to the sprite batch, scaled to fill a rectangle, tinted and optionally flipped.
	Draw(CanvasBitmap, Vector2, Vector4, Vector2, Single, Vector2, CanvasSpriteFlip)	[Win10_10586] Adds a sprite to the sprite batch, drawn at a specified offset, tinted with additional rotation and scale and optionally flipped.
	DrawFromSpriteSheet(CanvasBitmap, Matrix3x2, Rect)	[Win10_10586] Adds a sprite from a sprite sheet to the sprite batch, drawn using a specific transform.
	DrawFromSpriteSheet(CanvasBitmap, Vector2, Rect)	[Win10_10586] Adds a sprite from a sprite sheet to the sprite batch, drawn at a specified offset.
	DrawFromSpriteSheet(CanvasBitmap, Rect, Rect)	[Win10_10586] Adds a sprite from a sprite sheet to the sprite batch, scaled to fill a rectangle.
	DrawFromSpriteSheet(CanvasBitmap, Matrix3x2, Rect, Vector4)	[Win10_10586] Adds a sprite from a sprite sheet to the sprite batch, drawn using a specific transform and tinted
	DrawFromSpriteSheet(CanvasBitmap, Vector2, Rect, Vector4)	[Win10_10586] Adds a sprite from a sprite sheet to the sprite batch, drawn at a specified offset and tinted.
	DrawFromSpriteSheet(CanvasBitmap, Rect, Rect, Vector4)	[Win10_10586] Adds a sprite from a sprite sheet to the sprite batch, scaled to fill a rectangle and tinted.
	DrawFromSpriteSheet(CanvasBitmap, Matrix3x2, Rect, Vector4, CanvasSpriteFlip)	[Win10_10586] Adds a sprite from a sprite sheet to the sprite batch, drawn using a specific transform, tinted and optionally flipped.
	DrawFromSpriteSheet(CanvasBitmap, Rect, Rect, Vector4, CanvasSpriteFlip)	[Win10_10586] Adds a sprite from a sprite sheet to the sprite batch, scaled to fill a rectangle, tinted and optionally flipped.
	DrawFromSpriteSheet(CanvasBitmap, Vector2, Rect, Vector4, Vector2, Single, Vector2, CanvasSpriteFlip)	[Win10_10586] Adds a sprite from a sprite sheet to the sprite batch, drawn at a specified offset, tinted with additional rotation and scale and optionally flipped.
	IsSupported	Checks whether CanvasSpriteBatch is supported on the current operating system version.

Top

Remarks

This API is only available when running on Windows 10 build 10586 (released November 2015) or greater.

CanvasSpriteBatch allows multiple bitmaps to be drawn more efficiently than would be possible by calling DrawImage Overload directly. CanvasSpriteBatch supports the following features:

Sprites can be drawn with their own position, scale, rotation and tint (Draw Overload and DrawFromSpriteSheet Overload
Individual sprites may be flipped horizontally or vertically. (CanvasSpriteFlip)
Sprite Sheets (DrawFromSpriteSheet Overload)
Sprites can be clamped to a source rectangle, removing the need to add padding between sprites in a sprite sheet.
Batches can be sorted by bitmap for better performance.

To use a sprite batch you first create a CanvasSpriteBatch from the CanvasDrawingSession using CreateSpriteBatch Overload. Sprites can be added to the batch using Draw Overload and DrawFromSpriteSheet Overload. When you have finished adding sprites call Dispose. At this point all sprites will be send to the drawing session.

In C#, the 'using' statement makes this convenient:

Copy

void DrawSomeSprites(CanvasDrawingSession ds)
{
    using (var spriteBatch = ds.CreateSpriteBatch())
    {
        spriteBatch.DrawSprite(aBitmap, aPosition);
    }
}

In C++, 'delete' can be used to dispose the sprite batch:

C++

Copy

void DrawSomeSprites(CanvasDrawingSession^ ds)
{
    auto spriteBatch = ds->CreateSpriteBatch();
    spriteBatch->DrawSprite(aBitmap, aPosition);
    delete spriteBatch;
}

Unit Modes

The value of the drawing session's Units is checked once when the CanvasSpriteBatch is created. This is the unit mode that is used for all operations on the sprite batch.

Transform

The drawing session's Transform affects all the sprites in the sprite batch at the point that Dispose is called.

Reference

Microsoft.Graphics.Canvas Namespace