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

Annex K

(normative)

nVidia Cg shading language binding

# K.1 General

This annex defines the mapping of concepts of the Programmable shaders component to the nVidia Cg shading language (see [Cg]). It applies to the ProgramShader, ShaderProgram and PackagedShader nodes with the language field set to "Cg".

# K.2 Topics

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

Table K.1 — Topics

K.1 General K.2 Topics K.3 Concepts K.3.1 Rendering API support differences K.3.2 Language strings K.4 Interaction with other nodes and components K.4.1 Vertex shader K.4.1.1 OpenGL profiles K.4.1.2 Direct3D profiles K.4.2 Fragment shader K.4.2.1 OpenGL profiles K.4.2.2 Direct3D profiles K.4.3 LoadSensor K.4.4 Vertex attributes K.4.4.1 OpenGL profiles K.4.4.2 Direct3D profiles K.5 Data type and parameter mappings K.5.1 Node fields K.5.2 X3D field types to Cg data types K.5.3 X3D world state to Cg parameter names K.6 Event model K.6.1 Changing URL fields K.6.2 Changing the attrib field K.6.3 Activating programs Table K.1 — Topics Table K.2 — Language string to Cg profile mapping Table K.3 — Supported Direct3D vertex declaration usage types Table K.4 — Mapping of X3D texture node types to Cg sampler types Table K.5 — Mapping of X3D material and light node types to Cg structure declarations Table K.6 — Mapping of X3D field types to Cg data types Table K.7 — Mapping of X3D world state to Cg parameter names

# K.3 Concepts

## K.3.1 Rendering API support differences

The Cg language is a diverse set of shading capabilities that aim to support programmable shaders for a variety of APIs. This document supports the OpenGL and Microsoft Direct3D APIs. Programming APIs may express the same concepts in very distinctly different ways and the two cited APIs do so. Thus, a Cg shader program written to work on OpenGL will not work on Direct3D. Conversely, a Cg shader program written to work on Direct3D will not work on OpenGL.

Cg handles the incompatible code problem by defining Cg profiles. A Cg profile is a set of available shading language functionality. At the time the browser downloads the file, it can use the profile information to guide how to compile the code to the appropriate target. This annex defines its behaviour based on the Cg profile specified by the user.

## K.3.2 Language strings

Cg profile information is encoded as part of the language string of the ProgramShader node. All strings starting with "CG-" define behaviour defined in this annex. The part after the prefix defines the programming API and profile for which the Cg code shall be compiled. A X3D browser thus may quickly distinguish which nodes to ignore and which to investigate further. The source files are referenced in the ShaderProgram nodes. This document requires that the same profile is used for both the vertex and fragment programs.

Table K.2 defines the mappings between the language string and the appropriate Cg profile. As Cg evolves, newer profiles may be defined and shall follow a similar naming convention.

Table K.2 — Language string to Cg profile mapping

Language string | Cg vertex shader profile | Cg fragment shader profile
--- | --- | ---
CG_OPENGL_ARB | CG_PROFILE_ARBVP1 | CG_PROFILE_ARBFP1
CG_OPENGL_NV30 | CG_PROFILE_VP30 | CG_PROFILE_VP30
CG_OPENGL_NV20 | CG_PROFILE_VP20 | CG_PROFILE_VP20
CG_D3D_SHADER_2.0 | CG_PROFILE_VS_2_0 | CG_PROFILE_PS_2_0
CG_D3D_SHADER_3.0 | CG_PROFILE_VS_3_0 | CG_PROFILE_PS_3_0
CG_D3D_SHADER_1.3 | CG_PROFILE_VS_1_3 | CG_PROFILE_PS_1_3

# K.4 Interaction with other nodes and components

## K.4.1 Vertex shader

### K.4.1.1 OpenGL profiles

The vertex shader replaces the fixed functionality of the vertex processor. The OpenGL specification 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.

### K.4.1.2 Direct3D profiles

In Cg language Direct3D profiles, the vertex shader replaces the vertex processing done by the Microsoft Direct3D graphics pipeline. While using a vertex shader, state information regarding transformation and lighting operations is ignored by the fixed-function pipeline. The Direct3D specification 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.

