Class StaticSpriteBatch

Namespace

MLEM.Graphics

Assembly

MLEM.dll

A static sprite batch is a highly optimized variation of Microsoft.Xna.Framework.Graphics.SpriteBatch that keeps all batched items in a Microsoft.Xna.Framework.Graphics.VertexBuffer, allowing for them to be drawn multiple times. To add items to a static sprite batch, use BeginBatch(SpriteSortMode?) to begin batching, ClearBatch() to clear currently batched items, Add and its various overloads to add batch items, Remove(Item) to remove them again, and EndBatch() to end batching. To draw the batched items, call Draw(BlendState, SamplerState, DepthStencilState, RasterizerState, Effect, Matrix?).

public class StaticSpriteBatch : IDisposable

Inheritance

object

StaticSpriteBatch

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

SpriteBatchContextExtensions.Draw(StaticSpriteBatch, SpriteBatchContext)

SpriteBatchExtensions.Add(StaticSpriteBatch, Texture2D, RectangleF, Color)

SpriteBatchExtensions.Add(StaticSpriteBatch, Texture2D, RectangleF, Rectangle?, Color)

SpriteBatchExtensions.Add(StaticSpriteBatch, Texture2D, RectangleF, Rectangle?, Color, float, Vector2, SpriteEffects, float)

TextureRegionExtensions.Add(StaticSpriteBatch, TextureRegion, RectangleF, Color)

TextureRegionExtensions.Add(StaticSpriteBatch, TextureRegion, RectangleF, Color, float, Vector2, SpriteEffects, float)

TextureRegionExtensions.Add(StaticSpriteBatch, TextureRegion, Rectangle, Color)

TextureRegionExtensions.Add(StaticSpriteBatch, TextureRegion, Rectangle, Color, float, Vector2, SpriteEffects, float)

TextureRegionExtensions.Add(StaticSpriteBatch, TextureRegion, Vector2, Color)

TextureRegionExtensions.Add(StaticSpriteBatch, TextureRegion, Vector2, Color, float, Vector2, Vector2, SpriteEffects, float)

TextureRegionExtensions.Add(StaticSpriteBatch, TextureRegion, Vector2, Color, float, Vector2, float, SpriteEffects, float)

Constructors

StaticSpriteBatch(GraphicsDevice)

Creates a new static sprite batch with the given Microsoft.Xna.Framework.Graphics.GraphicsDevice

public StaticSpriteBatch(GraphicsDevice graphicsDevice)

Parameters

graphicsDevice GraphicsDevice

The graphics device to use for rendering

Properties

Buffers

The amount of vertex buffers that this static sprite batch has. To see the amount of buffers that are actually in use, see FilledBuffers.

public int Buffers { get; }

Property Value

int

FilledBuffers

The amount of vertex buffers that are currently filled in this static sprite batch. To see the amount of buffers that are available, see Buffers.

public int FilledBuffers { get; }

Property Value

int

Textures

The amount of textures that this static sprite batch is currently using.

public int Textures { get; }

Property Value

int

Vertices

The amount of vertices that are currently batched.

public int Vertices { get; }

Property Value

int

Methods

Add(Item)

Adds an item to this batch. Note that this batch needs to currently be batching, meaning BeginBatch(SpriteSortMode?) has to have been called previously.

public StaticSpriteBatch.Item Add(StaticSpriteBatch.Item item)

Parameters

item StaticSpriteBatch.Item

The item to add.

Returns

StaticSpriteBatch.Item

The added item, for chaining.

Add(Texture2D, Rectangle, Color)

Adds an item to this batch. Note that this batch needs to currently be batching, meaning BeginBatch(SpriteSortMode?) has to have been called previously.

public StaticSpriteBatch.Item Add(Texture2D texture, Rectangle destinationRectangle, Color color)

Parameters

texture Texture2D

A texture.

destinationRectangle Rectangle

The drawing bounds on screen.

color Color

A color mask.

Returns

StaticSpriteBatch.Item

The StaticSpriteBatch.Item that was created from the added data

