pngine 4.3.1 → 4.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pngine",
3
- "version": "4.3.1",
3
+ "version": "4.3.2",
4
4
  "description": "WebGPU spec mapped 1:1 to s-expressions that can be packed in a png",
5
5
  "type": "module",
6
6
  "scripts": {
@@ -89,12 +89,12 @@
89
89
  "./schema/pngine.sjon": "./schema/pngine.sjon"
90
90
  },
91
91
  "optionalDependencies": {
92
- "@pngine/darwin-arm64": "4.3.1",
93
- "@pngine/darwin-x64": "4.3.1",
94
- "@pngine/linux-x64": "4.3.1",
95
- "@pngine/linux-arm64": "4.3.1",
96
- "@pngine/win32-x64": "4.3.1",
97
- "@pngine/win32-arm64": "4.3.1"
92
+ "@pngine/darwin-arm64": "4.3.2",
93
+ "@pngine/darwin-x64": "4.3.2",
94
+ "@pngine/linux-x64": "4.3.2",
95
+ "@pngine/linux-arm64": "4.3.2",
96
+ "@pngine/win32-x64": "4.3.2",
97
+ "@pngine/win32-arm64": "4.3.2"
98
98
  },
99
99
  "files": [
100
100
  "dist/",
@@ -671,7 +671,8 @@
671
671
  (member :name rg16float :description "2×16-bit float; renderable, filterable.")
672
672
  (member :name r32float :description "1×32-bit float; renderable; filterable only with the float32-filterable feature.")
673
673
  (member :name r32uint :description "1×32-bit unsigned int; not filterable.")
674
- ; ---- base (no-feature) color / srgb / packed; compressed (BC/ETC2/EAC/ASTC) are deferred (need an upload path) ----
674
+ ; ---- base (no-feature) color / srgb / packed; all three compressed
675
+ ; families (BC, ETC2/EAC and ASTC) are exposed by plan 07 ----
675
676
  (member :name rgba8unorm-srgb :description "4×8-bit unorm, sRGB-encoded; renderable, filterable, blendable.")
676
677
  (member :name rgba8uint :description "4×8-bit unsigned int; renderable, not filterable.")
677
678
  (member :name rgba8sint :description "4×8-bit signed int; renderable, not filterable.")
@@ -706,6 +707,69 @@
706
707
  (member :name rgba16unorm :description "4×16-bit unorm; needs texture-formats-tier1. Renderable + blendable when enabled.")
707
708
  (member :name rgba16snorm :description "4×16-bit signed norm; needs texture-formats-tier1. Renderable + blendable when enabled.")
708
709
  (member :name depth32float-stencil8 :description "32-bit float depth plus 8-bit stencil; needs the depth32float-stencil8 device feature.")
710
+ ; ---- BC compressed (plan 07): 4×4 texel blocks, 8 or 16 bytes per
711
+ ; block, copy-only. Creation needs texture-compression-bc; 3D additionally
712
+ ; needs texture-compression-bc-sliced-3d. Descriptor width/height and copy
713
+ ; origin/extent are whole blocks. ----
714
+ (member :name bc1-rgba-unorm :description "BC1 4×4 RGB(A) unorm; 8 bytes per block. Needs texture-compression-bc.")
715
+ (member :name bc1-rgba-unorm-srgb :description "BC1 4×4 RGB(A), sRGB-encoded; 8 bytes per block. Needs texture-compression-bc.")
716
+ (member :name bc2-rgba-unorm :description "BC2 4×4 RGB(A) with explicit alpha; 16 bytes per block. Needs texture-compression-bc.")
717
+ (member :name bc2-rgba-unorm-srgb :description "BC2 4×4 RGB(A) with explicit alpha, sRGB-encoded; 16 bytes per block. Needs texture-compression-bc.")
718
+ (member :name bc3-rgba-unorm :description "BC3 4×4 interpolated alpha; 16 bytes per block. Needs texture-compression-bc.")
719
+ (member :name bc3-rgba-unorm-srgb :description "BC3 4×4 interpolated alpha, sRGB-encoded; 16 bytes per block. Needs texture-compression-bc.")
720
+ (member :name bc4-r-unorm :description "BC4 single-channel 4×4 unorm; 8 bytes per block. Needs texture-compression-bc.")
721
+ (member :name bc4-r-snorm :description "BC4 single-channel 4×4 snorm; 8 bytes per block. Needs texture-compression-bc.")
722
+ (member :name bc5-rg-unorm :description "BC5 two-channel 4×4 unorm; 16 bytes per block. Needs texture-compression-bc.")
723
+ (member :name bc5-rg-snorm :description "BC5 two-channel 4×4 snorm; 16 bytes per block. Needs texture-compression-bc.")
724
+ (member :name bc6h-rgb-ufloat :description "BC6H unsigned HDR RGB 4×4; 16 bytes per block. Needs texture-compression-bc.")
725
+ (member :name bc6h-rgb-float :description "BC6H signed HDR RGB 4×4; 16 bytes per block. Needs texture-compression-bc.")
726
+ (member :name bc7-rgba-unorm :description "BC7 high-quality RGBA 4×4 unorm; 16 bytes per block. Needs texture-compression-bc.")
727
+ (member :name bc7-rgba-unorm-srgb :description "BC7 high-quality RGBA 4×4, sRGB-encoded; 16 bytes per block. Needs texture-compression-bc.")
728
+ ; ---- ETC2/EAC compressed (plan 07 tranche B): 4×4 texel blocks, 8 or
729
+ ; 16 bytes per block, copy-only. Creation needs texture-compression-etc2;
730
+ ; the CRD has no ETC2/EAC sliced-3d feature, so 3D is refused. ----
731
+ (member :name etc2-rgb8unorm :description "ETC2 RGB 4×4 unorm; 8 bytes per block. Needs texture-compression-etc2.")
732
+ (member :name etc2-rgb8unorm-srgb :description "ETC2 RGB 4×4, sRGB-encoded; 8 bytes per block. Needs texture-compression-etc2.")
733
+ (member :name etc2-rgb8a1unorm :description "ETC2 RGB with 1-bit alpha, 4×4 unorm; 8 bytes per block. Needs texture-compression-etc2.")
734
+ (member :name etc2-rgb8a1unorm-srgb :description "ETC2 RGB with 1-bit alpha, 4×4, sRGB-encoded; 8 bytes per block. Needs texture-compression-etc2.")
735
+ (member :name etc2-rgba8unorm :description "ETC2 RGBA 4×4 unorm; 16 bytes per block. Needs texture-compression-etc2.")
736
+ (member :name etc2-rgba8unorm-srgb :description "ETC2 RGBA 4×4, sRGB-encoded; 16 bytes per block. Needs texture-compression-etc2.")
737
+ (member :name eac-r11unorm :description "EAC single-channel 4×4 unorm; 8 bytes per block. Needs texture-compression-etc2.")
738
+ (member :name eac-r11snorm :description "EAC single-channel 4×4 snorm; 8 bytes per block. Needs texture-compression-etc2.")
739
+ (member :name eac-rg11unorm :description "EAC two-channel 4×4 unorm; 16 bytes per block. Needs texture-compression-etc2.")
740
+ (member :name eac-rg11snorm :description "EAC two-channel 4×4 snorm; 16 bytes per block. Needs texture-compression-etc2.")
741
+ ; ---- ASTC compressed (plan 07 tranche C): the block dimensions are the
742
+ ; ones in the name (4×4 through 12×12), the block is always 16 bytes,
743
+ ; copy-only. Creation needs texture-compression-astc; 3D additionally
744
+ ; needs texture-compression-astc-sliced-3d. ----
745
+ (member :name astc-4x4-unorm :description "ASTC 4×4 RGBA unorm; 16 bytes per block. Needs texture-compression-astc.")
746
+ (member :name astc-4x4-unorm-srgb :description "ASTC 4×4 RGBA, sRGB-encoded; 16 bytes per block. Needs texture-compression-astc.")
747
+ (member :name astc-5x4-unorm :description "ASTC 5×4 RGBA unorm; 16 bytes per block. Needs texture-compression-astc.")
748
+ (member :name astc-5x4-unorm-srgb :description "ASTC 5×4 RGBA, sRGB-encoded; 16 bytes per block. Needs texture-compression-astc.")
749
+ (member :name astc-5x5-unorm :description "ASTC 5×5 RGBA unorm; 16 bytes per block. Needs texture-compression-astc.")
750
+ (member :name astc-5x5-unorm-srgb :description "ASTC 5×5 RGBA, sRGB-encoded; 16 bytes per block. Needs texture-compression-astc.")
751
+ (member :name astc-6x5-unorm :description "ASTC 6×5 RGBA unorm; 16 bytes per block. Needs texture-compression-astc.")
752
+ (member :name astc-6x5-unorm-srgb :description "ASTC 6×5 RGBA, sRGB-encoded; 16 bytes per block. Needs texture-compression-astc.")
753
+ (member :name astc-6x6-unorm :description "ASTC 6×6 RGBA unorm; 16 bytes per block. Needs texture-compression-astc.")
754
+ (member :name astc-6x6-unorm-srgb :description "ASTC 6×6 RGBA, sRGB-encoded; 16 bytes per block. Needs texture-compression-astc.")
755
+ (member :name astc-8x5-unorm :description "ASTC 8×5 RGBA unorm; 16 bytes per block. Needs texture-compression-astc.")
756
+ (member :name astc-8x5-unorm-srgb :description "ASTC 8×5 RGBA, sRGB-encoded; 16 bytes per block. Needs texture-compression-astc.")
757
+ (member :name astc-8x6-unorm :description "ASTC 8×6 RGBA unorm; 16 bytes per block. Needs texture-compression-astc.")
758
+ (member :name astc-8x6-unorm-srgb :description "ASTC 8×6 RGBA, sRGB-encoded; 16 bytes per block. Needs texture-compression-astc.")
759
+ (member :name astc-8x8-unorm :description "ASTC 8×8 RGBA unorm; 16 bytes per block. Needs texture-compression-astc.")
760
+ (member :name astc-8x8-unorm-srgb :description "ASTC 8×8 RGBA, sRGB-encoded; 16 bytes per block. Needs texture-compression-astc.")
761
+ (member :name astc-10x5-unorm :description "ASTC 10×5 RGBA unorm; 16 bytes per block. Needs texture-compression-astc.")
762
+ (member :name astc-10x5-unorm-srgb :description "ASTC 10×5 RGBA, sRGB-encoded; 16 bytes per block. Needs texture-compression-astc.")
763
+ (member :name astc-10x6-unorm :description "ASTC 10×6 RGBA unorm; 16 bytes per block. Needs texture-compression-astc.")
764
+ (member :name astc-10x6-unorm-srgb :description "ASTC 10×6 RGBA, sRGB-encoded; 16 bytes per block. Needs texture-compression-astc.")
765
+ (member :name astc-10x8-unorm :description "ASTC 10×8 RGBA unorm; 16 bytes per block. Needs texture-compression-astc.")
766
+ (member :name astc-10x8-unorm-srgb :description "ASTC 10×8 RGBA, sRGB-encoded; 16 bytes per block. Needs texture-compression-astc.")
767
+ (member :name astc-10x10-unorm :description "ASTC 10×10 RGBA unorm; 16 bytes per block. Needs texture-compression-astc.")
768
+ (member :name astc-10x10-unorm-srgb :description "ASTC 10×10 RGBA, sRGB-encoded; 16 bytes per block. Needs texture-compression-astc.")
769
+ (member :name astc-12x10-unorm :description "ASTC 12×10 RGBA unorm; 16 bytes per block. Needs texture-compression-astc.")
770
+ (member :name astc-12x10-unorm-srgb :description "ASTC 12×10 RGBA, sRGB-encoded; 16 bytes per block. Needs texture-compression-astc.")
771
+ (member :name astc-12x12-unorm :description "ASTC 12×12 RGBA unorm; 16 bytes per block. Needs texture-compression-astc.")
772
+ (member :name astc-12x12-unorm-srgb :description "ASTC 12×12 RGBA, sRGB-encoded; 16 bytes per block. Needs texture-compression-astc.")
709
773
  (member :name preferred-canvas-format :description "Resolved at runtime to the platform's canvas format. Runtime-provided; there is no authored document declaration to navigate to.")))
