mesh-converter

name: mesh-converter description: >- Guide for using the meshconvert command-line tool to convert Wavefront OBJ files to DirectX runtime formats (CMO, SDKMESH, VBO). license: MIT metadata: author: chuckw version: "1.0"

Mesh Converter Skill

This skill provides guidance for using the meshconvert command-line tool to convert Wavefront OBJ geometry files into runtime formats consumed by DirectX Tool Kit.

When to Use

Invoke this skill when:

• Converting Wavefront OBJ files to SDKMESH, CMO, or VBO format.
• Preparing mesh geometry for use with DirectX Tool Kit (DirectXTK).
• Generating normals, tangents, or performing vertex-cache optimization on mesh data.
• Understanding the available output formats and their requirements.

Overview

The meshconvert tool imports geometry from Wavefront Object (OBJ) or VBO files and prepares it for runtime use. It can generate normals and tangent frames, perform vertex-cache optimization, and write to formats suited for DirectX applications.

• Repository: https://github.com/microsoft/DirectXMesh
• Documentation: https://github.com/microsoft/DirectXMesh/wiki/Meshconvert
• Installation: winget install Microsoft.DirectX.Mesh

Installation

winget (Recommended)

winget install Microsoft.DirectX.Mesh

vcpkg

vcpkg install directxmesh[tools]

Basic Syntax

meshconvert [options] [--file-list <filename>] <file-name(s)>

The tool uses Windows-style - or / for options, and also supports GNU long options with --.

Output Formats

Common Workflows

Basic Conversion to SDKMESH (Default)

meshconvert model.obj

Produces model.sdkmesh with no additional processing.

Convert with Normals and Optimization

meshconvert model.obj -n -op

Generates normals (weight by angle) and performs vertex-cache optimization using the Hoppe algorithm.

Convert to CMO Format

CMO format requires normals, tangents, and texture coordinates:

meshconvert model.obj -ft cmo -n -tb

Convert to VBO Format

VBO format requires normals and texture coordinates:

meshconvert model.obj -ft vbo -n

Convert with Full Processing Pipeline

meshconvert model.obj -n -tb -op -y

Generates normals, tangent frames (tangents and bi-tangents), optimizes the vertex cache, and overwrites any existing output file.

Convert for Direct3D Coordinate System

OBJ files from tools using OpenGL conventions may need coordinate adjustments:

meshconvert model.obj -n -op --flip-v --flip-z

Flips the V texture coordinate and negates Z for right-hand to left-hand conversion.

Batch Conversion

meshconvert -r *.obj -n -op -y

Recursively processes all OBJ files in the current directory and subdirectories.

Or use a file list:

meshconvert --file-list models.txt -n -op -y

Where models.txt contains one filename per line (lines starting with # are comments).

Option Reference

See reference/options.md for the complete command-line options reference.

Format-Specific Notes

SDKMESH

• Default output format.
• Supports 16-bit and 32-bit index buffers (auto-selects 16-bit when possible).
• Supports configurable vertex formats for normals, UVs, and colors.
• Used by DirectX Tool Kit's Model class via Model::CreateFromSDKMESH.

CMO

• Visual Studio's mesh format.
• Requires normals, tangents, and texture coordinates — use -n -tb switches.
• Fixed vertex format (no -fn, -fuv, -fc, or -ib32 options).
• Used by DirectX Tool Kit's Model class via Model::CreateFromCMO.

VBO

• Simple binary format with position, normal, and texture coordinates.
• Requires normals and texture coordinates — use -n switch.
• Fixed vertex format (no -fn, -fuv, -fc, or -ib32 options).
• Limited to 65535 vertices (16-bit indices only).
• Used by DirectX Tool Kit's Model class via Model::CreateFromVBO.

Key References

• Meshconvert Wiki Page
• Geometry Formats
• VBO Format
• DirectX Tool Kit Model Class
• DirectX Tool Kit 12 Model Class