This is a native Direct3D 11 implementation of the SpriteBatch helper from XNA Game Studio, providing identical functionality and API.
Initialization
The SpriteBatch class requires a Direct3D 11 device context for drawing.
For exception safety, it is recommended you make use of the C++ RAII pattern and use a std::unique_ptr or std::shared_ptr
Simple drawing
The Draw method has many overloads with parameters controlling:
Sorting
The first parameter to SpriteBatch::Begin is a SpriteSortMode enum. For most efficient rendering, use SpriteSortMode_Deferred}" (which batches up sprites, then submits them all to the GPU during the End call), and manually draw everything in texture order. If it is not possible to draw in texture order, the second most efficient approach is to use {"SpriteSortMode_Texture, which will automatically sort on your behalf.
When drawing scenes with multiple depth layers, SpriteSortMode_BackToFront or SpriteSortMode_FrontToBack}" will sort by the layerDepth parameter specified to each Draw call.
{"SpriteSortMode_Immediate disables all batching, submitting a separate Direct3D draw call for each sprite. This is expensive, but convenient in rare cases when you need to set shader constants differently per sprite.
Multiple SpriteBatch instances are lightweight. It is reasonable to create several, Begin them at the same time with different sort modes, submit sprites to different batches in arbitrary orders as you traverse a scene, then End the batches in whatever order you want these groups of sprites to be drawn.
Custom render states
By default SpriteBatch uses premultiplied alpha blending, no depth buffer, counter clockwise culling, and linear filtering with clamp texture addressing. You can change this (if for instance you do not wish to use premultiplied alpha) by passing custom state objects to SpriteBatch::Begin. Pass null for any parameters that should use their default state.
To use SpriteBatch with a custom pixel shader (handy for 2D postprocessing effects such as bloom or blur) or even a custom vertex shader, use the setCustomShaders parameter to specify a state setting callback function:
SpriteBatch automatically sets pixel shader resource #0 to the texture specified by each Draw call, so you only need to call PSSetResources for any additional textures required by your shader.
SpriteBatch::Begin also has a transformMatrix parameter, which can be used for global transforms such as scaling or translation of an entire scene.
Threading model
Creation is fully asynchronous, so you can instantiate multiple SpriteBatch instances at the same time on different threads. Each SpriteBatch instanceonly supports drawing from one thread at a time, but you can simultaneously submit sprites on multiple threads if you create a separate SpriteBatch instance per D3D11 deferred context.
Further reading
http://www.shawnhargreaves.com/blogindex.html#spritebatch
http://blogs.msdn.com/b/shawnhar/archive/2010/06/18/spritebatch-and-renderstates-in-xna-game-studio-4-0.aspx
http://www.shawnhargreaves.com/blogindex.html#premultipliedalpha
Initialization
The SpriteBatch class requires a Direct3D 11 device context for drawing.
std::unique_ptr<SpriteBatch> spriteBatch(new SpriteBatch(deviceContext));
Simple drawing
spriteBatch->Begin(); spriteBatch->Draw(texture, XMFLOAT2(x, y)); spriteBatch->End();
- Specify position as XMFLOAT2, XMVECTOR or RECT
- Optional source rectangle for drawing just part of a sprite sheet
- Tint color
- Rotation (in radians)
- Origin point (position, scaling and rotation are relative to this)
- Scale
- SpriteEffects enum (for horizontal or vertical mirroring)
- Layer depth (for sorting)
Sorting
The first parameter to SpriteBatch::Begin is a SpriteSortMode enum. For most efficient rendering, use SpriteSortMode_Deferred}" (which batches up sprites, then submits them all to the GPU during the End call), and manually draw everything in texture order. If it is not possible to draw in texture order, the second most efficient approach is to use {"SpriteSortMode_Texture, which will automatically sort on your behalf.
When drawing scenes with multiple depth layers, SpriteSortMode_BackToFront or SpriteSortMode_FrontToBack}" will sort by the layerDepth parameter specified to each Draw call.
{"SpriteSortMode_Immediate disables all batching, submitting a separate Direct3D draw call for each sprite. This is expensive, but convenient in rare cases when you need to set shader constants differently per sprite.
Multiple SpriteBatch instances are lightweight. It is reasonable to create several, Begin them at the same time with different sort modes, submit sprites to different batches in arbitrary orders as you traverse a scene, then End the batches in whatever order you want these groups of sprites to be drawn.
Custom render states
By default SpriteBatch uses premultiplied alpha blending, no depth buffer, counter clockwise culling, and linear filtering with clamp texture addressing. You can change this (if for instance you do not wish to use premultiplied alpha) by passing custom state objects to SpriteBatch::Begin. Pass null for any parameters that should use their default state.
To use SpriteBatch with a custom pixel shader (handy for 2D postprocessing effects such as bloom or blur) or even a custom vertex shader, use the setCustomShaders parameter to specify a state setting callback function:
spriteBatch->Begin(SpriteSortMode_Deferred, nullptr, nullptr, nullptr, nullptr, [=] { deviceContext->PSSetShader(...); deviceContext->PSSetConstantBuffers(...); deviceContext->PSSetShaderResources(...); });
SpriteBatch::Begin also has a transformMatrix parameter, which can be used for global transforms such as scaling or translation of an entire scene.
Threading model
Creation is fully asynchronous, so you can instantiate multiple SpriteBatch instances at the same time on different threads. Each SpriteBatch instanceonly supports drawing from one thread at a time, but you can simultaneously submit sprites on multiple threads if you create a separate SpriteBatch instance per D3D11 deferred context.
Further reading
http://www.shawnhargreaves.com/blogindex.html#spritebatch
http://blogs.msdn.com/b/shawnhar/archive/2010/06/18/spritebatch-and-renderstates-in-xna-game-studio-4-0.aspx
http://www.shawnhargreaves.com/blogindex.html#premultipliedalpha