710
774
  (value-kind :name texture-usage
711
775
  :description "GPUTextureUsage flag — what the texture may be used for."
@@ -743,6 +807,19 @@
743
807
  :description "Texture size as [width], [width height], or [width height depth-or-array-layers]; the missing dimensions default to 1."
744
808
  :underlying vector
745
809
  :vector (vector-shape :element extent :min-len 1 :max-len 3))
810
+ ; GPUExtent3D as a COPY extent (writeTexture's `size` argument): [w], [w h]
811
+ ; or [w h d]. Same element type and length as extent3, deliberately its own
812
+ ; kind: an allocation dimension is `extent` (>= 1), while a copy dimension
813
+ ; can also be a bounded expression / define-ref through `u32`; and a copy
814
+ ; size is judged against the mip's physical extent by plan 01, not by a
815
+ ; texture's allocation rule. Its absent dimensions mean height/depth = 1
816
+ ; ONLY when the key is present. An absent KEY is a different thing: the
817
+ ; remaining physical extent at the origin, a recorded PNGine deviation from
818
+ ; the IDL's required `size` argument (see the write-texture form).
819
+ (value-kind :name copy-extent
820
+ :description "Copy size [width], [width height], or [width height depth-or-array-layers] (1–3 non-negative u32s). Absent dimensions default to 1 only when the key is present; an omitted :size means the remaining physical extent at the destination origin."
821
+ :underlying vector
822
+ :vector (vector-shape :element u32 :min-len 1 :max-len 3))
746
823
  ; GPUTextureDescriptor.size is ONE required member, so it is one required key
747
824
  ; over the three things a pngine texture may be sized by. Three
748
825
  ; different underlyings — vector, symbol member, cross-ref — so the union
@@ -851,11 +928,29 @@
851
928
  (head :name stencil-back :max 1)))
