Table of Contents

Class SpriteBatch

Namespace
Stride.Graphics
Assembly
Stride.Graphics.dll

Renders a group of sprites.

public class SpriteBatch : BatchBase<SpriteBatch.SpriteDrawInfo>, IDisposable, IComponent, IReferencable, ICollectorHolder
Inheritance
object
SpriteBatch
Implements
Inherited Members
Extension Methods

Constructors

SpriteBatch(GraphicsDevice, int, int)

Initializes a new instance of the SpriteBatch class.

public SpriteBatch(GraphicsDevice graphicsDevice, int bufferElementCount = 1024, int batchCapacity = 64)

Parameters

graphicsDevice GraphicsDevice

The graphics device.

bufferElementCount int

The maximum number element that can be batched in one time.

batchCapacity int

The batch capacity default to 64.

Properties

DefaultDepth

Gets or sets the default depth value used by the SpriteBatch when the VirtualResolution is not set.

public float DefaultDepth { get; set; }

Property Value

float

Remarks

More precisely, this value represents the length "farPlane-nearPlane" used by the default projection matrix.

TextureSpriteFontEffect 

public EffectInstance TextureSpriteFontEffect { get; }

Property Value

EffectInstance

VirtualResolution

Gets or sets the virtual resolution used for this SpriteBatch

public Vector3? VirtualResolution { get; set; }

Property Value

Vector3?

Methods

Begin(GraphicsContext, Matrix, Matrix, SpriteSortMode, BlendStateDescription?, SamplerState, DepthStencilStateDescription?, RasterizerStateDescription?, EffectInstance, int)

Begins a sprite batch rendering using the specified sorting mode and blend state, sampler, depth stencil, rasterizer state objects, plus a custom effect and a 2D transformation matrix. Passing null for any of the state objects selects the default default state objects (BlendState.AlphaBlend, DepthStencilState.Default, RasterizerState.CullCounterClockwise, SamplerState.LinearClamp). Passing a null effect selects the default SpriteBatch Class shader.

public void Begin(GraphicsContext graphicsContext, Matrix viewMatrix, Matrix projectionMatrix, SpriteSortMode sortMode = SpriteSortMode.Deferred, BlendStateDescription? blendState = null, SamplerState samplerState = null, DepthStencilStateDescription? depthStencilState = null, RasterizerStateDescription? rasterizerState = null, EffectInstance effect = null, int stencilValue = 0)

Parameters

graphicsContext GraphicsContext

The graphics context to use.

viewMatrix Matrix

The view matrix to use for the batch session

projectionMatrix Matrix

The projection matrix to use for the batch session

sortMode SpriteSortMode

The sprite drawing order to use for the batch session

blendState BlendStateDescription?

The blending state to use for the batch session

samplerState SamplerState

The sampling state to use for the batch session

depthStencilState DepthStencilStateDescription?

The depth stencil state to use for the batch session

rasterizerState RasterizerStateDescription?

The rasterizer state to use for the batch session

effect EffectInstance

The effect to use for the batch session

stencilValue int

The value of the stencil buffer to take as reference for the batch session

Begin(GraphicsContext, Matrix, SpriteSortMode, BlendStateDescription?, SamplerState, DepthStencilStateDescription?, RasterizerStateDescription?, EffectInstance, int)

Begins a sprite batch rendering using the specified sorting mode and blend state, sampler, depth stencil, rasterizer state objects, plus a custom effect and a 2D transformation matrix. Passing null for any of the state objects selects the default default state objects (BlendState.AlphaBlend, DepthStencilState.Default, RasterizerState.CullCounterClockwise, SamplerState.LinearClamp). Passing a null effect selects the default SpriteBatch Class shader.

public void Begin(GraphicsContext graphicsContext, Matrix viewMatrix, SpriteSortMode sortMode = SpriteSortMode.Deferred, BlendStateDescription? blendState = null, SamplerState samplerState = null, DepthStencilStateDescription? depthStencilState = null, RasterizerStateDescription? rasterizerState = null, EffectInstance effect = null, int stencilValue = 0)

Parameters

graphicsContext GraphicsContext

The graphics context to use.

viewMatrix Matrix

The view matrix to use for the batch session

sortMode SpriteSortMode

The sprite drawing order to use for the batch session

