(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

(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

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

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

Type: symbol

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

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

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

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

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())
});

Where these words come from

Every key and value on this page traced to the WebGPU name it stands for, with a link to the definition. How the tracing is made, and what keeps it from rotting, is the subject of Where the Words Come From.

(texture-view …) mirrors GPUTextureViewDescriptor (MDN).

Key	WebGPU	Note
`:name`	`GPUObjectDescriptorBase.label`	the `label` of `GPUObjectDescriptorBase`, and the name every cross-reference resolves
`:texture`	PNGine’s own	the `GPUTexture` whose `createView()` this is; WebGPU has it as the receiver, not a member
`:dimension`	`GPUTextureViewDescriptor.dimension`
`:aspect`	`GPUTextureViewDescriptor.aspect`
`:base-mip-level`	`GPUTextureViewDescriptor.baseMipLevel`
`:mip-level-count`	`GPUTextureViewDescriptor.mipLevelCount`
`:base-array-layer`	`GPUTextureViewDescriptor.baseArrayLayer`
`:array-layer-count`	`GPUTextureViewDescriptor.arrayLayerCount`
`:format`	`GPUTextureViewDescriptor.format`

Not expressible in PNGine yet: GPUTextureViewDescriptor.usage, GPUTextureViewDescriptor.swizzle.

The :texture key names the receiver of createView(); the spec has it as the object the method is called on, not as a member.

Values

view-dimension (:dimension on (texture-view …)) spells the GPUTextureViewDimension enum.

Value	WebGPU	Note
`1d`	`"1d"`
`2d`	`"2d"`
`2d-array`	`"2d-array"`
`cube`	`"cube"`
`cube-array`	`"cube-array"`
`3d`	`"3d"`

texture-aspect (:aspect on (texture-view …)) spells the GPUTextureAspect enum.

Value	WebGPU	Note
`all`	`"all"`
`stencil-only`	`"stencil-only"`
`depth-only`	`"depth-only"`

texture-format (:format on (texture-view …)) spells the GPUTextureFormat enum.

50 values

Value	WebGPU	Note
`rgba8unorm`	`"rgba8unorm"`
`rgba8snorm`	`"rgba8snorm"`
`bgra8unorm`	`"bgra8unorm"`
`rgba16float`	`"rgba16float"`
`rgba32float`	`"rgba32float"`
`depth24plus`	`"depth24plus"`
`depth24plus-stencil8`	`"depth24plus-stencil8"`
`depth32float`	`"depth32float"`
`stencil8`	`"stencil8"`
`depth16unorm`	`"depth16unorm"`
`r8unorm`	`"r8unorm"`
`rg8unorm`	`"rg8unorm"`
`r16float`	`"r16float"`
`rg16float`	`"rg16float"`
`r32float`	`"r32float"`
`r32uint`	`"r32uint"`
`rgba8unorm-srgb`	`"rgba8unorm-srgb"`
`rgba8uint`	`"rgba8uint"`
`rgba8sint`	`"rgba8sint"`
`r8snorm`	`"r8snorm"`
`r8uint`	`"r8uint"`
`r8sint`	`"r8sint"`
`rg8snorm`	`"rg8snorm"`
`rg8uint`	`"rg8uint"`
`rg8sint`	`"rg8sint"`
`r16uint`	`"r16uint"`
`r16sint`	`"r16sint"`
`rg16uint`	`"rg16uint"`
`rg16sint`	`"rg16sint"`
`r32sint`	`"r32sint"`
`rg32uint`	`"rg32uint"`
`rg32sint`	`"rg32sint"`
`rg32float`	`"rg32float"`
`rgba16uint`	`"rgba16uint"`
`rgba16sint`	`"rgba16sint"`
`rgba32uint`	`"rgba32uint"`
`rgba32sint`	`"rgba32sint"`
`rgb10a2unorm`	`"rgb10a2unorm"`
`rgb10a2uint`	`"rgb10a2uint"`
`rg11b10ufloat`	`"rg11b10ufloat"`
`rgb9e5ufloat`	`"rgb9e5ufloat"`
`bgra8unorm-srgb`	`"bgra8unorm-srgb"`
`r16unorm`	`"r16unorm"`
`r16snorm`	`"r16snorm"`
`rg16unorm`	`"rg16unorm"`
`rg16snorm`	`"rg16snorm"`
`rgba16unorm`	`"rgba16unorm"`
`rgba16snorm`	`"rgba16snorm"`
`depth32float-stencil8`	`"depth32float-stencil8"`
`preferred-canvas-format`	PNGine’s own	the runtime’s negotiated canvas format; see References

52 of the spec's 101 values PNGine does not offer

Checked against the WebGPU specification at revision b8c0fa9; the links go to the current draft.

(texture …) - The source texture
(bind-group …) - Bind a view via (entry :texture-view …)
(sampler …) - Configure texture sampling