Sample(S,float,int,float) function (HLSL reference)
Samples a Texture2D with an optional value to clamp sample level-of-detail (LOD) values to.
Note
Requires shader model 5 or higher.
Syntax
DXGI_FORMAT Sample(
in SamplerState S,
in float Location,
in int Offset,
in float Clamp
);
Parameters
-
S [in]
-
A Sampler state. This is an object declared in an effect file that contains state assignments.
-
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, Texture3D, TextureCube float3 TextureCubeArray float4 -
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 Texture3D int3 TextureCube, TextureCubeArray not supported -
Clamp [in]
-
An optional value to clamp sample LOD values to. For example, if you pass 2.0f for the clamp value, you ensure that no individual sample accesses a mip level less than 2.0f.
Return value
The texture format, which is one of the typed values listed in DXGI_FORMAT.
Remarks
Texture sampling uses the texel position to look up a texel value. An offset can be applied to the position before lookup. The sampler state contains the sampling and filtering options. This method can be invoked within a pixel shader, but it is not supported in a vertex shader or a geometry shader.
Use an offset only at an integer miplevel; otherwise, you may get different results depending on hardware implementation or driver settings.
Calculating Texel Positions
Texture coordinates are floating-point values that reference texture data, which is also known as normalized texture space. Address wrapping modes are applied in this order (texture coordinates + offsets + wrap mode) to modify texture coordinates outside the [0...1] range.
For texture arrays, an additional value in the location parameter specifies an index into a texture array. This index is treated as a scaled float value (instead of the normalized space for standard texture coordinates). The conversion to an integer index is done in the following order (float + round-to-nearest-even integer + clamp to the array range).
Applying Texture Coordinate Offsets
The offset parameter modifies the texture coordinates, in texel space. Even though texture coordinates are normalized floating-point numbers, the offset applies an integer offset. Also note that the texture offsets need to be static.
The data format returned is determined by the texture format. For example, if the texture resource was defined with the DXGI_FORMAT_A8B8G8R8_UNORM_SRGB format, the sampling operation converts sampled texels from gamma 2.0 to 1.0, filter, and writes the result as a floating-point value in the range [0..1].
Use an offset only at an integer miplevel; otherwise, you may get results that do not translate well to hardware.
See also