sample

Live Demo

The sample function reads a texture at specified coordinates using the texture's configured filtering and wrapping modes.

Signature

bwsl

sample :: (texture2D tex, sampler samp, float2 uv) -> float4 {...}
sample :: (texture2D tex, sampler samp, float2 uv, int2 offset) -> float4 {...}
sample :: (textureCube tex, sampler samp, float3 dir) -> float4 {...}

Parameters

Parameter	Type	Description
`tex`	`texture*`	The texture to sample
`samp`	`sampler`	Sampler state
`uv`	`float2`	Texture coordinates [0, 1]
`dir`	`float3`	Direction for cubemap sampling
`offset`	`int2`	Optional texel offset

Return Value

Returns the filtered texel value as a float4.

Example

bwsl

pipeline TexturedMaterial {
  resources {
    albedoTex: texture2D
    normalTex: texture2D
    linearSampler: sampler
  }

  pass "Main" {
    use resources { albedoTex, normalTex, linearSampler }

    fragment {
      // Sample textures at interpolated UV coordinates
      float4 albedo = sample(resources.albedoTex, resources.linearSampler, input.uv);
      float4 normalMap = sample(resources.normalTex, resources.linearSampler, input.uv);

      // Unpack normal from [0,1] to [-1,1]
      float3 normal = normalMap.xyz * 2.0 - 1.0;

      output.color = albedo;
    }
  }
}

Common Use Cases

Basic Texture Mapping

bwsl

// Sample diffuse texture
float4 diffuse = sample(resources.diffuseTex, resources.linearSampler, input.uv);

Cubemap Environment

bwsl

// Sample environment map with reflection vector
float3 reflectDir = reflect(-viewDir, normal);
float4 envColor = sample(resources.envCubemap, resources.linearSampler, reflectDir);

Tiled Textures

bwsl

// Sample tiled texture
float4 color = sample(resources.tileTex, resources.linearSampler, input.uv * tileCount);

With Offset

bwsl

// Sample with texel offset for blur/edge detection
float4 center = sample(resources.tex, resources.linearSampler, uv);
float4 right = sample(resources.tex, resources.linearSampler, uv, int2(1, 0));
float4 up = sample(resources.tex, resources.linearSampler, uv, int2(0, 1));

Multi-Texture Blending

bwsl

// Blend between textures
float4 tex1 = sample(resources.texture1, resources.linearSampler, uv);
float4 tex2 = sample(resources.texture2, resources.linearSampler, uv);
float4 blended = lerp(tex1, tex2, blendFactor);

Automatic LOD

In fragment shaders, sample automatically selects the appropriate mip level based on screen-space derivatives. For explicit LOD control, use sample_lod.

Vertex/Compute Shaders

The basic sample function is typically only available in fragment shaders. Use sample_lod with an explicit LOD for vertex or compute shaders.

Compiled Output

When compiled to GLSL:

glsl

texture(tex, uv)

When compiled to HLSL:

hlsl

tex.Sample(samplerState, uv)

When compiled to Metal:

metal

tex.sample(sampler, uv)

Test sample in a live shader

Live Demo

Signature

Parameters

Return Value

Example

Common Use Cases

Basic Texture Mapping

Cubemap Environment

Tiled Textures

With Offset

Multi-Texture Blending

Compiled Output

See Also