- 1. Foreword
- 2. Introduction
- 3. Object Model Basics
- 4. Core Pointers
- 5. Extension Pointers
- 5.1. KHR_texture_transform
- 5.2. KHR_lights_punctual
- 5.3. KHR_materials_anisotropy
- 5.4. KHR_materials_clearcoat
- 5.5. KHR_materials_dispersion
- 5.6. KHR_materials_emissive_strength
- 5.7. KHR_materials_ior
- 5.8. KHR_materials_iridescence
- 5.9. KHR_materials_sheen
- 5.10. KHR_materials_specular
- 5.11. KHR_materials_transmission
- 5.12. KHR_materials_volume
- 5.13. EXT_lights_ies
- 5.14. EXT_lights_image_based
- 5.15. ADOBE_materials_clearcoat_specular
- 5.16. ADOBE_materials_clearcoat_tint
|
Note
|
Note
Khronos posts the AsciiDoc source of the glTF specification to enable community feedback and remixing under CC-BY 4.0. Published versions of the Specification are located in the glTF Registry. |
Copyright 2023 The Khronos Group Inc.
This Document is protected by copyright laws and contains material proprietary to Khronos. Except as described by these terms, it or any components may not be reproduced, republished, distributed, transmitted, displayed, broadcast or otherwise exploited in any manner without the express prior written permission of Khronos.
Khronos grants a conditional copyright license to use and reproduce the unmodified Document for any purpose, without fee or royalty, EXCEPT no licenses to any patent, trademark or other intellectual property rights are granted under these terms.
Khronos makes no, and expressly disclaims any, representations or warranties, express or implied, regarding this Document, including, without limitation: merchantability, fitness for a particular purpose, non-infringement of any intellectual property, correctness, accuracy, completeness, timeliness, and reliability. Under no circumstances will Khronos, or any of its Promoters, Contributors or Members, or their respective partners, officers, directors, employees, agents or representatives be liable for any damages, whether direct, indirect, special or consequential damages for lost revenues, lost profits, or otherwise, arising from or in connection with these materials.
Khronos® is a registered trademark and glTF™ is a trademark of The Khronos Group Inc. All other product names, trademarks, and/or company names are used solely for identification and belong to their respective owners.
This document, referred to as the “glTF 2.0 Asset Object Model Specification” or just the “Object Model” hereafter, describes a portable runtime object model of a glTF asset.
The following documents are referenced by normative sections of the specification:
-
glTF 2.0 Specification https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html
-
Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., JavaScript Object Notation (JSON) Pointer, RFC 6901, DOI 10.17487/RFC6901, April 2013, https://www.rfc-editor.org/info/rfc6901
-
ISO/IEC 60559 Floating-point arithmetic https://www.iso.org/standard/80985.html
Although glTF 2.0 Specification does not define any runtime behavior, there is a growing demand for manipulating glTF assets at runtime and querying their state in a portable way.
Upon loading, applications usually parse glTF JSON into implementation-specific internal structures and therefore do not have a common protocol to manipulate asset contents.
This document defines a set of JSON pointers that glTF implementations are expected to support for identifying asset properties that could be manipulated at runtime.
-
The Object Model is defined only for valid glTF assets. Querying or setting properties of invalid glTF assets are undefined.
-
Upon loading an asset, an implementation registers specific glTF object properties for the Object Model by resolving JSON pointers identified by templates provided by this document to JSON properties of the asset being loaded. Undefined glTF properties that have default values are considered defined with their default values.
-
Each instance of empty curly braces (
{}) in the pointer templates is replaced with the corresponding array element index for each glTF asset property matching the template. -
Since JSON does not natively support vectors and matrices, the Object Model defines explicit types for all supported properties. JSON pointers to properties of these types are resolved into implementation-specific vectors and matrices, not raw JSON arrays. Pointers to individual vector or matrix components are not resolved.
-
Pointers to properties of explicit array types (as defined below) are resolved to implementation-defined arrays; pointers to array elements of properties of explicit array types are resolved to the corresponding array elements.
-
In addition to properties directly linked to glTF JSON, the Object Model defines extra read-only properties that reflect commonly-used parts of the glTF runtime state. Specifically, array sizes and current node transforms.
-
If a JSON pointer cannot be resolved to a glTF property, operations with it are undefined.
-
Some pointers are defined as read-only, i.e., applications can access them to discover the asset structure and its runtime state but it is generally not possible to update their values directly. Read-only pointers that represent glTF object references can be made mutable by extensions on a case-by-case basis.
The following data types are assumed by this document:
- float
-
single or double precision IEEE-754 floating-point type
- float[]
-
an array of float values
- float2
-
a two-component vector of float values read from or set to JSON array elements with indices 0 and 1
- float3
-
a three-component vector of float values read from or set to JSON array elements with indices 0, 1, and 2
- float4
-
a four-component vector of float values read from or set to JSON array elements with indices 0, 1, 2, and 3
- float4x4
-
a 4x4 matrix of float values
- bool
-
a boolean type
- int
-
a signed integer type with width of at least 32 bits
The following pointer templates represent mutable properties defined in the core glTF 2.0 Specification.
| Pointer | Type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The /nodes/{}/translation, /nodes/{}/rotation, and /nodes/{}/scale pointers represent the current TRS properties of the node. If the static matrix property is defined on the node object in JSON, the corresponding rotation and scale pointers are undefined.
|
Note
|
Rationale
Since the glTF 2.0 specification allows negative scale factors, TRS matrix decomposition is ambiguous with regard to rotation and scale. Two implementations that choose different scale factor signs for the same matrix may produce two different rotation quaternions for it. Therefore, updating only the rotation or the scale may result in different node transformation matrices in different implementations. This restriction does not apply to the translation because the translation vector directly corresponds to the first three values of the last column of the transformation matrix regardless of the decomposition process. |
The /nodes/{}/weights and /nodes/{}/weights/{} pointers represent the current morph target weights (as an array and as individual scalars respectively) of the mesh instantiated by the node regardless of whether the static weights property is defined on the node object in JSON. If the node instantiates no mesh or if the mesh has no morph targets, these pointers are undefined.
|
Note
|
Note
As in the core glTF 2.0 Specification, lengths of the If a mesh defines default morph target weights (via its own If a mesh does not define default morph target weights, the |
Additionally, the following pointer templates represent read-only runtime properties.
| Pointer | Type | Comment |
|---|---|---|
|
|
Number of animations |
|
|
Number of cameras |
|
|
Number of materials |
|
|
Whether the material is double sided |
|
|
Number of meshes |
|
|
Number of primitives |
|
|
Index of the material |
|
|
Number of nodes |
|
|
Index of the camera |
|
|
Number of children nodes |
|
|
Index of the child node |
|
|
Global transformation matrix of a node |
|
|
Local transformation matrix of a node |
|
|
Index of the mesh |
|
|
Index of the parent node |
|
|
Index of the skin |
|
|
Number of the instantiated mesh’s morph targets |
|
|
Index of the scene |
|
|
Number of scenes |
|
|
Number of root nodes |
|
|
Index of the root node |
|
|
Number of skins |
|
|
Number of joints |
|
|
Index of the joint node |
|
|
Index of the skeleton |
All pointers named *.length return zero if the corresponding array is not defined.
The /nodes/{}/matrix and /nodes/{}/globalMatrix pointers represent the node’s effective transformation matrices, i.e., the runtime state, regardless of whether the static matrix property is used in JSON.
The /nodes/{}/parent pointer represents the node’s parent, i.e., the index of the node that has the current node listed in its children array. If the current node is a root node, this pointer is undefined.
The following pointer templates represent mutable properties defined in glTF 2.0 extensions.
| Pointer | Type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
By definition, this extension applies to all properties of textureInfo type, including texture properties defined in other glTF 2.0 extensions.
| Pointer | Type |
|---|---|
|
|
|
|
|
|
|
|
|
|
Additional read-only properties
| Pointer | Type | Comment |
|---|---|---|
|
|
Number of punctual lights |
|
|
Index of the light |
| Pointer | Type |
|---|---|
|
|
|
|
| Pointer | Type |
|---|---|
|
|
|
|
|
|
| Pointer | Type |
|---|---|
|
|
|
|
|
|
| Pointer | Type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Pointer | Type |
|---|---|
|
|
| Pointer | Type |
|---|---|
|
|
| Pointer | Type |
|---|---|
|
|
|
|
|
|
|
|
| Pointer | Type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
| Pointer | Type |
|---|---|
|
|
|
|
| Pointer | Type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
| Pointer | Type |
|---|---|
|
|
|
|
| Pointer | Type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
| Pointer | Type |
|---|---|
|
|
| Pointer | Type |
|---|---|
|
|
|
|
|
|
| Pointer | Type |
|---|---|
|
|
|
|
|
|
| Pointer | Type |
|---|---|
|
|
|
|
|
|
| Pointer | Type |
|---|---|
|
|
|
|
Additional read-only properties
| Pointer | Type | Comment |
|---|---|---|
|
|
Number of IES light profiles |
| Pointer | Type |
|---|---|
|
|
|
|
Additional read-only properties
| Pointer | Type | Comment |
|---|---|---|
|
|
Number of image-based lights |
| Pointer | Type |
|---|---|
|
|
|
|
| Pointer | Type |
|---|---|
|
|
|
|
|
|
| Pointer | Type |
|---|---|
|
|
| Pointer | Type |
|---|---|
|
|
|
|
|
|