PrimitiveBatch

This is a helper for easily and efficiently drawing dynamically generated geometry using Direct3D 12 such as lines or trianges. It fills the same role as the legacy Direct3D 9 APIs DrawPrimitiveUP and DrawIndexedPrimitiveUP. Dynamic submission is a highly effective pattern for drawing procedural geometry, and convenient for debug rendering, but is not nearly as efficient as static buffers which is more suited to traditional meshes where the VBs and IBs do not change every frame. Excessive dynamic submission is a common source of performance problems in apps. Therefore, you should prefer to use Model, GeometricPrimitive, or your own VB/IB over PrimitiveBatch unless you really need the flexibility to regenerate the topology every frame.

PrimitiveBatch manages the vertex and index buffers for you. It automatically merges adjacent draw requests, so if you call DrawLine 100 times in a row, only a single GPU draw call will be generated.

PrimitiveBatch is responsible for setting the vertex buffer, index buffer, and primitive topology, then issuing the final draw call. Unlike the higher level SpriteBatch helper, it does not provide the Pipeline State Object (PSO). PrimitiveBatch is often used in conjunction with BasicEffect and the structures from VertexTypes, but it can work with any other shader or vertex formats of your own.

Header

#include <PrimitiveBatch.h>

Initialization

Initialize a PrimitiveBatch for drawing VertexPositionColor data

std::unique_ptr<PrimitiveBatch<VertexPositionColor>> primitiveBatch;
primitiveBatch = std::make_unique<PrimitiveBatch<VertexPositionColor>>(device);

For exception safety, it is recommended you make use of the C++ RAII pattern and use a std::unique_ptr or std::shared_ptr

The default values assume that your maximum batch size is 4096 vertices arranged in triangles. If you want to use larger batches, you need to provide the additional constructor parameter.

PrimitiveBatch<T>( ID3D11DeviceContext* deviceContext,
    size_t maxIndices = DefaultBatchSize * 3,
    size_t maxVertices = DefaultBatchSize)

Pipeline State Object (PSO)

Setting up a suitable BasicEffect for the given input layout:

std::unique_ptr<BasicEffect> basicEffect;

RenderTargetState rtState(m_deviceResources->GetBackBufferFormat(),
    m_deviceResources->GetDepthBufferFormat());

EffectPipelineStateDescription pd(
    &VertexPositionColor::InputLayout,
    &CommonStates::Opaque,
    &CommonStates::DepthDefault,
    &CommonStates::CullNone,
    &rtState,
    D3D12_PRIMITIVE_TOPOLOGY_TYPE_LINE);

m_basicEffect = std::make_unique<BasicEffect>(device,
    EffectFlags::VertexColor,
    pd);

basicEffect->SetProjection(XMMatrixOrthographicOffCenterRH(0,
    screenWidth, screenHeight, 0, 0, 1));

Drawing

basicEffect->Apply(commandList);

primitiveBatch->Begin(commandList);
primitiveBatch->DrawLine(VertexPositionColor(...), VertexPositionColor(...));
primitiveBatch->End();

PrimitiveBatch provides five drawing methods:

• DrawLine(v1, 2): Draws a single-pixel line between two vertices
• DrawTriangle(v1, v2, v3): Draws a triangle between three vertices
• DrawQuad(v1, v2, v3, v4): draws a quad from four corner vertices (submitted as two triangles)
• Draw(topology, vertices, vertexCount): Draws an array of vertices with the given topology
• DrawIndexed(topology, indices, indexCount, vertices, vertexCount): Draws an indexed array of vertices with a given topology.

Because of the way that Direct3D 12 Pipeline State Objects (PSOs) work, you must submit all the same 'topology group' items together that match the active PSO, end the batch, set up a new PSO with a different tpology type, and then start new batch. For example, if your PSO is set for D3D12_PRIMITIVE_TOPOLOGY_TYPE_TRIANGLE, you must use DrawTriangle, DrawQuad, or Draw/DrawIndexed using D3D_PRIMITIVE_TOPOLOGY_TRIANGLELIST, D3D_PRIMITIVE_TOPOLOGY_TRIANGLELIST_ADJ, D3D_PRIMITIVE_TOPOLOGY_TRIANGLESTRIP, or D3D_PRIMITIVE_TOPOLOGY_TRIANGLESTRIP_ADJ. Any other topology type will fail.

Optimization

For best performance, draw as much as possible inside the fewest separate Begin/End blocks. This will reduce overhead and maximize potential for batching.

Ideally submit draws of the same topology to avoid flushing, and preferably use D3D_PRIMITIVE_TOPOLOGY_POINTLIST, D3D_PRIMITIVE_TOPOLOGY_LINELIST, or D3D_PRIMITIVE_TOPOLOGY_TRIANGLELIST.

The PrimitiveBatch constructor allows you to specify what size index and vertex buffers to allocate. You may want to tweak these values to fit your workload, or if you only intend to draw non-indexed geometry, specify maxIndices = 0 to entirely skip creating the index buffer.

Draw order

Until End is called on PrimitiveBatch, the various Draw statements are likely still buffered. They are always drawn in the order of the individual Draw statements, but if mixing PrimitiveBatch drawing with other drawing, you need to call End before they will all be submitted to Direct3D.