Getting Started

The DirectXMesh library provides functions for mesh-processing operations to prepare geometry for rendering by Direct3D. The project includes a C++ library, some optional Utility C++ files, and a program built using the library.

flowchart TD
    A(DirectXMesh C++ Library)
    A-->C
    B(<b>Utilities</b><br />WaveFrontReader)
    B-->C
    C[meshconvert]

Loading

The DirectXMesh library itself consists of a few functional areas:

graph LR

subgraph IB/VB cache optimization
    I[Attribute Sort]
    F[OptimizeFaces]
    L[OptimizeFacesLRU]
    V[OptimizeVertices]
end

subgraph Vertex Buffers
   R[Reader]
   W[Writer]
end

subgraph Input Layouts
    1[D3D11]
    2[D3D12]
end

subgraph Geometry operations
    A[Adjacency]
    C[Clean and validate]
    N[Normals, tangents,<br />and bi-tangents]
    D[Vertex weld]
    T[Concat]
    E[Helper functions]
end

Loading

Command-line Tool

The program meshconvert is a command-line tool for reading geometry data from a Wavefront obj format file, doing various mesh operations, and then writing out a 'runtime' mesh format such as CMO, SDKMESH, or VBO. For example, this reads data from a WaveFront obj file cup.obj, generates normals, and then writes out the result to a VBO.

meshconvert cup.obj -n -ft vbo

• SDKMESH was created for the legacy DirectX SDK as a replacement for ".X" files used in older samples. The original format was updated with a variant that supports PBR materials. The DirectX Tool Kit supports loading these files. For technical details on the format, see SDKMESH.h.

• CMO or Compiled Mesh Object was introduced with Visual Studio 2012 in their Mesh Content Pipeline. Note that the mesh pipeline was removed in VS 2022 17.9.3 or later due to security concerns. The DirectX Tool Kit supports loading these files. For technical details on the format, see CMO.h.

• VBO or Vertex Buffer Object was introduced with Windows 8 era DirectX Samples. It's trivial format containing two counts, a Vertex Buffer in a fixed vertex format, and a 16-bit Index Buffer. The DirectX Tool Kit supports loading these files. For technical details on the format, see VBO.h.

While there are numerous widely-known formats for 3D model data, there is no single format that is considered 'standard' for runtime mesh content. As such, the DirectXMesh library itself does not have any code for saving mesh data to disk. Instead, the meshconvert command-line tool includes code for writing three common formats used in Microsoft samples.

"Hello, World"

This is a simple example that reads a WaveFront model, computes normals for it, and then writes it as a VBO file.

#define NOMINMAX
#include <Windows.h>

#include "DirectXMesh.h"

#include "WaveFrontReader.h"

#include <cstdio>
#include <iterator>
#include <memory>

namespace
{
    struct header_t
    {
        uint32_t numVertices;
        uint32_t numIndices;
    };

    // VBO vertex format matches DX::WaveFrontReader::Vertex
    constexpr size_t c_stride = 32;
}

using namespace DirectX;

int main()
{
    // Read model from WaveFront OBJ file
    auto mesh = std::make_unique<DX::WaveFrontReader<uint16_t>>();

    HRESULT hr = mesh->Load(L"cup.obj");
    if (FAILED(hr))
    {
        wprintf(L"Failed to load cup.obj (%08X)\n", static_cast<unsigned int>(hr));
        return 1;
    }

    auto reader = std::make_unique<VBReader>();

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

    size_t nVerts = mesh->vertices.size();
    size_t nFaces = mesh->indices.size() / 3;

    printf("cup.obj: %zu vertices, %zu faces\n", nVerts, nFaces);

    hr = reader->Initialize(layout, std::size(layout));
    if (SUCCEEDED(hr))
    {
        hr = reader->AddStream(mesh->vertices.data(), nVerts, 0, c_stride);
    }
    if (FAILED(hr))
    {
        wprintf(L"Failed creating VB reader (%08X)\n", static_cast<unsigned int>(hr));
        return 1;
    }

    // Compute normals
    auto pos = std::make_unique<XMFLOAT3[]>(nVerts);
    hr = reader->Read(pos.get(), "POSITION", 0, nVerts);
    if (FAILED(hr))
    {
        wprintf(L"Failed reading vertex positions (%08X)\n", static_cast<unsigned int>(hr));
        return 1;
    }

    auto normals = std::make_unique<XMFLOAT3[]>(nVerts);
    hr = ComputeNormals(
            mesh->indices.data(), nFaces,
            pos.get(), nVerts, CNORM_DEFAULT, normals.get());
    if (FAILED(hr))
    {
        wprintf(L"Failed computing normals (%08X)\n", static_cast<unsigned int>(hr));
        return 1;
    }

    // Store computed normals back into vertex
    auto writer = std::make_unique<VBWriter>();

    hr = writer->Initialize(layout, std::size(layout));
    if (SUCCEEDED(hr))
    {
        hr = writer->AddStream(mesh->vertices.data(), nVerts, 0, c_stride);
    }
    if (FAILED(hr))
    {
        wprintf(L"Failed creating VB writer (%08X)\n", static_cast<unsigned int>(hr));
        return 1;
    }

    hr = writer->Write(normals.get(), "NORMAL", 0, nVerts);
    if (FAILED(hr))
    {
        wprintf(L"Failed writing updated normals (%08X)\n", static_cast<unsigned int>(hr));
        return 1;
    }

    // Save VBO file
    header_t header = {};
    header.numVertices = static_cast<uint32_t>(nVerts);
    header.numIndices = static_cast<uint32_t>(nFaces * 3);

    FILE* f = nullptr;
    errno_t err = fopen_s(&f, "cup.vbo", "wb");
    if (err || !f)
    {
        wprintf(L"Failed opening output file cup.vbo (%d)\n", err);
        return 1;
    }

    size_t written = fwrite(&header, sizeof(header), 1, f);
    if (written != 1)
    {
        wprintf(L"Failed writing header to cup.vbo (%zu)\n", written);
        fclose(f);
        return 1;
    }

    written = fwrite(mesh->vertices.data(), c_stride, nVerts, f);
    if (written != nVerts)
    {
        wprintf(L"Failed writing vertex data to cup.vbo (%zu)\n", written);
        fclose(f);
        return 1;
    }

    written = fwrite(mesh->indices.data(), sizeof(uint16_t), nFaces * 3, f);
    if (written != nFaces * 3)
    {
        wprintf(L"Failed writing index data to cup.vbo (%zu)\n", written);
        fclose(f);
        return 1;
    }

    fclose(f);

    printf("Successfully wrote cup.vbo\n");

    return 0;
}

Further reading

DirectXMesh provides details on how to build and link the library

See meshconvert for more details on the command-line tool.