blendState BlendStateDescription?

The blending state to use for the batch session

samplerState SamplerState

The sampling state to use for the batch session

depthStencilState DepthStencilStateDescription?

The depth stencil state to use for the batch session

rasterizerState RasterizerStateDescription?

The rasterizer state to use for the batch session

effect EffectInstance

The effect to use for the batch session

stencilValue int

The value of the stencil buffer to take as reference for the batch session

Begin(GraphicsContext, SpriteSortMode, EffectInstance)

Begins a sprite batch operation using deferred sort and default state objects (BlendState.AlphaBlend, SamplerState.LinearClamp, DepthStencilState.Default, RasterizerState.CullCounterClockwise).

public void Begin(GraphicsContext graphicsContext, SpriteSortMode sortMode, EffectInstance effect)

Parameters

graphicsContext GraphicsContext

The graphics context to use.

sortMode SpriteSortMode

The sprite drawing order to use for the batch session

effect EffectInstance

The effect to use for the batch session

Begin(GraphicsContext, SpriteSortMode, BlendStateDescription?, SamplerState, DepthStencilStateDescription?, RasterizerStateDescription?, EffectInstance, int)

Begins a sprite batch rendering using the specified sorting mode and blend state, sampler, depth stencil and rasterizer state objects, plus a custom effect. Passing null for any of the state objects selects the default default state objects (BlendState.AlphaBlend, DepthStencilState.Default, RasterizerState.CullCounterClockwise, SamplerState.LinearClamp). Passing a null effect selects the default SpriteBatch Class shader.

public void Begin(GraphicsContext graphicsContext, SpriteSortMode sortMode = SpriteSortMode.Deferred, BlendStateDescription? blendState = null, SamplerState samplerState = null, DepthStencilStateDescription? depthStencilState = null, RasterizerStateDescription? rasterizerState = null, EffectInstance effect = null, int stencilValue = 0)

Parameters

graphicsContext GraphicsContext

The graphics context to use.

sortMode SpriteSortMode

The sprite drawing order to use for the batch session

blendState BlendStateDescription?

The blending state to use for the batch session

samplerState SamplerState

The sampling state to use for the batch session

depthStencilState DepthStencilStateDescription?

The depth stencil state to use for the batch session

rasterizerState RasterizerStateDescription?

The rasterizer state to use for the batch session

effect EffectInstance

The effect to use for the batch session

stencilValue int

The value of the stencil buffer to take as reference for the batch session

CalculateDefaultProjection(Vector3)

Calculate the default projection matrix for the provided virtual resolution.

public static Matrix CalculateDefaultProjection(Vector3 virtualResolution)

Parameters

virtualResolution Vector3

Returns

Matrix

The default projection matrix for the provided virtual resolution

Remarks

The sprite batch default projection is an orthogonal matrix such as (0,0) is the Top/Left corner of the screen and (VirtualResolution.X, VirtualResolution.Y) is the Bottom/Right corner of the screen.

CalculateDefaultProjection(ref Vector3, out Matrix)

Calculate the default projection matrix for the provided virtual resolution.

public static void CalculateDefaultProjection(ref Vector3 virtualResolution, out Matrix projection)

Parameters

virtualResolution Vector3
projection Matrix

Draw(Texture, RectangleF, Color4, Color4)

Adds a sprite to a batch of sprites for rendering using the specified texture, destination rectangle, and color.

public void Draw(Texture texture, RectangleF destinationRectangle, Color4 color, Color4 colorAdd = default)

Parameters

texture Texture

A texture.

destinationRectangle RectangleF

A rectangle that specifies (in screen coordinates) the destination for drawing the sprite.

color Color4

The color to tint a sprite. Use Color.White for full color with no tinting.

colorAdd Color4

Remarks

Before making any calls to Draw, you must call Begin. Once all calls to Draw are complete, call End.

Draw(Texture, RectangleF, RectangleF?, Color4, float, Vector2, SpriteEffects, ImageOrientation, float, Color4, SwizzleMode)

Adds a sprite to a batch of sprites for rendering using the specified texture, destination rectangle, source rectangle, color, rotation, origin, effects and layer.

