Guidelines for Writing Effects

This topic explains how to write DirectX Effects that are compatible with DigitalRune Graphics.

In general, it is not necessary to write DirectX Effects (.fx files) in a certain way. Most effects should be usable with DigitalRune Graphics. However, by using certain effect parameter names, semantics, and annotations, the engine can automate many task at runtime.

This topic contains the following sections:

Semantics

Animation
Camera
Lights
Material
Transforms
Decals
Fog
Misc
Terrain
Custom semantics

DirectX Standard Annotations and Semantics (DXSAS) 0.8
Sort hints
Hardware instancing
Restore pass

Semantics

When loading an effect, DigitalRune Graphics checks whether the effect parameter has a certain name or semantic. If it recognizes an effect parameter it will automatically create an effect parameter binding. It is not necessary to update these effect parameters explicitly at runtime. The graphics engine manages them automatically.

For example:

Copy

float4x4 w : WORLD;           // The world matrix.
float4x4 vp : VIEWPROJECTION; // The view-projection matrix.
float4x3 Bones[72];           // The skinning matrices.
texture LightBuffer0;         // The first light buffer (diffuse light).
texture LightBuffer1;         // The second light buffer (specular light).

These are examples of effect parameter, which are recognized by the graphics engine. The graphics engine checks whether the parameter name or its semantic matches the following pattern:

SEMANTICn

The graphics engine compares the first part SEMANTIC with the values listed below. (The string comparison is case-insensitive.)

The parameter names or semantic may end with an index n. The index is optional. It is only relevant when the effect parameter may be bound to multiple values. For example, consider a material shader that supports up to 4 point lights. The parameters storing the point light positions can be declared as:

Copy

float3 lightPos0 : POINTLIGHTPOSITION0;
float3 lightPos1 : POINTLIGHTPOSITION1;
float3 lightPos2 : POINTLIGHTPOSITION2;
float3 lightPos3 : POINTLIGHTPOSITION3;

Alternatively, the point light positions can be declared as:

Copy

float3 lightPos[4] : POINTLIGHTPOSITION;

In either case, the graphics engine will recognize the effect parameters and create effect parameter bindings. At runtime, whenever an object is rendered using this shader, the graphics engine will fetch the four point lights closest to the object, determine their positions and automatically set the effect parameters in the shader.

DigitalRune Graphics supports the following semantics (the semantics can also be found in the classes DefaultEffectParameterSemantics, SceneEffectParameterSemantics and TerrainEffectParameterSemantics):

Animation

Semantic	Types	Description
BONES	float4x3[]	The skinning matrices for mesh skinning.

Camera

Semantic	Types	Description
CAMERADIRECTION	float3 or float4	The camera direction in world space.
CAMERAPOSITION	float3 or float4	The camera position in world space.
LASTCAMERADIRECTION	float3 or float4	The camera direction of the last frame in world space.
LASTCAMERAPOSITION	float3 or float4	The camera position of the last frame in world space.
CAMERANEAR	float	The distance of the camera near plane.
CAMERAFAR	float	The distance of the camera far plane.
LODCAMERAPOSITION	float3	The position of the camera used as reference for LOD calculations

Lights

