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

Annex X

(normative)

Microsoft High Level Shading Language (HLSL)

--- X3D separator bar ---

cube 1 General

This annex defines how a browser implementing the Shader component maps the concepts of the Microsoft High Level Shading Language (HLSL) to the Shading Component. It applies to the ProgramShader, ShaderProgram and PackagedShader nodes with the language field set to "HLSL".

cube 2 Topics

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

Table 1 — Topics

cube 3 Interaction with Other Nodes and Components

3.1 Vertex Shader

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 HLSL specification states that the following functionality is disabled if a vertex shader is supplied:

The fixed function pipeline Direct3D graphics state is not available for use within an HLSL shader program. Shaders that wish to make use of this data, such as material, lighting, texture and transformation matrix state, must 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 4 Data Type and Parameter Mappings.

3.2 Fragment Shader

The fragment shader, also know as a pixel shader in HLSL, replaces the fixed functionality of the Direct3D fragment processor. The HLSL specification states that the following functionality is disabled if a fragment shader is supplied:

The fixed function pipeline Direct3D graphics state is not available for use within an HLSL pixel shader program. Shaders that wish to make use of this data, such as material, lighting, texture and transformation matrix state, must 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 4 Data Type and Parameter Mappings.

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 the all the following conditions have been satisifed:

3.4 Vertex Attributes

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 an HLSL 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 HLSL binding semantics listed in Table 2. If the name is can not be interpreted as a valid Direct3D usage type or HLSL binding semantic, the values of the node shall be ignored.

Table 2 — Supported Direct3D Vertex Declaration Usage Types

Direct3D Usage Type
POSITION
NORMAL
TEXCOORD
TANGENT
BINORMAL
COLOR
FOG

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

cube 4 Data Type and Parameter Mappings

4.1 Node fields

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

.

Table 3 — Mapping of X3D texture node types to HLSL Shading Language Sampler Types

X3D Texture type HLSL Variable Type
X3DTexture2DNode sampler2D
X3DTexture3DNode sampler3D
X3DEnvironmentTextureNode samplerCube

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

Field instances of type X3DMaterialNode and X3DLightNode are mapped to structures which must be declared in the shader program as defined in Table 4.

Table 4 — Mapping of X3D material and light node types to HLSL Shading Language Structure Declarations

X3D Node Type HLSL 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

4.2 X3D Field Types to HLSL Data Types

Table 5 indicates how the X3D field types shall be mapped to data types used in the HLSL Language.

Table 5 — Mapping of X3D Field Types to HLSL Data Types

X3D Field type HLSL Data Type
SFBool bool
MFBool bool[]
MFInt32 int[]
SFInt32 int
SFFloat float
MFFloat float[]
SFDouble double
MFDouble double[]
SFTime double
MFTime double[]
SFNode See 4.1 Node Fields
MFNode See 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[]

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

4.3 X3D World State to HLSL Parameter Names

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 HLSL shader program or directly accessible from the X3D scene graph. Thus, they must 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 6 indicates how internal states of the X3D world are mapped to parameter names used in the HLSL programs.

Table 6 — Mapping of X3D World State to HLSL Parameter Names

Parameter name Description
model The matrix transforming from local to global coordinates. Transforms vertices from their model position to their position in world space (i.e. after effect of all Transform nodes has been applied).
view The viewing matrix transforming from world to view relative coordinates.
projection The projection matrix transforming from viewing relative coordinates to clip space, including the projective part.
modelView Concatenation of model and view transforms vertices from their model position to their position in view space (i.e. after effect of all Transform nodes and current viewpoint has been applied).
modelViewProjection Concatenation of model, view and projection transforms vertices from their model position to their final position in clip space.
viewPosition The current viewer position in world space coordinates.

The following suffixes can be applied to the matrix builtin 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.

cube 5 Event Model

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 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 (eg due to errors) then no activation will occur for the shader program.

5.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.

5.3 Activating Programs

The user may, at any time, request that the 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.

--- X3D separator bar ---