`textureSample()`

Function in Builtins

Sample a 2D texture, returning vec4<f32>.

import { textureSample } from 'typeshade'

The signature, the description and the examples come from the compiler's own source at commit 26de7be8.

Syntax

function textureSample(
  tex: ReadonlyNode<'texture_2d<f32>'>,
  smp: ReadonlyNode<'sampler'>,
  uv: ReadonlyNode<'vec2<f32>'>,
): Node<'vec4<f32>'>;
function textureSample(
  tex: ReadonlyNode<'texture_2d_array<f32>'>,
  smp: ReadonlyNode<'sampler'>,
  uv: ReadonlyNode<'vec2<f32>'>,
  layer: ReadonlyNode<'i32' | 'u32'> | number,
): Node<'vec4<f32>'>;

Parameters

tex ReadonlyNode<'texture_2d<f32>'>: the sampled texture binding, resource(name, texture2dfT, at).node.
smp ReadonlyNode<'sampler'>: the sampler binding to filter with.
uv ReadonlyNode<'vec2<f32>'>: normalised texture coordinates.
layer: which layer to read, required for an array texture and rejected otherwise.

Return value

Node<'vec4<f32>'>

the filtered texel.

Exceptions

SD0109: That makes this call fragment-only, and the fragment-only-builtin lint rule, a core rule that fires at every emit, reports SD0109 when it appears in a vertex or compute stage. textureSampleLevel takes the level as an argument and is legal in every stage, so it is the form a vertex or compute shader reaches for.

Description

The level of detail is implicit: it comes from screen-space derivatives, which exist only in a fragment invocation. That makes this call fragment-only, and the fragment-only-builtin lint rule, a core rule that fires at every emit, reports SD0109 when it appears in a vertex or compute stage. textureSampleLevel takes the level as an argument and is legal in every stage, so it is the form a vertex or compute shader reaches for.

A 2D array texture uses the same name, and the first argument’s key picks the overload: a texture_2d_array<f32> requires the layer argument, and omitting it is a tsc error. A number layer lifts to an i32 literal. The targets spell the layer differently and the DSL absorbs that: WGSL takes it as its own argument, textureSample(t, s, uv, layer), while GLSL ES 3.00 folds it into the coordinate, texture(t, vec3(uv, float(layer))). Both spellings are core, so an array texture needs no capability on either target.

Integer texture keys (texture_2d<u32>, texture_2d<i32> and their array twins) are rejected at tsc, deliberately. Filtering is a weighted average, and interpolating integer texels has no meaning, so WGSL has no textureSample for them at all. GLSL’s texture(usampler2D, …) would compile, and accepting it would mint a construct that runs on WebGL2 and cannot be expressed on WebGPU. The surface both targets share for an integer texture is textureLoad, textureDimensions and textureNumLayers.

The CPU evaluation (compileModule) has no way to read a texture and returns a placeholder under its gpuStubs option.

Examples

Example

import { fn, resource, textureSample, texture2dfT, samplerT, vec2fT, vec4fT } from 'typeshade'

const tex = resource('tex', texture2dfT, { group: 0, binding: 1 })
const smp = resource('tex_sampler', samplerT, { group: 0, binding: 2 })

const fs = fn('fs_main', { uv: vec2fT }, vec4fT, ({ uv }) => textureSample(tex.node, smp.node, uv), {
  stage: 'fragment',
})

Targets

Target	Support	Notes
WGSL (WebGPU)	Supported	`textureSample(tex, smp, uv)`.
GLSL ES 3.00 (WebGL2)	Supported	`texture(tex, uv)`.
CPU oracle	Stub	The oracle has no texture memory and no neighbouring fragments. The call throws unless the module was compiled with `{ gpuStubs: true }`, which returns a placeholder.

In the guide

Source

src/core/ir/node.ts, line 2049, at commit 26de7be8

Edit this page Report a problem

textureSample()