Extensible 3D (X3D)
Part 1: Architecture and base components

Annex I

(normative)

OpenGL shading language (GLSL) binding

## I.1 General

This annex defines the mapping of concepts of the programmable shaders component to the OpenGL Shading Language (GLSL) (see [GLSL]). It applies to a ComposedShader node that sets the language field to "GLSL".

# I.2 Topics

Table I.1 provides links to the major topics in this annex.

Table I.1 — Topics

I.1 General I.2 Topics I.3 Interaction with Other Nodes and Components I.3.1 Vertex Shader I.3.2 Fragment Shader I.3.3 LoadSensor I.3.4 VertexAttributes I.4 Data Type Mapping I.4.1 Node fields I.4.2 X3D Field types to OpenGL Data Types I.5 Event Model I.5.1 Changing URL fields I.5.2 Changing the object field I.5.3 Changing the attrib field I.5.4 Relinking Programs Table I.1 — Topics Table I.2 — Mapping of X3D texture node types to GLSL sampler types Table I.3 — Mapping of X3D Field types to GLSL data types

# I.3 Interaction with other nodes and components

## I.3.1 Vertex shader

The vertex shader replaces the fixed functionality of the vertex processor. The GLSL specification (see [GLSL]) states that the following functionality is disabled if a vertex shader is supplied:

1. The model view matrix is not applied to vertex coordinates.
2. The projection matrix is not applied to vertex coordinates.
3. The texture matrices are not applied to texture coordinates.
4. The normals are not transformed to eye coordinates.
5. The normals are not rescaled or normalized.
6. Texture coordinates are not generated automatically.
7. Per-vertex lighting is not performed.
8. Color material lighting is not performed.
9. Point size distance attenuation is not performed.

## I.3.2 Fragment shader

The fragment shader replaces the fixed functionality of the fragment processor. The GLSL specification (see [GLSL]) states that the following functionality is disabled if a fragment shader is supplied:

1. Textures are not applied.
2. Fog is not applied.

## I.3.3 LoadSensor

The LoadSensor node (See 9.4.3 LoadSensor) has two output fields isActive and isLoaded. The isLoaded field behaviour is unchanged.

The isActive field is defined to issue a TRUE event when all the following conditions have been satisfied:

1. the content identified by the url field has been successfully loaded;
2. a valid OpenGL program object handle has been created for the shader object ( GLhandleARB in OpenGL 1.5 and uint in OpenGL 2.0);
3. the shader source has been set without error; and
4. the shader has been successfully compiled, without error.

The LoadSensor node does not have any interaction with the process of linking multiple shader objects into a complete shader program.

## I.3.4 Vertex attributes

Each vertex attribute node directly maps the name field to the uniform variable of the same name. If the name is not available as a uniform variable in the provided shader source, the values of the node shall be ignored.

The browser implementation shall automatically assign appropriate internal index values for each attribute.

# I.4 Data type mapping

## I.4.1 Node fields

Fields that are of type SFNode/MFNode are ignored unless the value is of type X3DTextureNode. Field instances of type X3DTextureNode are mapped according to the appropriate sampler data type. The texture types are mapped as defined in Table I.2.

Table I.2 — Mapping of X3D texture node types to GLSL sampler types

X3D texture type | GLSL variable type
--- | ---
X3DTexture2DNode | sampler2D.
X3DTexture3DNode | sampler3D.
X3DEnvironmentTextureNode | samplerCube.

X3D does not define mappings to the GLSL types sampler1D, sampler1DShadow and sampler2DShadow.

## I.4.2 X3D Field types to GLSL data types

Table I.3 indicates how the X3D field types shall be mapped to data types used in GLSL.

Table I.3 — Mapping of X3D field types to GLSL data types

X3D field type | GLSL variable type
--- | ---
SFBool | bool
MFBool | bool[]
SFInt32 | int
MFInt32 | int[]
SFFloat | float
MFFloat | float[]
SFDouble | float
MFDouble | float[]
SFTime | float
MFTime | float[]
SFNode | See 4.1 Node fields
MFNode | See 4.1 Node fields
SFVec2f | vec2
MFVec2f | vec2[]
SFVec3f | vec3
MFVec3f | vec3[]
SFVec4f | vec4
MFVec4f | vec4[]
SFVec3d | float3
MFVec3d | float3[]
SFVec4d | float4
MFVec4d | float4[]
SFRotation | vec4
MFRotation | vec4[]
MFColor | vec4[]
SFColor | vec4
SFColor | vec3
MFColor | vec3[]
SFColorRGBA | vec4
MFColorRGBA | vec4[]
SFImage | int[]
MFImage | int[]
SFString | Not supported
MFString | Not supported
SFMatrix3f | mat3
MFMatrix3f | mat3[]
SFMatrix4f | mat4
MFMatrix4f | mat4[]

OpenGL defines maximum supported lengths of each array data type, which may conflict with the minimum support requirements for X3D. OpenGL will automatically convert double-precision data types to single precision types.

# I.5 Event model

## I.5.1 Changing URL fields

When the url receives an event changing the value, the browser shall immediately attempt to download the new source. Upon successful download, the browser shall attempt to compile the new source and issue the appropriate LoadSensor events. It shall not automatically relink the shader program, nor disable the currently running shader. This follows the semantics of the OpenGL API requirements for separate register-compile-link steps.

Values defined at load time of the file do not require an explicit request to relink. It shall be assumed to automatically link once all the objects have successfully downloaded. If some of the shader source files are not downloaded or compiled (e.g., due to errors), no linking will occur for the shader program.

## I.5.2 Changing the object field

If at any time after the initial load, the user changes the values of the object field, the user shall need to request an explicit relink of the containing shader program. The containing ComposedShader shall not automatically relink, nor should it automatically disable the current shader.

## I.5.3 Changing the attrib field

Per-vertex attributes may be defined as one of the fields of X3DComposedGeometryNode. These may be changed at runtime by adding or removing node instances. Adding new node instances to the field shall require that the user request an explicit relink in order to make them visible to the shader.

## I.5.4 Relinking Programs

The user may, at any time, request that OpenGL re-link the composing shader objects by sending a TRUE value to the activate inputOnly field of the ComposedShader node. Users may need to force a relink of the ComposedShader under various circumstances, such as changing the url field of one or more ShaderPart nodes, or adding or removing ShaderPart nodes. Relinking the shader shall replace the existing shader with the new executable.