VBWriter

DirectXMesh

This C++ class is used to write elements into vertex buffer(s) based on a Direct3D input layout description. Data is provided as arrays by individual semantics (i.e. POSITION or NORMALS).

This can be used to 'edit' an existing Vertex Buffer by overwriting some or all of the elements of the layout, or to create a new vertex buffer interleaving and encoding the data for use with Direct3D.

This class supports multi-stream vertex buffer descriptions, but does not support instancing vertex buffers.

Header

#include "DirectXMesh.h"

By default, the library supports Direct3D 11. If you want to support Direct3D 12, then you need to #include <d3d12.h> before you do #include "DirectXMesh.h".

Usage

Initialization

The writer is initialized by providing a input layout description for the vertex buffer data, and then one or more memory buffers for the output streams.

auto writer = std::make_unique<VBWriter>();

D3D11_INPUT_ELEMENT_DESC layout[] =
{
    { "POSITION", 0, DXGI_FORMAT_R32G32B32_FLOAT, 0, 0, D3D11_INPUT_PER_VERTEX_DATA, 0 },
    { "TEXCOORD", 0, DXGI_FORMAT_R32G32_FLOAT, 0, 12, D3D11_INPUT_PER_VERTEX_DATA, 0 },
};

struct Vertex
{
    XMFLOAT3 Pos;
    XMFLOAT2 Tex;
};

if ( FAILED( writer->Initialize( layout, 2 ) ) )
   // Error

// For Direct3D 12, use:
//    D3D12_INPUT_LAYOUT_DESC desc = { layout, 2 };
//    if ( FAILED( reader->Initialize( desc ) ) )

auto vb = std::make_unique<uint8_t[]>(sizeof(Vertex) * nVerts);

// We are creating a new VB, so a good practice would be to zero-fill it.
memset( vb.get(), 0, sizeof(Vertex) * nVerts );

if ( FAILED( writer->AddStream( vb.get(), nVerts, 0, sizeof(Vertex) ) ) )
   // Error

Note that AddStream can accept a stride of 0 which means to use the stride implied by the input layout description.

Inserting vertex data

The writer is designed to insert an array of XMVECTOR values given the layout semantic name and semantic index.

struct aligned_deleter { void operator()(void* p) { _aligned_free(p); } };

std::unique_ptr<XMVECTOR[], aligned_deleter> buff(
    reinterpret_cast<XMVECTOR*>( _aligned_malloc( sizeof(XMVECTOR) * nVerts, 16 ) ) );
std::unique_ptr<XMVECTOR[], aligned_deleter> buff2(
    reinterpret_cast<XMVECTOR*>( _aligned_malloc( sizeof(XMVECTOR) * nVerts, 16 ) ) );

// Store position data into XMVECTOR buff array
// Store texcoord data into XMVECTOR buff2 array

if ( FAILED( writer->Write( buff.get(), "POSITION", 0, nVerts ) ) )
   // Error

if ( FAILED( writer->Write( buff2.get(), "TEXCOORD", 0, nVerts ) ) )
   // Error

To simplify implementation of applications, the writer will accept either POSITION or SV_Position as an alias for the actual semantic name provided in the layout.

Overloads

The Write method has overloads for float, XMFLOAT2, XMFLOAT3, and XMFLOAT4 data arrays, in addition to native XMVECTOR arrays.

Biased data

The Write method takes an optional bool x2bias that defaults to false. If set to true, then DXGI_FORMAT_x_UNORM and DXGI_FORMAT_R11G11B10_FLOAT values are scaled so that the -1 to 1 range becomes 0 to 1. Typically this is used to store normals in compressed formats such as DXGI_FORMAT_R10G10B10A2_UNORM.

Accessors

The GetElement11 method can be used to obtain the original Direct3D 11 input layout element from the semantic information.

The GetElement12 method can be used to obtain the original Direct3D 12 input layout element from the semantic information.

Returns

Return success or failure as a HRESULT error code (E_INVALIDARG, E_OUTOFMEMORY, E_FAIL, E_BOUNDS, E_UNEXPECTED, HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED), or HRESULT_FROM_WIN32(ERROR_INVALID_NAME)).

Exceptions

Most methods in this class are marked noexcept and only return HRESULT error codes.

The constructor can throw a C++ exception in the case of a failed memory allocation.

The Initialize and GetElement methods makes use of a Standard C++ Library container so may throw C++ exceptions in some cases.

Remarks

The class does not support input layouts used for instancing.

Further reading

Semantics