Copyright (C) 2013-2017 The Khronos Group Inc. All Rights Reserved. glTF is a trademark of The Khronos Group Inc. See Appendix for full Khronos Copyright Statement.

Status

Draft (not ratified yet)

Dependencies

Written against the glTF 2.0 spec.

Overview

This extension allows glTF to define instances of shading techniques with external shader programs along with their parameterized values. Shading techniques use JSON properties to describe data types and semantics for GLSL vertex and fragment shader programs.

This extension specification is targeting WebGL 1.0, and can be supported in any WebGL 1.0-based engine if the device supports the necessary WebGL extensions.

The conformance section specifies how the extension interacts with the attributes defined in the base specification, as well as how the extension interacts with other extensions.

glTF Schema Updates

KHR_techniques_webgl introduces an array of shading techniques used in the asset in techniques. A technique and any uniform values are specified in any glTF material by adding a KHR_techniques_webgl extension.

Extending Materials

A shading technique and any corresponding uniform values are specified by adding the KHR_techniques_webgl extension to any glTF material. For example, the following defines a material which selects the technique at index 0 from the techniques array and specifies a blue color for the u_light0Color uniform.

Technique

The KHR_techniques_webgl.technique property references the index of a technique listed in the asset's KHR_techniques_webgl.techniques property.

Values

The KHR_techniques_webgl.values dictionary property defines the uniform values of a technique.uniform of the same key, and when specified, overrides the corresponding uniform value. The value supplied must conform to the type and count properties, if present, of the corresponding Uniform object, and must be present if no value is supplied in the referenced Uniform object.

Extension

KHR_techniques_webgl is defined in the asset's top level extensions property with the following additional values.

Programs

GLSL shader programs are stored in the asset's KHR_techniques_webgl.programs property. This property contains one or more objects, one for each program.

Each shader program includes the properties fragmentShader and vertexShader, which reference the index of the shader in the KHR_techniques_webgl.shaders property for the fragment and vertex shader GLSL source code, respectively.

{
"programs": [
{
"fragmentShader": 0,
"vertexShader": 1
}
]
}

Shaders

One or more shader source files are listed in the asset's KHR_techniques_webgl.shaders property. Each shader specifies a type (vertex or fragment, defined as GL enum types) and either a uri to the file or a reference to a bufferView. Shader URIs may be URIs to external files or data URIs, allowing the shader content to be embedded as base64-encoded data in the asset.

Shader Requirements

Implementation Note: TODO: Reference shader implementation notes on doubleSided once included in the main spec, including how to account for normal and tangent-space calculations.

The value of a material's alphaCutoff property should be passed to the technique shaders using a uniform with the semantic ALPHACUTOFF. A uniform with this semantic will ignore a supplied default value and the corresponding material uniform value.

File Extension and MIME Type

External shader files may have any extension. The preferred MIME type is text/plain.

Techniques

One or more techniques are listed in the KHR_techniques_webgl.techniques property. A technique describes the shading used for an asset's material. Each technique must include the program property and define any attributes or uniforms to be passed as inputs to the program by their key in the attributes and uniforms dictionary properties.

The following example shows a technique and the properties it defines. This section describes each property in detail.

Program Instances

The program property of a technique creates an instance of a shader program. The value of the property is the index of a program defined in the asset's KHR_techniques_webgl.programs property. A shader program may be instanced multiple times within the glTF asset.

Attributes and uniforms passed to the program instance's shader code are defined in the attributes and uniforms properties of the technique, respectively.

Attributes

The attributes dictionary property specifies the vertex attributes of the data that will be passed to the shader. Each attribute's key is a string that corresponds to the attribute name in the GLSL source code. Each attribute's value is an attribute object, where the semantic of the attribute is defined. The semantic corresponds with the mesh attribute semantic specified in the primitive, the value of which is the index of the accessor containing attribute's data. It's invalid to specify a semantic that does not exist in the mesh data.

Uniforms

The uniforms dictionary property specifies the uniform variables that will be passed to the shader. Each uniform's key is a string that corresponds to the uniform name in the GLSL source code. Each uniform's value is a string that references a uniform object, where the type (GL types such as a floating point number, vector, etc.) and potentially the semantic and default value of the uniform is defined.

When a material instances a technique, the name of each supplied value in its KHR_techniques_webgl.values property must correspond to one of the uniforms defined in the technique.

Uniforms which specify the SAMPLER_2D type use a textureInfo object as a value to reference a texture, (see conformance for objects with extended with KHR_texture_transform).

The above example illustrates several uniforms. The property u_ambient is defined as a FLOAT_VEC4 type; and u_light0Color is defined as a FLOAT_VEC3 with a default color value of white.

Semantics

Technique uniforms may also optionally define a semantic, an enumerated value describing how the runtime is to interpret the data to be passed to the shader.

In the above example, the uniform u_light0Transform defines the MODEL semantic, which corresponds to the world space position of the node referenced in the property node, in this case the node 1.

If no node property is supplied for a uniform, the semantic is implied in a context-specific manner: either to the node which is being rendered, or in the case of camera-specific semantics, to the current camera. In the following fragment, which defines a uniform named u_projectionMatrix that is derived from the implementation's projection matrix, the semantic would be applied to the camera.

This extension defines the ALPHACUTOFF uniform semantic, which corresponds to the value of a material's alphaCutoff property, which must be respected by the supplied technique, (see Shader Requirements). A uniform with this semantic will ignore a supplied default value and the corresponding material uniform value.

Table 1. Uniform Semantics

Semantic

Type

Description

LOCAL

FLOAT_MAT4

Transforms from the node's coordinate system to its parent's. This is the node's matrix property (or derived matrix from translation, rotation, and scale properties).

MODEL

FLOAT_MAT4

