Using Standard Semantics and Standard Annotations
Microsoft DirectX 9.0 SDK Update (October 2004)

Using Standard Semantics and Standard Annotations


Standardized semantics and annotations make it possible for an application to understand the intention behind an effect parameter. This is because semantics and annotations specify additional usage information about a parameter. Parameters that an effect author doesn't need (or want) an application to understand do not need to attach semantics or annotations (because they are optional). The example below will help illustrate cases where it is highly desirable to use standardized usage information.

Parameters that are meant to be shared between the effect and the application must somehow indicate their usage to the application. For instance, almost all effects require the current transformation matrices for use in the vertex shader. Unless the application was specifically written to work with a particular effect file, there's no way for the application to know the names of the parameters which hold the transformation matrices (or whether those parameters even exist).

Instead of creating naming guidelines for parameters, Microsoft has created a set of optional standard semantics and annotations which can be attached to effect parameters. Any effect which implements these standard semantics and annotations can be read by an application.

Attaching a Standard Semantic

For instance, an effect parameter which the application is expected to fill with the current world transformation matrix could use a semantic like this:

float4x4 MyWorldMatrix : World;

The world semantic is a standard semantic which has been defined as a 4x4 floating-point matrix which contains the world transformation (see Standard Semantics Reference). Attaching this standard semantic to an effect parameter makes it possible for an application to understand the intent of this effect parameter.

Attaching a Standard Annotation

Some parameters require additional information to specify the parameter usage. For instance, this parameter uses the diffuse semantic which identifies it as a diffuse color. But what is this the diffuse color of? The annotation can identify the usage as shown here:

float4 MyLightDiffuseColor : Diffuse
<
    string Object = "Light";
>;

An annotation is attached to a parameter inside of a pair of angle brackets. This annotation has a single string which identifies the parameter usage as a light. This means that the diffuse color parameter is the diffuse color of a light (whose index is 0 because the index is not specified). This annotation used a single string, but annotations can use several strings to identify different types of information.

For instance, here's an example of a parameter that is connected to a user interface (UI) control:

float4 MyTweakableLightDiffuseColor : Diffuse
<
    string Object = "Light";

    string UIWidget = "Color";
    float4 UIMin = float4(0.2, 0.2, 0.2, 1.0);
    float4 UIMax = float4(1.0, 1.0, 1.0, 1.0);
    string UIName = "The diffuse color of the light";
>;

This example has several annotations. They are attached to a diffuse light color, which is intended to be interactively adjusted by a user. The annotations define the following:

This example highlights the use of semantics and annotations to identify the parameters necessary for an application to connect this parameter to a UI control. This means that any effect that chooses to implement standard annotations and semantics can now be read by an application that knows how to interpret them. This means that shader development and application development can take advantage of each other even if both are written at different times by different authors.



© 2004 Microsoft Corporation. All rights reserved.
Feedback? Please provide us with your comments on this topic.
For more help, visit the DirectX Developer Center.