glTF Attribute Naming for Primary and Secondary UVs

In the glTF (GL Transmission Format) 2.0 specification, vertex texture coordinates rely on a strict naming convention to organize multiple UV sets. This article explains how glTF identifies and separates primary and secondary UV channels using the TEXCOORD_<n> attribute standard, how material properties reference these coordinates, and the rules governing multi-UV implementations.

The TEXCOORD_<n> Standard

glTF distinguishes texture coordinate layers through indexed vertex attribute names using the format TEXCOORD_<n>, where <n> is a zero-based integer index:

  • Primary UVs: Designated by the attribute name TEXCOORD_0.
  • Secondary UVs: Designated by the attribute name TEXCOORD_1.
  • Additional UVs: Any subsequent sets increment sequentially, such as TEXCOORD_2, TEXCOORD_3, and so forth.

Each TEXCOORD_<n> attribute points to an accessor that supplies 2D vector data (VEC2), typically represented as floating-point numbers or normalized integers.

Material Integration and the texCoord Property

While vertex attributes define the coordinate sets, glTF materials dictate which UV set a texture sampler actually uses. Inside a glTF material definition, any texture reference object (such as baseColorTexture, normalTexture, or occlusionTexture) can include an optional texCoord integer property.

  • Default Behavior: If the texCoord property is omitted, the renderer defaults to 0, reading coordinates from TEXCOORD_0.
  • Secondary Targeting: Setting "texCoord": 1 instructs the engine to sample that specific texture using the coordinates defined in TEXCOORD_1.

Common Use Cases for Multi-UV Workflows

Separating primary and secondary UVs allows 3D artists and pipelines to optimize texture resolution and memory:

  • TEXCOORD_0 (Primary): Typically dedicated to unique asset texturing, including base color (albedo), roughness, metallic, and normal maps, where mirroring and overlapping UV shells are common.
  • TEXCOORD_1 (Secondary): Frequently used for ambient occlusion, lightmaps, or directional baked lighting. Because lightmaps require unique, non-overlapping coordinates across the entire surface to avoid lighting artifacts, a dedicated secondary channel is essential.
  • Detail Maps: Secondary channels are also employed for tiled detail textures, applying fine-scale surface variation independently of the primary material layout.

Implementation Rules and Constraints

To maintain valid glTF asset structure, implementations must adhere to the following rules:

  1. Sequential Indexing: UV sets must be indexed contiguously starting from zero. An asset cannot define TEXCOORD_1 without also defining TEXCOORD_0.
  2. Missing Reference Handling: A material must not point a texCoord index to an attribute that does not exist in the corresponding mesh primitive.
  3. Data Types: All texture coordinate accessors must use VEC2 components with component types of FLOAT, UNSIGNED_BYTE (normalized), or UNSIGNED_SHORT (normalized).