852
929
 
853
930
  ; ---- Phase 2d: MRT / MSAA / advanced render state ----
854
- ; A render-pass attachment view: the canvas (context-current-texture) or a
855
- ; declared (texture …) — e.g. an MSAA color target, or a resolve target.
931
+ ; A render-pass attachment view: the canvas (context-current-texture), a
932
+ ; declared (texture …), or a declared (texture-view …) selecting one mip and
933
+ ; one array layer. The union is the authoring surface of plan 09: a bare
934
+ ; texture still means the texture's default view (legacy bytes unchanged),
935
+ ; an explicit view names exactly the subresource the pass renders into.
936
+ ;
937
+ ; Two cross-ref arms first-match is safe here for the reason the one-namespace
938
+ ; rule exists: `checkNameNamespace` refuses a name declared by two forms, so
939
+ ; a symbol cannot be both a texture and a texture-view in one document. The
940
+ ; emitter resolves through its separate id tables and the union only has to
941
+ ; admit the spellings; should a collision ever survive schema validation, it
942
+ ; is refused before any phase, never silently resolved one way here and the
943
+ ; other downstream.
856
944
  (value-kind :name attachment-view
857
945
  :underlying union
858
- :union (union-shape :alternatives [view-source texture-ref]))
946
+ :union (union-shape :alternatives [view-source texture-ref texture-view-ref]))
947
+ ; The DEPTH authoring form's own union: texture or texture-view, never the
948
+ ; canvas. A depth attachment has no canvas spelling (the runtime's depth view
949
+ ; is the document's to declare), and the plan refuses it deliberately; the
950
+ ; colour/resolve `attachment-view` union keeps its view-source arm.
951
+ (value-kind :name depth-attachment-view
952
+ :underlying union
953
+ :union (union-shape :alternatives [texture-ref texture-view-ref]))
859
954
  (value-kind :name blend-factor
860
955
  :description "GPUBlendFactor — multiplier applied to source / destination color in the blend equation."
861
956
  :underlying symbol
@@ -1094,14 +1189,15 @@
1094
1189
  ; `duplicate_cross_ref_target` at the declaration, so a step can never be
1095
1190
  ; ambiguous. A named graph is in the list because the frame names it in the
1096
1191
  ; AUTHORED aggregate, where it is a `(pass-graph …)` / `(draw-graph …)` and
1097
- ; not yet the `(step-group …)` its hook emits; a `(select …)` joins for the
1098
- ; same reason (2089e59's fix, applied to the fourth member).
1192
+ ; not yet the `(step-group …)` its hook emits; a `(select …)` and a
1193
+ ; `(mip-chain …)` join for the same reason (2089e59's fix, applied to the
1194
+ ; fourth and fifth members).
1099
1195
  ; (It used to be a union tried in order, while the emitter kept
1100
1196
  ; one table for both pass kinds — a collision silently dropped the render pass.)
1101
1197
  (value-kind :name frame-step
1102
- :description "One frame step: a render-pass, compute-pass or queue name, a named pass-graph/draw-graph (a step group), a step-group name, or a select name (one namespace across the forms)."
1198
+ :description "One frame step: a render-pass, compute-pass or queue name, a named pass-graph/draw-graph/mip-chain (a step group), a step-group name, or a select name (one namespace across the forms)."
1103
1199
  :underlying symbol
1104
- :cross-ref (cross-ref :target [render-pass compute-pass queue step-group pass-graph draw-graph select]))
1200
+ :cross-ref (cross-ref :target [render-pass compute-pass queue step-group pass-graph draw-graph select mip-chain]))
1105
1201
  (value-kind :name frame-step-list
1106
1202
  :description "Passes and queues run every frame, in order."
1107
1203
  :underlying vector :vector (vector-shape :element frame-step :max-len 2048))
@@ -1298,11 +1394,12 @@
1298
1394
  (value-kind :name in-stage-section :underlying form :heads (head-set
1299
1395
  (head :name constant)))
1300
1396
  (value-kind :name bind-entry-item :underlying form :heads (head-set :names [entry]))
1301
- (value-kind :name queue-action :underlying form :heads (head-set :names [write-buffer copy-texture-to-texture copy-external-image-to-texture resolve-query-set copy-buffer-to-buffer]))
1302
- ; Both texture copies take exactly one endpoint of each kind. The heads
1303
- ; are shared but the FORMS are not — each copy declares its own slot-local
1397
+ (value-kind :name queue-action :underlying form :heads (head-set :names [write-buffer write-texture copy-buffer-to-texture copy-texture-to-buffer copy-texture-to-texture copy-external-image-to-texture resolve-query-set copy-buffer-to-buffer]))
1398
+ ; Every copy takes exactly one endpoint of each kind. The heads are shared
1399
+ ; but the FORMS are not — each copy declares its own slot-local
1304
1400
  ; `source`/`destination`, resolved local-first, so `(source :image …)` under
1305
- ; one is not `(source :texture …)` under the other.
1401
+ ; one is not `(source :texture …)` under the other, and a buffer endpoint's
1402
+ ; members are not a texture endpoint's.
1306
1403
  (value-kind :name copy-endpoints-section :underlying form :heads (head-set
1307
1404
  (head :name source :min 1 :max 1)
1308
1405
  (head :name destination :min 1 :max 1)))
@@ -1679,9 +1776,10 @@
1679
1776
  :description "Number of queries in the set, 1 to 4096 (the createQuerySet bound)."))
