This topic has not yet been rated - Rate this topic

SampleCmp (DirectX HLSL Texture Object)

Samples a texture and compares a single component against the specified comparison value.

float Object.SampleCmp(

SamplerComparisonState S,

float Location,

float CompareValue,

[int Offset]

);

The comparison is a single component comparison between the first component stored in the texture, and the comparison value passed into the method.

This method can be invoked only from a pixel shader; it is not supported in a vertex or geometry shader.

Parameters

Object

Any texture-object type (except Texture2DMS, Texture2DMSArray, or Texture3D).

S

[in] A sampler-comparison state, which is the sampler state plus a comparison state (a comparison function and a comparison filter). See the sampler type for details and an example.

Location

[in] The texture coordinates. The argument type is dependent on the texture-object type.

Texture-Object Type	Parameter Type
Texture1D	float
Texture1DArray, Texture2D	float2
Texture2DArray1, TextureCube	float3
TextureCubeArray1	float4

CompareValue

A floating-point value to use as a comparison value.

Offset

[in] An optional texture coordinate offset, which can be used for any texture-object types. The offset is applied to the location before sampling. The argument type is dependent on the texture-object type. For more info, see Applying Integer Offsets.

Texture-Object Type	Parameter Type
Texture1D, Texture1DArray	int
Texture2D, Texture2DArray1	int2
TextureCube, TextureCubeArray1	int3

Return Value

Returns a floating point value in the range [0..1].

For each texel fetched (based on the sampler configuration of the filter mode), SampleCmp performs a comparison of the z value (3rd component of input) from the shader against the texel value (1 if the comparison passes; otherwise 0). SampleCmp then blends these 0 and 1 results for each texel together as in normal texture filtering (not an average) and returns the resulting [0..1] value to the shader.

Remarks

Comparison filtering provides a basic filtering operation that is useful for percentage-closer-depth filtering.

When using this method on a floating-point resource (Instead of a signed-normalized or unsigned-normalized format), the comparison value is not automatically clamped between 0.0 and 1.0. Therefore, a manual clamp of the comparison value may be necessary for common shadowing techniques.

Minimum Shader Model

This function is supported in the following shader models.

vs_4_0	vs_4_12	ps_4_0	ps_4_12	gs_4_0	gs_4_12
		x1	x

Texture2DArray and TextureCubeArray are available in Shader Model 4.1 or higher.
Shader Model 4.1 is available in Direct3D 10.1 or higher.

Note SampleCmp is also available in ps 4_0_level_9_1 and 4_0_level_9_3 when you use the techniques that are described in Implementing shadow buffers for Direct3D feature level 9.

Community Additions