Shader Parameters @ 3DVIA Studio: A Powerful 3D Development Tool

Shader Parameters

Shader Inputs, Outputs and Semantics
Automatic Parameters
Additional Semantics
Manual Parameters
Annotations
Static Variables
Intrinsic Vertex Shader Parameters
Intrinsic Pixel Shader Parameters
Retrieving Lights

Shader Inputs, Outputs and Semantics

A Shader uses parameters to transmit its execution input and output values. There are two possible paths from which a Shader’s input parameter can acquire its value: directly from the 3D Engine, using Semantics, or from user inputs through a material’s parameters.

Values fed from user inputs (called Exposed Parameters) need to be declared inside the shader code as Manual Parameters. A parameter specified with a Semantic, on the other hand, will take its values directly from the 3D Engine. HLSL uses Semantics specifically for that purpose. Semantics are keywords added right after a parameter declaration that tells the Engine from which engine parameter the shader parameter value needs to be retrieved, in a syntax such as:

type id:SEMANTIC
type

The parameter’s type declaration: a scalar (bool, half, float4), vector, matrix (float4x4), texture, etc.

The parameter’s name. Note: HLSL is case sensitive for parameter names.

“:” is the HLSL operator indicating that the word that follows it is a semantic.

SEMANTIC

HLSL or 3DVIA Studio-defined keyword having a special meaning for the application. The value assigned to “id” will depend on the semantic’s string. See Additional Semantics for an exhaustive list of valid semantics in 3DVIA Studio.

Top-level shader input parameters (see Automatic Parameters), such as the world matrix of the object currently being rendered, or the view matrix of the camera currently rendering the scene, will acquire their value directly from the 3DVIA Studio’s 3D Engine through standard and additional semantics.

Inputs of Vertex Shader functions and Pixel Shader functions cannot be exposed and hence need to be fed directly by the 3D Engine using Semantics (see VS Intrinsic Parameters and PS Intrinsic Parameters). HLSL defines a limited set of semantics, Context-Specific Semantics, for inputs that are streamed into the shader from the vertex buffer (semantics are the key to actually getting the value from the vertices in the input buffer). For pixel shaders, they are values being passed through from the vertex shader. Note that pixel and vertex shaders have different sets of input semantics due to their differences in the graphics pipeline:

Vertex Shader input semantics describe the per vertex information to be loaded from a vertex buffer into a form that can be consumed by the vertex shader.
Pixel Shader input semantics describe the information that is provided per pixel by the rasterization unit.

Data provided by vertex and pixel shaders to the subsequent graphics pipeline stages constitute the Shader Outputs. Vertex shader output semantics are used to link the shader both to the pixel shader and the rasterizer stage. Pixel shader output semantics bind the output colors of a pixel shader with the correct render target.

To sum up, there are five distinguished groups of semantics:

Top-level shader parameters’ semantics.
Context-specific:
- Vertex Shader function’s input semantics.
- Vertex Shader function’s output semantics.
- Pixel Shader function’s input semantics.
- Pixel Shader function’s output semantics.

Automatic Parameters

Automatic Parameters let the user create a link between a variable located inside the shader source code and an engine-side attribute (like the material diffuse color or the behavioral timer).

Automatic Parameters are generally declared at the top of the shader source code and in most cases they are identified with the following syntax:

Syntax:

type id : SEMANTIC

where the semantic string is highlighted in yellow using Shader Editor features to indicate that is a global semantic (no VS or PS input or output).

For example, the following statements correspond to different Automatic Parameters’ declarations:

Examples:

texture tex : TEXTURE;

A texture object linked to the material’s texture.

float time : TIME;

A floating point real number linked to the behavioral timer.

float4 colDif : DIFFUSE;

A color linked to the material’s diffuse color.

float4x4 world : WORLD;

A 4×4 matrix linked to the object world matrix.

Note: All semantics used to define variables as being Automatic Parameters are listed at the top of the Shader source code.

Note: A (non context-specific) semantic should appear only once inside a shader source code.

Note: Do not mix up global semantics used for Automatic Parameters and context-specific semantics used for intrinsic Vertex/Pixel Shader Function Parameters. (c.f. intrinsic parameters are explained later.)