1680
1777
 
1681
1778
  (form :name queue
1682
- :description "Queue actions (write-buffer, copy-buffer-to-buffer, copy-texture-to-texture,
1683
- copy-external-image-to-texture, resolve-query-set) run in order by the
1684
- frames that reference it."
1779
+ :description "Queue actions (write-buffer, write-texture, copy-buffer-to-texture,
1780
+ copy-texture-to-buffer, copy-buffer-to-buffer, copy-texture-to-texture,
1781
+ copy-external-image-to-texture, resolve-query-set)
1782
+ run in order by the frames that reference it."
1685
1783
  :positional queue-action
1686
1784
  (key :name name :type symbol))
1687
1785
 
@@ -1698,31 +1796,150 @@
1698
1796
  (key :name data :type write-buffer-source
1699
1797
  :description "Source: a (data …) ref, a (wasm-call …) whose result is written each frame, or a runtime builtin — pngine-inputs (16B time/width/height/aspect), scene-time-inputs (12B), pngine-frame-inputs (20B, + frameIndex), pointer-inputs (48B), control-inputs (4B per declared (control …) in declaration order)."))
1700
1798
 
1799
+ ; The flat form of GPUQueue.writeTexture. Nine keys mirror the two texel-copy
1800
+ ; dictionaries plus the method's own `data` and `size` arguments:
1801
+ ; GPUTexelCopyTextureInfo (texture, mipLevel, origin, aspect) and
1802
+ ; GPUTexelCopyBufferLayout (offset, bytesPerRow, rowsPerImage). PNGine spells
1803
+ ; every one as a :key, so the mapping table's only sentinels are `data` and
1804
+ ; `size`, the two arguments that are NOT members of either dictionary.
1805
+ ;
1806
+ ; Presence is the wire's: `:bytes-per-row` and `:rows-per-image` are optional
1807
+ ; because the IDL gives those members NO default, and their absence survives
1808
+ ; into the PNGB presence flags (explicit zero is not omission). `:origin`
1809
+ ; carries no `:default` token because origin3 is a vector; each component
1810
+ ; defaults to 0, which is what the IDL's `{}` means.
1811
+ ;
1812
+ ; `:size` is the ONE recorded deviation: the IDL REQUIRES the size argument,
1813
+ ; but an omitted `:size` here means the remaining physical extent at the
1814
+ ; origin (plan 01's calculateWrite), so an author can update a subregion
1815
+ ; without restating the texture size. An explicit `:size` keeps its absent
1816
+ ; dimensions at height/depth 1 only because the key is present.
1817
+ (form :name write-texture
1818
+ :description "Queue op: upload raw texels into a texture (GPUQueue.writeTexture). :texture and :data are required; :offset, :origin, :mip-level and :aspect carry WebGPU's defaults. An omitted :size means the remaining physical extent at :origin — a recorded PNGine deviation from the IDL's required size argument. Omitted :bytes-per-row / :rows-per-image stay absent on the wire; explicit zero is not omission."
1819
+ (key :name texture :type texture-ref
1820
+ :description "Destination texture (needs copy-dst usage, one sample, and a non-pooled id).")
1821
+ (key :name data :type data-ref
1822
+ :description "Raw source bytes: a (data …) entry with a byte length. Image-MIME-wrapped data is refused; the bytes are never base64 on the wire.")
1823
+ (key :name offset :type byte-count :default 0
1824
+ :description "Byte offset into :data (GPUTexelCopyBufferLayout.offset, default 0). Unaligned values are legal: writeTexture has no 256-byte rule.")
1825
+ (key :name bytes-per-row :type byte-count :optional true
1826
+ :description "GPUTexelCopyBufferLayout.bytesPerRow — bytes per texel-block row. Optional because the IDL gives it no default; absent stays absent (explicit 0 is not omission).")
1827
+ (key :name rows-per-image :type byte-count :optional true
1828
+ :description "GPUTexelCopyBufferLayout.rowsPerImage — rows per texel image (array layer / depth slice). Optional because the IDL gives it no default; absent stays absent (explicit 0 is not omission).")
1829
+ (key :name origin :type origin3 :optional true
1830
+ :description "Destination origin [x y z] in texels (GPUTexelCopyTextureInfo.origin, IDL default {} = all zero); components default to 0. z selects the array layer or depth slice.")
1831
+ (key :name mip-level :type subresource-index :default 0
1832
+ :description "Destination mip level (GPUTexelCopyTextureInfo.mipLevel, default 0); a u32 varint, no u8 ceiling.")
1833
+ (key :name aspect :type texture-aspect :default all
1834
+ :description "Destination aspect (GPUTexelCopyTextureInfo.aspect, default all). Depth/stencil formats require a single aspect and a full-subresource write.")
1835
+ (key :name size :type copy-extent :optional true
1836
+ :description "GPUExtent3D size to write (1–3 u32s). Optional only through the recorded deviation: absent means the remaining physical extent at :origin, whereas the IDL requires the size argument. Present, absent dimensions default to 1."))
1837
+
1838
+ ; Buffer↔texture copies reuse plan 01's descriptor/layout model with an
1839
+ ; explicit aligned-buffer policy (plan 05, D16). Both endpoints are separate
1840
+ ; IDL dictionaries, so both are slot-local child forms: the buffer side is
1841
+ ; GPUTexelCopyBufferInfo (its `buffer` plus the inherited
1842
+ ; GPUTexelCopyBufferLayout members) and the texture side is
1843
+ ; GPUTexelCopyTextureInfo. `:size` is each method's own `copySize` argument,
1844
+ ; not a member of either dictionary.
1845
+ ;
1846
+ ; Compared with writeTexture, the buffer copy adds exactly two rules, both
1847
+ ; only when the texture endpoint is present: a supplied `:bytes-per-row` is a
1848
+ ; multiple of 256, and `:offset` is a multiple of the texel block copy
1849
+ ; footprint — except a depth-stencil texture endpoint (source or
1850
+ ; destination) uses 4. `writeTexture` has neither rule.
1851
+ (form :name copy-buffer-to-texture
1852
+ :description "Queue op: copy from a buffer into a texture subresource (GPUCommandEncoder.copyBufferToTexture). The source is a GPUTexelCopyBufferInfo and the destination a GPUTexelCopyTextureInfo; :size is the method's copySize. A supplied source :bytes-per-row must be a multiple of 256, and :offset a multiple of the texel block copy footprint (4 for a depth-stencil destination)."
1853
+ :positional copy-endpoints-section
1854
+ (key :name size :type copy-extent :optional true
1855
+ :description "GPUCommandEncoder.copyBufferToTexture's copySize (1–3 u32s). Optional only through the recorded deviation: absent means the remaining physical extent at the destination origin.")
1856
+ (form :name source
1857
+ :description "Buffer source (GPUTexelCopyBufferInfo with its GPUTexelCopyBufferLayout)."
1858
+ (key :name buffer :type buffer-ref
1859
+ :description "Source buffer name; needs copy-src usage.")
1860
+ (key :name offset :type byte-count :default 0
1861
+ :description "Byte offset into the source buffer (GPUTexelCopyBufferLayout.offset, default 0). Must be a multiple of the texel block copy footprint, or 4 for a depth-stencil endpoint.")
1862
+ (key :name bytes-per-row :type byte-count :optional true
1863
+ :description "GPUTexelCopyBufferLayout.bytesPerRow — bytes between texel-block rows. Optional in the IDL (no default); a supplied value must be a multiple of 256, and WebGPU requires it when the copy spans more than one block row or image.")
1864
+ (key :name rows-per-image :type byte-count :optional true
1865
+ :description "GPUTexelCopyBufferLayout.rowsPerImage — rows per texel image. Optional in the IDL (no default); WebGPU requires it when the copy spans more than one image."))
1866
+ (form :name destination
1867
+ :description "Texture destination (GPUTexelCopyTextureInfo)."
1868
+ (key :name texture :type texture-ref
1869
+ :description "Destination texture name; needs copy-dst usage, one sample, and a non-pooled id.")
1870
+ (key :name mip-level :type subresource-index :default 0
1871
+ :description "Destination mip level (GPUTexelCopyTextureInfo.mipLevel, default 0).")
1872
+ (key :name origin :type origin3 :optional true
1873
+ :description "Destination origin [x y z] in texels (GPUTexelCopyTextureInfo.origin, IDL default {} = all zero); z selects the array layer or depth slice.")
1874
+ (key :name aspect :type texture-aspect :default all
1875
+ :description "Destination aspect (GPUTexelCopyTextureInfo.aspect, default all). Depth/stencil formats require a single aspect and a full-subresource copy.")))
1876
+
1877
+ (form :name copy-texture-to-buffer
1878
+ :description "Queue op: copy a texture subresource into a buffer (GPUCommandEncoder.copyTextureToBuffer), the byte-preserving readback path. The source is a GPUTexelCopyTextureInfo and the destination a GPUTexelCopyBufferInfo; :size is the method's copySize. A supplied destination :bytes-per-row must be a multiple of 256, and :offset a multiple of the texel block copy footprint (4 for a depth-stencil source)."
1879
+ :positional copy-endpoints-section
1880
+ (key :name size :type copy-extent :optional true
1881
+ :description "GPUCommandEncoder.copyTextureToBuffer's copySize (1–3 u32s). Optional only through the recorded deviation: absent means the remaining physical extent at the source origin.")
1882
+ (form :name source
1883
+ :description "Texture source (GPUTexelCopyTextureInfo)."
1884
+ (key :name texture :type texture-ref
1885
+ :description "Source texture name; needs copy-src usage.")
1886
+ (key :name mip-level :type subresource-index :default 0
1887
+ :description "Source mip level (GPUTexelCopyTextureInfo.mipLevel, default 0).")
1888
+ (key :name origin :type origin3 :optional true
1889
+ :description "Source origin [x y z] in texels (GPUTexelCopyTextureInfo.origin, IDL default {} = all zero); z selects the array layer or depth slice.")
1890
+ (key :name aspect :type texture-aspect :default all
1891
+ :description "Source aspect (GPUTexelCopyTextureInfo.aspect, default all). Depth/stencil formats require a single aspect and a full-subresource copy."))
1892
+ (form :name destination
1893
+ :description "Buffer destination (GPUTexelCopyBufferInfo with its GPUTexelCopyBufferLayout)."
1894
+ (key :name buffer :type buffer-ref
1895
+ :description "Destination buffer name; needs copy-dst usage, and map-read when the bytes are read back to the host.")
1896
+ (key :name offset :type byte-count :default 0
1897
+ :description "Byte offset into the destination buffer (GPUTexelCopyBufferLayout.offset, default 0). Must be a multiple of the texel block copy footprint, or 4 for a depth-stencil endpoint.")
1898
+ (key :name bytes-per-row :type byte-count :optional true
1899
+ :description "GPUTexelCopyBufferLayout.bytesPerRow — bytes between texel-block rows. Optional in the IDL (no default); a supplied value must be a multiple of 256, and WebGPU requires it when the copy spans more than one block row or image.")
1900
+ (key :name rows-per-image :type byte-count :optional true
1901
+ :description "GPUTexelCopyBufferLayout.rowsPerImage — rows per texel image. Optional in the IDL (no default); WebGPU requires it when the copy spans more than one image.")))
1902
+
1701
1903
  ; Both ends of a copy are dictionaries in the IDL
1702
1904
  ; (GPUTexelCopyTextureInfo / GPUCopyExternalImageSourceInfo), so they are
1703
1905
  ; child forms, and their members are that form's keys: `:mip-level` and
1704
- ; `:origin` describe the DESTINATION subresource, not the copy. The flat
1906
+ ; `:origin` describe the endpoint's subresource, not the copy. The flat
1705
1907
  ; `:source X :texture Y` spelling is retired rather than kept as a second one.
1706
1908
  ; Their heads are SLOT-LOCAL: `source` carries a texture under one copy
1707
1909
  ; and an image under the other, and neither is a global form.
1708
1910
  ;
1709
- ; There is no `:size`: pngine copies the whole source, which is what both
1710
- ; runtimes do today. A key the bytecode cannot carry would validate and be
1711
- ; dropped in silence — the texture→texture opcode encodes the two texture
1712
- ; ids and nothing else (`wire_schema` L_2V); the external-image opcode encodes
1713
- ; the bitmap id, the texture id and the destination mip level + origin
1714
- ; (L_COPY_EXT_IMG). Neither carries a size. It arrives when the opcode does.
1911
+ ; COMPATIBILITY RULE (plan 06): a `(copy-texture-to-texture …)` that authors
1912
+ ; none of `:mip-level`, `:origin`, `:aspect` on either endpoint and no `:size`
1913
+ ; stays on the legacy whole-texture operation forever — PNGB 0x23 and command
1914
+ ; 0x23, byte-identical, including the canvas-size fallback. Any one of those
1915
+ ; keys (even with its default value) selects the subresource operation and the
1916
+ ; normalized SubresourceCopy model. The legacy opcode carries two ids and
1917
+ ; nothing else (`wire_schema` L_2V); the new operation is PNGB 0x80.
1715
1918
  (form :name copy-texture-to-texture
1716
- :description "Queue op: GPU texture→texture copy. context-current-texture names the canvas; otherwise a (texture …) name."
1919
+ :description "Queue op: GPU texture→texture copy. With no :mip-level, :origin or :aspect on either endpoint and no :size, this is the legacy whole-texture copy (PNGB 0x23) byte-identically; any such key selects the subresource operation. context-current-texture names the canvas; otherwise a (texture …) name."
1717
1920
  :positional copy-endpoints-section
1921
+ (key :name size :type copy-extent :optional true
1922
+ :description "GPUCommandEncoder.copyTextureToTexture's copySize (1–3 u32s). Optional only through the recorded deviation: absent means the remaining physical SOURCE extent at the source :origin and :mip-level; the destination must contain the same extent at its origin. Presence selects the subresource operation.")
1718
1923
  (form :name source
1719
- :description "Copy source (GPUTexelCopyTextureInfo)."
1924
+ :description "Copy source (GPUTexelCopyTextureInfo). With no subresource key and no outer :size it is the legacy whole-texture source."
1720
1925
  (key :name texture :type attachment-view
1721
- :description "Source texture: context-current-texture or a (texture …) name."))
1926
+ :description "Source texture: context-current-texture or a (texture …) name; needs copy-src usage.")
1927
+ (key :name mip-level :type subresource-index :default 0
1928
+ :description "Source mip level (GPUTexelCopyTextureInfo.mipLevel, default 0). Authoring the key selects the subresource operation; omitting it leaves the legacy route available.")
1929
+ (key :name origin :type origin3 :optional true
1930
+ :description "Source origin [x y z] in texels (GPUTexelCopyTextureInfo.origin, IDL default {} = all zero); z selects the array layer or depth slice. Its presence selects the subresource operation.")
1931
+ (key :name aspect :type texture-aspect :default all
1932
+ :description "Source aspect (GPUTexelCopyTextureInfo.aspect, default all). A depth-stencil texture→texture copy requires all on BOTH endpoints — the opposite of the write path's single-aspect rule. Its presence selects the subresource operation."))
1722
1933
  (form :name destination
1723
- :description "Copy destination (GPUTexelCopyTextureInfo)."
1934
+ :description "Copy destination (GPUTexelCopyTextureInfo). With no subresource key and no outer :size it is the legacy whole-texture destination."
1724
1935
  (key :name texture :type attachment-view
1725
- :description "Destination texture: context-current-texture or a (texture …) name.")))
1936
+ :description "Destination texture: context-current-texture or a (texture …) name; needs copy-dst usage and a non-pooled id on the subresource path.")
1937
+ (key :name mip-level :type subresource-index :default 0
1938
+ :description "Destination mip level (GPUTexelCopyTextureInfo.mipLevel, default 0). Its presence selects the subresource operation.")
1939
+ (key :name origin :type origin3 :optional true
1940
+ :description "Destination origin [x y z] in texels (GPUTexelCopyTextureInfo.origin, IDL default {} = all zero); z selects the array layer or depth slice. Its presence selects the subresource operation.")
1941
+ (key :name aspect :type texture-aspect :default all
1942
+ :description "Destination aspect (GPUTexelCopyTextureInfo.aspect, default all). A depth-stencil texture→texture copy requires all on BOTH endpoints. Its presence selects the subresource operation.")))
1726
1943
 