The fixed-function pipeline Direct3D graphics state is not available for use within a Cg shader program. Shaders that wish to make use of this data, such as material, lighting, texture and transformation matrix state, shall declare parameters of the appropriate type and pass values into them via declared fields of the containing ShaderProgram node in the X3D scene graph. The parameter types and mappings to those types from built-in X3D values are defined in K.4 Data type and parameter mappings.

## K.4.2 Fragment shader

### K.4.2.1 OpenGL profiles

The fragment shader replaces the fixed functionality of the fragment processor. The OpenGL specification states that the following functionality is disabled if a fragment shader is supplied:

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

### K.4.2.2 Direct3D profiles

In Cg language Direct3D profiles, the fragment shader, also known as a pixel shader in Cg, replaces the fixed functionality of the Direct3D fragment processor. The Direct3D specification states that textures are not applied if a fragment shader is supplied.

The fixed function pipeline Direct3D graphics state is not available for use within a Cg pixel shader program. Shaders that wish to make use of this data, such as material, lighting, texture and transformation matrix state, shall declare parameters of the appropriate type and pass values into them via declared fields of the containing ShaderProgram node in the X3D scene graph. The parameter types and mappings to those types from built-in X3D values are defined in K.4 Data Type and Parameter Mappings.

## K.4.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. The shader program has been successfully compiled without error.

## K.4.4 Vertex attributes

### K.4.4.1 OpenGL profiles

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 X3D browser implementation shall automatically assign appropriate internal index values for each attribute

### K.4.4.2 Direct3D profiles

In Cg language Direct3D profiles, each vertex attribute node directly maps the name field to a Direct3D usage type for use within a Direct3D vertex declaration (with the prefix "D3DDECLUSAGE_" prepended to the name), as well as a Cg binding semantic of the same name defined on the varying inputs to a shader program. This language binding allows the use of the predefined Direct3D vertex declaration usage types and Cg binding semantics listed in Table K.3. If the name cannot be interpreted as a valid Direct3D usage type or Cg binding semantic, the values of the node shall be ignored.

Table K.3 — Supported Direct3D vertex declaration usage types

Direct3D usage type
POSITION
NORMAL
TEXCOORD
TANGENT
BINORMAL
COLOR
FOG

The X3D browser implementation shall automatically assign appropriate internal index values for each attribute in the case where multiple nodes are defined having the same value in the name field.

# K.5 Data Type and Parameter Mappings

## K.5.1 Node fields

Fields that are of type SFNode/MFNode are ignored unless the value is of type X3DTextureNode, or in Direct3D profiles, X3DMaterialNode, or X3DLightNode. Field instances of type X3DTextureNode are mapped according to the appropriate Direct3D or OpenGL sampler data type. The mappings from texture nodes to built-in sampler types are defined in Table K.4.

Table K.4 — Mapping of X3D texture node types to OpenGL or Direct3D sampler types

X3D texture type | OpenGL variable type | Direct3D variable type
--- | --- | ---
X3DTexture2DNode | sampler2D | sampler2D
X3DTexture3DNode | sampler3D | sampler3D
X3DEnvironmentTextureNode | samplerCube | samplerCube

X3D does not define mappings to the OpenGL types sampler1D, sampler1DShadow and sampler2DShadow or the Direct3D types sampler1D, sampler1DShadow and sampler2DShadow.

In Cg language OpenGL profiles, the current geometry and pipeline state is exposed through the built-in variable glstate.

In Cg language Direct3D profiles, field instances of type X3DMaterialNode and X3DLightNode are mapped to structures that shall be declared in the shader program as defined in Table K.5.

Table K.5 — Mapping of X3D material and light node types to Cg structure declarations (Direct3D profiles only)

X3D node type | Cg structure declaration | Additional information
--- | --- | ---
X3DMaterialNode |
    struct X3DMaterial {
        float4 diffuseColor;
        float4 ambientColor;
        float4 specularColor;
        float4 emissiveColor;
        float power;
    };
