Sample (DirectX HLSL Texture Object)

Samples a texture.

DXGI_FORMAT Object.Sample(

sampler_state S,

float Location

[, int Offset]

);

 

Parameters

ItemDescription

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 TypeParameter Type
Texture1Dfloat
Texture1DArray, Texture2Dfloat2
Texture2DArray, Texture3D, TextureCubefloat3
TextureCubeArray1float4

 

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. Use an offset only at an integer miplevel; otherwise, you may get results that do not translate well to hardware. The argument type is dependent on the texture-object type. For more info, see Applying Integer Offsets.

Texture-Object TypeParameter Type
Texture1D, Texture1DArrayint
Texture2D, Texture2DArrayint2
Texture3Dint3
TextureCube, TextureCubeArray1not supported

 

 

Return Value

The texture format, which is one of the typed values listed in DXGI_FORMAT.

Minimum Shader Model

This function is supported in the following shader models.

vs_4_0vs_4_12ps_4_0ps_4_12gs_4_0gs_4_12
xx

 

  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 from the BasicHLSL10.fx file in the BasicHLSL10 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.

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.

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

 

 

Community Additions

ADD
Show:
© 2014 Microsoft