1727
1944
  (form :name copy-external-image-to-texture
1728
1945
  :description "Queue op: upload a decoded image (image-bitmap) into a texture. mip-level / origin default to 0 per the WebGPU spec."
@@ -2167,9 +2384,9 @@
2167
2384
  (form :name color-attachment
2168
2385
  :description "One color target of a render pass."
2169
2386
  (key :name view :type attachment-view
2170
- :description "Texture written by this pass: the canvas (context-current-texture) or a (texture …).")
2387
+ :description "Attachment written by this pass: the canvas (context-current-texture), a (texture …) (its default view), or a (texture-view …) selecting one mip level and one array layer.")
2171
2388
  (key :name resolve-target :type attachment-view :optional true
2172
- :description "Receives the resolved single-sample output when :view is multisampled.")
2389
+ :description "Receives the resolved single-sample output when :view is multisampled — the canvas, a (texture …), or a (texture-view …) selecting one mip level and one array layer.")
2173
2390
  (key :name clear-value :type clear-color :optional true
2174
2391
  :description "RGBA the attachment is cleared to when load-op is clear (WebGPU default: transparent black). Stating one beside `:load-op load` is an error — WebGPU would ignore it.")
2175
2392
  ; REQUIRED, matching GPURenderPassColorAttachment.loadOp/storeOp. WebGPU has
