cgltf Documentation

cgltf is a single-file/stb-style C library. To integrate it, follow these steps:

1. Include cgltf.h in your project files.
2. In exactly one C source file, define CGLTF_IMPLEMENTATION before including the header to generate the implementation.
3. If you need writing support, you must also define CGLTF_WRITE_IMPLEMENTATION in your implementation file and include cgltf_write.h.

Note: cgltf_write.h includes cgltf.h, so ensure your implementation defines are handled correctly to avoid multiple definition errors.

#define CGLTF_IMPLEMENTATION
#include "cgltf.h"

// If writing is needed:
#define CGLTF_WRITE_IMPLEMENTATION
#include "cgltf_write.h"

To write glTF data, you need a valid cgltf_data structure. You can use a structure you constructed manually or one loaded via the parser.

Warning: The writer functions do not deallocate memory. If you obtained your cgltf_data via cgltf_parse or cgltf_parse_file, you must call cgltf_free() manually after writing. Also, cgltf does not write the contents of external files (buffers/images); you must handle that data yourself.

#define CGLTF_IMPLEMENTATION
#define CGLTF_WRITE_IMPLEMENTATION
#include "cgltf_write.h"

cgltf_options options = {0};
cgltf_data* data = /* TODO must be valid data */;
cgltf_result result = cgltf_write_file(&options, "out.gltf", data);
if (result != cgltf_result_success)
{
	/* TODO handle error */
}

Use cgltf_parse to load glTF data from an existing memory buffer. This is useful when the file data is already in memory (e.g., loaded via a custom asset manager).

Note on Images: For data URIs in images, you will need to use cgltf_load_buffer_base64 manually, as they are not loaded by default.

#define CGLTF_IMPLEMENTATION
#include "cgltf.h"

void* buf; /* Pointer to glb or gltf file data */
size_t size; /* Size of the file data */

cgltf_options options = {0};
cgltf_data* data = NULL;
cgltf_result result = cgltf_parse(&options, buf, size, &data);
if (result == cgltf_result_success)
{
	/* TODO make awesome stuff */
	cgltf_free(data);
}

Use cgltf_parse_file to load a glTF or GLB file from disk. You must provide a cgltf_options struct (can be zero-initialized) and a pointer to a cgltf_data* which will be populated on success.

Important: By default, cgltf does not load external buffer or image files into memory. You must manually read these using the URIs provided in data->buffers[] or data->images[]. Alternatively, you can call cgltf_load_buffers to automatically use FILE* APIs to read buffer files and decode base64 data URIs in buffers.

#define CGLTF_IMPLEMENTATION
#include "cgltf.h"

cgltf_options options = {0};
cgltf_data* data = NULL;
cgltf_result result = cgltf_parse_file(&options, "scene.gltf", &data);
if (result == cgltf_result_success)
{
	/* TODO make awesome stuff */
	cgltf_free(data);
}

Writing to memory is a two-step process with cgltf_write:

1. Call cgltf_write with a NULL buffer and 0 size to determine the required buffer size (cgltf_size).
2. Allocate a buffer of that size and call cgltf_write again with the allocated buffer to perform the actual write.

As with file writing, the writer does not handle external buffer/image data or deallocate the cgltf_data structure.

#define CGLTF_IMPLEMENTATION
#define CGLTF_WRITE_IMPLEMENTATION
#include "cgltf_write.h"
cgltf_options options = {0};
cgltf_data* data = /* TODO must be valid data */;

cgltf_size size = cgltf_write(&options, NULL, 0, data);

char* buf = malloc(size);

cgltf_size written = cgltf_write(&options, buf, size, data);
if (written != size)
{
	/* TODO handle error */
}