glTF Mesh Entity Base Definition Explained

In the glTF (GL Transmission Format) 2.0 specification, a mesh defines the geometric shape of a 3D object through an array of renderable components known as primitives. This article explains the base structural definition of a glTF mesh entity, breaking down its top-level schema, the role of mesh primitives, mandatory vertex attributes, and how geometric data connects to the broader scene hierarchy.

The Top-Level Mesh Object

In glTF, meshes are stored in the root meshes array. A single mesh entity is defined as a JSON object containing the following primary properties:

  • primitives (Required): An array of one or more mesh.primitive objects. Each primitive represents a discrete set of geometry that can be rendered in a single draw call.
  • weights (Optional): An array of floating-point numbers that specify the default weights for morph targets defined across the primitives.
  • name (Optional): A user-defined string identifier for the mesh.
  • extensions and extras (Optional): Application-specific or standard extensions and user metadata.

The Mesh Primitive

The core geometric and rendering information of a mesh resides inside its primitives array. A primitive is not a standalone node; rather, it encapsulates how vertex data and surface properties are assembled on the GPU.

A base primitive object contains:

  • attributes (Required): A dictionary mapping semantic attribute names (such as POSITION, NORMAL, and TEXCOORD_0) to the indices of accessor objects. Accessors decode raw binary arrays stored in bufferViews and buffers.
  • indices (Optional): An accessor index referencing an array of vertex indices. When present, the primitive uses indexed rendering (such as glDrawElements). When omitted, non-indexed rendering (such as glDrawArrays) is used.
  • material (Optional): An index pointing to a material entity in the root materials array. If omitted, the runtime applies a default fallback material.
  • mode (Optional): An integer specifying the rendering topology (WebGL primitive type). The values range from 0 to 6 (POINTS, LINES, LINE_LOOP, LINE_STRIP, TRIANGLES, TRIANGLE_STRIP, TRIANGLE_FAN). If not defined, mode defaults to 4 (TRIANGLES).
  • targets (Optional): An array of morph target attribute dictionaries used for shape-key animations.

Required Geometric Attributes

To constitute a valid primitive under the glTF specification, the attributes dictionary must include at least the POSITION attribute:

  • POSITION: Must reference an accessor with type VEC3 and component type FLOAT (5126). This attribute also requires min and max bounding properties within the referenced accessor to define the local bounding box of the geometry.

Other common attributes, such as NORMAL (VEC3), TANGENT (VEC4), TEXCOORD_n (VEC2), and COLOR_n (VEC3 or VEC4), are optional and depend on the rendering needs and material configurations of the model.

Mesh Instantiation in the Scene Graph

A mesh definition in glTF is purely an asset description and does not render by itself. To appear in the 3D scene, a mesh must be instantiated by a node in the scene graph. A node object references a mesh using the mesh property, pointing to the zero-based index of the mesh in the root meshes array. A single mesh entity can be referenced by multiple nodes to facilitate efficient hardware instancing with different local transforms.