Sample (DirectX HLSL Texture Object)
Samples a texture.
| DXGI_FORMAT Object.Sample( sampler_state S, float Location [, int Offset] ); |
Parameters
| Item | Description |
|---|---|
|
Any texture-object type (except Texture2DMS and Texture2DMSArray). | |
|
[in] A Sampler state. This is an object declared in an effect file that contains state assignments. | |
|
[in] The texture coordinates. The argument type is dependent on the texture-object type. Texture-Object TypeParameter Type Texture1Dfloat Texture1DArray, Texture2Dfloat2 Texture2DArray, Texture3D, TextureCubefloat3 TextureCubeArray¹float4
| |
|
[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, TextureCubeArray¹not 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_0 | vs_4_1² | ps_4_0 | ps_4_1² | gs_4_0 | gs_4_1² |
|---|---|---|---|---|---|
| x | x |
- TextureCubeArray is available in Shader Model 4.1 or higher.
- 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