Sample (DirectX HLSL Texture Object)

Samples a texture.

<Template Type> Object.Sample( sampler_state S, float Location [, int Offset] );

Parameters

Item	Description
Object	Any texture-object type (except Texture2DMS and Texture2DMSArray).
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

Return value

The texture's template type, which may be a single- or multi-component vector. The format is based on the texture's DXGI_FORMAT.

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. TextureCubeArray is available in Shader Model 4.1 or higher.
2. Shader Model 4.1 is available in Direct3D 10.1 or higher.

Example

This partial code example is based on the BasicHLSL11.fx file in the BasicHLSL11 Sample.

// Object Declarations
Texture2D g_MeshTexture;            // Color texture for mesh

SamplerState MeshTextureSampler
{
    Filter = MIN_MAG_MIP_LINEAR;
    AddressU = Wrap;
    AddressV = Wrap;
};

struct VS_OUTPUT
{
    float4 Position   : SV_POSITION; // vertex position 
    float4 Diffuse    : COLOR0;      // vertex diffuse color (note that COLOR0 is clamped from 0..1)
    float2 TextureUV  : TEXCOORD0;   // vertex texture coords 
};

VS_OUTPUT In;

// Shader body calling the intrinsic function
   ...
        Output.RGBColor = g_MeshTexture.Sample(MeshTextureSampler, In.TextureUV) * In.Diffuse;

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].

Related topics

Texture-Object