(sampler …)

Creates a texture sampler for controlling how textures are sampled in shaders.

Syntax

(sampler :name name
  :mag-filter linear
  :min-filter linear
  :mipmap-filter linear
  :address-mode clamp-to-edge
  :lod-min-clamp 0
  :lod-max-clamp 32
  :max-anisotropy 1
  :compare less)

Every key but :name is optional. The fence above shows values, not defaults: each omitted key takes the GPUSamplerDescriptor default, which for all three filters is nearest.

Keys

Key	Type	Required	Default	Description
:name	symbol	Yes	-	Unique sampler name
:mag-filter	symbol	No	nearest	Magnification filter
:min-filter	symbol	No	nearest	Minification filter
:mipmap-filter	symbol	No	nearest	Filter between mip levels
:address-mode	symbol	No	clamp-to-edge	Wrapping mode for all three axes
:address-mode-u	symbol	No	clamp-to-edge	Per-axis wrapping (U/S); overrides :address-mode
:address-mode-v	symbol	No	clamp-to-edge	Per-axis wrapping (V/T); overrides :address-mode
:address-mode-w	symbol	No	clamp-to-edge	Per-axis wrapping (W/R; 3D / cube)
:lod-min-clamp	number	No	0	Minimum mip level of detail
:lod-max-clamp	number	No	32	Maximum mip level of detail
:max-anisotropy	number	No	1	Anisotropy [1,16] (needs linear filters)
:compare	symbol	No	-	Comparison function (shadow maps)

Every default here is WebGPU’s own. A sampler that should smooth says so, with :mag-filter linear :min-filter linear; a raw-WebGPU sample ported line for line renders the same way it did.

:mag-filter / :min-filter

Type: symbol

Filter mode for texture magnification and minification. Both default to nearest.

Value	Description
nearest	Nearest-neighbor (pixelated), the default
linear	Bilinear interpolation (smooth)

(sampler :name pixelArt
  :mag-filter nearest
  :min-filter nearest)

(sampler :name smooth
  :mag-filter linear
  :min-filter linear)

:address-mode

Type: symbol

Texture wrapping mode: how coordinates outside [0,1] behave. Defaults to clamp-to-edge.

Value	Description
clamp-to-edge	Clamp to edge pixels, the default
repeat	Tile texture
mirror-repeat	Tile with mirroring

(sampler :name tiling
  :address-mode repeat)

(sampler :name clamped
  :address-mode clamp-to-edge)

:address-mode applies to all three axes. To wrap axes independently, use :address-mode-u (S), :address-mode-v (T), and :address-mode-w (R, for 3D and cube textures); each overrides the shorthand for its axis.

(sampler :name mixed
  :address-mode-u repeat
  :address-mode-v mirror-repeat
  :address-mode-w clamp-to-edge)

:mipmap-filter

Type: symbol (nearest | linear)

Filter applied when sampling between mip levels. Defaults to nearest, and is only observable on a mipmapped texture.

:lod-min-clamp / :lod-max-clamp

Type: number (non-negative real; defaults 0 and 32)

The mip level-of-detail window the sampler is allowed to select. Only relevant for mipmapped textures.

:max-anisotropy

Type: number (integer in [1,16]; default 1)

Maximum number of samples for anisotropic filtering. Values greater than 1 require :mag-filter, :min-filter, and :mipmap-filter to all be linear, and since all three default to nearest, all three have to be written out. The compiler reports the combination on the sampler rather than leaving WebGPU to reject it at runtime. Out-of-range values are a validation error (number_above_max).

(sampler :name aniso
  :mag-filter linear :min-filter linear :mipmap-filter linear
  :max-anisotropy 16)

:compare

Type: symbol

Comparison function for shadow map sampling. When set, the sampler returns a comparison result instead of the texel value.

Value	Description
never	Always 0
less	1 if ref < texel
equal	1 if ref == texel
less-equal	1 if ref <= texel
greater	1 if ref > texel
not-equal	1 if ref != texel
greater-equal	1 if ref >= texel
always	Always 1

(sampler :name shadowSampler
  :compare less
  :mag-filter linear
  :min-filter linear)

Examples

Basic Linear Sampler

(sampler :name linearSampler
  :mag-filter linear
  :min-filter linear)

(bind-group :name textures :layout pipeline :group 0
  (entry :binding 0 :texture diffuseMap)
  (entry :binding 1 :sampler linearSampler))

Tiling Texture Sampler

(sampler :name tilingSampler
  :mag-filter linear
  :min-filter linear
  :address-mode repeat)

Shadow Map Sampler

(sampler :name shadowCompare
  :compare less
  :mag-filter linear
  :min-filter linear)

Pixel Art Sampler

(sampler :name pixelPerfect
  :mag-filter nearest
  :min-filter nearest
  :address-mode clamp-to-edge)

Validation Rules

Rule	Error
A name is declared once, across every form kind	duplicate_cross_ref_target, or duplicate name 'x': already declared as a (sampler …) at line N
:mag-filter / :min-filter / :mipmap-filter are nearest or linear	not_member
:address-mode and the three per-axis keys are clamp-to-edge, repeat or mirror-repeat	not_member
:compare is one of the eight comparison functions	not_member
:max-anisotropy must be an integer in [1,16]	number_above_max / number_below_min
:lod-min-clamp / :lod-max-clamp must be non-negative	number_below_min
:max-anisotropy above 1 needs all three filters linear	sampler 's' sets :max-anisotropy 8 but :mag-filter is nearest

The rows with a code are schema checks; the last row is a compiler check that reads a value rather than a shape, and it reports the line the form is written on.

Every numeric key here also accepts an expression or a (define …) constant, :max-anisotropy ANISO as readily as :max-anisotropy 16.

WebGPU Mapping

Maps to GPUSampler via:

device.createSampler({
  magFilter: 'linear',
  minFilter: 'linear',
  mipmapFilter: 'linear',
  addressModeU: 'repeat',
  addressModeV: 'mirror-repeat',
  addressModeW: 'clamp-to-edge',
  lodMinClamp: 0,
  lodMaxClamp: 8,
  maxAnisotropy: 4,
  compare: 'less'
});

Related

• (texture …) - Texture resources to sample
• (bind-group …) - Bind samplers to shaders
• (bind-group-layout …) - Define sampler bindings