Additional Semantics

A Semantic provides the 3DVIA Studio engine with an exposed variable’s special meaning. They avoid setting a ton of parameters by hand, things for which you should set a value every time you instantiate a shader.

A semantic is, in a general sense, a mapping to a specific concept for the shader to use. The colon “:” is used in HLSL to map any semantic to any variable or function return. For example, the following statement is a declaration of the world-view projection matrix, the camera position, the simulation time and the material’s diffuse value:

float4x4 wvpMatrix : WORLDVIEWPROJECTION;
float3 camPosition : CAMERAPOSITION;
float time : TIME;
float4 materialDiffuse : DIFFUSE;

Some semantics are common to most 3D engines – called Standard Semantics – while other ones are particular to 3DVIA Studio – called Additional Semantics. Each semantic has a particular meaning for the 3DVIA Studio’s 3D engine; below is the complete list:

*Object Related Semantics & Engine Globals:*

World	World Matrix (transformation from local to world)
View	View Matrix (transformation from world to view)
Projection	Projection Matrix (transformation from view to screen)
WorldView	World x View Matrix (transformation from local to view)
WorldViewProjection	World x View x Projection Matrix (transformation from local to screen)
Position	Object’s position (float3)
CamPos EyePos World_Camera_Position WorldCameraPosition	Camera Position expressed in world space by default. Valid Annotations: Space.
CamPos EyePos	Camera direction expressed in world space by default.
BoundingBoxMax Local_BBox_Max LocalBBoxMax	Bounding box maximum x, y, z coordinates in object space by default (float3, or vector).
BoundingBoxMin Local_BBox_Min LocalBBoxMin	Bounding box minimum x, y, z coordinates in object space by default (float3, or vector).
BoundingBoxSize Local_BBox_Size LocalBBoxSize	Bounding box size in object space by default (float3, or vector).
BoundingBoxCenter	Bounding box center position in object space by default (float3, or vector).
BoundingSphereSize	Bounding sphere median radius in object space by default (float).
BoundingSphereMin	Bounding sphere minimum radius in object space by default (float).
BoundingSphereMax	Bounding sphere maximum radius in object space by default (float).
Time	Time elapsed since 3DVIA Studio’s PLAY event occured (float in seconds)
LastTime	Last simulation time (float in seconds)
ElapsedTime	Last delta time (float in seconds)
NearestLight	Nearest light properties (float = range, float3 = position, float4 = color, float4x4 = matrix) Valid Annotations: Nearest, Sort, Default, Space. (see retrieving lights)
LightCount	Number of active lights in the scene (int) Valid Annotations: Nearest, Sort, Default, Space.
Random	Random number in range [0.0 - 1.0] (float)
GlobalAmbient	Global ambient color (float4)

*Material Related:*

Diffuse	Material’s Diffuse Color (float4)
Emissive	Material’s Emissive Color (float4)
Specular	Material’s Specular Color (float4)
Ambient	Material’s Ambient Color (float4)
SpecularPower Power	Material’s Specular Power (float)
Texture	Material’s texture
Texturei	Material’s Texture of Channel i (with i between 0 and 7)
TexelSize	Texel Size of the last texture parsed in the shader (float2)

*Skin & Bones:*

Bones Joint	Bones’ Matrices.
TBones TJoint	Transposed Bones’ Matrices
RBones RJoint	Index of the register where bones matrices of the skinned character will be copied (int)
RTBones RTJoint	Index of the register where transposed bones matrices of the skinned character will be copied (int)
BonesPerVertex JointPerVertex	Maximum number of bones per vertex (int)

*Tranposed Matrices:*

TWorld	Transposed World Matrix
TView	Transposed View Matrix
TProjection	Transposed Projection Matrix
TWorldView	Transposed World x View Matrix
TWorldViewProjection	Transposed World x View x Projection Matrix

*Inversed Matrices:*

