gltf20 Reference Guide
gltf20 Reference Guide
gltf20 Reference Guide
node
glTF was designed and specified by the Khronos
Group, for the efficient transfer of 3D content
over networks. camera mesh skin
The core of glTF is a JSON file that describes the
structure and composition of a scene containing
3D models. The top-level elements of this file are: material accessor animation
scenes, nodes
Basic structure of the scene texture bufferView
cameras
View configurations for the scene sampler image buffer
meshes
Geometry of 3D objects Binary data references
The images and buffers of a glTF asset may refer to
buffers, bufferViews, accessors external files that contain the data that are required
Data references and data layout descriptions for rendering the 3D content:
materials "buffers": [ The buffers refer to binary
Definitions of how objects should be rendered { files (.BIN) that contain
"uri": "buffer01.bin"
geometry- or animation
textures, images, samplers "byteLength": 102040,
} data.
Surface appearance of objects
],
"images": [
The images refer to image
skins { files (PNG, JPG...) that
Information for vertex skinning "uri": "image01.png" contain texture data for
}
], the models.
animations
Changes of properties over time
The data is referred to via URIs, but can also be
These elements are contained in arrays. References included directly in the JSON using data URIs. The
between the objects are established by using their data URI defines the MIME type, and contains the
indices to look up the objects in the arrays. data as a base64 encoded string:
It is also possible to store the whole asset in a single Buffer data:
binary glTF file. In this case, the JSON data is stored "data:application/gltf-buffer;base64,AAABAAIAAgA..."
as a string, followed by the binary data of buffers
or images. Image data (PNG):
"data:image/png;base64,iVBORw0K..."
animation then describes how one property } array of weights that define
changes over time. The attached objects will move ]
the contribution of each morph
}
accordingly, allowing to model moving objects or target to the final, rendered
],
camera flights. "weights": [0, 0.5] state of the mesh.
}
Nodes are also used in vertex skinning: A node
hierarchy can define the skeleton of an animated Combining multiple morph targets with different
character. The node then refers to a mesh and to weights allows, for example, modeling different
a skin. The skin contains further information about facial expressions of a character: The weights can
how the mesh is deformed based on the current be modified with an animation, to interpolate
skeleton pose. between different states of the geometry.
Rev. 0922 www.khronos.org/gltf
glTF 2.0 API Reference Guide Page 3
buffers, bufferViews, accessors
The buffers contain the data that is used for the
Sparse accessors
geometry of 3D models, animations, and skinning. When only few elements of an accessor differ from
The bufferViews add structural information to this a default value (which is often the case for morph
data. The accessors define the exact type and targets), then the data can be given in a very
layout of the data. compact form using a sparse data description:
"buffers": [ Each of the buffers refers
"accessors": [ The accessor defines the
{ to a binary data file, using
"byteLength": 35, { type of the data (here,
a URI. It is the source of "type": "SCALAR",
"uri": "buffer01.bin" scalar float values), and
} one block of raw data with "componentType": 5126,
the total element count.
], the given byteLength. "count": 10,
The sparse data block
Each of the bufferViews "sparse": {
contains the count of
"bufferViews": [ "count": 4,
{ refers to one buffer. It sparse data elements.
"buffer": 0, has a byteOffset and a "values": {
"byteOffset": 4, byteLength, defining the "bufferView": 2, The values refer to the
"byteLength": 28,
part of the buffer that }, bufferView that contains
"byteStride": 12,
belongs to the bufferView, the sparse data values.
"target": 34963 "indices": {
} and an optional OpenGL "bufferView": 1, The target indices for
], buffer target. "componentType": 5123 the sparse data values
The accessors define how }
are defined with a
"accessors": [ }
{ the data of a bufferView is } reference to a
"bufferView": 0, bufferView and the
interpreted. They may ]
"byteOffset": 4,
"type": "VEC2", define an additional componentType.
"componentType": 5126, byteOffset referring to the
"count": 2, start of the bufferView, The values are written into the final accessor data,
"min" : [0.1, 0.2]
and contain information at the positions that are given by the indices:
"max" : [0.9, 0.8]
} about the type and layout sparse (count=4)
] of the bufferView data: 4.3 9.1 5.2 2.7 values
The data may, for example, be defined as 2D vectors indices
1 4 5 7
of floating point values when the type is "VEC2"
and the componentType is GL_FLOAT (5126). The
range of all values is stored in the min and max
property.
The data of multiple accessors may be interleaved
inside a bufferView. In this case, the bufferView will 0 1 2 3 4 5 6 7 8 9
have a byteStride property that says how many 0.0 4.3 0.0 0.0 9.1 5.2 0.0 2.7 0.0 0.0
bytes are between the start of one element of an Final accessor data with 10 float values
accessor, and the start of the next.
Roughness
to make sure that the appearance of the rendered object is 0.5
consistent among all renderers.
The default material model is the Metallic-Roughness-Model. 0.25
Values between 0.0 and 1.0 are used to describe how much the
material characteristics resemble that of a metal, and how rough 0.0
the surface of the object is. These properties may either be
given as individual values that apply to the whole object, or be 0.0 0.25 0.5 0.75 1.0
read from textures. Metal
Computing the joint matrices
The skin refers to the inverseBindMatrices. This For each node whose index appears in the joints of
is an accessor which contains one inverse bind the skin, a global transform matrix can be computed.
matrix for each joint. Each of these matrices It transforms the mesh from the local space of the
transforms the mesh into the local space of the joint, based on the current global transform of the
joint. joint, and is called globalJointTransform.
inverseBindMatrix[1]
From these matrices, a jointMatrix
may be
joint2
computed for each joint:
joint2
jointMatrix[j] =
inverse(globalTransform) * joint1
globalJointTransform[j] *
joint1
inverseBindMatrix[j];
Any global transform of the node that contains
the mesh and the skin is cancelled out by joint0
joint0 pre-multiplying the joint matrix with the inverse
of this transform.
For implementations based on OpenGL or WebGL,
the jointMatrix array will be passed to the
vertex shader as a uniform.
globalJointTransform[1]
...
...
...
...
vertex n: px py pz pw j0 j1 j2 j3 w0 w1 w2 w3 mat4 skinMatrix =
a_weight.x * u_jointMatrix[int(a_joint.x)] +
The data of these accessors is passed as attributes to a_weight.y * u_jointMatrix[int(a_joint.y)] +
a_weight.z * u_jointMatrix[int(a_joint.z)] +
the vertex shader, together with the jointMatrix array. a_weight.w * u_jointMatrix[int(a_joint.w)];
the vertex shader, the skinMatrix is computed. It is
In gl_Position =
linear combination of the joint matrices whose indices
a modelViewProjection * skinMatrix * position;
}
are contained in the JOINTS_0 attribute, weighted with
the WEIGHTS_0 values:
a_weight.x a_weight.y
a_joint.x a_joint.y
skinMatrix =
1.0 * jointMatrix[1] +
0.0 * jointMatrix[0]+...
The skinMatrix
transforms the skinMatrix = 0.75 * jointMatrix[1] + 0.25 * jointMatrix[0] +...
joint2
vertices based on
the skeleton pose, skinMatrix = 0.5 * jointMatrix[1] + 0.5 * jointMatrix[0] +...
before they are
transformed with joint1
skinMatrix = 0.25 * jointMatrix[1] + 0.75 * jointMatrix[0] +...
the model-view-
perspective matrix. joint0
0 1 2 3 4 5 6
Global time:
Current time: 1.2
The data of the input accessor
0.0 0.8 1.6 2.4 3.2 The sampler looks up the key frames for
of the animation sampler,
the current time, in the input data.
containing the key frame times
The data of the output accessor 10.0 14.0 18.0 24.0 31.0 The corresponding values of the output
of the animation sampler, data are read, and interpolated based on
containing the key frame values 5.0 3.0 1.0 -1.0 -3.0
for the animated property the interpolation mode of the sampler.
-5.0 -2.0 1.0 4.0 7.0 16.0
The interpolated value is forwarded
2.0
to the animation channel target.
-0.5
Animation channel targets Animating the weights for the morph targets that
The interpolated value that is provided by an are defined for the primitives of a mesh that is
animation sampler may be applied to different attached to a node:
animation channel targets. Original mesh
primitive attribute
Animating the translation of a node: Displacement for "POSITION" Displacement for
translation=[2, 0, 0] translation=[3, 2, 0] "POSITION" from "POSITION" from
morph target 0: morph target 1:
weights= weights=
[0.5,0.0] [0.0,0.5]
The magic entry has the value 0x46546C67, The chunkLength is the length of the chunkData, in bytes
which is the ASCII string "glTF".This is used
to identify the data as a binary glTF The chunkType value defines what type of data is contained in the chunkData.
It may be 0x4E4F534A, which is the ASCII string "JSON", for JSON data, or
The version defines the file format version. 0x004E4942, which is the ASCII string "BIN", for binary data.
The version described here is version 2
The chunkData contains the actual data of the chunk. This may be
The length is the total length of the file, in bytes the ASCII representation of the JSON data, or binary buffer data.
Extensions
"textures" : [ Extensions allow adding
The glTF format allows extensions to add new {
functionality, or to simplify the definition of ...
arbitrary objects in the
commonly used properties. "extensions" : { extensions property of
"KHR_lights_common" : { other objects.
When an extension is used "extensionsUsed" : [ "lightSource" : true, The name of such an
in a glTF asset, it has to be "KHR_lights_common", },
"CUSTOM_EXTENSION" "CUSTOM_EXTENSION" : {
object is the same as the
listed in the top-level
] "customProperty" : name of the extension,
extensionsUsed property. "customValue" and it may contain
The extensionsRequired "extensionsRequired" : [ } further, extension-specific
property lists the extensions "KHR_lights_common" }
] }
properties.
that are strictly required to
]
properly load the asset.
Existing extensions
Several extensions are developed and maintained on the Khronos GitHub repository. The full list of
extensions can be found at https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0.
The following extensions are official extensions that are ratified by the Khronos Group:
• KHR_draco_mesh_compression: glTF geometry can be compressed with the Draco library.
• KHR_lights_punctual: Adds support for point lights, spot lights, and directional lights.
• KHR_materials_clearcoat: Allows adding a clear coating layer to existing glTF PBR materials.
• KHR_materials_ior: Transparent materials can be extended with an index of refraction.
• KHR_materials_iridescence: Models thin-film effects where the hue depends on the viewing angle.
• KHR_materials_sheen: Adds a color parameter for the backscattering caused by cloth fibers.
• KHR_materials_specular: Allows defining the strength and color of specular reflections.
• KHR_materials_transmission: More realistic modeling of reflection, refraction, and opacity.
• KHR_materials_unlit: Allows defining materials that are not part of physically based rendering.
• KHR_materials_variants: Multiple materials on the same geometry, to be selected at runtime.
• KHR_materials_volume: Detailed modeling of the thickness and attenuation of volumetric objects.
• KHR_mesh_quantization: More compact representation of vertex attributes with smaller data types.
• KHR_mesh_basisu: Adds support for KTX v2 images with Basis Universal supercompression.
• KHR_texture_transform: Support offset, rotation, and scaling for textures, to create texture atlases.
• KHR_xmp_json_ld: Adds support for XMP metadata on scenes, nodes, meshes, and other glTF objects.