public void Draw(Texture texture, RectangleF destinationRectangle, RectangleF? sourceRectangle, Color4 color, float rotation, Vector2 origin, SpriteEffects effects = SpriteEffects.None, ImageOrientation orientation = ImageOrientation.AsIs, float layerDepth = 0, Color4 colorAdd = default, SwizzleMode swizzle = SwizzleMode.None)

Parameters

texture Texture

A texture.

destinationRectangle RectangleF

A rectangle that specifies (in screen coordinates) the destination for drawing the sprite. If this rectangle is not the same size as the source rectangle, the sprite will be scaled to fit.

sourceRectangle RectangleF?

A rectangle that specifies (in texels) the source texels from a texture. Use null to draw the entire texture.

color Color4

The color to tint a sprite. Use Color.White for full color with no tinting.

rotation float

Specifies the angle (in radians) to rotate the sprite about its center.

origin Vector2

The sprite origin in the texture in pixels (dependent of image orientation). Default value is (0,0) which represents the upper-left corner.

effects SpriteEffects

Effects to apply.

orientation ImageOrientation

The source image orientation

layerDepth float

The depth of a layer. By default, 0 represents the front layer and 1 represents a back layer. Use SpriteSortMode if you want sprites to be sorted during drawing.

colorAdd Color4
swizzle SwizzleMode

Draw(Texture, Vector2)

Adds a sprite to a batch of sprites for rendering using the specified texture, position and color.

public void Draw(Texture texture, Vector2 position)

Parameters

texture Texture

A texture.

position Vector2

The location (in screen coordinates) to draw the sprite.

Draw(Texture, Vector2, Color, Color4)

Adds a sprite to a batch of sprites for rendering using the specified texture, position and color.

public void Draw(Texture texture, Vector2 position, Color color, Color4 colorAdd = default)

Parameters

texture Texture

A texture.

position Vector2

The location (in screen coordinates) to draw the sprite.

color Color

The color to tint a sprite. Use Color.White for full color with no tinting.

colorAdd Color4

Draw(Texture, Vector2, Color4, float, Vector2, Vector2, SpriteEffects, ImageOrientation, float)

Adds a sprite to a batch of sprites for rendering using the specified texture, position, source rectangle, color, rotation, origin, scale, effects, and layer.

public void Draw(Texture texture, Vector2 position, Color4 color, float rotation, Vector2 origin, Vector2 scale, SpriteEffects effects = SpriteEffects.None, ImageOrientation orientation = ImageOrientation.AsIs, float layerDepth = 0)

Parameters

texture Texture

A texture.

position Vector2

The location (in screen coordinates) to draw the sprite.

color Color4

The color to tint a sprite. Use Color.White for full color with no tinting.

rotation float

Specifies the angle (in radians) to rotate the sprite about its center.

origin Vector2

The sprite origin in the texture in pixels (dependent of image orientation). Default value is (0,0) which represents the upper-left corner.

scale Vector2

Scale factor.

effects SpriteEffects

Effects to apply.

orientation ImageOrientation

The source image orientation

layerDepth float

The depth of a layer. By default, 0 represents the front layer and 1 represents a back layer. Use SpriteSortMode if you want sprites to be sorted during drawing.

Draw(Texture, Vector2, Color4, float, Vector2, float, SpriteEffects, ImageOrientation, float)

Adds a sprite to a batch of sprites for rendering using the specified texture, position, source rectangle, color, rotation, origin, scale, effects, and layer.

public void Draw(Texture texture, Vector2 position, Color4 color, float rotation, Vector2 origin, float scale = 1, SpriteEffects effects = SpriteEffects.None, ImageOrientation orientation = ImageOrientation.AsIs, float layerDepth = 0)

Parameters

texture Texture

A texture.

position Vector2

The location (in screen coordinates) to draw the sprite.

color Color4

The color to tint a sprite. Use Color.White for full color with no tinting.

rotation float

Specifies the angle (in radians) to rotate the sprite about its center.

origin Vector2

The sprite origin in the texture in pixels (dependent of image orientation). Default value is (0,0) which represents the upper-left corner.

scale float

Scale factor.

effects SpriteEffects

Effects to apply.

orientation ImageOrientation

The source image orientation

layerDepth float

The depth of a layer. By default, 0 represents the front layer and 1 represents a back layer. Use SpriteSortMode if you want sprites to be sorted during drawing.

Draw(Texture, Vector2, RectangleF?, Color4, Color4)

