API
glTF enumerations
AccessorType
-
enum class fastgltf::AccessorType : std::uint8_t
Represents the type of element in the buffer pointed to by the accessor.
We encode these values with the number of components in their top 8 bits for fast access & storage. Therefore, use the fastgltf::getNumComponents and fastgltf::getElementByteSize functions to extract data from this enum.
0aaaaabbb, where a is the component num, and b is the type index.
Values:
-
enumerator Invalid
-
enumerator Scalar
-
enumerator Vec2
-
enumerator Vec3
-
enumerator Vec4
-
enumerator Mat2
-
enumerator Mat3
-
enumerator Mat4
-
enumerator Invalid
-
constexpr auto fastgltf::getNumComponents(AccessorType type) noexcept
Gets the number of components for each element for the given accessor type.
For example, with a Vec3 accessor type this will return 3, as a Vec3 contains 3 components.
-
constexpr auto fastgltf::getElementRowCount(AccessorType type) noexcept
Returns the number of rows in the given accessor type.
-
constexpr bool fastgltf::isMatrix(AccessorType type) noexcept
-
constexpr auto fastgltf::getElementByteSize(AccessorType type, ComponentType componentType) noexcept
Warning
doxygenfunction: Cannot find function “fastgltf::getAccessorType” in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml
Warning
doxygenfunction: Cannot find function “fastgltf::getAccessorTypeName” in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml
ComponentType
-
enum class fastgltf::ComponentType : std::uint16_t
Represents the various types of components an accessor could point at.
This describes the format each component of the structure, which in return is described by fastgltf::AccessorType, is in.
As the constants used to identify component type in glTF fit within 13-bits, we store them in the lower 13 bits. The remaining three bits are then used to store the byte width of the type, minus 1, as 8 is not representable with just three bits.
To get the byte or bit size of a component, use the fastgltf::getComponentByteSize or fastgltf::getComponentBitSize, respectively. To get the OpenGL constant for the component type, use fastgltf::getGLComponentType.
aaabbbbbbbbbbbbb, where a is the byte size, and b the OpenGL type enumeration.
Values:
-
enumerator Invalid
-
enumerator Byte
-
enumerator UnsignedByte
-
enumerator Short
-
enumerator UnsignedShort
-
enumerator HalfFloat
Half floats are allowed either when using glTF 2.1 or KHR_accessor_float16.
-
enumerator Int
Signed integers are allowed when using glTF 2.1.
-
enumerator UnsignedInt
-
enumerator Float
-
enumerator Int64
Signed 64-bit integers are allowed when using glTF 2.1.
-
enumerator UnsignedInt64
Unsigned 64-bit integers are allowed when using glTF 2.1.
-
enumerator Double
Doubles are allowed either when using glTF 2.1, KHR_accessor_float64, or with AllowDouble.
-
enumerator Invalid
-
constexpr auto fastgltf::getComponentByteSize(ComponentType componentType) noexcept
-
constexpr auto fastgltf::getComponentBitSize(ComponentType componentType) noexcept
-
constexpr auto fastgltf::getGLComponentType(ComponentType type) noexcept
Returns the OpenGL component type enumeration for the given component type.
All OpenGL enumerations use GLenum, which is a 32-bit wide integer, which is why this function returns a std::uint32_t.
For example, getGLComponentType(ComponentType::Float) will return GL_FLOAT (0x1406).
Warning
doxygenfunction: Cannot find function “fastgltf::getComponentType” in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml
PrimitiveType
Filter
Wrap
BufferTarget
MimeType
AnimationInterpolation
-
enum class fastgltf::AnimationInterpolation : std::uint8_t
Values:
-
enumerator Linear
The animated values are linearly interpolated between keyframes.
When targeting a rotation, spherical linear interpolation (slerp) SHOULD be used to interpolate quaternions.
-
enumerator Step
The animated values remain constant to the output of the first keyframe, until the next keyframe.
-
enumerator CubicSpline
The animation’s interpolation is computed using a cubic spline with specified tangents.
The number of output elements MUST equal three times the number of input elements. For each input element, the output stores three elements, an in-tangent, a spline vertex, and an out-tangent.
-
enumerator Linear
AnimationPath
-
enum class fastgltf::AnimationPath : std::uint8_t
Values:
-
enumerator Translation
The values are the translation along the X, Y, and Z axes.
-
enumerator Rotation
The values are a quaternion in the order x, y, z, w where w is the scalar.
-
enumerator Scale
The values are scaling factors along the X, Y, and Z axes.
-
enumerator Weights
-
enumerator Translation
AlphaMode
MeshoptCompressionMode
MeshoptCompressionFilter
LightType
glTF structs
This section contains all types fastgltf provides to represent data from a glTF asset.
DataSource
-
using fastgltf::DataSource = std::variant<std::monostate, sources::BufferView, sources::URI, sources::Array, sources::Vector, sources::CustomBuffer, sources::ByteView, sources::Fallback>
Represents the data source of a buffer or image.
These could be a buffer view, a file path (including offsets), a static_vector (if #Options::LoadExternalBuffers or #Options::LoadGLBBuffers was specified), or the ID of a custom buffer.
Note
As a user, you should never encounter this variant holding the std::monostate, as that would be an ill-formed glTF, which fastgltf already checks for while parsing.
Note
For buffers, this variant will never hold a sources::BufferView, as only images are able to reference buffer views as a source.
AssetInfo
-
struct AssetInfo
Accessor
-
struct Accessor
Public Functions
- template<typename T> inline requires AccessorBoundsArray::is_valid_type_v< T > void updateBoundsToInclude (T value)
Helper function that updates the max/min variables dynamically.
- template<typename T, std::size_t N> inline requires AccessorBoundsArray::is_valid_type_v< T > void updateBoundsToInclude (math::vec< T, N > value)
Helper function that updates the max/min variables dynamically.
Note that the value passed in needs to be a vector with the same size as max/min
Public Members
-
std::size_t byteOffset = 0
-
std::size_t count
-
bool normalized = false
-
AccessorType type
-
ComponentType componentType
-
optional<AccessorBoundsArray> max
-
optional<AccessorBoundsArray> min
-
optional<std::size_t> bufferViewIndex
-
boxed_optional<SparseAccessor> sparse
-
std::string name
Animation
-
struct Animation
Buffer
-
struct Buffer
BufferView
-
struct BufferView
Public Members
-
std::size_t bufferIndex
-
std::size_t byteOffset = 0
-
std::size_t byteLength
-
optional<std::size_t> byteStride
-
optional<BufferTarget> target
-
boxed_optional<CompressedBufferView> meshoptCompression
Data from EXT_meshopt_compression or KHR_meshopt_compression, or empty if the extension was not enabled or used.
-
std::string name
-
std::size_t bufferIndex
Camera
-
struct Camera
Public Members
-
std::variant<Perspective, Orthographic> camera
Variant holding either a perspective or a orthographic camera.
Use std::holds_alternative and/or std::get_if to figure out which camera type is being used.
-
std::string name
-
struct Orthographic
-
struct Perspective
-
std::variant<Perspective, Orthographic> camera
Image
-
struct Image
Light
-
struct Light
Public Members
-
math::nvec3 color
RGB light color in linear space.
-
num intensity
Point and spot lights use candela (lm/sr) while directional use lux (lm/m^2)
-
optional<num> range
Range for point and spot lights.
If not present, range is infinite.
-
optional<num> innerConeAngle
The inner and outer cone angles only apply to spot lights.
-
optional<num> outerConeAngle
-
std::string name
-
math::nvec3 color
Material
-
struct Material
Public Members
-
PBRData pbrData
A set of parameter values that are used to define the metallic-roughness material model from Physically Based Rendering (PBR) methodology.
-
optional<NormalTextureInfo> normalTexture
The tangent space normal texture.
-
boxed_optional<OcclusionTextureInfo> occlusionTexture
-
boxed_optional<TextureInfo> emissiveTexture
-
math::nvec3 emissiveFactor = math::nvec3(0)
The factors for the emissive color of the material.
-
AlphaMode alphaMode = AlphaMode::Opaque
The values used to determine the transparency of the material.
-
bool doubleSided = false
Determines whether back-face culling should be disabled when using this material.
-
bool unlit = false
Only true when KHR_materials_unlit is enabled and specified for this material.
-
num alphaCutoff = 0.5f
The alpha value that determines the upper limit for fragments that should be discarded for transparency.
-
num emissiveStrength = 1.0f
The emissive strength from the KHR_materials_emissive_strength extension.
-
num ior = 1.5f
The index of refraction as specified through KHR_materials_ior.
-
num dispersion = 0.0f
The dispersion factor from KHR_materials_dispersion, specifies as 20/Abbe number (20/V).
-
boxed_optional<MaterialAnisotropy> anisotropy
-
boxed_optional<MaterialClearcoat> clearcoat
-
boxed_optional<MaterialDiffuseTransmission> diffuseTransmission
Diffuse transmission information from KHR_materials_diffuse_transmission.
-
boxed_optional<MaterialIridescence> iridescence
Iridescence information from KHR_materials_iridescence.
-
boxed_optional<MaterialSheen> sheen
-
boxed_optional<MaterialSpecular> specular
Specular information from KHR_materials_specular.
-
boxed_optional<MaterialSpecularGlossiness> specularGlossiness
Specular/Glossiness information from KHR_materials_pbrSpecularGlossiness.
-
boxed_optional<MaterialTransmission> transmission
Specular information from KHR_materials_transmission.
-
boxed_optional<MaterialVolume> volume
Volume information from KHR_materials_volume.
-
boxed_optional<TextureInfo> packedNormalMetallicRoughnessTexture
The index of a packed texture from the MSFT_packing_normalRoughnessMetallic extension, providing normal, roughness and metallic data.
-
boxed_optional<MaterialPackedTextures> packedOcclusionRoughnessMetallicTextures
-
std::string name
-
PBRData pbrData
Mesh
-
struct Mesh
Node
-
struct Node
Public Functions
- inline auto findInstancingAttribute (const std::string_view attributeName) noexcept FASTGLTF_LIFETIMEBOUND
- inline auto findInstancingAttribute (const std::string_view attributeName) const noexcept FASTGLTF_LIFETIMEBOUND
Public Members
-
optional<std::size_t> meshIndex
-
optional<std::size_t> skinIndex
-
optional<std::size_t> cameraIndex
-
optional<std::size_t> lightIndex
Only ever non-empty when KHR_lights_punctual is enabled and used by the asset.
-
std::vector<std::size_t> children
-
std::vector<num> weights
-
std::variant<TRS, math::nmat4x4> transform
Variant holding either the three TRS components; transform, rotation, and scale, or a transformation matrix, which cannot skew or shear.
The latter can be decomposed into the TRS components by specifying Options::DecomposeNodeMatrices.
-
bool visible = true
-
bool selectable = true
-
bool hoverable = true
-
std::vector<Attribute> instancingAttributes
Only ever non-empty when EXT_mesh_gpu_instancing is enabled and used by the asset.
-
boxed_optional<PhysicsRigidBody> physicsRigidBody
-
std::string name
Sampler
-
struct Sampler
Scene
-
struct Scene
Skin
-
struct Skin
Texture
-
struct Texture
Public Members
-
optional<std::size_t> samplerIndex
If no sampler is specified, use a default sampler with repeat wrap and auto filter.
-
optional<std::size_t> imageIndex
The index of the image used by this texture.
Either this will have a value, or one of the following extensions will define a texture index. If no extensions were enabled while parsing, this will always have a value.
-
optional<std::size_t> basisuImageIndex
An optional texture index from the KHR_texture_basisu extension.
-
optional<std::size_t> ddsImageIndex
An optional texture index from the MSFT_texture_dds extension.
-
optional<std::size_t> webpImageIndex
An optional texture index from the EXT_texture_webp extension.
-
optional<std::size_t> avifImageIndex
An optional texture index from the EXT_texture_avif extension.
-
std::string name
-
optional<std::size_t> samplerIndex
Asset
-
class Asset
Public Functions
-
explicit Asset() = default
Public Members
-
std::vector<std::string> extensionsUsed
-
std::vector<std::string> extensionsRequired
-
optional<std::size_t> defaultScene
-
std::vector<BufferView> bufferViews
-
std::vector<CollisionFilter> collisionFilters
-
std::vector<PhysicsMaterial> physicsMaterials
-
std::vector<PhysicsJoint> physicsJoints
-
std::vector<Shape> shapes
-
std::vector<std::string> materialVariants
-
Category availableCategories = Category::None
-
explicit Asset() = default
Reading & Writing
This section contains all types that one requires to read or write a glTF file using fastgltf. This includes the Parser class, Exporter class, options, and data buffers.
Error
-
enum class fastgltf::Error : std::uint64_t
Values:
-
enumerator None
-
enumerator InvalidPath
The glTF directory passed to load*GLTF is invalid.
-
enumerator MissingExtensions
One or more extensions are required by the glTF but not enabled in the Parser.
-
enumerator UnknownRequiredExtension
An extension required by the glTF is not supported by fastgltf.
-
enumerator UnsupportedVersion
The glTF version is not supported by fastgltf.
-
enumerator InvalidVersion
The glTF version string is invalid or not recognized.
-
enumerator ValueOutOfRange
A numeric value in the JSON is outside of the range fastgltf can represent.
-
enumerator InvalidJson
An error occurred while parsing the JSON.
-
enumerator MissingField
A field is missing that is required by the glTF spec.
-
enumerator UnexpectedJsonType
A value in the JSON had an unexpected type.
-
enumerator InvalidGltf
The glTF is either missing something or has invalid data.
-
enumerator InvalidOrMissingAssetField
The glTF asset object is missing or invalid.
-
enumerator InvalidGLB
The GLB container is invalid.
-
enumerator MissingExternalFile
An external file (a buffer or image) was not found.
-
enumerator MissingExternalBuffer
-
enumerator InvalidFileData
The file data is invalid, or the file type could not be determined.
-
enumerator FailedWritingFiles
The exporter failed to write some files (buffers/images) to disk.
-
enumerator FileBufferAllocationFailed
The constructor of GltfDataBuffer failed to allocate a sufficiently large buffer.
-
enumerator Unknown
Something unexpected happened. This is likely a bug with fastgltf.
-
enumerator None
Extensions
Warning
doxygenenum: Cannot find enum “fastgltf::Extensions” in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml
-
constexpr std::string_view fastgltf::stringifyExtension(Extensions extensions)
Returns the name of the passed glTF extension.
Note
If
extensionshas more than one bit set (multiple extensions), this will return the name of the first set bit.
-
inline auto fastgltf::stringifyExtensionBits(const Extensions extensions) -> decltype(Asset::extensionsRequired)
Returns a list of extension names based on the given extension flags.
Category
Warning
doxygenenum: Cannot find enum “fastgltf::Category” in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml
Options
Warning
doxygenenum: Cannot find enum “fastgltf::Options” in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml
ExportOptions
Warning
doxygenenum: Cannot find enum “fastgltf::ExportOptions” in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml
Expected
-
template<typename T, typename E = Error>
class Expected A tagged union that stores either T or an Error.
To inspect if an error has occurred, use hasError(), error(), or operator bool(). If hasError() returned false or error() return Error::None then one of the value getters, such as get() or operator*() can be used.
Public Functions
-
inline Expected(error_type error)
- template<typename U> inline requires std::is_convertible_v< U, T > Expected (U &&other) noexcept(std::is_nothrow_move_constructible_v< T >)
- template<typename U> inline explicit requires std::is_convertible_v< U, T > Expected (Expected< U > &&other) noexcept(std::is_nothrow_move_constructible_v< T >)
-
inline ~Expected()
-
inline bool has_error() const noexcept
-
inline bool has_value() const noexcept
-
inline error_type error() const
-
inline reference get()
Returns a reference to the value of T.
When has_value() is false, the returned value is undefined.
-
inline const_reference get() const
-
inline pointer get_if() noexcept
Returns the address of the value of T, or nullptr if has_value() is false.
-
inline const_pointer get_if() const noexcept
-
inline pointer operator->()
-
inline const_pointer operator->() const
-
inline reference operator*()
-
inline const_reference operator*() const
-
inline operator bool() const noexcept
-
inline Expected(error_type error)
GltfDataGetter
-
class GltfDataGetter
This interface defines how the parser can read the bytes making up a glTF or GLB file.
Subclassed by fastgltf::GltfDataBuffer, fastgltf::GltfDataString, fastgltf::GltfFileStream
Public Functions
-
virtual ~GltfDataGetter() noexcept = default
-
virtual void read(void *ptr, std::size_t count) = 0
The read functions expect the implementation to store an offset from the start of the buffer/file to the current position.
The parse process will always linearly access the memory, meaning it will go through the memory once from start to finish.
- virtual std::span< std::byte > read (std::size_t count, std::size_t padding) FASTGLTF_LIFETIMEBOUND=0
Reads a chunk of memory from the current offset, with some amount of padding.
This padding is necessary for the simdjson parser, but can be initialized to anything. The memory pointed to by the span only needs to live until the next call to read().
-
virtual void reset() = 0
Reset is used to put the offset index back to the start of the buffer/file.
This is only necessary for functionality like determineGltfFileType. However, reset() will be called at the beginning of every parse process.
-
virtual std::size_t bytesRead() = 0
-
virtual std::size_t totalSize() = 0
-
virtual ~GltfDataGetter() noexcept = default
GltfDataBuffer
-
class GltfDataBuffer : public fastgltf::GltfDataGetter
Public Functions
-
explicit GltfDataBuffer() noexcept = default
-
GltfDataBuffer(const GltfDataBuffer &other) = delete
-
GltfDataBuffer &operator=(const GltfDataBuffer &other) = delete
-
GltfDataBuffer(GltfDataBuffer &&other) noexcept = default
-
GltfDataBuffer &operator=(GltfDataBuffer &&other) noexcept = default
-
~GltfDataBuffer() noexcept override = default
-
virtual void read(void *ptr, std::size_t count) override
The read functions expect the implementation to store an offset from the start of the buffer/file to the current position.
The parse process will always linearly access the memory, meaning it will go through the memory once from start to finish.
- virtual std::span< std::byte > read (std::size_t count, std::size_t padding) FASTGLTF_LIFETIMEBOUND override
Reads a chunk of memory from the current offset, with some amount of padding.
This padding is necessary for the simdjson parser, but can be initialized to anything. The memory pointed to by the span only needs to live until the next call to read().
-
virtual void reset() override
Reset is used to put the offset index back to the start of the buffer/file.
This is only necessary for functionality like determineGltfFileType. However, reset() will be called at the beginning of every parse process.
-
virtual std::size_t bytesRead() override
-
virtual std::size_t totalSize() override
- inline explicit operator std::span< std::byte > () const FASTGLTF_LIFETIMEBOUND
Public Static Functions
-
static inline Expected<GltfDataBuffer> FromPath(const std::filesystem::path &path) noexcept
-
static inline Expected<GltfDataBuffer> FromBytes(const std::byte *bytes, std::size_t count) noexcept
-
static inline Expected<GltfDataBuffer> FromSpan(const std::span<std::byte> data) noexcept
-
explicit GltfDataBuffer() noexcept = default
GltfFileStream
-
class GltfFileStream : public fastgltf::GltfDataGetter
Public Functions
-
explicit GltfFileStream(const std::filesystem::path &path)
-
~GltfFileStream() noexcept override = default
-
bool isOpen() const
-
virtual void read(void *ptr, std::size_t count) override
The read functions expect the implementation to store an offset from the start of the buffer/file to the current position.
The parse process will always linearly access the memory, meaning it will go through the memory once from start to finish.
- virtual std::span< std::byte > read (std::size_t count, std::size_t padding) FASTGLTF_LIFETIMEBOUND override
Reads a chunk of memory from the current offset, with some amount of padding.
This padding is necessary for the simdjson parser, but can be initialized to anything. The memory pointed to by the span only needs to live until the next call to read().
-
virtual void reset() override
Reset is used to put the offset index back to the start of the buffer/file.
This is only necessary for functionality like determineGltfFileType. However, reset() will be called at the beginning of every parse process.
-
virtual std::size_t bytesRead() override
-
virtual std::size_t totalSize() override
-
explicit GltfFileStream(const std::filesystem::path &path)
Parser
-
GltfType fastgltf::determineGltfFileType(GltfDataGetter &data)
This function starts reading into the buffer and tries to determine what type of glTF container it is.
This should be used to know whether to call Parser::loadGltfJson or Parser::loadGltfBinary.
Note
Usually, you’ll want to just use Parser::loadGltf, which will call this itself.
- Returns:
The type of the glTF file, either glTF, GLB, or Invalid if it was not determinable. If this function returns Invalid it is highly likely that the buffer does not actually represent a valid glTF file.
-
class Parser
A parser for one or more glTF files.
It uses a SIMD based JSON parser to maximize efficiency and performance at runtime.
Note
This class is not thread-safe.
Public Functions
-
explicit Parser(Extensions extensionsToLoad = Extensions::None) noexcept
-
~Parser()
-
Expected<Asset> loadGltf(GltfDataGetter &buffer, std::filesystem::path directory, Options options = Options::None, Category categories = Category::All)
Loads a glTF file from pre-loaded bytes.
This function tries to detect wether the bytes represent a standard JSON glTF or a binary glTF.
-
Expected<Asset> loadGltfJson(GltfDataGetter &buffer, std::filesystem::path directory, Options options = Options::None, Category categories = Category::All)
Loads a glTF file from pre-loaded bytes representing a JSON file.
-
Expected<Asset> loadGltfBinary(GltfDataGetter &buffer, std::filesystem::path directory, Options options = Options::None, Category categories = Category::All)
Loads a glTF file embedded within a GLB container, which may contain the first buffer of the glTF asset.
-
void setBufferAllocationCallback(BufferMapCallback *mapCallback, BufferUnmapCallback *unmapCallback = nullptr) noexcept
This function can be used to set callbacks so that you can control memory allocation for large buffers and images that are loaded from a glTF file.
For example, one could use the callbacks to map a GPU buffer through Vulkan or DirectX so that fastgltf can write the buffer directly to the GPU to avoid a copy into RAM first. To remove the callbacks for a specific load, call this method with both parameters as nullptr before load*GLTF. Using Parser::setUserPointer you can also set a user pointer to access your own class or other data you may need.
Note
This is likely only useful for advanced users who know what they’re doing.
- Parameters:
mapCallback – function called when the parser requires a buffer to write data embedded in a GLB file or decoded from a base64 URI, cannot be nullptr.
unmapCallback – function called when the parser is done with writing into a buffer, can be nullptr.
-
void setExtrasParseCallback(ExtrasParseCallback *extrasCallback) noexcept
-
void setUserPointer(void *pointer) noexcept
-
explicit Parser(Extensions extensionsToLoad = Extensions::None) noexcept
-
struct BufferInfo
Exporter
-
class Exporter
A exporter for serializing one or more glTF assets into JSON and GLB forms.
Note
This does not write anything to any files. This class only serializes data into memory structures, which can then be used to manually write them to disk. If you want to let fastgltf handle the file writing too, use fastgltf::FileExporter.
Subclassed by fastgltf::FileExporter
Public Functions
-
explicit Exporter()
-
~Exporter()
-
void setBufferPath(std::filesystem::path folder)
Sets the relative base path for buffer URIs.
If folder.is_relative() returns false, this has no effect.
-
void setImagePath(std::filesystem::path folder)
Sets the relative base path for image URIs.
If folder.is_relative() returns false, this has no effect.
-
void setExtrasWriteCallback(ExtrasWriteCallback *callback) noexcept
-
void setUserPointer(void *pointer) noexcept
-
Expected<ExportResult<std::string>> writeGltfJson(const Asset &asset, ExportOptions options = ExportOptions::None)
Generates a glTF JSON string from the given asset.
-
Expected<ExportResult<std::vector<std::byte>>> writeGltfBinary(const Asset &asset, ExportOptions options = ExportOptions::None)
Generates a glTF binary (GLB) blob from the given asset.
If the first buffer holds a sources::Vector, a sources::Array, a or sources::ByteView and the byte length is smaller than 2^32 (4.2GB), it will be embedded into the binary. Note that the returned vector might therefore get quite large.
-
struct impl
Public Functions
-
void setBufferPath(std::filesystem::path folder)
-
void setImagePath(std::filesystem::path folder)
-
void setExtrasWriteCallback(ExtrasWriteCallback *callback) noexcept
-
void setUserPointer(void *pointer) noexcept
Public Members
-
ExportOptions options = ExportOptions::None
-
bool exportingBinary = false
-
std::filesystem::path bufferFolder = ""
-
std::filesystem::path imageFolder = ""
-
void *userPointer = nullptr
-
ExtrasWriteCallback *extrasWriteCallback = nullptr
-
std::vector<std::optional<std::filesystem::path>> bufferPaths
-
std::vector<std::optional<std::filesystem::path>> imagePaths
-
void setBufferPath(std::filesystem::path folder)
-
explicit Exporter()
-
class FileExporter : public fastgltf::Exporter
A exporter for serializing one or more glTF files into JSON and GLB forms.
This exporter builds upon Exporter by writing all files automatically to the given paths.
Public Functions
-
Error writeGltfJson(const Asset &asset, const std::filesystem::path &target, ExportOptions options = ExportOptions::None)
Writes a glTF JSON string generated from the given asset to the specified target file.
This will also write all buffers and textures to disk using the buffer and image paths set using Exporter::setBufferPath and Exporter::setImagePath.
-
Error writeGltfBinary(const Asset &asset, const std::filesystem::path &target, ExportOptions options = ExportOptions::None)
Writes a glTF binary (GLB) blob from the given asset to the specified target file.
This will also write all buffers and textures to disk using the buffer and image paths set using Exporter::setBufferPath and Exporter::setImagePath.
If the first buffer holds a sources::Vector, a sources::Array, a or sources::ByteView and the byte length is smaller than 2^32 (4.2GB), it will be embedded into the binary.
See also
-
Error writeGltfJson(const Asset &asset, const std::filesystem::path &target, ExportOptions options = ExportOptions::None)
Math
fastgltf includes a small math library with everything necessary for working with glTF assets.
Warning
doxygenfunction: Unable to resolve function “fastgltf::math::clamp” with arguments None in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml. Potential matches:
- template<typename T, std::size_t N> auto clamp(const vec<T, N> &v, const T &min, const T &max) noexcept
- template<typename T> decltype(auto) clamp(const T &v, const T &min, const T &max) noexcept
Warning
doxygenfunction: Unable to resolve function “fastgltf::math::lerp” with arguments None in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml. Potential matches:
- template<typename T, std::size_t N> auto lerp(const vec<T, N> &a, const vec<T, N> &b, const T &t) noexcept
- template<typename T> auto lerp(T a, T b, T t) noexcept
-
template<typename T>
auto fastgltf::math::radians(const T °rees) noexcept Degree to radians conversion.
-
template<typename T>
auto fastgltf::math::degrees(const T &radians) noexcept Radians to degrees conversion.
Vector
-
template<typename T, std::size_t N>
class vec Public Functions
-
inline constexpr vec() noexcept
- template<typename... Args> inline requires (sizeof...(Args)==N) const expr vec(Args... args) noexcept
Creates a new vector with N components from N values in the order X, Y, Z, W.
- template<typename U> requires (!std::is_same_v< T, U >) const expr explicit vec(const vec< U
Public Members
- N &other noexcept {for (std::size_t i = 0; i < N; ++i)(*this)[i] = static_cast<T>(other[i])
-
inline constexpr vec() noexcept
-
template<typename T, std::size_t N>
auto fastgltf::math::sum(const vec<T, N> &a) noexcept Reduction sum of a single vector.
Warning
doxygenfunction: Unable to resolve function “fastgltf::math::dot” with arguments None in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml. Potential matches:
- template<typename T, std::size_t N> auto dot(const vec<T, N> &a, const vec<T, N> &b) noexcept
- template<typename T> auto dot(const quat<T> &a, const quat<T> &b) noexcept
-
template<typename T>
auto fastgltf::math::cross(const vec<T, 3> &a, const vec<T, 3> &b) noexcept Computes the 3D cross product of two vectors.
-
template<typename T, std::size_t N>
T fastgltf::math::length(const vec<T, N> &v) noexcept Computes the euclidean length of this vector.
Warning
doxygenfunction: Unable to resolve function “fastgltf::math::normalize” with arguments None in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml. Potential matches:
- template<typename T, std::size_t N> auto normalize(const vec<T, N> &v) noexcept
- template<typename T> auto normalize(const quat<T> &q) noexcept
Warning
doxygenfunction: Unable to resolve function “fastgltf::math::clamp” with arguments None in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml. Potential matches:
- template<typename T, std::size_t N> auto clamp(const vec<T, N> &v, const T &min, const T &max) noexcept
- template<typename T> decltype(auto) clamp(const T &v, const T &min, const T &max) noexcept
Warning
doxygenfunction: Unable to resolve function “fastgltf::math::lerp” with arguments None in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml. Potential matches:
- template<typename T, std::size_t N> auto lerp(const vec<T, N> &a, const vec<T, N> &b, const T &t) noexcept
- template<typename T> auto lerp(T a, T b, T t) noexcept
Quaternion
-
template<std::floating_point T>
class quat A quaternion.
Public Functions
-
inline explicit constexpr quat() noexcept
- template<typename... Args> inline requires (sizeof...(Args)==4) const expr explicit quat(Args... args) noexcept
Creates a new quaternion from 4 floats in the order X, Y, Z, W.
- inline constexpr decltype(auto) operator[] (std::size_t idx) noexcept FASTGLTF_LIFETIMEBOUND
- inline constexpr decltype(auto) operator[] (std::size_t idx) const noexcept FASTGLTF_LIFETIMEBOUND
- inline constexpr decltype(auto) x () noexcept FASTGLTF_LIFETIMEBOUND
- inline constexpr decltype(auto) y () noexcept FASTGLTF_LIFETIMEBOUND
- inline constexpr decltype(auto) z () noexcept FASTGLTF_LIFETIMEBOUND
- inline constexpr decltype(auto) w () noexcept FASTGLTF_LIFETIMEBOUND
- inline constexpr decltype(auto) x () const noexcept FASTGLTF_LIFETIMEBOUND
- inline constexpr decltype(auto) y () const noexcept FASTGLTF_LIFETIMEBOUND
- inline constexpr decltype(auto) z () const noexcept FASTGLTF_LIFETIMEBOUND
- inline constexpr decltype(auto) w () const noexcept FASTGLTF_LIFETIMEBOUND
- inline constexpr auto data () noexcept FASTGLTF_LIFETIMEBOUND
- inline constexpr auto data () const noexcept FASTGLTF_LIFETIMEBOUND
-
inline constexpr auto operator+() const noexcept
-
inline constexpr auto operator-() const noexcept
-
inline explicit constexpr quat() noexcept
Warning
doxygenfunction: Unable to resolve function “fastgltf::math::dot” with arguments None in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml. Potential matches:
- template<typename T, std::size_t N> auto dot(const vec<T, N> &a, const vec<T, N> &b) noexcept
- template<typename T> auto dot(const quat<T> &a, const quat<T> &b) noexcept
Warning
doxygenfunction: Unable to resolve function “fastgltf::math::normalize” with arguments None in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml. Potential matches:
- template<typename T, std::size_t N> auto normalize(const vec<T, N> &v) noexcept
- template<typename T> auto normalize(const quat<T> &q) noexcept
Matrix
-
template<typename T, std::size_t N, std::size_t M>
class mat A matrix stored in column major order.
- Template Parameters:
N – Number of rows, or the length of a single column.
M – Number of columns, or the length of a single row.
Public Functions
-
inline explicit constexpr mat(T value = T(1)) noexcept
Initialises a identity matrix with a specified value.
- template<typename... Args> inline requires (sizeof...(Args)==M) const expr explicit mat(Args... args) noexcept
Creates a matrix from M vectors.
- template<typename... Args> inline requires (sizeof...(Args)==M *N) const expr explicit mat(Args... args) noexcept
Creates a matrix from N * M floats.
- template<std::size_t Q, std::size_t P> requires (N< Q &&M< P) const expr explicit mat(const mat< T
Truncates the matrix to a smaller one, discarding the additional rows and/or colums
- template<std::size_t Q, std::size_t P> requires (Q< N &&P< M) const expr explicit mat(const mat< T
Creates a larger matrix from a smaller one, while initializing the new components to identity
Public Members
- Q
- P &other noexcept {for (std::size_t i = 0; i < columns(); ++i)(*this).col(i) =vec<T, N>(other.col(i))
-
template<typename T, std::size_t N, std::size_t M>
auto fastgltf::math::transpose(const mat<T, N, M> &m) noexcept Transposes the given matrix.
Warning
doxygenfunction: Unable to resolve function “fastgltf::math::determinant” with arguments None in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml. Potential matches:
- template<typename T> auto determinant(const mat<T, 2, 2> &m) noexcept
- template<typename T> auto determinant(const mat<T, 3, 3> &m) noexcept
- template<typename T> auto determinant(const mat<T, 4, 4> &m) noexcept
Warning
doxygenfunction: Unable to resolve function “fastgltf::math::inverse” with arguments None in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml. Potential matches:
- template<typename T> auto inverse(const mat<T, 2, 2> &m) noexcept
- template<typename T> auto inverse(const mat<T, 3, 3> &m) noexcept
- template<typename T> auto inverse(const mat<T, 4, 4> &m) noexcept
-
template<typename T>
auto fastgltf::math::affineInverse(const mat<T, 4, 4> &m) noexcept Computes the affine inverse of a 4x4 matrix.
-
template<typename T>
auto fastgltf::math::translate(const mat<T, 4, 4> &m, const vec<T, 3> &translation) noexcept Translates a given transform matrix by the world space translation vector.
-
template<typename T>
auto fastgltf::math::scale(const mat<T, 4, 4> &m, const vec<T, 3> &scale) noexcept Scales a given matrix by the three dimensional scale vector.
-
template<typename T>
auto fastgltf::math::rotate(const mat<T, 4, 4> &m, const quat<T> &rot) noexcept Rotates the given matrix using the given quaternion.
-
template<std::floating_point T>
inline void fastgltf::math::decomposeTransformMatrix(mat<T, 4, 4> matrix, vec<T, 3> &scale, quat<T> &rotation, vec<T, 3> &translation) Decomposes a transform matrix into the translation, rotation, and scale components.
This function does not support skew, shear, or perspective. This currently uses a quick algorithm to calculate the quaternion from the rotation matrix, which might occasionally loose some precision, though we try to use doubles here.
Utility
This sections contains various types used by fastgltf to simplify & process glTF data, and for types used to enhance performance & minimize memory usage.
URIView
-
class URIView
Custom URI class for fastgltf’s needs.
glTF 2.0 only allows two types of URIs: (1) Data URIs as specified in RFC 2397. (2) Relative paths as specified in RFC 3986.
See https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#uris for details. However, the glTF spec allows more broader URIs in client implementations. Therefore, this supports all types of URIs as defined in RFC 3986.
Public Functions
-
URIView() noexcept = default
-
explicit URIView(std::string_view uri) noexcept
-
inline auto string() const noexcept
-
inline auto scheme() const noexcept
-
inline auto userinfo() const noexcept
-
inline auto host() const noexcept
-
inline auto port() const noexcept
-
inline auto path() const noexcept
-
inline auto query() const noexcept
-
inline auto fragment() const noexcept
-
auto fspath() const -> std::filesystem::path
-
inline bool valid() const noexcept
-
inline bool isLocalPath() const noexcept
-
inline bool isDataUri() const noexcept
-
URIView() noexcept = default
URI
-
class URI
Custom URI class for fastgltf’s needs.
glTF 2.0 only allows two types of URIs: (1) Data URIs as specified in RFC 2397. (2) Relative paths as specified in RFC 3986.
See https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#uris for details. However, the glTF spec allows more broader URIs in client implementations. Therefore, this supports all types of URIs as defined in RFC 3986.
Public Functions
-
URI() noexcept = default
-
explicit URI(std::string uri) noexcept
-
explicit URI(std::string_view uri) noexcept
- operator URIView () const noexcept FASTGLTF_LIFETIMEBOUND
- inline auto string () const noexcept FASTGLTF_LIFETIMEBOUND
- inline auto scheme () const noexcept FASTGLTF_LIFETIMEBOUND
- inline auto userinfo () const noexcept FASTGLTF_LIFETIMEBOUND
- inline auto host () const noexcept FASTGLTF_LIFETIMEBOUND
- inline auto port () const noexcept FASTGLTF_LIFETIMEBOUND
- inline auto path () const noexcept FASTGLTF_LIFETIMEBOUND
- inline auto query () const noexcept FASTGLTF_LIFETIMEBOUND
- inline auto fragment () const noexcept FASTGLTF_LIFETIMEBOUND
-
inline auto fspath() const
-
inline bool valid() const noexcept
-
inline bool isLocalPath() const noexcept
-
inline bool isDataUri() const noexcept
-
URI() noexcept = default
small_vector
-
template<typename T, std::size_t N = initial_small_vector_storage, typename Allocator = std::allocator<T>>
class small_vector A custom vector class for fastgltf, which can store up to N objects within itself.
This is useful for cases where the vector is expected to only ever hold a tiny amount of small objects, such as a node’s children. small_vector is also mostly conformant to C++17’s std::vector, and can therefore be used as a drop-in replacement.
Note
It is also available with polymorphic allocators in the fastgltf::pmr namespace.
Public Types
-
using size_type = std::size_t
-
using difference_type = std::ptrdiff_t
-
using reference = value_type&
-
using const_reference = const value_type&
-
using pointer = traits::pointer
-
using const_pointer = traits::const_pointer
-
using const_reverse_iterator = std::reverse_iterator<const_iterator>
Public Functions
-
small_vector() noexcept(std::is_nothrow_default_constructible_v<allocator_type>) = default
-
inline small_vector(const size_type size, const_reference value, const Allocator &allocator = Allocator())
-
inline small_vector(std::initializer_list<value_type> init, const Allocator &allocator = Allocator())
-
inline small_vector(const small_vector &other)
-
inline small_vector(const small_vector &other, const Allocator &allocator)
-
inline small_vector(small_vector &&other) noexcept(std::is_nothrow_move_constructible_v<value_type>)
-
inline small_vector(small_vector &&other, const Allocator &allocator)
-
inline small_vector &operator=(const small_vector &other)
-
inline small_vector &operator=(small_vector &&other) noexcept((traits::propagate_on_container_move_assignment::value || traits::is_always_equal::value) && std::is_nothrow_move_constructible_v<value_type>)
-
inline ~small_vector()
- inline iterator begin () noexcept FASTGLTF_LIFETIMEBOUND
- inline const_iterator begin () const noexcept FASTGLTF_LIFETIMEBOUND
- inline const_iterator cbegin () const noexcept FASTGLTF_LIFETIMEBOUND
- inline iterator end () noexcept FASTGLTF_LIFETIMEBOUND
- inline const_iterator end () const noexcept FASTGLTF_LIFETIMEBOUND
- inline const_iterator cend () const noexcept FASTGLTF_LIFETIMEBOUND
- inline reverse_iterator rbegin () noexcept FASTGLTF_LIFETIMEBOUND
- inline const_reverse_iterator rbegin () const noexcept FASTGLTF_LIFETIMEBOUND
- inline const_reverse_iterator crbegin () const noexcept FASTGLTF_LIFETIMEBOUND
- inline reverse_iterator rend () noexcept FASTGLTF_LIFETIMEBOUND
- inline const_reverse_iterator rend () const noexcept FASTGLTF_LIFETIMEBOUND
- inline const_reverse_iterator crend () const noexcept FASTGLTF_LIFETIMEBOUND
- inline pointer data () noexcept FASTGLTF_LIFETIMEBOUND
- inline const_pointer data () const noexcept FASTGLTF_LIFETIMEBOUND
-
inline bool empty() const noexcept
-
inline bool is_using_stack() const noexcept
-
inline allocator_type get_allocator() const noexcept(std::is_nothrow_copy_constructible_v<allocator_type>)
- inline void reserve (const size_type newCapacity) requires(std
-
inline void assign(const size_type count, const_reference value)
-
inline void assign(std::initializer_list<value_type> init)
requires std
-
inline void push_back(value_type &&value)
-
inline void pop_back()
- inline reference at (size_type idx) FASTGLTF_LIFETIMEBOUND
- inline const_reference at (size_type idx) const FASTGLTF_LIFETIMEBOUND
- inline reference operator[] (size_type idx) FASTGLTF_LIFETIMEBOUND
- inline const_reference operator[] (size_type idx) const FASTGLTF_LIFETIMEBOUND
- inline reference front () FASTGLTF_LIFETIMEBOUND
- inline const_reference front () const FASTGLTF_LIFETIMEBOUND
- inline reference back () FASTGLTF_LIFETIMEBOUND
- inline const_reference back () const FASTGLTF_LIFETIMEBOUND
-
using size_type = std::size_t
Optional
Warning
doxygentypedef: Cannot find typedef “fastgltf::Optional” in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml
OptionalFlagValue
Warning
doxygenstruct: Cannot find class “fastgltf::OptionalFlagValue” in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml
OptionalWithFlagValue
Warning
doxygenclass: Cannot find class “fastgltf::OptionalWithFlagValue” in doxygen xml output for project “fastgltf” from directory: /home/docs/checkouts/fastgltf/checkouts/latest/build/docs/doxygen/xml