Add(Texture2D, Rectangle, Rectangle?, Color)

Adds an item to this batch. Note that this batch needs to currently be batching, meaning BeginBatch(SpriteSortMode?) has to have been called previously.

public StaticSpriteBatch.Item Add(Texture2D texture, Rectangle destinationRectangle, Rectangle? sourceRectangle, Color color)

Parameters

texture Texture2D

A texture.

destinationRectangle Rectangle

The drawing bounds on screen.

sourceRectangle Rectangle?

An optional region on the texture which will be rendered. If null - draws full texture.

color Color

A color mask.

Returns

StaticSpriteBatch.Item

The StaticSpriteBatch.Item that was created from the added data

Add(Texture2D, Rectangle, Rectangle?, Color, float, Vector2, SpriteEffects, float)

Adds an item to this batch. Note that this batch needs to currently be batching, meaning BeginBatch(SpriteSortMode?) has to have been called previously.

public StaticSpriteBatch.Item Add(Texture2D texture, Rectangle destinationRectangle, Rectangle? sourceRectangle, Color color, float rotation, Vector2 origin, SpriteEffects effects, float layerDepth)

Parameters

texture Texture2D

A texture.

destinationRectangle Rectangle

The drawing bounds on screen.

sourceRectangle Rectangle?

An optional region on the texture which will be rendered. If null - draws full texture.

color Color

A color mask.

rotation float

A rotation of this sprite.

origin Vector2

Center of the rotation. 0,0 by default.

effects SpriteEffects

Modificators for drawing. Can be combined.

layerDepth float

A depth of the layer of this sprite.

Returns

StaticSpriteBatch.Item

The StaticSpriteBatch.Item that was created from the added data

Add(Texture2D, Vector2, Color)

Adds an item to this batch. Note that this batch needs to currently be batching, meaning BeginBatch(SpriteSortMode?) has to have been called previously.

public StaticSpriteBatch.Item Add(Texture2D texture, Vector2 position, Color color)

Parameters

texture Texture2D

A texture.

position Vector2

The drawing location on screen.

color Color

A color mask.

Returns

StaticSpriteBatch.Item

The StaticSpriteBatch.Item that was created from the added data

Add(Texture2D, Vector2, Rectangle?, Color)

Adds an item to this batch. Note that this batch needs to currently be batching, meaning BeginBatch(SpriteSortMode?) has to have been called previously.

public StaticSpriteBatch.Item Add(Texture2D texture, Vector2 position, Rectangle? sourceRectangle, Color color)

Parameters

texture Texture2D

A texture.

position Vector2

The drawing location on screen.

sourceRectangle Rectangle?

An optional region on the texture which will be rendered. If null - draws full texture.

color Color

A color mask.

Returns

StaticSpriteBatch.Item

The StaticSpriteBatch.Item that was created from the added data

Add(Texture2D, Vector2, Rectangle?, Color, float, Vector2, Vector2, SpriteEffects, float)

Adds an item to this batch. Note that this batch needs to currently be batching, meaning BeginBatch(SpriteSortMode?) has to have been called previously.

public StaticSpriteBatch.Item Add(Texture2D texture, Vector2 position, Rectangle? sourceRectangle, Color color, float rotation, Vector2 origin, Vector2 scale, SpriteEffects effects, float layerDepth)

Parameters

texture Texture2D

A texture.

position Vector2

The drawing location on screen.

sourceRectangle Rectangle?

An optional region on the texture which will be rendered. If null - draws full texture.

color Color

A color mask.

rotation float

A rotation of this sprite.

origin Vector2

Center of the rotation. 0,0 by default.

scale Vector2

A scaling of this sprite.

effects SpriteEffects

Modificators for drawing. Can be combined.

layerDepth float

A depth of the layer of this sprite.

Returns

StaticSpriteBatch.Item

The StaticSpriteBatch.Item that was created from the added data

Add(Texture2D, Vector2, Rectangle?, Color, float, Vector2, float, SpriteEffects, float)

Adds an item to this batch. Note that this batch needs to currently be batching, meaning BeginBatch(SpriteSortMode?) has to have been called previously.