Adds a sprite to a batch of sprites for rendering using the specified texture, position, source rectangle, and color.

public void Draw(Texture texture, Vector2 position, RectangleF? sourceRectangle, Color4 color, Color4 colorAdd = default)

Parameters

texture Texture

A texture.

position Vector2

The location (in screen coordinates) to draw the sprite.

sourceRectangle RectangleF?

A rectangle that specifies (in texels) the source texels from a texture. Use null to draw the entire texture.

color Color4

The color to tint a sprite. Use Color.White for full color with no tinting.

colorAdd Color4

Draw(Texture, Vector2, RectangleF?, Color4, float, Vector2, Vector2, SpriteEffects, ImageOrientation, float, Color4)

Adds a sprite to a batch of sprites for rendering using the specified texture, position, source rectangle, color, rotation, origin, scale, effects, and layer.

public void Draw(Texture texture, Vector2 position, RectangleF? sourceRectangle, Color4 color, float rotation, Vector2 origin, Vector2 scale, SpriteEffects effects = SpriteEffects.None, ImageOrientation orientation = ImageOrientation.AsIs, float layerDepth = 0, Color4 colorAdd = default)

Parameters

texture Texture

A texture.

position Vector2

The location (in screen coordinates) to draw the sprite.

sourceRectangle RectangleF?

A rectangle that specifies (in texels) the source texels from a texture. Use null to draw the entire texture.

color Color4

The color to tint a sprite. Use Color.White for full color with no tinting.

rotation float

Specifies the angle (in radians) to rotate the sprite about its center.

origin Vector2

The sprite origin in the texture in pixels (dependent of image orientation). Default value is (0,0) which represents the upper-left corner.

scale Vector2

Scale factor.

effects SpriteEffects

Effects to apply.

orientation ImageOrientation

The source image orientation

layerDepth float

The depth of a layer. By default, 0 represents the front layer and 1 represents a back layer. Use SpriteSortMode if you want sprites to be sorted during drawing.

colorAdd Color4

Draw(Texture, Vector2, RectangleF?, Color4, float, Vector2, float, SpriteEffects, ImageOrientation, float, Color4, SwizzleMode)

Adds a sprite to a batch of sprites for rendering using the specified texture, position, source rectangle, color, rotation, origin, scale, effects, and layer.

public void Draw(Texture texture, Vector2 position, RectangleF? sourceRectangle, Color4 color, float rotation, Vector2 origin, float scale = 1, SpriteEffects effects = SpriteEffects.None, ImageOrientation orientation = ImageOrientation.AsIs, float layerDepth = 0, Color4 colorAdd = default, SwizzleMode swizzle = SwizzleMode.None)

Parameters

texture Texture

A texture.

position Vector2

The location (in screen coordinates) to draw the sprite.

sourceRectangle RectangleF?

A rectangle that specifies (in texels) the source texels from a texture. Use null to draw the entire texture.

color Color4

The color to tint a sprite. Use Color4.White for full color with no tinting.

rotation float

Specifies the angle (in radians) to rotate the sprite about its center.

origin Vector2

The sprite origin in the texture in pixels (dependent of image orientation). Default value is (0,0) which represents the upper-left corner.

scale float

Scale factor.

effects SpriteEffects

Effects to apply.

orientation ImageOrientation

The source image orientation

layerDepth float

The depth of a layer. By default, 0 represents the front layer and 1 represents a back layer. Use SpriteSortMode if you want sprites to be sorted during drawing.

colorAdd Color4
swizzle SwizzleMode

DrawString(SpriteFont, string, Vector2, Color4, TextAlignment)

Adds a string to a batch of sprites for rendering using the specified font, text, position, and color.

public void DrawString(SpriteFont spriteFont, string text, Vector2 position, Color4 color, TextAlignment alignment = TextAlignment.Left)

Parameters

spriteFont SpriteFont

A font for displaying text.

text string

A text string.

position Vector2

The location (in screen coordinates) to draw the sprite.

color Color4

The color to tint a sprite. Use Color.White for full color with no tinting.

alignment TextAlignment

Describes how to align the text to draw

DrawString(SpriteFont, string, Vector2, Color4, float, Vector2, Vector2, SpriteEffects, float, TextAlignment)