Semantic	Types	Description
AMBIENTLIGHT	float3 or float4	The intensity of an ambient light.
AMBIENTLIGHTATTENUATION	float	The hemispheric attenuation factor of the ambient light. (0 = pure ambient, no hemispheric lighting; 1 = one-sided hemispheric lighting)
AMBIENTLIGHTUP	float3	The up vector of the ambient light in world space. (Required for hemispheric attenuation.)
DIRECTIONALLIGHTDIFFUSE	float3 or float4	The diffuse intensity of a directional light.
DIRECTIONALLIGHTSPECULAR	float3 or float4	The specular intensity of a directional light.
DIRECTIONALLIGHTDIRECTION	float3 or float4	The light direction in world space.
DIRECTIONALLIGHTTEXTURE	Texture2D	The texture of a directional light.
DIRECTIONALLIGHTTEXTUREOFFSET	float2	The texture offset of a directional light.
DIRECTIONALLIGHTTEXTURESCALE	float2	The texture scale of a directional light.
DIRECTIONALLIGHTTEXTUREMATRIX	float4x4	The texture matrix of a directional light which converts positions from world space to the texture space of the light.
DIRECTIONALLIGHTSHADOWMAP	Texture2D	The shadow map of a directional light.
DIRECTIONALLIGHTSHADOWPARAMETERS	*	The shadow parameters of a directional light shadow. * The supported types are struct ShadowParameters as defined in ShadowMap.fxh or or struct CascadedShadowParameters as defined in CascadedShadowMap.fxh.
ENVIRONMENTMAP	TextureCube	The cube map texture containing the environment.
ENVIRONMENTMAPSIZE	float	The side length of one cube map face of the environment map in texels.
ENVIRONMENTMAPDIFFUSE	float3 or float4	The intensity of diffuse environment map reflections.
ENVIRONMENTMAPSPECULAR	float3 or float4	The intensity of specular environment map reflections.
ENVIRONMENTMAPRGBMMAX	float	The max value (see also RgbmEncodingMax) of the RGBM encoding. If the environment map is encoded using sRGB, this value is 1.
ENVIRONMENTMAPMATRIX	float4x4	The texture matrix of the environment map which converts positions from world space to the texture space of the cube map.
POINTLIGHTDIFFUSE	float3 or float4	The diffuse intensity of a point light.
POINTLIGHTSPECULAR	float3 or float4	The specular intensity of a point light.
POINTLIGHTPOSITION	float3 or float4	The position of a point light in world space.
POINTLIGHTRANGE	float	The range of a point light.
POINTLIGHTATTENUATION	float	The attenuation exponent of a point light.
POINTLIGHTTEXTURE	TextureCube	The texture of a point light.
POINTLIGHTTEXTUREMATRIX	float3x3 or float4x4	The texture matrix of a point light which converts directions from world space to the texture space of the light.
PROJECTORLIGHTDIFFUSE	float3 or float4	The diffuse intensity of a projector light.
PROJECTORLIGHTSPECULAR	float3 or float4	The specular intensity of a projector light.
PROJECTORLIGHTPOSITION	float3 or float4	The position of a projector light in world space.
PROJECTORLIGHTDIRECTION	float3 or float4	The direction of a projector light in world space.
PROJECTORLIGHTRANGE	float	The range of a projector light.
PROJECTORLIGHTATTENUATION	float	The attenuation exponent of a projector light.
PROJECTORLIGHTTEXTURE	Texture2D	The texture that is projected by the projector light.
PROJECTORLIGHTVIEWPROJECTION	float4x4	The view-projection matrix of the projector light.
PROJECTORLIGHTTEXTUREMATRIX	float4x4	The texture matrix of a projector light which converts positions from world space to the texture space of the light.
SPOTLIGHTDIFFUSE	float3 or float4	The diffuse intensity of a spotlight.
SPOTLIGHTSPECULAR	float3 or float4	The specular intensity of a spotlight.
SPOTLIGHTPOSITION	float3 or float4	The position of a spotlight in world space.
SPOTLIGHTDIRECTION	float3 or float4	The direction of a spotlight in world space.
SPOTLIGHTRANGE	float	The range of a spotlight.
SPOTLIGHTFALLOFFANGLE	float	The falloff (umbra) angle of the spotlight in radians.
SPOTLIGHTCUTOFFANGLE	float	The cutoff (penumbra) angle of the spotlight in radians.
SPOTLIGHTATTENUATION	float	The attenuation exponent of a spotlight.
SPOTLIGHTTEXTURE	Texture2D	The texture of a spotlight.
SPOTLIGHTTEXTUREMATRIX	float4x4	The texture matrix of a spotlight which converts positions from world space to the texture space of the light.

Material

Semantic	Types	Description
DIFFUSECOLOR	float3 or float4	The diffuse material color.
DIFFUSETEXTURE	Texture2D	The diffuse (albedo) texture.
SPECULARCOLOR	float3 or float4	The specular material color.
SPECULARTEXTURE	Texture2D	The gloss texture containing the specular intensity (not specular power).
SPECULARPOWER	float or float3	The material specular color exponent as a single value or per-component.
EMISSIVECOLOR	float3 or float4	The emissive material color.
EMISSIVETEXTURE	Texture2D	The emissive texture.
OPACITY	float	The opacity (alpha).
ALPHA	float	The opacity (alpha).
BLENDMODE	float	The blend mode: 0 = additive blending, 1 = normal alpha-blending. (Other values than 0 and 1 are allowed to create mixed blend modes.)
REFERENCEALPHA	float	The reference value used for alpha testing.
NORMALTEXTURE	Texture2D	The normal texture.
FRESNELPOWER	float	The power of the Fresnel term.
INSTANCECOLOR	float3	The instance color as RGB.
INSTANCEALPHA	float	The instance opacity (alpha).