public StaticSpriteBatch.Item Add(Texture2D texture, Vector2 position, Rectangle? sourceRectangle, Color color, float rotation, Vector2 origin, float scale, SpriteEffects effects, float layerDepth)

Parameters

texture Texture2D

A texture.

position Vector2

The drawing location on screen.

sourceRectangle Rectangle?

An optional region on the texture which will be rendered. If null - draws full texture.

color Color

A color mask.

rotation float

A rotation of this sprite.

origin Vector2

Center of the rotation. 0,0 by default.

scale float

A scaling of this sprite.

effects SpriteEffects

Modificators for drawing. Can be combined.

layerDepth float

A depth of the layer of this sprite.

Returns

StaticSpriteBatch.Item

The StaticSpriteBatch.Item that was created from the added data

BeginBatch(SpriteSortMode?)

Begins batching. Call this method before calling Add or any of its overloads.

public void BeginBatch(SpriteSortMode? sortMode = null)

Parameters

sortMode SpriteSortMode?

The drawing order for sprite drawing. When null is passed, the last used sort mode will be used again. The initial sort mode is Microsoft.Xna.Framework.Graphics.SpriteSortMode.Texture. Note that Microsoft.Xna.Framework.Graphics.SpriteSortMode.Immediate is not supported.

Exceptions

InvalidOperationException

Thrown if this batch is currently batching already

ArgumentOutOfRangeException

Thrown if the sortMode is Microsoft.Xna.Framework.Graphics.SpriteSortMode.Immediate, which is not supported.

ClearBatch()

Clears the batch, removing all currently batched vertices. After this operation, Vertices will return 0.

public void ClearBatch()

Exceptions

InvalidOperationException

Thrown if this method is called before BeginBatch(SpriteSortMode?) was called

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Draw(BlendState, SamplerState, DepthStencilState, RasterizerState, Effect, Matrix?)

Draws this batch's content onto the Microsoft.Xna.Framework.Graphics.GraphicsDevice's current render target (or the back buffer) with the given settings. Note that this method should not be called while a regular Microsoft.Xna.Framework.Graphics.SpriteBatch is currently active.

public void Draw(BlendState blendState = null, SamplerState samplerState = null, DepthStencilState depthStencilState = null, RasterizerState rasterizerState = null, Effect effect = null, Matrix? transformMatrix = null)

Parameters

blendState BlendState

State of the blending. Uses Microsoft.Xna.Framework.Graphics.BlendState.AlphaBlend if null.

samplerState SamplerState

State of the sampler. Uses Microsoft.Xna.Framework.Graphics.SamplerState.LinearClamp if null.

depthStencilState DepthStencilState

State of the depth-stencil buffer. Uses Microsoft.Xna.Framework.Graphics.DepthStencilState.None if null.

rasterizerState RasterizerState

State of the rasterization. Uses Microsoft.Xna.Framework.Graphics.RasterizerState.CullCounterClockwise if null.

effect Effect

A custom Microsoft.Xna.Framework.Graphics.Effect to override the default sprite effect. Uses default sprite effect if null.

transformMatrix Matrix?

An optional matrix used to transform the sprite geometry. Uses Microsoft.Xna.Framework.Matrix.Identity if null.

Exceptions

InvalidOperationException

Thrown if this batch is currently batching

EndBatch()

Ends batching. Call this method after calling Add or any of its overloads the desired number of times to add batched items.

public void EndBatch()

Exceptions

InvalidOperationException

Thrown if this method is called before BeginBatch(SpriteSortMode?) was called.

Remove(Item)

Removes the given item from this batch. Note that this batch needs to currently be batching, meaning BeginBatch(SpriteSortMode?) has to have been called previously.

public bool Remove(StaticSpriteBatch.Item item)

Parameters

item StaticSpriteBatch.Item

The item to remove

Returns

bool

Whether the item was successfully removed

Exceptions

InvalidOperationException

Thrown if this method is called before BeginBatch(SpriteSortMode?) was called