IWorld WorldI Inv_World	Inversed World Matrix Other Synonym: WorldInverse
IView ViewI Inv_View	Inversed View Matrix Other Synonym: ViewInverse
IProjection ProjectionI Inv_Projection	Inversed Projection Matrix Other Synonym: ProjectionInverse
IWorldView WorldViewI Inv_WorldView	Inversed World x View Matrix Other Synonym: WorldViewInverse
IWorldViewProjection WorldViewProjectionI Inv_WorldViewProjection	Inversed World x View x Projection Matrix Other Synonym: WorldViewProjectionInverse

*Transposed Inversed Matrices:*

ITWorld WorldIT Inv_TWorld	Transposed Inversed World Matrix Other Synonym: WorldInverseTranspose
ITView ViewIT Inv_TView	Transposed Inversed View Matrix Other Synonym: ViewInverseTranspose
ITProjection ProjectionIT Inv_TProjection	Transposed Inversed Projection Matrix Other Synonym: ProjectionInverseTranspose
ITWorldView WorldViewIT Inv_TWorldView	Transposed Inversed World x View Matrix Other Synonym: WorldViewInverseTranspose
ITWorldViewProjection WorldViewProjectionIT Inv_TWorldViewProjection	Transposed Inversed World x View x Projection Matrix Other Synonym: WorldViewProjectionInverseTranspose

Note: Another type of semantic exists, called Context-specific Semantics.
They have no relation to exposed parameters, and are only used to define pixel and vertex shader function’s input/output parameters. See Intrinsic Vertex Shader Parameters and Intrinsic Pixel Shader Parameters for more information on Context-specific Semantics.

Manual Parameters

If a variable is not defined as Automatic (i.e. it has no valid semantic at the end), and if its usage is not static (see Static Variables), then it is considered a Manual Parameter.

When a shader is used by a material A, then a list of 3DVIA Studio parameters matching the shader’s Manual Parameters is created and stored in material A. If another material B uses the same shader, then another list of 3DVIA Studio parameters matching the shader’s Manual Para maters is created and stored in material B. Both lists are independent. In other words, each material owns its own version of the parameter.

The following statements provide examples of Manual Parameters’ declarations:

Examples:

float3 myVector;

myVector will be exposed in the Material Editor through an 3DVIA Studio 3D vector parameter.

texture tex;

tex will be exposed through an 3DVIA Studio’s texture parameter.

Note: It is always better to compute big calculations outside the shader code and pass the result to an exposed parameter, rather than making big calculations inside the shader code. Remember that a vertex shader function is called for every vertex, and a pixel shader function is called for every pixel! So if part of the code can be computed once for all vertices/pixels, then use a Manual Parameter and compute its value in an 3DVIA Studio Graph or VSL program.

Annotations

Annotations add some information to an exposed parameter, a technique, a pass or a function. This information is “invisible” to the shader compiler itself, but can be relevant for the 3D engine (e.g. for a macro).

In other words it gives hints to the 3D engine, while keeping the generated assembly code unchanged.

In 3DVIA Studio, only Exposed Parameters and Techniques can be extended with Annotations.

Syntax:

type id = value;
type

Parameter/annotation type (ex: float3, int, texture, etc).

Parameter name (ex: UIMax, Width, Name, etc).

string

Annotation name (a vkString).

value

Annotation value (ex: “Geometry”, “Local”, “Vector”, etc).

value

Parameter value.

Examples:

float3 lightPos ;

lightPos has been added a string annotation named objType with value entity3d.

float3< lightPos ;

Two annotations can be set in the same line.

float3 lightPos = {0,0,-100};

An initialization value can still be added while using annotations.

float4 vec ;

vec is exposed as a 4D vector, not as a color.

texture tex;
static float2 texelSize ;

texelSize will receive the computed texel size of exposed tex texture.

Annotations Context:

Annotations are meaningful only if used on proper contexts. For instance, the annotation used in the first line is meaningful (retrieves the camera position in the local object space), while the same annotation used in the second line is meaningless:

float3 camPos : CamPos ;//— Meaningful
float3 difCol : Diffuse ;//— Meaningless

General Annotations:

Syntax	Applies To	Meaning
string Type=“Geometry”;	float3	The parameter will be exposed as a 3DVIA Studio 3D Entity, and the float3 variable will be set to the 3D Entity’s position. Synonyms: string Type=“Entity3D“;, string Type=“3DEntity“;
string Type=“Camera”;	float3	The parameter will be exposed as a 3DVIA Studio Camera, and thefloat3 variable will be set to the Camera’s position.
string Type=“Light”;	float3	The parameter will be exposed as a 3DVIA Studio Light, and thefloat3 variable will be set to the Light’s position.
string Type=“Vector”;	float4	The parameter will be exposed as a 4D vector, not as a color (by default afloat4 is exposed as a RGBA color).
bool IsTexelSize=true;	float2	The parameter will not be exposed to the user (will react as an automatic parameter), and will received the texel size of the last declared texture (same behavior as the TexelSize semantic).
string Space=value;	float3, float4x4	The parameter (vector or matrix) will be given in the specified referential depending on value. “Local” = object’s referential. “World” = world’s referential (default). Note: the Space annotation is valid for exposed manual parameters, but also for CamPos or NearestLight semantics.

Lights Retrieval Annotations:

Syntax	Applies To	Meaning
int Nearest=value	float, float3, float4, float4x4	This annotation is relevant only in relation to the NearestLight semantic. It defines the index of the light to retrieve (default is 0). (see retrieving lights).
bool Sort=true	float, float3, float4, float4x4	This annotation is relevant only in relation to the NearestLight semantic. It tells the engine either to sort the light array by proximity order, or not (default is true). (see retrieving lights).
float Default=value float4 Default=value	float, float4	This annotation is relevant only in relation to the NearestLight semantic. It defines the default value the parameter should take if it ever happen the expected light doesn’t exist. By default, if the parameter is afloat3, the camera’s position will be taken, and in the same way if the parameter is afloat4x4, the camera’s matrix will be taken. Otherwise, forfloat, andfloat4 parameters the default value is defined by this annotation. (see retrieving lights).

*Texture Annotations:*

Syntax	Applies To	Meaning
string Name=name;	texture	The parameter will not be exposed to the user (will react as an automatic parameter), and the texture variable will be linked to the texture object in the scene matching the specified name.
string ResourceName=filename;	texture	The parameter will not be exposed to the user (will react as an automatic parameter), and the texture variable will be linked to the texture object loaded using the specified filename. Note: the texture will be loaded at compilation time.
string ResourceType=restype;	texture	This annotation is relevant only in relation to the Function annotation or the ResourceName annotation. It defines the procedural texture type: “Volume”, “3D”, “2D” or “Cube”. Default value is “2D”.
string Function=fctname;	texture	The parameter will not be exposed to the user (will react as an automatic parameter), and the texture variable will be link to a procedural texture object created and filled with texels evaluated from the specified fctname. Note: the procedural texture is created and filled at compilation time.
string Target=tname;	texture	This annotation is relevant only in relation to the Function annotation. It defines the procedural texture profile (by default tx_1_0) to compile the function with.
int Width=value;	texture	This annotation is relevant only in relation to the Function annotation. It defines the width of the created texture.
int Height=value;	texture	This annotation is relevant only in relation to the Function annotation. It defines the height of the created texture.
int Depth=value;	texture	This annotation is relevant only in relation to the Function annotation, and if the created procedural texture is a 3D texture (volume map). It defines the depth of the created 3D texture.
float4 Dimensions=value;	texture	This annotation is relevant only in relation to the Function annotation. It defines the dimension of the procedural texture (same as Width, Height and Depth at the same time).
string Format=value	texture	This annotation is relevant only in relation to the Function annotation. It defines the format of the procedural texture. See D3DFORMAT for a complete list of formats (ensure the 3d card support the chosen format). Remove the D3DFMT_ prefix.
int MipLevels=value;	texture	This annotation is relevant only in relation to the Function annotation. It defines the number of mipmaping levels of the created texture.

User Interface Annotations:

Syntax	Applies To	Meaning
float UIMin=value	float	This annotation is relevant only in relation to the UIMax annotation. It exposes a FloatSlider parameter instead of a single float parameter. The specified value defines the slider minimum value.
float UIMax=value	float	This annotation is relevant only in relation to the UIMin annotation. It exposes a FloatSlider parameter instead of a single float parameter. The specified value defines the slider maximum value.