| All color values are 4-component with alpha value = 1.0.
X3DLightNode |
    struct X3DLight {
        int type;
        float4 diffuseColor;
        float4 specularColor;
        float4 ambientColor;
        point3 position;
        point3 direction;
        float range;
        float falloff;
        float attenuation0;
        float attenuation1;
        float attenuation2;
        float theta;
        float phi;
        bool on;
    };
| Valid type member values are 1 for Point light, 2 for Spot light and 3 for Direction light. All color values are 4-component with alpha value = 1.0. All position, direction and scalar values are assumed to be in world space. The on member specifies whether the light is enabled.

## K.5.2 X3D field types to Cg data types

Table K.6 indicates how the X3D field types shall be mapped to data types used in the Cg Language.

Table K.6 — Mapping of X3D field types to Cg data types

X3D Field type | Cg Data Type
--- | ---
SFBool | bool
MFBool | bool[]
MFInt32 | float[]
SFInt32 | float
SFFloat | float
MFFloat | float[]
SFDouble | double
MFDouble | double[]
SFTime | double
MFTime | double[]
SFNode | See K.4.1 Node fields
MFNode | See K.4.1 Node fields
SFVec2f | float2
MFVec2f | float2[]
SFVec3f | float3
MFVec3f | float3[]
SFVec4f | float4
MFVec4f | float4[]
SFVec3d | float3
MFVec3d | float3[]
SFVec4d | float4
MFVec4d | float4[]
SFRotation | float4
MFRotation | float4[]
MFColor | float4[]
SFColor | float4
SFImage | int[]
MFImage | int[]
SFString | Not supported
MFString | Not supported
SFMatrix3f | float3x3
MFMatrix3f | float3x3[]
SFMatrix4f | float4x4
MFMatrix4f | float4x4[]

Cg defines maximum supported lengths of each array data type, which may conflict with the minimum support requirements for X3D.

## K.5.3 X3D world state to Cg parameter names

In Cg language Direct3D profiles, certain internal states of the X3D world, such as transformation matrices, or the viewer's position in world space, are neither readily available via the Cg shader program or directly accessible from the X3D scene graph. Thus if used, these world state values shall be explicitly passed in to the shader program as named parameters. This binding defines an automatic mapping of these states to predefined shader program parameter names. Table K.7 specifies the mapping of internal states of the X3D world to parameter names used in the Cg programs.

Table K.7 — Mapping of X3D world state to Cg parameter names (Direct3D profiles only)

Parameter name | Description
--- | ---
model | This name refers to the matrix transforming from local to global coordinates. The model matrix transforms vertices from their model position to their position in world space ( i.e., after the effects of all Transform nodes have been applied).
view | This name refers to the viewing matrix transforming from world to view relative coordinates.
projection | This name refers to the projection matrix transforming from viewing relative coordinates to clip space, including the projective part.
modelView | This name refers to the matrix that represents the concatenation of model and view matrices. This matrix transforms vertices from their model position to their position in view space ( i.e., after the effects of all Transform nodes and the current viewpoint have been applied).
modelViewProjection | This name refers to the matrix that represents the concatenation of model, view and projection matrices. This matrix transforms vertices from their model position to their final position in clip space.
viewPosition | This name refers to the current viewer position in world space coordinates.

The following suffixes can be applied to the matrix built-in values. A suffix of I signifies the inverse of the matrix. T signifies the transpose of the matrix. IT signifies the inverse transpose of the matrix.

# K.6 Event model

## K.6.1 Changing URL fields

When the url receives an event changing the value, the X3D 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 activate the shader program, nor disable the currently running shader.

Values defined at load time of the file do not require an explicit request to activate the shader program. It shall be assumed to automatically activate the program 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 activation shall occur for the shader program.

## K.6.2 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 activate in order to make them visible to the shader.

## K.6.3 Activating programs

The user may, at any time, request that the X3D browser activate the composing shader objects by sending a TRUE value to the activate inputOnly field of the ProgramShader or PackagedShader node. Users may need to force a re-activation of the node under various circumstances, such as changing the url field of one or more ShaderProgram or PackagedShader nodes, or adding or removing ShaderProgram nodes from the programsfield of the ProgramShader node. Reactivating the shader shall replace the existing shader with the new compiled shader for subsequent rendering.