Edit

Share via

SampleCmp (DirectX HLSL Texture Object)

  • Article

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 isn't 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
Texture2DArray¹, TextureCube float3
TextureCubeArray¹ 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 type; the offset is applied to the location before sampling. The texture offsets need to be static. The argument type is dependent on the texture-object type. For more info, see Applying texture coordinate offsets.

Texture-Object Type Parameter Type
Texture1D, Texture1DArray int
Texture2D, Texture2DArray¹ int2
TextureCube, TextureCubeArray¹ Not supported

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.

Use an offset only at an integer miplevel; otherwise, you may get different results depending on hardware implementation or driver settings.

Minimum Shader Model

This function is supported in the following shader models.

vs_4_0 vs_4_1² ps_4_0 ps_4_1² gs_4_0 gs_4_1²
x¹ x
  1. Texture2DArray and TextureCubeArray are available in Shader Model 4.1 or higher.
  2. 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.

Texture-Object