Transforms from model to world coordinates using the transform's node and all of its ancestors.

VIEW

FLOAT_MAT4

Transforms from world to view coordinates using the active camera node.

PROJECTION

FLOAT_MAT4

Transforms from view to clip coordinates using the active camera node.

MODELVIEW

FLOAT_MAT4

Combined MODEL and VIEW.

MODELVIEWPROJECTION

FLOAT_MAT4

Combined MODEL, VIEW, and PROJECTION.

MODELINVERSE

FLOAT_MAT4

Inverse of MODEL.

VIEWINVERSE

FLOAT_MAT4

Inverse of VIEW.

PROJECTIONINVERSE

FLOAT_MAT4

Inverse of PROJECTION.

MODELVIEWINVERSE

FLOAT_MAT4

Inverse of MODELVIEW.

MODELVIEWPROJECTIONINVERSE

FLOAT_MAT4

Inverse of MODELVIEWPROJECTION.

MODELINVERSETRANSPOSE

FLOAT_MAT3

The inverse-transpose of MODEL without the translation. This transforms normals in model coordinates to world coordinates.

MODELVIEWINVERSETRANSPOSE

FLOAT_MAT3

The inverse-transpose of MODELVIEW without the translation. This transforms normals in model coordinates to eye coordinates.

VIEWPORT

FLOAT_VEC4

The viewport's x, y, width, and height properties stored in the x, y, z, and w components, respectively. For example, this is used to scale window coordinates to [0, 1]: vec2 v = gl_FragCoord.xy / viewport.zw;

JOINTMATRIX

FLOAT_MAT4[]

Array parameter; its length (uniform.count) must be greater than or equal to the length of jointNames array of a skin being used. Each element transforms mesh coordinates for a particular joint for skinning and animation.

For forward-compatibility, application-specific semantics must start with an underscore, e.g., _SIMULATION_TIME.

Conformance

Implementations should continue to respect material doubleSided, alphaMode, and alphaCutoff properties by modifying the render state. The default state of the WebGL context should not be assumed.

textureInfo objects referenced by the KHR_techniques_webgl extension may not use the KHR_texture_transform extension. The offset, rotation, and scale transforms applied to the texture by using KHR_texture_transform can be applied with this extension by providing uniforms for these values and performing the necessary transformations in the supplied GLSL shader code.

uniform.count

When defined, the uniform is an array of count elements of the specified type. Otherwise, the uniform is not an array. When defined, value's length must equal count, times the number of components in the type, e.g., 3 for FLOAT_VEC3. A uniform array of scalar values is not the same as a uniform vector of the same size; for example, when count is 2 and type is 5126 (FLOAT), the uniform is an array of two floating-point values, not a FLOAT_VEC2. When a glTF-defined semantic is used, the semantic must be JOINTMATRIX; application-specific uniforms can be arrays and, therefore, define count.

Type: integer

Required: No

Minimum: >= 1

uniform.node

The index of the node whose transform is used as the uniform's value. When this is defined, type must be 35676 (FLOAT_MAT4), therefore, when the semantic is "MODELINVERSETRANSPOSE", "MODELVIEWINVERSETRANSPOSE", or "VIEWPORT", the node property can't be defined.

technique ✅

The index of the technique.

Type: integer

Required: Yes

Minimum: >= 0

values

Dictionary object of uniform values. Uniforms with the same name as the technique's uniform must conform to the referenced type and count (if present) properties, and override the technique's uniform value. A uniform value must be supplied here if not present in the technique uniforms.

Type: object

Required: No, default: {}

extensions

Dictionary object with extension-specific objects.

Type: object

Required: No

Type of each property: Extension

extras

Application-specific data.

Type: any

Required: No

References

Appendix: Full Khronos Copyright Statement

Copyright 2013-2017 The Khronos Group Inc.

Some parts of this Specification are purely informative and do not define requirements necessary for compliance and so are outside the Scope of this Specification. These parts of the Specification are marked as being non-normative, or identified as Implementation Notes.

Where this Specification includes normative references to external documents, only the specifically identified sections and functionality of those external documents are in Scope. Requirements defined by external documents not created by Khronos may contain contributions from non-members of Khronos not covered by the Khronos Intellectual Property Rights Policy.

This specification 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.

This specification has been created under the Khronos Intellectual Property Rights Policy, which is Attachment A of the Khronos Group Membership Agreement available at www.khronos.org/files/member_agreement.pdf. Khronos grants a conditional copyright license to use and reproduce the unmodified specification for any purpose, without fee or royalty, EXCEPT no licenses to any patent, trademark or other intellectual property rights are granted under these terms. Parties desiring to implement the specification and make use of Khronos trademarks in relation to that implementation, and receive reciprocal patent license protection under the Khronos IP Policy must become Adopters and confirm the implementation as conformant under the process defined by Khronos for this specification; see https://www.khronos.org/adopters.

Khronos makes no, and expressly disclaims any, representations or warranties, express or implied, regarding this specification, 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.

Vulkan is a registered trademark and Khronos, OpenXR, SPIR, SPIR-V, SYCL, WebGL, WebCL, OpenVX, OpenVG, EGL, COLLADA, glTF, NNEF, OpenKODE, OpenKCAM, StreamInput, OpenWF, OpenSL ES, OpenMAX, OpenMAX AL, OpenMAX IL, OpenMAX DL, OpenML and DevU are trademarks of The Khronos Group Inc. ASTC is a trademark of ARM Holdings PLC, OpenCL is a trademark of Apple Inc. and OpenGL and OpenML are registered trademarks and the OpenGL ES and OpenGL SC logos are trademarks of Silicon Graphics International used under license by Khronos. All other product names, trademarks, and/or company names are used solely for identification and belong to their respective owners.