Adds a string to a batch of sprites for rendering using the specified font, text, position, color, rotation, origin, scale, effects and layer.

public void DrawString(SpriteFont spriteFont, string text, Vector2 position, Color4 color, float rotation, Vector2 origin, Vector2 scale, SpriteEffects effects, float layerDepth, TextAlignment alignment)

Parameters

spriteFont SpriteFont

A font for displaying text.

text string

A text string.

position Vector2

The location (in screen coordinates) to draw the sprite.

color Color4

The color to tint a sprite. Use Color.White for full color with no tinting.

rotation float

Specifies the angle (in radians) to rotate the sprite about its center.

origin Vector2

The sprite origin in virtual pixels; the default is (0,0) which represents the upper-left corner.

scale Vector2

Scale factor.

effects SpriteEffects

Effects to apply.

layerDepth float

The depth of a layer. By default, 0 represents the front layer and 1 represents a back layer. Use SpriteSortMode if you want sprites to be sorted during drawing.

alignment TextAlignment

Describes how to align the text to draw

DrawString(SpriteFont, string, float, Vector2, Color4, TextAlignment)

Adds a string to a batch of sprites for rendering using the specified font, text, position, and color.

public void DrawString(SpriteFont spriteFont, string text, float fontSize, Vector2 position, Color4 color, TextAlignment alignment = TextAlignment.Left)

Parameters

spriteFont SpriteFont

A font for displaying text.

text string

A text string.

fontSize float

The font size in pixels (ignored in the case of static fonts)

position Vector2

The location (in screen coordinates) to draw the sprite.

color Color4

The color to tint a sprite. Use Color.White for full color with no tinting.

alignment TextAlignment

Describes how to align the text to draw

DrawString(SpriteFont, string, float, Vector2, Color4, float, Vector2, Vector2, SpriteEffects, float, TextAlignment)

Adds a string to a batch of sprites for rendering using the specified font, text, position, color, rotation, origin, scale, effects and layer.

public void DrawString(SpriteFont spriteFont, string text, float fontSize, Vector2 position, Color4 color, float rotation, Vector2 origin, Vector2 scale, SpriteEffects effects, float layerDepth, TextAlignment alignment)

Parameters

spriteFont SpriteFont

A font for displaying text.

text string

A text string.

fontSize float

The font size in pixels (ignored in the case of static fonts)

position Vector2

The location (in screen coordinates) to draw the sprite.

color Color4

The color to tint a sprite. Use Color.White for full color with no tinting.

rotation float

Specifies the angle (in radians) to rotate the sprite about its center.

origin Vector2

The sprite origin in virtual pixels; the default is (0,0) which represents the upper-left corner.

scale Vector2

Scale factor.

effects SpriteEffects

Effects to apply.

layerDepth float

The depth of a layer. By default, 0 represents the front layer and 1 represents a back layer. Use SpriteSortMode if you want sprites to be sorted during drawing.

alignment TextAlignment

Describes how to align the text to draw

DrawString(SpriteFont, StringBuilder, Vector2, Color4, TextAlignment)

Adds a string to a batch of sprites for rendering using the specified font, text, position, and color.

public void DrawString(SpriteFont spriteFont, StringBuilder text, Vector2 position, Color4 color, TextAlignment alignment = TextAlignment.Left)

Parameters

spriteFont SpriteFont

A font for displaying text.

text StringBuilder

Text string.

position Vector2

The location (in screen coordinates) to draw the sprite.

color Color4

The color to tint a sprite. Use Color.White for full color with no tinting.

alignment TextAlignment

Describes how to align the text to draw

DrawString(SpriteFont, StringBuilder, Vector2, Color4, float, Vector2, Vector2, SpriteEffects, float, TextAlignment)

Adds a string to a batch of sprites for rendering using the specified font, text, position, color, rotation, origin, scale, effects and layer.

public void DrawString(SpriteFont spriteFont, StringBuilder text, Vector2 position, Color4 color, float rotation, Vector2 origin, Vector2 scale, SpriteEffects effects, float layerDepth, TextAlignment alignment)

Parameters

spriteFont SpriteFont

A font for displaying text.

text StringBuilder

Text string.

position Vector2

The location (in screen coordinates) to draw the sprite.

color Color4

The color to tint a sprite. Use Color.White for full color with no tinting.

