Mesh Converter

Documents

mesh-converter

Mesh Converter is an Agent Skill for documents published in the microsoft/DirectXMesh repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Guide for using the meshconvert command-line tool to convert Wavefront OBJ files to DirectX runtime formats (CMO, SDKMESH, VBO).

View on GitHub ↗

QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

Open your project in Codex.
Copy and paste the prompt below.
Review files and risks before approving any action.

Prompt to paste

Inspect the Agent Skill at https://github.com/microsoft/DirectXMesh/blob/HEAD/skills/mesh-converter/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/mesh-converter, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

Format	Switch	Description	Requirements
SDKMESH	`-ft sdkmesh`	Default output format for DirectX Tool Kit `Model` class	None
SDKMESH (PBR)	`-ft sdkmesh2`	SDKMESH with PBR materials	None
CMO	`-ft cmo`	Visual Studio CMO format for DirectX Tool Kit `Model` class	Normals, tangents, and texture coordinates
VBO	`-ft vbo`	Simple vertex buffer object format for DirectX Tool Kit	Normals and texture coordinates
OBJ	`-ft obj`	Re-export as Wavefront OBJ	None

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.