Transforms

Semantic	Types	Description
POSITION	float3 or float4	The position of the object in world space.
WORLD	float4x4	The world matrix.
WORLDINVERSE	float4x4	The inverse world matrix.
WORLDTRANSPOSE	float4x4	The transpose of the world matrix.
WORLDINVERSETRANSPOSE	float4x4	The transpose of the inverse world matrix.
VIEW	float4x4	The view matrix.
VIEWINVERSE	float4x4	The inverse view matrix.
VIEWTRANSPOSE	float4x4	The transpose of the view matrix.
VIEWINVERSETRANSPOSE	float4x4	The transpose of the inverse view matrix.
PROJECTION	float4x4	The projection matrix.
PROJECTIONINVERSE	float4x4	The inverse projection matrix.
PROJECTIONTRANSPOSE	float4x4	The transpose of the projection matrix.
PROJECTIONINVERSETRANSPOSE	float4x4	The transpose of the inverse projection matrix.
WORLDVIEW	float4x4	The world-view matrix.
WORLDVIEWINVERSE	float4x4	The inverse world-view matrix.
WORLDVIEWTRANSPOSE	float4x4	The transpose of the world-view matrix.
WORLDVIEWINVERSETRANSPOSE	float4x4	The transpose of the inverse world-view matrix.
VIEWPROJECTION	float4x4	The view-projection matrix.
VIEWPROJECTIONINVERSE	float4x4	The inverse view-projection matrix.
VIEWPROJECTIONTRANSPOSE	float4x4	The transpose of the view-projection matrix.
VIEWPROJECTIONINVERSETRANSPOSE	float4x4	The transpose of the inverse view-projection matrix.
WORLDVIEWPROJECTION	float4x4	The world-view-projection matrix.
WORLDVIEWPROJECTIONINVERSE	float4x4	The inverse world-view-projection matrix.
WORLDVIEWPROJECTIONTRANSPOSE	float4x4	The transpose of the world-view-projection matrix.
WORLDVIEWPROJECTIONINVERSETRANSPOSE	float4x4	The transpose of the inverse world-view-projection matrix.
LASTPOSITION	float3 or float4	The position of the object in world space of the last frame.
LASTWORLD	float4x4	The world matrix of the last frame.
LASTWORLDINVERSE	float4x4	The inverse world matrix of the last frame.
LASTWORLDTRANSPOSE	float4x4	The transpose of the world matrix of the last frame.
LASTWORLDINVERSETRANSPOSE	float4x4	The transpose of the inverse world matrix of the last frame.
LASTVIEW	float4x4	The view matrix of the last frame.
LASTVIEWINVERSE	float4x4	The inverse view matrix of the last frame.
LASTVIEWTRANSPOSE	float4x4	The transpose of the view matrix of the last frame.
LASTVIEWINVERSETRANSPOSE	float4x4	The transpose of the inverse view matrix of the last frame.
LASTPROJECTION	float4x4	The projection matrix of the last frame.
LASTPROJECTIONINVERSE	float4x4	The inverse projection matrix of the last frame.
LASTPROJECTIONTRANSPOSE	float4x4	The transpose of the projection matrix of the last frame.
LASTPROJECTIONINVERSETRANSPOSE	float4x4	The transpose of the inverse projection matrix of the last frame.
LASTWORLDVIEW	float4x4	The world-view matrix of the last frame.
LASTWORLDVIEWINVERSE	float4x4	The inverse world-view matrix of the last frame.
LASTWORLDVIEWTRANSPOSE	float4x4	The transpose of the world-view matrix of the last frame.
LASTWORLDVIEWINVERSETRANSPOSE	float4x4	The transpose of the inverse world-view matrix of the last frame.
LASTVIEWPROJECTION	float4x4	The view-projection matrix of the last frame.
LASTVIEWPROJECTIONINVERSE	float4x4	The inverse view-projection matrix of the last frame.
LASTVIEWPROJECTIONTRANSPOSE	float4x4	The transpose of the view-projection matrix of the last frame.
LASTVIEWPROJECTIONINVERSETRANSPOSE	float4x4	The transpose of the inverse view-projection matrix of the last frame.
LASTWORLDVIEWPROJECTION	float4x4	The world-view-projection matrix of the last frame.
LASTWORLDVIEWPROJECTIONINVERSE	float4x4	The inverse world-view-projection matrix of the last frame.
LASTWORLDVIEWPROJECTIONTRANSPOSE	float4x4	The transpose of the world-view-projection matrix of the last frame.
LASTWORLDVIEWPROJECTIONINVERSETRANSPOSE	float4x4	The transpose of the inverse world-view-projection matrix of the last frame.
UNSCALEDWORLD	float4x4	Same as WORLD, except that the matrix does not contain any scale factors.
UNSCALEDWORLDVIEW	float4x4	Same as WORLDVIEW, except that the matrix does not contain any scale factors.

