Class SpriteBatch
Renders a group of sprites.
public class SpriteBatch : BatchBase<SpriteBatch.SpriteDrawInfo>, IDisposable, IComponent, IReferencable, ICollectorHolder
- Inheritance
-
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
GraphicsDeviceThe graphics device.
bufferElementCount
intThe maximum number element that can be batched in one time.
batchCapacity
intThe 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
Remarks
More precisely, this value represents the length "farPlane-nearPlane" used by the default projection matrix.
TextureSpriteFontEffect
public EffectInstance TextureSpriteFontEffect { get; }
Property Value
VirtualResolution
Gets or sets the virtual resolution used for this SpriteBatch
public Vector3? VirtualResolution { get; set; }
Property Value
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
GraphicsContextThe graphics context to use.
viewMatrix
MatrixThe view matrix to use for the batch session
projectionMatrix
MatrixThe projection matrix to use for the batch session
sortMode
SpriteSortModeThe sprite drawing order to use for the batch session
blendState
BlendStateDescription?The blending state to use for the batch session
samplerState
SamplerStateThe 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
EffectInstanceThe effect to use for the batch session
stencilValue
intThe 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
GraphicsContextThe graphics context to use.
viewMatrix
MatrixThe view matrix to use for the batch session
sortMode
SpriteSortModeThe sprite drawing order to use for the batch session
blendState
BlendStateDescription?The blending state to use for the batch session
samplerState
SamplerStateThe 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
EffectInstanceThe effect to use for the batch session
stencilValue
intThe 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
GraphicsContextThe graphics context to use.
sortMode
SpriteSortModeThe sprite drawing order to use for the batch session
effect
EffectInstanceThe 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
GraphicsContextThe graphics context to use.
sortMode
SpriteSortModeThe sprite drawing order to use for the batch session
blendState
BlendStateDescription?The blending state to use for the batch session
samplerState
SamplerStateThe 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
EffectInstanceThe effect to use for the batch session
stencilValue
intThe 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
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
TextureA texture.
destinationRectangle
RectangleFA rectangle that specifies (in screen coordinates) the destination for drawing the sprite.
color
Color4The 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
TextureA texture.
destinationRectangle
RectangleFA 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
Color4The color to tint a sprite. Use Color.White for full color with no tinting.
rotation
floatSpecifies the angle (in radians) to rotate the sprite about its center.
origin
Vector2The sprite origin in the texture in pixels (dependent of image orientation). Default value is (0,0) which represents the upper-left corner.
effects
SpriteEffectsEffects to apply.
orientation
ImageOrientationThe source image orientation
layerDepth
floatThe 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
Color4swizzle
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
TextureA texture.
position
Vector2The 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
TextureA texture.
position
Vector2The location (in screen coordinates) to draw the sprite.
color
ColorThe 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
TextureA texture.
position
Vector2The location (in screen coordinates) to draw the sprite.
color
Color4The color to tint a sprite. Use Color.White for full color with no tinting.
rotation
floatSpecifies the angle (in radians) to rotate the sprite about its center.
origin
Vector2The sprite origin in the texture in pixels (dependent of image orientation). Default value is (0,0) which represents the upper-left corner.
scale
Vector2Scale factor.
effects
SpriteEffectsEffects to apply.
orientation
ImageOrientationThe source image orientation
layerDepth
floatThe 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
TextureA texture.
position
Vector2The location (in screen coordinates) to draw the sprite.
color
Color4The color to tint a sprite. Use Color.White for full color with no tinting.
rotation
floatSpecifies the angle (in radians) to rotate the sprite about its center.
origin
Vector2The sprite origin in the texture in pixels (dependent of image orientation). Default value is (0,0) which represents the upper-left corner.
scale
floatScale factor.
effects
SpriteEffectsEffects to apply.
orientation
ImageOrientationThe source image orientation
layerDepth
floatThe 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
TextureA texture.
position
Vector2The 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
Color4The 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
TextureA texture.
position
Vector2The 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
Color4The color to tint a sprite. Use Color.White for full color with no tinting.
rotation
floatSpecifies the angle (in radians) to rotate the sprite about its center.
origin
Vector2The sprite origin in the texture in pixels (dependent of image orientation). Default value is (0,0) which represents the upper-left corner.
scale
Vector2Scale factor.
effects
SpriteEffectsEffects to apply.
orientation
ImageOrientationThe source image orientation
layerDepth
floatThe 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
TextureA texture.
position
Vector2The 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
Color4The color to tint a sprite. Use Color4.White for full color with no tinting.
rotation
floatSpecifies the angle (in radians) to rotate the sprite about its center.
origin
Vector2The sprite origin in the texture in pixels (dependent of image orientation). Default value is (0,0) which represents the upper-left corner.
scale
floatScale factor.
effects
SpriteEffectsEffects to apply.
orientation
ImageOrientationThe source image orientation
layerDepth
floatThe 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
Color4swizzle
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
SpriteFontA font for displaying text.
text
stringA text string.
position
Vector2The location (in screen coordinates) to draw the sprite.
color
Color4The color to tint a sprite. Use Color.White for full color with no tinting.
alignment
TextAlignmentDescribes 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
SpriteFontA font for displaying text.
text
stringA text string.
position
Vector2The location (in screen coordinates) to draw the sprite.
color
Color4The color to tint a sprite. Use Color.White for full color with no tinting.
rotation
floatSpecifies the angle (in radians) to rotate the sprite about its center.
origin
Vector2The sprite origin in virtual pixels; the default is (0,0) which represents the upper-left corner.
scale
Vector2Scale factor.
effects
SpriteEffectsEffects to apply.
layerDepth
floatThe 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
TextAlignmentDescribes 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
SpriteFontA font for displaying text.
text
stringA text string.
fontSize
floatThe font size in pixels (ignored in the case of static fonts)
position
Vector2The location (in screen coordinates) to draw the sprite.
color
Color4The color to tint a sprite. Use Color.White for full color with no tinting.
alignment
TextAlignmentDescribes 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
SpriteFontA font for displaying text.
text
stringA text string.
fontSize
floatThe font size in pixels (ignored in the case of static fonts)
position
Vector2The location (in screen coordinates) to draw the sprite.
color
Color4The color to tint a sprite. Use Color.White for full color with no tinting.
rotation
floatSpecifies the angle (in radians) to rotate the sprite about its center.
origin
Vector2The sprite origin in virtual pixels; the default is (0,0) which represents the upper-left corner.
scale
Vector2Scale factor.
effects
SpriteEffectsEffects to apply.
layerDepth
floatThe 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
TextAlignmentDescribes 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
SpriteFontA font for displaying text.
text
StringBuilderText string.
position
Vector2The location (in screen coordinates) to draw the sprite.
color
Color4The color to tint a sprite. Use Color.White for full color with no tinting.
alignment
TextAlignmentDescribes 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
SpriteFontA font for displaying text.
text
StringBuilderText string.
position
Vector2The location (in screen coordinates) to draw the sprite.
color
Color4The color to tint a sprite. Use Color.White for full color with no tinting.
rotation
floatSpecifies the angle (in radians) to rotate the sprite about its center.
origin
Vector2The sprite origin in virtual pixels; the default is (0,0) which represents the upper-left corner.
scale
Vector2Scale factor.
effects
SpriteEffectsEffects to apply.
layerDepth
floatThe 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
TextAlignmentDescribes 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
SpriteFontA font for displaying text.
text
StringBuilderText string.
fontSize
floatThe font size in pixels (ignored in the case of static fonts)
position
Vector2The location (in screen coordinates) to draw the sprite.
color
Color4The color to tint a sprite. Use Color.White for full color with no tinting.
alignment
TextAlignmentDescribes 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
SpriteFontA font for displaying text.
text
StringBuilderText string.
fontSize
floatThe font size in pixels (ignored in the case of static fonts)
position
Vector2The location (in screen coordinates) to draw the sprite.
color
Color4The color to tint a sprite. Use Color.White for full color with no tinting.
rotation
floatSpecifies the angle (in radians) to rotate the sprite about its center.
origin
Vector2The sprite origin in virtual pixels; the default is (0,0) which represents the upper-left corner.
scale
Vector2Scale factor.
effects
SpriteEffectsEffects to apply.
layerDepth
floatThe 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
TextAlignmentDescribes 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
SpriteFontThe font used to draw the text.
text
stringThe 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
SpriteFontThe font used to draw the text.
text
stringThe text to measure.
fontSize
floatThe 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>.ElementInfoThe structure containing the information about the element to draw.
vertexPtr
nintindexPtr
nintvertexOffset
int