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

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.

Hardware fog specific semantics

Note: Currently not supported for the glslShader plug-in.
Name Type Description
HardwareFogEnabled bool Specifies whether hardware fog is enabled.
HardwareFogMode int Specifies whether the fog type is Linear, Exponential or Exponential squared.
HardwareFogStart float Specifies the near distance used in the linear fog.
HardwareFogEnd float Specifies the far distance used in the linear fog.
HardwareFogDensity float Specifies the density of the exponential fog.
HardwareFogColor float4 (dx11Shader)

vec4 (glslShader)

Specifies the fog color in RGBA values.

Selection semantics

Name Type Description

HWS_PrimitiveBase

int

Integer used to generate the color of the object, or the first component, or the first geometry instance. (GPU Instancing must be enabled in the Viewport 2.0 options window.)

Corresponds to: MUniformParameter::kSemanticHWSPrimitiveBase.

HWS_PrimitiveCountPerInstance

int Specifies the amount that HWS_PrimitiveBase needs to be incremented for each geometry instance.

Corresponds to: MUniformParameter::kSemanticHWSPrimitiveCountPerInstance.

HWS_ObjectLevel

bool Specifies whether selection is to be done at the object level.

Corresponds to: MUniformParameter::kSemanticHWSObjectLevel.

HWS_FaceLevel

bool Specifies whether selection is to be done at the face level.

Corresponds to: MUniformParameter::kSemanticHWSFaceLevel.

HWS_EdgeLevel

bool Specifies whether selection is to be done at the edge level.

Corresponds to: MUniformParameter::kSemanticHWSEdgeLevel.

HWS_VertexLevel

bool Specifies whether selection is to be done at the vertex level.

Corresponds to: MUniformParameter::kSemanticHWSVertexLevel.

HWS_FrontCCW

bool Specifies whether a counter clockwise triangle is front facing. Useful when generating fat points or lines.

Corresponds to: MUniformParameter::kSemanticHWSFrontCCW.

HWS_InstancedDraw

bool Specifies whether geometry instances are being drawn.

Corresponds to: MUniformParameter::kSemanticHWSInstancedDraw.

Supported technique annotations

Name Type Description
index_buffer_type string

Allows specifying of custom primitive types via index buffer generator and mutator plug-ins. Usually used for tessellation, in order to provide the shader with an index buffer that contains extra data.

The dx11Shader/glslShader project contains a mutator that can generate Point-Normal Triangles using Adjacent Edge Normals (PN-AEN) index buffers. See Customizing Geometric Data for Shaders in the Maya Developer Help.

For dx11Shader / glslShader, use these values:

no-value : default index buffer (default)

"PNAEN9” / "GLSL_PNAEN9" : triangle and adjacent edges

“PNAEN18” / "GLSL_PNAEN18": triangle, adjacent edges, dominant edges, and dominant vertices

Any other value is acceptable as long as it matches the registered name of an index mutator.

Corresponds to MHWRender::MPxPrimitiveGenerator.

texture_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 technique definition to specify the mip map levels that should be generated when loading textures while using this technique. 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:

technique11 T0
< 
    bool overridesDrawState = false;
    int isTransparent = 0;
    int texture_mipmaplevels = <val>;
>

Can be combined with the parameter annotation mipmaplevels, in which case the latter takes precedence. See Texture specific parameter annotations.

isTransparent

(dx11Shader)

int Specifies the opacity of the effect, allowing Maya to use proper passes and culling. Supported values are:

0: Technique is always opaque

1: Technique is always transparent

2: Opacity of the technique is tied to the float parameter that uses the "Opacity" semantic, and is transparent if the opacity value is lower than 1.0.

Transparency

(glslShader)

string

Specifies if this technique should be rendered in semi-transparency mode.

"Opaque" : no transparency (default)

"Transparent" : transparency is enabled.

Corresponds to MPxShaderOverride::isTransparent().

