Skip to content
PNGine

(texture-view …)

Creates an explicit GPUTextureView over a (texture …). Binding a texture directly ((entry :texture …)) gives the shader that texture’s default 2d view; sampling a 1d / 3d / array / cube texture needs an explicit view whose :dimension matches the WGSL binding.

Syntax

Section titled “Syntax”
(texture-view :name arr_view
  :texture arr
  :dimension 2d-array)

Bind it with (entry :texture-view …) in a (bind-group …):

(bind-group :name g :layout pipe :group 0
  (entry :binding 0 :sampler samp)
  (entry :binding 1 :texture-view arr_view))

Keys

Section titled “Keys”
Key Type Required Default Description
:name symbol Yes - Unique view name
:texture reference Yes - Source (texture …) this view aliases
:dimension symbol No inferred from the texture How the view is addressed (see table)
:aspect symbol No all all / stencil-only / depth-only
:base-mip-level number No 0 First mip level the view exposes
:mip-level-count number No all Mip levels from the base
:base-array-layer number No 0 First array layer the view exposes
:array-layer-count number No all Array layers from the base
:format symbol No texture’s Reinterpret the texel format

:dimension

Section titled “:dimension”

Type: symbol

Spelled as the WebGPU specification spells it, and it must match the WGSL binding the view is bound to.

Value WGSL binding Description
1d texture_1d One-dimensional view
2d texture_2d Two-dimensional view (what a one-layer 2d texture infers)
2d-array texture_2d_array Array of 2d layers
cube texture_cube Cube map: six 2d layers
cube-array texture_cube_array Array of cube maps: 6 x N layers
3d texture_3d Volume view

The spellings are digit-leading, so a bare number is not a shorthand for one: a number here is a wrong_underlying error, and a spelling outside the six is a not_member that lists them.

:aspect

Section titled “:aspect”

Type: symbol

Which aspect(s) of a depth/stencil texture the view exposes: all (default), stencil-only, or depth-only.

Subresource range

Section titled “Subresource range”

:base-mip-level / :mip-level-count restrict the view to a mip sub-range; :base-array-layer / :array-layer-count to a layer sub-range. Omitted counts mean “all remaining”, the WebGPU default.

Example

Section titled “Example”

A 2-layer 2d-array texture sampled through an explicit 2d-array view:

(texture :name arr :size [256 256 2]
  :dimension 2d
  :format rgba8unorm :usage [texture-binding copy-dst])


(texture-view :name arr_view :texture arr :dimension 2d-array)


; WGSL: @group(0) @binding(1) var tex: texture_2d_array<f32>;
;       textureSample(tex, samp, uv, 0)  // layer 0

Validation Rules

Section titled “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 (texture …) at line N
:texture is required and must resolve to a declared texture missing_required_key, not_cross_ref
:dimension is one of the six spellings not_member; wrong_underlying for a number
:aspect is all, stencil-only or depth-only not_member
:base-mip-level / :base-array-layer must be ≥ 0; counts ≥ 1 number_below_min

WebGPU Mapping

Section titled “WebGPU Mapping”

Maps to GPUTextureView via:

const arr_view = arr.createView({
  dimension: "2d-array",        // when :dimension 2d-array
  // aspect, baseMipLevel, mipLevelCount, baseArrayLayer, arrayLayerCount, format
  // are emitted only when authored (an all-default view is a bare createView())
});
Section titled “Related”