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:
| 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.
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:
 New for Maya 2016 Extension 1 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:
New for Maya 2016 Extension 1 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
| 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
New for Maya 2016 Extension 1
| 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.
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 Note:
New for Maya 2016 Extension 1 |
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 Note: New for
Maya 2016 Extension 2
|
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".
Note:
New for Maya 2016 Extension 1 |
|
PrimitiveFilter Note:
New for Maya 2016 Extension 1 |
string |
Specifies that this pass can handle the rendering of the following components:
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. |