Technique Annotations:

Syntax	Applies To	Meaning
bool NeedTangentSpace=true	technique	This annotation is relevant only on a technique. It forces the Tangent Spaces to be built on each mesh using the shader. Note: for efficiency reasons, a false value won’t remove the built Tangent Spaces.
bool NeedColorAndNormal=true	technique	This annotation is relevant only on a technique. It forces the normals and colors to both be sent to the shader stream.

Static Variables

A Static Variable is not exposed nor its value retrieved from the 3D Engine, and it is only known and understood by
the shader source code. In other words, a static variable is “local” to the shader’s code, just like a local variable inside a statement.

Example:

static float4 colEmi = {1,1,0,0};

A static color initialized in yellow.

Static Variables are very useful to precalculate values that just change once per shader execution (not at every vertex/pixel shader function execution).

Example:

static float4 tmp = sin(colEmi.r) * 150.0f;

A floating point number processed just once for all vertices.

Note: Variables that do not need to be exposed should always be defines as static variables to avoid useless processing.

Note: The static keyword is only necessary in the global scope of the shader source code. Once inside a function, a variable is always compiled as a local variable whether or not the static keyword is used.

Intrinsic Vertex Shader Parameters

Intrinsic Vertex Shader Parameters are the input/output parameters handled by a vertex shader function. Context-specific VS semantics are used to so that the Vertex Shader function understands how to use them.

Example:

struct EdgeVSOut
{
float4 Pos : POSITION;
float4 Col : COLOR;
};

A Vertex Shader can use this structure to output the Vertex Position and Vertex Color.

EdgeVSOut
EdgeVS
(
float4 Pos : POSITION,
float4 Norm : NORMAL
)
{
/*
… code … */
}

This Vertex Shader takes the Vertex Position and the Vertex Normal as Input Parameters.

Context-Specific VS Semantics

*Vertex Shader Input Semantics:*

POSITION[n]	Vertex position expressed in the mesh’s referential.POSITION (without brackets) is an alias forPOSITION[0]. 3DVIA Studio manages only one set of vertices positions, soPOSITION[1..n] are not supported by 3DVIA Studio.
BLENDWEIGHT[n]	Vertex blend weights. Not supported by 3DVIA Studio.
BLENDINDICES[n]	Vertex blend indices. Not supported by 3DVIA Studio.
NORMAL[n]	Vertex normal vector expressed in the mesh’s referential.NORMAL (without brackets) is an alias for NORMAL[0]. 3DVIA Studio manages only one set of vertices normals, so NORMAL[1..n] are not supported by 3DVIA Studio.
PSIZE[n]	Vertex point size. Not supported by 3DVIA Studio.
DIFFUSE[n]	Vertex diffuse color. DIFFUSE (without brackets) is an alias for DIFFUSE[0]. 3DVIA Studio manages only one set of vertices diffuse colors, so DIFFUSE[1..n] are not supported by 3DVIA Studio.
SPECULAR[n]	Vertex specular color. SPECULAR (without brackets) is an alias for SPECULAR[0]. 3DVIA Studio manages only one set of vertices specular colors, so SPECULAR[1..n] are not supported by 3DVIA Studio.
TEXCOORD[n]	Vertex texture coordinate. TEXCOORD (without brackets) is an alias for TEXCOORD[0].
TANGENT[n]	Not managed by 3DVIA Studio; use instead TEXCOORD1 with the NeedTangentSpace technique annotation. The tangent set can also be built through the Build Tangent Space building block or in the mesh setup.
BINORMAL[n]	Not managed by 3DVIA Studio; use instead TEXCOORD2 with the NeedTangentSpace technique annotation. The binormal set can also be built through the Build Tangent Space building block or in the mesh setup.
TESSFACTOR[n]	Vertex tessellation factor. Not supported by 3DVIA Studio.

*Vertex Shader Output Semantics:*

POSITION	Vertex position expressed in world space.
PSIZE	Vertex point size.
FOG	Vertex fog.
COLOR[n]	Vertex color. COLOR (without brackets) is an alias for COLOR0.
TEXCOORD[n]	Vertex texture coordinate. TEXCOORD (without brackets) is an alias for TEXCOORD0.

