Data Binding

Use SasHostParameterValue Collection to define the collection of host application values, as well as their type and members, exposed to effects. Use the SasBindAddress annotation in an effect file to associate an effect parameter with its corresponding parameter in the host application.

SasHostParameterValue Collection

The SasHostParameterValue is defined using effect file (.fx) syntax. While the syntax is very similar to the effect file syntax, some differences exist. For example, object types, such as texture2d, samplers, and strings, are not valid in actual effect files, but are valid in the SasHostParameterValue. A host application can implement SasHostParameterValue in any way so long as it conforms to the description below; the actual definition is located in the DXSAS standard effect include file ([SDK Root]/Utilities/Source/Sas/Sas.fxh).

Note that arrays in the SasHostParameterValue such as Lights or Cameras have unbounded length. This means that effects can bind to any arbitrary index in those arrays and host applications must provide meaningful defaults in the cases where no application value can be provided.

Some types and constants are required to be defined in the DXSAS standard include, as noted in the definition of the standard include. This allows effects to easily bind aggregated values from the SasHostParameterValue to structured effect parameters.

SasHostParameterValue Collection	Type	Member
Time	float	Sas.Time.Now
	float	Sas.Time.Last
	int	Sas.Time.FrameNumber
Environment Map	textureCUBE	Sas.EnvironmentMap
Camera	SasCamera	Sas.Camera
	float4x4	Sas.Camera.WorldToView
	float4x4	Sas.Camera.Projection
	float2	Sas.Camera.NearFarClipping
Light	SasAmbientLight	AmbientLight[ZeroOrMore];
	int	Sas.NumAmbientLights
	SasAmbientLight	DirectionalLight[ZeroOrMore];
	int	Sas.NumDirectionalLights
	SasAmbientLight	PointLight[ZeroOrMore];
	int	Sas.NumPointLights
	SasAmbientLight	SpotLight[ZeroOrMore];
	int	Sas.NumSpotLights
Shadow	float4x4	Sas.Shadow[ZeroOrMore].WorldToShadow
	texture2D	Sas.Shadow[ZeroOrMore].ShadowMap
Skeleton	float4x4	Sas.Skeleton.MeshToJointToWorld[OneOrMore]
	int	Sas.Skeleton.NumJoints

 

Time

The host application's virtual clock or time value. Members include:

• Sas.Time.Now - the value of the host application virtual clock at the point at which the effect will be rendered.
• Sas.Time.Last - the value of Now at the previous render.
• Sas.Time.FrameNumber - the counter value that is incremented once per rendered frame.

Effects must properly handle the fact that the values of these members can potentially wrap around during extremely long execution times. Now and Last may have very large values.

Environment Map

A cubic environment map. Host applications must provide a valid cube texture if an effect attempts to bind to Sas.EnvironmentMap.

Camera

The camera currently being rendered. Members include:

• Sas.Camera.WorldToView - the composite world-view matrix for the camera.
• Sas.Camera.Projection - the projection matrix for the camera.
• Sas.Camera.NearFarClipping - the values of the near and far clipping planes.

Light

One or more scene lights. The collection of lights is declared as an array where:

• Color - an RGB color. The default value is (0,0,0).
• Direction - the light direction. The default value is (0,0,0).
• Range - the distance from the light where the light rays have no effect on the scene. The default value is 0.
• Theta - the inner cone angle of a spotlight, measured in radians. The default value is 0.
• Phi - the outer cone angle of a spotlight, measured in radians. The default value is 0.

The number of lights must be set to the number of lights bound into the associated array. Effects can choose to ignore the number of lights and bind to any element of one of the light arrays. Therefore, host applications must provide a valid binding for elements beyond the number of lights in the array.

ZeroOrMore implies that the array may have any number of elements.

Shadow

Shadow buffers which consists of:

• WorldToShadow - an array of matrices.
• ShadowMap - a 2D texture file.

ZeroOrMore implies that the array may have any number of elements (zero means an empty array).

An effect would declare a sampler as follows:

texture2D Shadow 
<
  string SasBindAddress = "Sas.Shadow[0].ShadowMap";
>;

sampler ShadowSampler = shadow_sampler(Shadow);

Skeleton

The set of frames that compose the currently rendering object. Frame examples are bones and transforms. This includes:

• MeshToJointToWorld - an array of matrices.
• NumJoints - the number of joints in the skeleton.

OneOrMore implies that the array has at least one and may contain any number of elements.

The definition supports both rigid and skinned mesh objects using the same set of SasHostParameterValue Collection values with different interpretation.

SasBindAddress

This annotation is added to the top of an effect file to associate an effect parameter with its corresponding parameter defined in the SasHostParameterValue Collection. The annotation is declared like this:

string SasBindAddress = "SasHostParameterValue";

This example binds the effect world matrix to the MeshToJointToWorld matrix:

float4x3 World
<
  string SasBindAddress = "Sas.Skeleton.MeshToJointToWorld[0]";
>;

This annotation tells the host application that it needs to set the value of the effect world matrix using the data in the MeshToJointToWorld matrix.

The bind address annotation syntax was defined to be very similar with the syntax used by ID3DXEffect to get and set effect parameters. The only difference between the DXSAS grammar and ID3DXEffect methods is the addition of the asterisk index token. Here is another example using the asterisk index:

float3 LightColors[6]
<
  string SasBindAddress = "Sas.Light[*].Color";
>;

The asterisk index token denotes that all elements of the particular host envirnmant value array (color in this case) should be bound in the associated parameter. Multiple asterisk index tokens allow effects to bind to sub-elements of an array of structures without the need to bind the entire structure itself. This example binds the color values of the first six lights to an effect parameter.

Related topics

DirectX Standard Annotations and Semantics Reference