Decals

Semantic	Types	Description
DECALALPHA	float	The opacity of the decal.
DECALNORMALTHRESHOLD	float	The normal threshold of the decal.
DECALOPTIONS	-	The decal options.
DECALORIENTATION	float3	The z-axis of the decal in world space.

Fog

Semantic	Types	Description
FOGCOLOR	float4	The fog color.
FOGSTART	float	The start distance of the fog.
FOGEND	float	The end distance of the fog.
FOGDENSITY	float	The density of the fog.
FOGPARAMETERS	float4	The combined parameters of the fog; a 4-dimensional vector containing: (start distance, end distance or 1 / density, fog curve exponent, height falloff).

Misc

Semantic	Types	Description
DEBUG	float4	A 4-element vector with user-defined data for debugging. The values are set using Debug0 and Debug1.
ELAPSEDTIME	float	The time since the previous frame in seconds.
GBUFFER	Texture2D	The G-buffer.
DITHERMAP	Texture2D	An 8-bit texture (alpha only) with 16x16 dither values.
JITTERMAP	Texture2D	A quadratic RGBA texture (8 bit per channel) with random values.
JITTERMAPSIZE	float or float2	The width of the quadratic JITTERMAP in texels.
LIGHTBUFFER	Texture2D	The light buffer.
NAN	float	A float value containing NaN.
NOISEMAP	Texture2D	A quadratic, tileable RGBA texture (8 bit per channel) with smooth noise values.
NORMALSFITTINGTEXTURE	Texture2D	The normals fitting texture for encoding "best fit" normals.
PASSINDEX	int	The zero-based index of the current effect pass.
SOURCETEXTURE	Texture2D	The source texture, which is usually the last backbuffer or the result of a previous post-processor.
VIEWPORTSIZE	float2	The viewport width and height in pixels.

Terrain

The class TerrainEffectParameterSemantics defines additional semantics supported by the terrain rendering system.

Custom semantics

See How To: Add Support for New Effect Parameters

DirectX Standard Annotations and Semantics (DXSAS) 0.8

DigitalRune Graphics partially supports the DirectX Standard Annotations and Semantics (DXSAS) version 0.8.

The following DXSAS 0.8 semantics are supported:

AMBIENT, CAMERAPOSITION, DIFFUSE, DIFFUSEMAP, DIRECTION, ELAPSEDTIME, EMISSIVE, ENVIRONMENT, ENVMAP, FALLOFFANGLE, LIGHTPOSITION, NORMAL, OPACITY, POSITION, PROJECTION, PROJECTIONINVERSE, PROJECTIONTRANSPOSE, PROJECTIONINVERSETRANSPOSE, SPECULAR, SPECULARMAP, SPECULARPOWER, VIEW, VIEWINVERSE, VIEWINVERSETRANSPOSE, VIEWPORTPIXELSIZE, VIEWPROJECTION, VIEWPROJECTIONINVERSE, VIEWPROJECTIONTRANSPOSE, VIEWPROJECTIONINVERSETRANSPOSE, VIEWTRANSPOSE, WORLD, WORLDINVERSE, WORLDINVERSETRANSPOSE, WORLDTRANSPOSE, WORLDVIEW, WORLDVIEWINVERSE, WORLDVIEWINVERSETRANSPOSE, WORLDVIEWTRANSPOSE, WORLDVIEWPROJECTION, WORLDVIEWPROJECTIONINVERSE, WORLDVIEWPROJECTIONINVERSETRANSPOSE, WORLDVIEWPROJECTIONTRANSPOSE

The following DXSAS 0.8 semantics are not (yet) supported:

ATTENUATION, BOUNDINGCENTER, BOUNDINGBOXMAX, BOUNDINGBOXMIN, BOUNDINGBOXSIZE, BOUNDINGSPHEREMAX, BOUNDINGSPHEREMIN, BOUNDINGSPHERESIZE, CONSTANTATTENUATION, ENVIRONMENTNORMAL, FALLOFFEXPONENT, HEIGHT, JOINT, JOINTWORLD, JOINTWORLDINVERSE, JOINTWORLDINVERSETRANSPOSE, JOINTWORLDTRANSPOSE, JOINTWORLDVIEW, JOINTWORLDVIEWINVERSE, JOINTWORLDVIEWINVERSETRANSPOSE, JOINTWORLDVIEWTRANSPOSE, LASTTIME, LINEARATTENUATION, QUADRATICATTENUATION, RANDOM, REFRACTION, TEXTUREMATRIX, TIME

Sort hints

A sort hint (see enum EffectParameterHint) is a value that indicates when an effect parameter should be updated and how it should be treated during state sorting.

The supported sort hints are:

Hint	Description
Global	Global effect parameters are identical for all meshes that use the same effect and effect technique. They do not depend on the object that is being rendered or on the location of the object in the scene. Examples of global parameters are: view matrix, projection matrix, camera position, etc.
Material	This effect parameter defines the material of a mesh. Multiple meshes can share the same material. Material parameters are independent of the location of the object in the scene. Examples of material parameters are: diffuse color, albedo texture, specular color, gloss texture, normal map, etc.
Local	This effect parameter depends on the location of the mesh in the scene. Multiple meshes which are close to each other in the scene may share the same parameter values. Examples of local parameters are: local environment maps, local lights, etc.
PerInstance	This effect parameter can be different for each mesh instance. Examples of instance parameters are: world matrix, skinning matrices.
PerPass	This effect parameter can be different in each effect pass. Examples of per-pass parameters are: pass index.

The engine automatically sets an appropriate sort hint, if it recognizes an effect parameter name or semantic. But the sort hints can also be set or overridden in the DirectX Effect file using annotations. Examples:

Copy

// The following parameter is a global parameter that stores the simulation time. 
// It only needs to be updated once per frame.
float time
<
  string Hint = "Global";
>;

// The following parameter is used in a fur effect. The fur density is a material 
// property. All mesh instances with the same material share the same value.
float furDensity
<
  string Hint = "Material";
>;

// The following parameter is used in a material shader that paints each mesh 
// instance with a different color.
float4 uniqueColor
<
  string Hint = "PerInstance";
>;

By default, if the graphics engine does not recognize an effect parameter, it assigns the sort hint Material.

Hardware instancing

DigitalRune Graphics supports hardware instancing. The DirectX Effect used for rendering the objects needs to include two effect techniques:

The effect technique for rendering without instancing, and
the effect technique for hardware instancing.

DigitalRune Graphics uses a naming scheme to identify the instancing technique. The instancing technique needs to have the same name as the default technique plus the postfix "Instancing". Example:

Naming scheme to identify hardware instancing technique (MonoGame, XNA)

Copy

// Technique without hardware instancing
technique MyTechnique
{
  pass
  {
    VertexShader = compile vs_2_0 VS();
    PixelShader = compile ps_2_0 PS();
  }
}

// Equivalent of MyTechnique that supports hardware instancing.
technique MyTechniqueInstancing
{
  pass
  {
    VertexShader = compile vs_3_0 HardwareInstancingVS();
    PixelShader = compile ps_3_0 PS();
  }
}

You may also designate the instancing technique by adding the effect annotation InstancingTechnique to the default technique.

Caution
MonoGame currently does not support effect annotations. Therefore, this only works in XNA.

Effect annotation to identify hardware instancing techniqe (XNA only!)

Copy

// Default technique without hardware instancing
technique MyTechnique
<
  // There is an equivalent of this technique that supports hardware instancing.
  string InstancingTechnique = "HardwareInstancing"; 
>
{
  pass
  {
    VertexShader = compile vs_2_0 VS();
    PixelShader = compile ps_2_0 PS();
  }
}

// Hardware instancing technique.
technique HardwareInstancing
{
  pass
  {
    VertexShader = compile vs_3_0 HardwareInstancingVS();
    PixelShader = compile ps_3_0 PS();
  }
}

At runtime, you can query whether an effect technique has a matching instancing technique by checking the property InstancingTechnique.

Restore pass

Effect techniques can have a restore pass. The purpose of this pass is to reset render pipeline states to default values - without rendering geometry.

The restore pass needs to be the last effect pass of a technique and it needs to be named Restore.

Copy

technique
{
  pass
  {
    ZEnable = false;
    VertexShader = compile vs_2_0 VS();
    PixelShader = compile ps_2_0 PS();
  }
  pass Restore
  {
    ZEnable = true;
  }
}