See Microsoft DirectX 9 HLSL Reference > Shader Semantics for additional information on Context-Specific Vertex Shader Semantics.

Intrinsic Pixel Shader Parameters

Intrinsic Pixel Shader Parameters are the input/output parameters handled by a Pixel Shader Function. Context-specific PS semantics are used so that the Pixel Shader Function understands how to use them.

Context-Specific PS Semantics

*Pixel Shader Input Semantics:*

COLOR[n]	Pixel color (interpolated from output vertex color). COLOR (without brackets) is an alias for COLOR0.
TEXCOORD[n]	Pixel texture coordinate (interpolated from output texture coordinates). TEXCOORD (without brackets) is an alias for TEXCOORD0.

*Pixel Shader Output Semantics:*

COLOR[n]	Pixel color. COLOR (without brackets) is an alias for COLOR0.
TEXCOORD[n]	Pixel texture coordinate. TEXCOORD (without brackets) is an alias for TEXCOORD0.

See Microsoft DirectX 9 HLSL Reference > Shader Semantics for additional
information on Intrinsic Vertex Shader Semantics.

Retrieving Lights

Lights position, color, range and matrix can be retrieved with the NEARESTLIGHT semantic as follow:

float3 posLight    : NEARESTLIGHT; //— Nearest Light’s Position
float4x4 matLight   : NEARESTLIGHT; //— Nearest Light’s World Matrix
float4 colLight    : NEARESTLIGHT; //— Nearest Light’s Color
float rangeLight : NEARESTLIGHT; //— Nearest Light’s Range

To those types, somes annotations can be added: “< int Nearest=2; >;” retrieves the 3rd nearest light (0 based array).
Default value is 0 (nearest). This annotation works for all types.

Example:

//— Retrieves the 3d Nearest Light’s Position
float3 posLight : NEARESTLIGHT int Nearest=2; >;
//— Retrieves the 3d Nearest Light’s Color
float4 colLight : NEARESTLIGHT int Nearest=2; >;

The above Semantics / Annotations are valid for Arrays too.

Example:

//— Retrieves the First 2 Nearest Light’s Positions
float3 posLight[2]   : NEARESTLIGHT;
//— Retrieves the First 5 Nearest Light’s Matrices
float4x4 posLight[5] : NEARESTLIGHT;
//— Retrieves the First 2 Nearest Light’s Colors
float4 posLight[2]   : NEARESTLIGHT;
//— Retrieves the First 3 Nearest Light’s Ranges
float posLight[3]    : NEARESTLIGHT;

“< bool Sort=false; >;” by default, the retrieved light(s) will be sorted by proximity order. Default value is true. Setting this boolean annotation to false will retrieve lights in the order in which they are stored by the 3D engine (Not listed by proximity, but typically in their creation order).

Example:

//— Retrieves the 2 first Light’s Position in the 3d Engine natural order
float3 posLight[2] : NEARESTLIGHT bool Sort=false; >;

Sometimes, a Shader expects a light’s position when no light is available. In such a case, the missing light’s position will be replaced by the camera’s position.
The same goes for matrices. A missing light’s matrix will be replaced by the camera’s matrix.
For a light’s color, the default color is black, but this value can be overridden using the annotation:

;

Example:

//— Gives missing lights a default white color
float4 rangeLight[3] : NEARESTLIGHT< float4 Default={1,1,1,1}; >;

The missing light’s range has a default value of 200. But this too can be overridden using the annotation:

float Default=myRange; >;

Example:

//— Gives missing lights a default range of 1000
float rangeLight[5] : NEARESTLIGHT ;

“< string Space=“Local”; >;” retrieves the position or matrix in the “Local” or “World” referential.
Default value is “World”.

Example:

//— Retrieves the Nearest Light’s Position, expressed in the Object Referencial
float3 posLight : NEARESTLIGHT< string Space="Local"; >;
//— Retrieves the Nearest Light’s Matrix, expressed in the World Referential
float4x4 matLight : NEARESTLIGHT< string Space="World"; >;