SupportsAdvancedTransparency string (bool)

Specifies if this technique supports advanced transparency algorithms (such as depth peeling).

If true, the technique must define passes for draw context "transparentPeel", "transparentPeelAndAvg" and "transparentWeightedAvg".

"false" : no advanced transparency support (default value)

"true" : supports advanced transparency

Corresponds to: MPxShaderOverride::supportsAdvancedTransparency() .

OverridesDrawState string (bool)

Specifies if this technique should follow Maya's transparent object rendering or is self-managed (multi-passes).

"false" : does not override state (default value)

"true" : self-managed

Corresponds to: MPxShaderOverride::overridesDrawState().

OverridesNonMaterialItems

string (bool)

Specifies if this technique should be used to render non-material items such as the wireframe and the selected edges/vertices components.

This is particularly useful for shading effects that compute displacement for which the object geometry will not match the rendered material, making selection difficult.

"false" : does not override non-material items (default)

"true" : used to render non-material items, so that the shader can display UI primitives

See DrawContext in Supported pass annotations.

Corresponds to: MPxShaderOverride::overridesNonMaterialItems() .

ExtraScale float

Specifies if this technique requires an extra scale factor to be applied to the object space bounding box.

This allows the technique to indicate that the bounding box should be bigger than the base geometry; normally due to effects such as displacement, and to prevent the geometry from being discarded when moved to the edge of the viewport or during selection.

Default value is 1.0.

Corresponds to: MPxShaderOverride::boundingBoxExtraScale().

VariableNameAsAttributeName string (bool)

Tells Maya to use the uniform variable name as the Maya attribute name (instead of the UIName, when present).

"false" : use UIName as attribute name (default)

"true" : use variable name as attribute name

Can be used to maintain backward compatibility with a saved Maya scene, when the UI names defined in the shader file have been modified.

handlesConsolidatedGeometry

string (bool)

When set to False, specifies that the Consolidate World feature should be disabled on the geometry to which the glslShader is applied.

This annotation is useful when your technique draws displacement, the calculations of which involve the object-space co-ordinates of an object, such as use of the World transformation matrix. Consolidate World moves vertices of multiple objects into a new shared object-space, and maybe therefore cause your plug-in shader to render incorrectly. In this case, you may want to disable Consolidate World.

Supported pass annotations

The effect can request that some of the passes in the technique be activated in a specialized context, such as when drawing depth maps for shadows. This is done by adding a string annotation named "DrawContext", specifying the context in which the pass can be activated.

Name Type Description
DrawContext string

Specifies that this pass should be enabled only for this draw context.

Multiple passes can have the same DrawContext value.

This can be any string value that matches a pass semantic in MHWRender::MPassContext. For example, the following contexts are supported: "colorPass", "shadowPass", "depthPass", and "normalDepthPass".

An empty value (or if DrawContext is not set) is equivalent to setting this annotation to "colorPass".

Set to "nonMaterialItemsPass" for passes used to render non-material items. Set to “selectionPass” for passes used to select non-material items See OverridesNonMaterialItems in Supported technique annotations above.

PrimitiveFilter

string

Specifies that this pass can handle the rendering of the following components:

  • line as fat line (line size > 1)

  • point as fat point (point size > 1)

Can be used to handle edge or vertex components during the rendering pass or the selection pass.

Vertex components are rendered as quads instead of single pixels, and edge components, mostly during pre-selection highlighting, are rendered larger, for better visibility.

This is usually achieved by using a geometry shader to convert lines and points to quads.

"fatLine" : this pass can render lines as quads

"fatPoint" : this pass can render points as quads

If there is no pass defined that handles this special case, the default pass that handles the draw context "nonMaterialItemsPass" or "selectionPass" is used.

Global semantic

Name Type Description
MayaSwatchRender bool

Identifies when the current rendering process is used to draw the swatch.

Allows the user to handle a specific path when drawing the swatch.