Semantics and annotations supported by the dx11Shader and glslShader plug-ins in Viewport 2.0

If you are writing your own custom shader for use with the dx11Shader or glslShader plug-in in Viewport 2.0, the following are the supported semantics and annotations.

Supported parameter and uniform annotations

The dx11ShaderNode and GLSLShaderNode classes look for the following annotations on parameters and uniforms (GLSL) and forward relevant information to the MUniformParameter class at creation time:

Note: Although the OpenGL Shading Language (GLSL) does not support annotations, OGSFX does and they can be used for uniform, technique, and pass definitions.

Name Type Description

UIOrder

int

Allows reordering of parameters in the Attribute Editor, especially useful since the parameter order returned by the compiler does not always follow the order of declaration in the FX file. The parameter with the smallest UIOrder is laid out at the top of the AE, and the other parameters are added following increasing UIOrder.

If not set, the parameter is placed in the same order as it appears in the shader file, but after the parameters with a specified UIOrder.

UVEditorOrder int Allows reordering of textures in the UV Texture Editor. The texture parameter with the lowest UVEditorOrder appears first under the Textures menu.

UIGroup

string

All parameters with the same UIGroup attribute are laid out in a separate collapsible panel, the label of which is the UIGroup value. The panels are inserted at the position of the group parameter with the lowest UIOrder.

If not set (or empty), the parameter is not placed in any named group.

Object

string

Group different shader parameters as part of the same Maya object.

This is commonly used to define all parameters for a light. At the Attribute Editor parameter layout level, this acts exactly as a UIGroup annotation, except that the panel is collapsed by default. This is also used to determine the type of the light object when the object name contains "Light" (or "Lamp") and "Point", "Spot", "Ambient" or "Directional".

A drop-down menu is created for each distinct Object, allowing easy connections to existing Maya scene lights.

Example:

uniform lightColor : DIFFUSE
<
    Object = "Light0_Spot";
>;
uniform lightPosition : POSITION
<
    Object = "Light0_Spot;
>;

lightColor and lightPosition will be bound to the attributes of the same light node, which will likely be a Spot Light.

UIName string Allows renaming of a parameter in the UI (Attribute Editor). By default, the variable name is shown.

SasUiVisible

UIType

UIWidget

bool

string

Controls the visibility of the variable in the UI.

For the two string annotations, a value of None hides the variable.

Set UIType or UIWidget to ColorPicker to use the Color Chooser widget.

SasUiMin

UIMin

uimin

float/int

(same as Parameter)

Minimum range value.

Corresponds to MUniformParameter::setRangeMin().

SasUiMax

UIMax

uimax

float/int

(same as Parameter)

Maximum range value.

Corresponds to MUniformParameter::setRangeMax().

UISoftMin

uisoftmin

float/int

(same as Parameter)

Minimum slider value for a range. Values smaller than UISoftMin (but larger than UIMin if specified) can be entered in the numeric input of the parameter.

Corresponds to MUniformParameter::setSoftRangeMin().

UISoftMax

uisoftmax

float/int

(same as Parameter)

Maximum slider value for a range. Values greater than UISoftMax (but smaller than UIMax if specified) can be entered in the numeric input of the parameter.

Corresponds to MUniformParameter::setSoftRangeMax().

UIFieldNames

string

Creates a drop-down menu for the int parameter using the strings found in the attribute value.

The format is the same as the MEL command attributeQuery -listEnum, which is a string of colon ":" delimited field names which can specify an index value separated by an equal sign "=". The indexing starts at zero, and the index value of an item, when it is not explicitly specified, is the index of the previous item (if any) incremented by one.

Example: "Shaded:Wireframe=8:Bounding Box" defines 3 items with values 0, 8, and 9.

ResourceName

SasResourceAddress

string

Default texture file name. The plug-in automatically loads and connects the texture when setting the effect.

The path can be absolute or relative. If a relative path is defined, the plug-in first tries to search for the file in the same folder hierarchy as the current ogsfx file.

If the file is not found, then the plug-in searches for the file in the paths defined in MHWRender::MTextureManager::imagePaths().

TextureType

ResourceType

string

If the variable is described as an under-specified texture instead of a texture[1D|2D|3D|Cube], then this annotation allows you to specify the texture type. Valid values are “1D”, “2D”, “3D”, and “Cube”.

Space

string

Allows specifying of the default space for position and direction semantics. Valid values are “Object”, “World”, “View”, and “Camera”. Any other value is ignored and the semantic remains undefined.

"Object" corresponds to: semantic MUniformParameter::kSemanticObjectPos or MUniformParameter::kSemanticObjectDir

"World" corresponds to: MUniformParameter::kSemanticWorldPos or MUniformParameter::kSemanticWorldDir

"View" or "Camera" corresponds to: MUniformParameter::kSemanticViewPos or MUniformParameter::kSemanticViewDir

Texture specific parameter annotations

Name Type Description

mipmaplevels

int

The dx11Shader allows for you to control the number of mip-map levels that should be loaded or generated, either at the technique or texture description level.

Use this annotation with your texture description. The following values are valid.

<val> = 0: generates all mip map levels for affected textures. If there are any existing mip maps in the textures, then they will be loaded. This allows, for example, the loading of pre-calculated mip maps for DDS textures.
<val> = 1-10 : only generates mipmaps up to the specified level.

To reduce texture memory, the default value for the dx11Shader plug-in is set to 1, so that only the first mip map level (<val>=1) is loaded / computed.

Note: For the glslShader and shaderFX plug-ins, the default value is set to 0.

It is also possible to enforce this on a per texture basis to explicitly reduce memory usage.

Sample implementation as follows:

Texture2D DiffuseTexture
<
    string UIName = "Diffuse Map";
    string ResourceType = "2D";
    int mipmaplevels = <val>; 