rotation float

Specifies the angle (in radians) to rotate the sprite about its center.

origin Vector2

The sprite origin in virtual pixels; the default is (0,0) which represents the upper-left corner.

scale Vector2

Scale factor.

effects SpriteEffects

Effects to apply.

layerDepth float

The depth of a layer. By default, 0 represents the front layer and 1 represents a back layer. Use SpriteSortMode if you want sprites to be sorted during drawing.

alignment TextAlignment

Describes how to align the text to draw

DrawString(SpriteFont, StringBuilder, float, Vector2, Color4, TextAlignment)

Adds a string to a batch of sprites for rendering using the specified font, text, position, and color.

public void DrawString(SpriteFont spriteFont, StringBuilder text, float fontSize, Vector2 position, Color4 color, TextAlignment alignment = TextAlignment.Left)

Parameters

spriteFont SpriteFont

A font for displaying text.

text StringBuilder

Text string.

fontSize float

The font size in pixels (ignored in the case of static fonts)

position Vector2

The location (in screen coordinates) to draw the sprite.

color Color4

The color to tint a sprite. Use Color.White for full color with no tinting.

alignment TextAlignment

Describes how to align the text to draw

DrawString(SpriteFont, StringBuilder, float, Vector2, Color4, float, Vector2, Vector2, SpriteEffects, float, TextAlignment)

Adds a string to a batch of sprites for rendering using the specified font, text, position, color, rotation, origin, scale, effects and layer.

public void DrawString(SpriteFont spriteFont, StringBuilder text, float fontSize, Vector2 position, Color4 color, float rotation, Vector2 origin, Vector2 scale, SpriteEffects effects, float layerDepth, TextAlignment alignment)

Parameters

spriteFont SpriteFont

A font for displaying text.

text StringBuilder

Text string.

fontSize float

The font size in pixels (ignored in the case of static fonts)

position Vector2

The location (in screen coordinates) to draw the sprite.

color Color4

The color to tint a sprite. Use Color.White for full color with no tinting.

rotation float

Specifies the angle (in radians) to rotate the sprite about its center.

origin Vector2

The sprite origin in virtual pixels; the default is (0,0) which represents the upper-left corner.

scale Vector2

Scale factor.

effects SpriteEffects

Effects to apply.

layerDepth float

The depth of a layer. By default, 0 represents the front layer and 1 represents a back layer. Use SpriteSortMode if you want sprites to be sorted during drawing.

alignment TextAlignment

Describes how to align the text to draw

MeasureString(SpriteFont, string, Vector2?)

Measure the size of the given text in virtual pixels depending on the target size.

public Vector2 MeasureString(SpriteFont spriteFont, string text, Vector2? targetSize = null)

Parameters

spriteFont SpriteFont

The font used to draw the text.

text string

The text to measure.

targetSize Vector2?

The size of the target to render in. If null, the size of the window back buffer is used.

Returns

Vector2

The size of the text in virtual pixels.

Exceptions

ArgumentNullException

The provided sprite font is null.

MeasureString(SpriteFont, string, float, Vector2?)

Measure the size of the given text in virtual pixels depending on the target size.

public Vector2 MeasureString(SpriteFont spriteFont, string text, float fontSize, Vector2? targetSize = null)

Parameters

spriteFont SpriteFont

The font used to draw the text.

text string

The text to measure.

fontSize float

The font size (in pixels) used to draw the text.

targetSize Vector2?

The size of the target to render in. If null, the size of the window back buffer is used.

Returns

Vector2

The size of the text in virtual pixels.

Exceptions

ArgumentNullException

The provided sprite font is null.

PrepareForRendering() 

protected override void PrepareForRendering()

UpdateBufferValuesFromElementInfo(ref ElementInfo, nint, nint, int)

Update the mapped vertex and index buffer values using the provided element info.

protected override void UpdateBufferValuesFromElementInfo(ref BatchBase<SpriteBatch.SpriteDrawInfo>.ElementInfo elementInfo, nint vertexPtr, nint indexPtr, int vertexOffset)

Parameters

elementInfo BatchBase<SpriteBatch.SpriteDrawInfo>.ElementInfo

The structure containing the information about the element to draw.

vertexPtr nint
indexPtr nint
vertexOffset int
Edit this page