@@ -2204,8 +2421,8 @@
2204
2421
  ; document. The emitter says it instead, with a span on the attachment.
2205
2422
  (form :name depth-stencil-attachment
2206
2423
  :description "Depth/stencil target of a render pass."
2207
- (key :name view :type texture-ref
2208
- :description "The depth/stencil (texture …) this pass tests/writes against.")
2424
+ (key :name view :type depth-attachment-view
2425
+ :description "The depth/stencil (texture …) or (texture-view …) this pass tests/writes against. The canvas is not a depth attachment.")
2209
2426
  (key :name depth-clear-value :type unorm :optional true
2210
2427
  :description "Depth cleared to when depth-load-op is clear, in [0,1]. Required when it clears — WebGPU has no default for it — and rejected beside `:depth-load-op load`.")
2211
2428
  (key :name depth-load-op :type load-op :optional true
@@ -2455,6 +2672,34 @@
2455
2672
  (key :name else :type frame-step-list :optional true
2456
2673
  :description "The steps that run when no case holds. Becomes the last group's :else, so it is the chain's fallback arm."))
2457
2674
 
2675
+ ; =====================================================================
2676
+ ; `(mip-chain …)` sugar — lowered to a render-pass chain by
2677
+ ; pngine/mips-v1 (plan 08)
2678
+ ; =====================================================================
2679
+ ; A mip chain is ordinary resources and ordinary scheduling: the hook emits
2680
+ ; a sampled/attachment (texture-view …) pair per generated level, one linear
2681
+ ; sampler, one fullscreen module/pipeline for the texture's format, a bind
2682
+ ; group and render pass per level, and one named `(step-group …)` holding
2683
+ ; those passes in ascending order. The author schedules that group in a
2684
+ ; frame like any other step and queues the level-0 write before it; nothing
2685
+ ; runs at load time and no once-only side channel is created.
2686
+ ;
2687
+ ; The descriptor checks are the hook's, not the schema's (they relate keys
2688
+ ; to a sibling `(texture …)`): 2d, one sample, one layer, not pooled, at
2689
+ ; least two mip levels, sampled AND attachable, and a format that is both
2690
+ ; filterable and color-renderable without an optional feature. A one-level
2691
+ ; texture is `nothing-to-generate` rather than an empty group.
2692
+ (form :name mip-chain
2693
+ :description "Generate a (texture …)'s mip levels from level 0 with a named step-group of ordinary render passes. Sugar: pngine/mips-v1."
2694
+ :lowering (lowering :hook pngine/mips-v1
2695
+ :produces [texture-view sampler shader-module render-pipeline vertex
2696
+ fragment color-target bind-group entry render-pass
2697
+ color-attachment draw step-group])
2698
+ (key :name name :type symbol
2699
+ :description "The generated step-group's name. A (frame …) performs it like any other step, after the step that writes level 0.")
2700
+ (key :name texture :type texture-ref
2701
+ :description "The (texture …) whose levels 1..mip-level-count-1 the chain generates. Level 0 is an input and is never overwritten; the texture must be 2d, one-sample, one-layer, non-pooled, sampled and renderable, with a filterable color format."))
2702
+
2458
2703
 
2459
2704
  ; ---- init sugar: lowered to compute-pipeline + bind-group + compute-pass ----
2460
2705
  (form :name init