>;

This value takes precedence over the value set for the technique annotation (texture_mipmaplevels). See Supported technique annotations.

See AutodeskUberShader.fx in the presets\HLSL11\examples folder of your Maya installation for example use of this annotation.

Supported semantics

Semantic	Type	Description
Color	float3/4 (dx11Shader) vec3/4 (glslShader)	Color parameter: use Color Chooser widget in the Attribute Editor.
Ambient	float3/4 (dx11Shader) vec3/4 (glslShader)	Color parameter: use Color Chooser widget in the Attribute Editor.
Specular	float3/4 (dx11Shader) vec3/4 (glslShader)	Color parameter: use Color Chooser widget in the Attribute Editor.
Diffuse	float3/4 (dx11Shader) vec3/4 (glslShader)	Color parameter: use Color Chooser widget in the Attribute Editor.
TranspDepthTexture	texture	Texture used by the Depth Peeling and Weighted Average transparency algorithms.
OpaqueDepthTexture	texture	Texture used by the Depth Peeling and Weighted Average transparency algorithms.

Light specific semantics

In addition to all the semantics currently supported by the MUniformParameter class, the dx11ShaderNode and GLSLShaderNode add extra light specific semantics to bind the properties of a scene light to shader parameters. When a light is driven by Maya, the values of all supported parameters are written using light information from the draw context. Unsupported parameters are left at the value found in the shader. This means that connecting a point light drives the position parameter, but not the direction.

Semantic	Type	Maya light parameter	Description
LightColor, Color, LightDiffuseColor, Diffuse, LightAmbientColor, Ambient, LightSpecularColor, Specular	float3/4 (dx11Shader) vec3/4 (glslShader)	Color	Color parameter: use Color Chooser widget in the Attribute Editor. Values are not premultiplied by the light intensity.
LightIntensity	float	Intensity
LightEnable	bool	Illuminate by default	Follows the visibility of the light, including global light settings. When true, the Maya light is active and visible.
LightType	int	Type	Allows writing of generic lighting code that can react correctly when connected to any light type. Valid values are: 2- Spot 3- Point 4- Directional 5- Ambient 6- Volume 7- Area
Position	float3/4 (dx11Shader) vec3/4 (glslShader)		Position for point, spot, area and volume lights. For area lights, the Position is the center of the area light. Reference space can be specified with an annotation.
Direction	float3/4 (dx11Shader) vec3/4 (glslShader)		Direction for directional and spot lights. Reference space can be specified with an annotation.
AreaPosition0-3	float3/4 (dx11Shader) vec3/4 (glslShader)		Position for the four corners of an area light.
Hotspot	float	Cone Angle/ Penumbra Angle	For spot lights, half angle, in radians. The Hotspot is computed as the minimum of ConeAngle and (ConeAngle+PenumbraAngle).
LightFalloff Falloff	float	Cone Angle/ Penumbra Angle	For spot lights, half angle, in radians. The Falloff is computed as the maximum of ConeAngle and (ConeAngle+PenumbraAngle).
DecayRate	float	Decay Rate	For spot, point, area, and volume lights, expressed as an exponent. Maya provides the following values: 0.0 – No Decay 1.0 – Linear 2.0 – Quadratic 3.0 – Cubic
ShadowFlag	bool	Various	When true, the light casts a shadow that the surface can receive. This value is true only when global Shadows are enabled, the light Use Depth Map Shadows is on, and the surface Receive Shadows is on.
ShadowColor	float3/4 (dx11Shader) vec3/4 (glslShader)	Shadow Color	Color parameter: use Color Chooser widget in the Attribute Editor.
ShadowMap	Texture2D		Contains the depth map shadow texture as computed by Maya.
ShadowMapBias	float	dmapBias
ShadowMapMatrix ShadowMapXForm	float4x4 (dx11Shader) mat4 (glslShader)		View transformation matrix of the light

Varying attributes for vertex streams

Semantic	Type	Description
POSITION	float3/4 (dx11Shader) vec3/4 (glslShader)	Instructs Maya to bind this attribute to the vertex buffer that contains the positions
NORMAL	float3/4 (dx11Shader) vec3/4 (glslShader)	Instructs Maya to bind this attribute to the normal vertex buffer.
TANGENT	float3/4 (dx11Shader) vec3/4 (glslShader)	Instructs Maya to bind this attribute to the tangent vertex buffer.
BINORMAL	float3/4 (dx11Shader) vec3/4 (glslShader)	Instructs Maya to bind this attribute to the binormal (or bitangent) vertex buffer.
COLOR0	float3/4 (dx11Shader) vec3/4 (glslShader)	Instructs Maya to bind this attribute to the color set vertex buffer. Note: For glslShader only: Currently, there is only 1 stream available. While OGSFX is limited to only one color stream defined by the COLOR0 semantic, it is still possible to define more than one color stream by using the TEXCOORDx semantic. An attribute using the TEXCOORDx semantic that is of a vec3 or vec4 type can be used to convey a color stream to the shader, and an attribute using the TEXCOORDx semantic that is of vec2 type used to convey a UV coordinate stream.
TEXCOORD0-7	float3/4 (dx11Shader) vec 2 or vec3/4 (glslShader)	Instructs Maya to bind this attribute to the UV set vertex buffer. Currently, there are 8 streams available. Note: For glslShader only: While OGSFX is limited to only one color stream defined by the COLOR0 semantic, it is still possible to define more than one color stream by using the TEXCOORDx semantic. An attribute using the TEXCOORDx semantic that is of a vec3 or vec4 type can be used to convey a color stream to the shader, and an attribute using the TEXCOORDx semantic that is of vec2 type can be used to convey a UV coordinate stream.

Continues in Part 2 of this section.