xbintsc 0.5.38 → 0.5.42
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/dist/src/cli/help.d.ts +1 -1
- package/dist/src/codegen/generator/module.js +23 -7
- package/dist/src/codegen/generator/module.js.map +1 -1
- package/dist/src/driver/version.d.ts +1 -1
- package/dist/src/driver/version.js +1 -1
- package/dist/src/extensions/gui/html.js +9 -2
- package/dist/src/extensions/gui/html.js.map +1 -1
- package/dist/tests/codegen/closures.test.js +7 -0
- package/dist/tests/codegen/closures.test.js.map +1 -1
- package/dist/tests/e2e/compile-objects-classes.test.js +31 -0
- package/dist/tests/e2e/compile-objects-classes.test.js.map +1 -1
- package/dist/tests/e2e/gui-canvas-state.test.d.ts +9 -0
- package/dist/tests/e2e/gui-canvas-state.test.js +297 -0
- package/dist/tests/e2e/gui-canvas-state.test.js.map +1 -0
- package/dist/tests/e2e/gui-data-url.test.d.ts +10 -0
- package/dist/tests/e2e/gui-data-url.test.js +127 -0
- package/dist/tests/e2e/gui-data-url.test.js.map +1 -0
- package/dist/tests/e2e/gui-draw-perf.test.d.ts +22 -0
- package/dist/tests/e2e/gui-draw-perf.test.js +405 -0
- package/dist/tests/e2e/gui-draw-perf.test.js.map +1 -0
- package/dist/tests/e2e/gui-effects.test.js +96 -0
- package/dist/tests/e2e/gui-effects.test.js.map +1 -1
- package/dist/tests/e2e/gui-paint.test.js +77 -0
- package/dist/tests/e2e/gui-paint.test.js.map +1 -1
- package/dist/tests/e2e/gui-perf.test.d.ts +23 -0
- package/dist/tests/e2e/gui-perf.test.js +283 -0
- package/dist/tests/e2e/gui-perf.test.js.map +1 -0
- package/dist/tests/e2e/gui-script-import-order.test.js +9 -1
- package/dist/tests/e2e/gui-script-import-order.test.js.map +1 -1
- package/dist/tests/e2e/gui-webgl.test.js +4 -4
- package/dist/tests/e2e/gui-webgl.test.js.map +1 -1
- package/dist/tests/e2e/gui-webgl2-shadow-sampler.test.d.ts +8 -0
- package/dist/tests/e2e/gui-webgl2-shadow-sampler.test.js +336 -0
- package/dist/tests/e2e/gui-webgl2-shadow-sampler.test.js.map +1 -0
- package/dist/tests/extensions/gui.test.js +23 -0
- package/dist/tests/extensions/gui.test.js.map +1 -1
- package/doc/gui/api.md +28 -2
- package/doc/gui/canvas.md +114 -27
- package/doc/gui/known-issues.md +47 -19
- package/doc/gui/media.md +11 -2
- package/doc/gui/rendering.md +120 -18
- package/doc/gui/runtime.md +18 -3
- package/doc/gui/webgl.md +38 -19
- package/doc/gui.md +38 -5
- package/doc/zh-CN/gui/api.md +25 -2
- package/doc/zh-CN/gui/canvas.md +97 -26
- package/doc/zh-CN/gui/known-issues.md +32 -12
- package/doc/zh-CN/gui/media.md +9 -2
- package/doc/zh-CN/gui/rendering.md +89 -11
- package/doc/zh-CN/gui/runtime.md +13 -3
- package/doc/zh-CN/gui/webgl.md +27 -5
- package/doc/zh-CN/gui.md +25 -2
- package/package.json +7 -7
- package/runtime/ext_gui/browser.cpp +3 -1
- package/runtime/ext_gui/canvas.cpp +135 -89
- package/runtime/ext_gui/canvas.h +116 -0
- package/runtime/ext_gui/canvas_clip.cpp +143 -0
- package/runtime/ext_gui/canvas_composite.cpp +241 -0
- package/runtime/ext_gui/canvas_coverage.cpp +241 -0
- package/runtime/ext_gui/canvas_gradient.cpp +41 -4
- package/runtime/ext_gui/canvas_image_data.cpp +4 -0
- package/runtime/ext_gui/canvas_internal.h +34 -9
- package/runtime/ext_gui/canvas_raster.cpp +207 -178
- package/runtime/ext_gui/canvas_shadow.cpp +161 -0
- package/runtime/ext_gui/canvas_stroke.cpp +37 -9
- package/runtime/ext_gui/canvas_style.cpp +59 -0
- package/runtime/ext_gui/canvas_text.cpp +140 -0
- package/runtime/ext_gui/css.h +7 -0
- package/runtime/ext_gui/css_sheet.cpp +22 -0
- package/runtime/ext_gui/document.cpp +25 -1
- package/runtime/ext_gui/document.h +8 -0
- package/runtime/ext_gui/dom_api_canvas.cpp +48 -15
- package/runtime/ext_gui/dom_api_canvas_image.cpp +9 -0
- package/runtime/ext_gui/dom_api_canvas_state.cpp +217 -0
- package/runtime/ext_gui/dom_api_internal.h +36 -37
- package/runtime/ext_gui/dom_api_offscreen.cpp +213 -0
- package/runtime/ext_gui/dom_api_proto.cpp +18 -0
- package/runtime/ext_gui/dom_api_webgl.cpp +19 -9
- package/runtime/ext_gui/dom_api_webgl_internal.h +58 -0
- package/runtime/ext_gui/dom_api_webgl_source.cpp +18 -0
- package/runtime/ext_gui/gradient_values.cpp +56 -49
- package/runtime/ext_gui/gui.cpp +5 -0
- package/runtime/ext_gui/gui_canvas.cpp +4 -0
- package/runtime/ext_gui/gui_engine.h +30 -0
- package/runtime/ext_gui/gui_events.cpp +185 -58
- package/runtime/ext_gui/gui_media.cpp +3 -0
- package/runtime/ext_gui/image.cpp +225 -1
- package/runtime/ext_gui/image.h +6 -4
- package/runtime/ext_gui/image_bitmap_browser.cpp +11 -0
- package/runtime/ext_gui/layout.cpp +4 -0
- package/runtime/ext_gui/paint.cpp +72 -3
- package/runtime/ext_gui/paint.h +11 -1
- package/runtime/ext_gui/paint_background.cpp +110 -12
- package/runtime/ext_gui/paint_effects.cpp +2 -1
- package/runtime/ext_gui/paint_internal.h +5 -1
- package/runtime/ext_gui/perf.cpp +171 -0
- package/runtime/ext_gui/perf.h +127 -0
- package/runtime/ext_gui/renderer.cpp +190 -54
- package/runtime/ext_gui/renderer.h +52 -14
- package/runtime/ext_gui/renderer_image.cpp +135 -65
- package/runtime/ext_gui/renderer_internal.h +41 -3
- package/runtime/ext_gui/renderer_layer.cpp +552 -0
- package/runtime/ext_gui/renderer_text.cpp +24 -12
- package/runtime/ext_gui/style.cpp +101 -30
- package/runtime/ext_gui/style.h +35 -4
- package/runtime/ext_gui/style_print.cpp +15 -1
- package/runtime/ext_gui/style_values.cpp +10 -0
- package/runtime/ext_gui/text.cpp +23 -4
- package/runtime/ext_gui/text.h +29 -0
- package/runtime/ext_gui/text_cache.cpp +118 -0
- package/runtime/ext_gui/text_glyph_cache.cpp +100 -0
- package/runtime/ext_gui/webgl.h +48 -146
- package/runtime/ext_gui/webgl_blit.cpp +12 -1
- package/runtime/ext_gui/webgl_blit_depth.cpp +270 -0
- package/runtime/ext_gui/webgl_buffer.cpp +59 -1
- package/runtime/ext_gui/webgl_buffer_objects.cpp +106 -9
- package/runtime/ext_gui/webgl_clear.cpp +3 -0
- package/runtime/ext_gui/webgl_context.cpp +29 -3
- package/runtime/ext_gui/webgl_draw.cpp +75 -270
- package/runtime/ext_gui/webgl_draw_buffers.cpp +1 -0
- package/runtime/ext_gui/webgl_draw_setup.cpp +321 -0
- package/runtime/ext_gui/webgl_draw_state.h +130 -0
- package/runtime/ext_gui/webgl_glsl_scan.cpp +3 -8
- package/runtime/ext_gui/webgl_objects.h +148 -0
- package/runtime/ext_gui/webgl_pipeline.cpp +8 -8
- package/runtime/ext_gui/webgl_program_internal.h +35 -0
- package/runtime/ext_gui/webgl_shader.cpp +22 -30
- package/runtime/ext_gui/webgl_webgl2.cpp +36 -0
- package/runtime/ext_gui/window.cpp +56 -1
- package/src/codegen/generator/module.ts +22 -7
- package/src/driver/version.ts +1 -1
- package/src/extensions/gui/html.ts +9 -2
package/doc/gui/canvas.md
CHANGED
|
@@ -36,6 +36,16 @@ a shared prototype. The handle is cached on the element, so every call returns
|
|
|
36
36
|
the **same** object and the drawing state (transform, styles, path) is per
|
|
37
37
|
canvas, not per call. `ctx.canvas` is the owning element handle.
|
|
38
38
|
|
|
39
|
+
`OffscreenCanvas` has the same 2D surface without a DOM element:
|
|
40
|
+
`new OffscreenCanvas(width, height)` allocates a bitmap owned by the window,
|
|
41
|
+
`getContext("2d")` returns a context whose `canvas` is the offscreen object, and
|
|
42
|
+
`canvas.transferControlToOffscreen()` hands a live element's bitmap to one
|
|
43
|
+
(`element.getContext(…)` then answers `null`). `drawImage`, `createPattern`,
|
|
44
|
+
`createImageBitmap` and `texImage2D` accept an `OffscreenCanvas` as a source.
|
|
45
|
+
`transferToImageBitmap()` returns an `ImageBitmap` and `convertToBlob()`
|
|
46
|
+
resolves to the same PNG blob shape as `toBlob` (there is no worker or
|
|
47
|
+
`OffscreenCanvas` WebGL context in this runtime).
|
|
48
|
+
|
|
39
49
|
`getContext("2d", attributes)` honours `alpha` on the first call: with
|
|
40
50
|
`{ alpha: false }` the bitmap starts (and clears) opaque black. The other
|
|
41
51
|
attributes are reported by `getContextAttributes()` at their specification
|
|
@@ -51,7 +61,36 @@ horizontal coverage** pass, and fills paths with the **non-zero winding rule**
|
|
|
51
61
|
(so `arc`-shaped holes work when wound the other way) unless
|
|
52
62
|
`fill("evenodd")` selects the even-odd rule. An axis-aligned rectangle
|
|
53
63
|
(`b == 0 && c == 0` in the transform) takes a direct coverage fast path.
|
|
54
|
-
Blending
|
|
64
|
+
Blending uses non-premultiplied source-over by default. `globalCompositeOperation`
|
|
65
|
+
selects the full canvas set: the Porter-Duff operators (`source-over`,
|
|
66
|
+
`source-in`, `source-out`, `source-atop`, `destination-over`,
|
|
67
|
+
`destination-in`, `destination-out`, `destination-atop`, `lighter`, `copy`,
|
|
68
|
+
`xor`) and the separable/non-separable blend modes (`multiply`, `screen`,
|
|
69
|
+
`overlay`, `darken`, `lighten`, `color-dodge`, `color-burn`, `hard-light`,
|
|
70
|
+
`soft-light`, `difference`, `exclusion`, `hue`, `saturation`, `color`,
|
|
71
|
+
`luminosity`). Coverage from anti-aliasing and the clip region interpolates
|
|
72
|
+
between the untouched destination and the composited result, so a partially
|
|
73
|
+
covered pixel is correct for every operator.
|
|
74
|
+
|
|
75
|
+
`clip()` intersects the current clip region with the current path (or a
|
|
76
|
+
`Path2D` and an optional `"nonzero"`/`"evenodd"` rule). The region is stored as
|
|
77
|
+
a device-space coverage mask, so it follows the transform in effect when
|
|
78
|
+
`clip()` was called; `save`/`restore` restore it and resizing the bitmap clears
|
|
79
|
+
it. Every fill, stroke, text run, image draw and `clearRect` honours the mask.
|
|
80
|
+
|
|
81
|
+
Shadows (`shadowColor`, `shadowBlur`, `shadowOffsetX`, `shadowOffsetY`) are
|
|
82
|
+
painted from the operation's own alpha: the draw is first rendered into a
|
|
83
|
+
scratch layer, its alpha is offset and box-blurred (three separable passes),
|
|
84
|
+
tinted with `shadowColor`, composited, and the unfiltered layer is drawn over
|
|
85
|
+
it. The offset and blur are in canvas (device) units and are not affected by
|
|
86
|
+
the transform, as the API specifies. `clearRect` and `putImageData` never cast
|
|
87
|
+
a shadow.
|
|
88
|
+
|
|
89
|
+
`isPointInPath(x, y[, fillRule])`, `isPointInPath(path, x, y[, fillRule])`,
|
|
90
|
+
`isPointInStroke(x, y)` and `isPointInStroke(path, x, y)` hit-test the current
|
|
91
|
+
path (or the supplied `Path2D`) under the current transform; stroke hit testing
|
|
92
|
+
uses the device-space distance to each flattened segment and the current line
|
|
93
|
+
width.
|
|
55
94
|
|
|
56
95
|
A fill or stroke paints with a solid colour **or a `CanvasGradient`**. Gradient
|
|
57
96
|
coordinates are user-space coordinates, so the rasteriser maps each device pixel
|
|
@@ -67,6 +106,33 @@ decode table). It is released when the node is dropped (`loadHTML`, window
|
|
|
67
106
|
close/quit, or a mutation that discards the subtree), which also releases the
|
|
68
107
|
matching GPU texture.
|
|
69
108
|
|
|
109
|
+
## Performance
|
|
110
|
+
|
|
111
|
+
A canvas is redrawn by the script, not by the engine, so its cost is per drawing
|
|
112
|
+
call. With many elements the hot paths are deliberately branch-light:
|
|
113
|
+
|
|
114
|
+
- a solid, opaque `fillRect` is a byte store into the bitmap (fractional edges
|
|
115
|
+
still take the anti-aliased path), and `clearRect` over the whole bitmap is a
|
|
116
|
+
single `memset`;
|
|
117
|
+
- path coverage is rasterised with a per-row **active-edge list**, and only the
|
|
118
|
+
**covered span of each row** is materialised — a thin diagonal stroke costs
|
|
119
|
+
its own pixels, not its bounding box;
|
|
120
|
+
- one `stroke()` batches all of its segment quads, joins and caps into a single
|
|
121
|
+
non-zero fill instead of one coverage pass per piece (each piece's winding is
|
|
122
|
+
normalised first, so overlapping pieces cover rather than cancel);
|
|
123
|
+
- `fillText` shares the shaped-run cache with layout (`text_cache.cpp`) and uses
|
|
124
|
+
a bounded two-generation glyph bitmap cache (`text_glyph_cache.cpp`);
|
|
125
|
+
- `drawImage` at integer offsets with no scaling copies one texel per pixel
|
|
126
|
+
instead of running the bilinear sampler.
|
|
127
|
+
|
|
128
|
+
The bitmap reaches the screen through a **dirty rectangle**: every draw unions
|
|
129
|
+
its device-space bounds, and the renderer copies only that region into the
|
|
130
|
+
canvas texture. All of a frame's canvas and video uploads share the frame's one
|
|
131
|
+
upload command buffer, so K animated canvases cost one submit rather than K.
|
|
132
|
+
`getImageData` always reads the CPU bitmap, so it is unaffected.
|
|
133
|
+
`tests/e2e/gui-draw-perf.test.ts` measures the multi-element paths and pins the
|
|
134
|
+
counter behaviour (one upload per frame, only the dirty bytes).
|
|
135
|
+
|
|
70
136
|
## Supported API
|
|
71
137
|
|
|
72
138
|
State and transforms: `save` / `restore` (which restore the transform, line
|
|
@@ -79,34 +145,43 @@ canvas order: `translate(x, y); rotate(a)` rotates around the translated origin.
|
|
|
79
145
|
|
|
80
146
|
Styles and settings: `fillStyle` / `strokeStyle` (CSS colors understood by the
|
|
81
147
|
cascade's color parser, or a `CanvasGradient`), `lineWidth`, `globalAlpha`,
|
|
148
|
+
`globalCompositeOperation`, `shadowColor` / `shadowBlur` / `shadowOffsetX` /
|
|
149
|
+
`shadowOffsetY`, `imageSmoothingEnabled` / `imageSmoothingQuality`,
|
|
82
150
|
`lineCap` (`butt`/`round`/`square`), `lineJoin` (`miter`/`round`/`bevel`),
|
|
83
151
|
`miterLimit`, `lineDashOffset`, `font` (a CSS font shorthand resolving to
|
|
84
152
|
family, size and bold/italic — default `10px sans-serif`), `textAlign`
|
|
85
153
|
(`start`/`left`, `center`, `right`/`end`) and `textBaseline` (`alphabetic`,
|
|
86
154
|
`top`, `middle`, `bottom`, `hanging`, `ideographic`). Reading a property returns
|
|
87
155
|
the value last assigned; assigning an unparseable color keeps the previous one.
|
|
156
|
+
`imageSmoothingEnabled` defaults to `true` (bilinear sampling);
|
|
157
|
+
`imageSmoothingQuality` reports `low`, `medium` or `high` and selects the same
|
|
158
|
+
bilinear filter in this backend.
|
|
88
159
|
|
|
89
160
|
Gradients: `createLinearGradient(x0, y0, x1, y1)` and
|
|
90
161
|
`createRadialGradient(x0, y0, r0, x1, y1, r1)` return a `CanvasGradient` with
|
|
91
162
|
`addColorStop(offset, color)`. Stops stay live, so a stop added after
|
|
92
163
|
`fillStyle = gradient` affects later fills, and the `fillStyle`/`strokeStyle`
|
|
93
|
-
getter returns the same gradient handle.
|
|
94
|
-
|
|
95
|
-
|
|
164
|
+
getter returns the same gradient handle. A radial gradient is the general
|
|
165
|
+
two-circle cone: the colour at a point is resolved from the interpolated circle
|
|
166
|
+
(`centre = c0 + t·(c1 − c0)`, `radius = r0 + t·(r1 − r0)`), so an offset inner
|
|
167
|
+
circle and different radii behave like a browser's. A point inside the inner
|
|
168
|
+
circle samples stop 0.
|
|
96
169
|
|
|
97
170
|
Paths: `beginPath`, `closePath`, `moveTo`, `lineTo`, `rect`, `roundRect`,
|
|
98
171
|
`arc`, `ellipse`, `quadraticCurveTo`, `bezierCurveTo`, then
|
|
99
172
|
`fill(fillRule?)` / `fill(path, fillRule?)` (multi-loop; `"nonzero"` or
|
|
100
|
-
`"evenodd"`)
|
|
101
|
-
|
|
102
|
-
|
|
173
|
+
`"evenodd"`), `stroke(path?)`, `clip(path?, fillRule?)` and the
|
|
174
|
+
`isPointInPath`/`isPointInStroke` hit tests. Bezier and quadratic segments are
|
|
175
|
+
flattened into line segments; arcs and ellipses are flattened too. `roundRect`
|
|
176
|
+
accepts a single radius number or the CSS radius list (`[all]`, `[tl, br]`,
|
|
103
177
|
`[tl, tr, br]`, `[tl, tr, br, bl]`, numbers or `{ x, y }` pairs; corners are
|
|
104
178
|
drawn circular).
|
|
105
179
|
|
|
106
180
|
`Path2D` is implemented with the same path commands (`moveTo`, `lineTo`,
|
|
107
181
|
`closePath`, `rect`, `roundRect`, `arc`, `ellipse`, `quadraticCurveTo`,
|
|
108
|
-
`bezierCurveTo`, `addPath`) and can be passed to `fill`/`stroke
|
|
109
|
-
be built once and replayed under different
|
|
182
|
+
`bezierCurveTo`, `addPath`) and can be passed to `fill`/`stroke`/`clip` and the
|
|
183
|
+
`isPointIn*` hit tests, so a path can be built once and replayed under different
|
|
184
|
+
transforms.
|
|
110
185
|
|
|
111
186
|
Rectangles: `clearRect`, `fillRect`, `strokeRect`.
|
|
112
187
|
|
|
@@ -129,35 +204,47 @@ Images: `drawImage(source, …)` in the 3-argument (`dx, dy`), 5-argument
|
|
|
129
204
|
(`dx, dy, dw, dh`) and 9-argument (`dx, dy, dw, dh, sx, sy, sw, sh`; this
|
|
130
205
|
engine's 9-argument form is destination-first) forms. A full affine transform
|
|
131
206
|
(rotation/skew/scale) is honoured: the destination rectangle becomes a
|
|
132
|
-
parallelogram and every device pixel is inverse-mapped to the source rectangle
|
|
133
|
-
|
|
134
|
-
`<canvas
|
|
135
|
-
|
|
136
|
-
|
|
207
|
+
parallelogram and every device pixel is inverse-mapped to the source rectangle.
|
|
208
|
+
`source` may be an `<img>` element (decoded through the image module), another
|
|
209
|
+
`<canvas>`, an `OffscreenCanvas`, an `ImageBitmap`, or — an engine extension — a
|
|
210
|
+
string path/`data:` URL that is decoded directly, so an SVG or bitmap data URL
|
|
211
|
+
can be drawn without an `<img>`. A vector source is rasterised at the destination
|
|
212
|
+
size (`dw`/`dh`), keeping a scaled SVG crisp. Sampling is bilinear when
|
|
213
|
+
`imageSmoothingEnabled` is `true` (the default) and nearest-neighbour when it is
|
|
214
|
+
`false`.
|
|
137
215
|
|
|
138
216
|
Test hook: `getImageData(x, y, w, h)` copies a region to
|
|
139
217
|
`{ width, height, data }` where `data` is a row-major RGBA8 byte array.
|
|
140
218
|
Out-of-bounds pixels are transparent.
|
|
141
219
|
|
|
142
|
-
Patterns: `createPattern(source, repetition?)` accepts an `<img
|
|
143
|
-
`<canvas
|
|
144
|
-
`no-repeat`), so the tiles follow the
|
|
145
|
-
`fillStyle`/`strokeStyle`; assigning a
|
|
220
|
+
Patterns: `createPattern(source, repetition?)` accepts an `<img>`,
|
|
221
|
+
`<canvas>`, `OffscreenCanvas` or `ImageBitmap` and tiles it in user space
|
|
222
|
+
(`repeat`, `repeat-x`, `repeat-y`, `no-repeat`), so the tiles follow the
|
|
223
|
+
current transform. Assign the result to `fillStyle`/`strokeStyle`; assigning a
|
|
224
|
+
colour replaces it.
|
|
146
225
|
|
|
147
226
|
Image data and export: `createImageData(width, height)` allocates a blank
|
|
148
227
|
`{ width, height, data }`, and `putImageData(imageData, dx, dy[, dirtyX, dirtyY,
|
|
149
228
|
dirtyWidth, dirtyHeight])` copies bytes straight into the bitmap (no transform,
|
|
150
|
-
blending or `globalAlpha`). `canvas.toDataURL(type?)` exports a PNG data
|
|
151
|
-
`canvas.toBlob(callback, type?)` delivers a Blob-shaped `{ type, size }`
|
|
152
|
-
microtask (the bytes are on `__xt_gui_blob_data`; there is no
|
|
153
|
-
`URL.createObjectURL`).
|
|
229
|
+
blending, clip or `globalAlpha`). `canvas.toDataURL(type?)` exports a PNG data
|
|
230
|
+
URL and `canvas.toBlob(callback, type?)` delivers a Blob-shaped `{ type, size }`
|
|
231
|
+
from a microtask (the bytes are on `__xt_gui_blob_data`; there is no
|
|
232
|
+
`URL.createObjectURL`). `OffscreenCanvas.convertToBlob()` resolves to the same
|
|
233
|
+
shape and `transferToImageBitmap()` snapshots the bitmap.
|
|
234
|
+
|
|
235
|
+
CSS backgrounds: `background-image: url(...)` accepts a file path or a `data:`
|
|
236
|
+
URL (a raster payload or an SVG document, base64 or percent-encoded), so a
|
|
237
|
+
canvas can be used as a CSS background by exporting it first
|
|
238
|
+
(`element.style.backgroundImage = "url(" + canvas.toDataURL() + ")"`). An image
|
|
239
|
+
layer is stretched to the element's border box; `background-size`,
|
|
240
|
+
`background-position` and tiling are not modelled.
|
|
154
241
|
|
|
155
242
|
## Not implemented
|
|
156
243
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
244
|
+
Smoothing quality has one filter (bilinear) on this backend. Offscreen canvases
|
|
245
|
+
support the 2D context only (a WebGL context needs a DOM element for its
|
|
246
|
+
texture table). Text under a rotated or skewed transform places glyphs on the
|
|
247
|
+
transformed baseline but does not rotate the glyph bitmaps, and `strokeText`
|
|
248
|
+
fills with the stroke style rather than outlining.
|
|
162
249
|
See also [Media](./media.md) for the image/video/audio decode stack that
|
|
163
250
|
`drawImage` and the texture upload share.
|
package/doc/gui/known-issues.md
CHANGED
|
@@ -11,16 +11,17 @@
|
|
|
11
11
|
glslang — consumed directly by the Vulkan backend, or cross-compiled to MSL by
|
|
12
12
|
the bundled SPIRV-Cross for Metal — and the drawing buffer is an offscreen
|
|
13
13
|
colour texture that the page composites without a readback. WebGL 2 adds VAOs,
|
|
14
|
-
instancing, integer attributes, sampler objects, `texStorage2D
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
14
|
+
instancing, integer attributes, sampler objects, `texStorage2D`, buffer copies,
|
|
15
|
+
uniform blocks, cube/3D/array textures, float/depth/compressed textures,
|
|
16
|
+
multiple render targets and scissored clears. `blitFramebuffer` copies colour
|
|
17
|
+
and depth; transform feedback, MSAA and stencil blits are not implemented
|
|
18
|
+
(SDL_GPU has no transform-feedback stage, its Metal multisample resolve is
|
|
19
|
+
unreliable, and a stencil attachment is not sampleable). On an SDL_GPU backend
|
|
20
|
+
that accepts neither SPIR-V nor MSL (Direct3D 12, which would need DXIL) both
|
|
21
|
+
context kinds are `null`. The `.js` asset loader now patches only three.js's
|
|
22
|
+
shader unroller; `WebGLRenderer` runs on the real backend and there is no
|
|
23
|
+
Canvas2D fallback. Shadow maps (comparative `sampler2DShadow` targeting depth
|
|
24
|
+
textures), cube textures/environment maps and HDR render targets are supported.
|
|
24
25
|
|
|
25
26
|
|
|
26
27
|
|
|
@@ -58,18 +59,22 @@
|
|
|
58
59
|
`pointer-events`, `@media` queries, generated content (`::before`/`::after`),
|
|
59
60
|
multi-layer linear/radial backgrounds, `text-shadow`, `clip-path`
|
|
60
61
|
(`inset`/`circle`/`ellipse`/`polygon`) and `filter` colour functions are
|
|
61
|
-
implemented. Known limits: `
|
|
62
|
-
`background-position`/`size`/`repeat
|
|
63
|
-
|
|
64
|
-
|
|
62
|
+
implemented. Known limits: `background-clip`,
|
|
63
|
+
`background-position`/`size`/`repeat` and `backdrop-filter` compositing are not
|
|
64
|
+
implemented (`backdrop-filter` parses and cascades, but sampling the backdrop
|
|
65
|
+
needs an offscreen layer, so it paints nothing); `mix-blend-mode` and repeating
|
|
66
|
+
gradients are implemented (see [Rendering](./rendering.md)), but group
|
|
67
|
+
`opacity` is a per-shape alpha rather than a true group composite, and the
|
|
68
|
+
blend compositor is unavailable on the D3D12/DXIL backend, where groups fall
|
|
69
|
+
back to normal source-over painting;
|
|
65
70
|
`filter: blur()` is a nine-tap per-shape spread rather than a true group blur,
|
|
66
71
|
so overlapping descendants can darken; `drop-shadow` is approximated from box
|
|
67
72
|
silhouettes; at most two nested `clip-path` shapes are intersected (deeper
|
|
68
73
|
nesting keeps the outer two); and images/canvases are not colour-filtered
|
|
69
74
|
except for the brightness/opacity tint the image shader can carry. Canvas
|
|
70
75
|
textures are sampled nearest-neighbour. Background gradients remain solid
|
|
71
|
-
bands (18 for linear, 32 concentric ellipses for radial
|
|
72
|
-
may show slight banding.
|
|
76
|
+
bands (18 for linear, 32 concentric ellipses for radial; 64 for repeating
|
|
77
|
+
gradients), so a soft gradient may show slight banding.
|
|
73
78
|
- **SVG is NanoSVG's subset.** SVG *files* (`<img src="logo.svg">`) and inline
|
|
74
79
|
`<svg>` trees share the vendored NanoSVG parser/rasteriser
|
|
75
80
|
(`runtime/ext_gui/svg.cpp`, `inline_svg.cpp`), which renders
|
|
@@ -77,9 +82,32 @@
|
|
|
77
82
|
gradients and class-based `<style>` rules. `<text>`, `<use>`, filters, masks
|
|
78
83
|
and clip paths are not rendered, and CSS applied by the document cascade does
|
|
79
84
|
not reach inside the artwork (fill/stroke are SVG presentation attributes,
|
|
80
|
-
not CSS properties here).
|
|
81
|
-
|
|
82
|
-
|
|
85
|
+
not CSS properties here). An SVG whose only artwork comes from a filter
|
|
86
|
+
(`feTurbulence` noise, blur, …) therefore shows the unfiltered shapes — often
|
|
87
|
+
a solid rect — rather than the filter result. Vector art that needs those has
|
|
88
|
+
to be rasterised beforehand, drawn from boxes, or restricted to the supported
|
|
89
|
+
syntax. See [Media](./media.md#images-m6a).
|
|
90
|
+
- **Rendering is still whole-document per change.** A DOM mutation recomputes
|
|
91
|
+
the cascade and lays out the complete document again (there is no incremental
|
|
92
|
+
subtree invalidation), and a change that only affects paint (a hover colour,
|
|
93
|
+
for example) reflows too. Documents with generated content
|
|
94
|
+
(`::before`/`::after`) are not special-cased. The measured cost of each stage
|
|
95
|
+
is exposed by `win.stats()`/`XT_GUI_PERF`, which is what a follow-up would be
|
|
96
|
+
keyed off; see [Performance](./rendering.md#performance-m20).
|
|
97
|
+
- **Draw calls follow painter order.** Runs only merge when they are
|
|
98
|
+
consecutive in painter order and share pipeline, clip and texture, so a list
|
|
99
|
+
whose rows alternate a background and text costs one shape run and one text
|
|
100
|
+
run per row (`drawCalls` in `win.stats()`). Reordering for fewer draw calls
|
|
101
|
+
needs an overlap-aware batcher (text may be covered by a later background) and
|
|
102
|
+
is not implemented. Measured: the 200-row perf page issues 400 draw calls and
|
|
103
|
+
spends about 0.4 ms in the draw phase, so this is a follow-up for
|
|
104
|
+
draw-call-dominated pages rather than the current bottleneck.
|
|
105
|
+
- **The text shaping cache is bounded.** Two generations of up to 2 MiB of
|
|
106
|
+
glyphs / 8,192 entries hold `(face, text) -> glyphs`. A document with more
|
|
107
|
+
distinct words than that re-shapes some of them after a cache rotation;
|
|
108
|
+
`textCacheBytes`/`textShapeHits` in `win.stats()` show whether it is the
|
|
109
|
+
bottleneck. Inline `style="…"` attributes are re-parsed on each restyle of
|
|
110
|
+
the element that carries them.
|
|
83
111
|
|
|
84
112
|
## Open questions
|
|
85
113
|
|
package/doc/gui/media.md
CHANGED
|
@@ -43,6 +43,15 @@ subtree, whose DOM nodes are serialized into a document first
|
|
|
43
43
|
without limit.
|
|
44
44
|
- The parse is cached per path; the parse and rasteriser state are released in
|
|
45
45
|
`xt_svg_shutdown` (`xt_image_shutdown`).
|
|
46
|
+
- `data:` URLs are decoded in memory and work wherever a path does:
|
|
47
|
+
`<img src>`, CSS `background-image` and `canvas.drawImage(url, …)`. Both the
|
|
48
|
+
`;base64` form and a percent-encoded (or plain) payload are accepted, and the
|
|
49
|
+
`base64` flag is case-insensitive. The MIME type only classifies the payload:
|
|
50
|
+
`image/svg+xml` (or an SVG sniff when the type is generic or absent) goes
|
|
51
|
+
through NanoSVG — a data-URL SVG is rasterised at the drawn size exactly like
|
|
52
|
+
an SVG file — while PNG/JPEG/BMP/GIF/TGA go through `stb_image`. NanoSVG's
|
|
53
|
+
subset still applies: an SVG whose only artwork comes from `<filter>`
|
|
54
|
+
(`feTurbulence`, …) decodes and lays out, but the filter itself is ignored.
|
|
46
55
|
|
|
47
56
|
Document CSS styles the `<svg>` **box** — size, margins, background, borders,
|
|
48
57
|
`transform`, opacity, `display` — exactly as it styles any other element. The
|
|
@@ -55,8 +64,8 @@ renderer caches one texture per markup-and-size pair, so a program that rewrites
|
|
|
55
64
|
its artwork every frame keeps a texture per variant; prefer animating the box
|
|
56
65
|
(`transform`, `opacity`) or swapping between a small set of documents.
|
|
57
66
|
|
|
58
|
-
Still to do for images:
|
|
59
|
-
`
|
|
67
|
+
Still to do for images: `object-fit` and 9-slice borders. (CSS
|
|
68
|
+
`background-image: url(...)` and `data:` URLs are supported.)
|
|
60
69
|
|
|
61
70
|
Both kinds of SVG share NanoSVG's subset: `path`, `rect`, `circle`, `ellipse`,
|
|
62
71
|
`line`, `polyline`, `polygon`, groups (`g`), `defs` with linear/radial gradients
|
package/doc/gui/rendering.md
CHANGED
|
@@ -15,12 +15,14 @@ up to two indices into the display list's triangulated `clip-path` polygons, so
|
|
|
15
15
|
`overflow`/`clip-path` clipping and `z-index` ordering survive into the renderer.
|
|
16
16
|
`DisplayList::dump()` feeds `paintList()`/`paintCount()`.
|
|
17
17
|
|
|
18
|
-
`opacity`
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
18
|
+
`opacity` multiplies the alpha of every colour painted by the box and its
|
|
19
|
+
descendants (the values multiply down the paint chain), so fractional opacity and
|
|
20
|
+
the `opacity` transitions the CSS parser accepts are visible. It is a
|
|
21
|
+
per-shape approximation, not an offscreen group: overlapping children of a
|
|
22
|
+
translucent box composite individually, whereas a browser composes the group
|
|
23
|
+
once and then applies the alpha. `opacity: 0` still skips the whole subtree.
|
|
24
|
+
Hiding and revealing a layer with `opacity: 0` on the hidden state is what
|
|
25
|
+
`examples/gui/pelican-bike`'s game-over overlay does.
|
|
24
26
|
|
|
25
27
|
`runtime/ext_gui/renderer.{h,cpp}` turns that list into batched vertex buffers
|
|
26
28
|
per window (shapes, glyph quads and images) and merges consecutive ops that
|
|
@@ -80,14 +82,23 @@ The window background (`setBackground`) is the render-pass clear colour.
|
|
|
80
82
|
comma-separated layer list is painted bottom-up (the first declaration layer is
|
|
81
83
|
topmost), and both gradient kinds are supported:
|
|
82
84
|
|
|
83
|
-
- a **linear** gradient is sampled at 18 points
|
|
84
|
-
`to <side>`, `deg`/`grad`/`rad`/`turn`, percentage
|
|
85
|
-
(
|
|
86
|
-
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
85
|
+
- a **linear** gradient is sampled at 18 points (64 when repeating) and emitted
|
|
86
|
+
as solid rectangles; `to <side>`, `deg`/`grad`/`rad`/`turn`, percentage or
|
|
87
|
+
length (`px`/`em`/…) offsets, the `color <start> <end>` shorthand and
|
|
88
|
+
multi-stop colours work (the band walk is axis-aligned, so an oblique angle
|
|
89
|
+
uses the nearest axis);
|
|
90
|
+
- a **radial** gradient is 32 concentric ellipses (64 when repeating). Each is a
|
|
91
|
+
unit-radius rounded rectangle mapped through the shape pipeline's transform
|
|
92
|
+
slot, so a circle or ellipse keeps the distance-field antialiasing.
|
|
93
|
+
Shape/size keywords (`circle`/`ellipse`, `closest-side`/`farthest-side`/
|
|
94
|
+
`closest-corner`/`farthest-corner`, explicit radii) and `at <position>` are
|
|
95
|
+
parsed.
|
|
96
|
+
|
|
97
|
+
`repeating-linear-gradient()` and `repeating-radial-gradient()` tile the stop
|
|
98
|
+
pattern from 0 to the last stop's offset across the whole box; the stop list is
|
|
99
|
+
not forced to end at 100%, so `red 0%, blue 10%` repeats every 10%. A normal
|
|
100
|
+
gradient whose last stop is below 100% holds that colour for the rest of the box,
|
|
101
|
+
as in CSS.
|
|
91
102
|
|
|
92
103
|
The background colour sits under every layer. Gradients are partially
|
|
93
104
|
transparent if their stops are, and the band approximation can show banding and
|
|
@@ -117,10 +128,24 @@ nesting keeps the outermost two.
|
|
|
117
128
|
colour, so a box and its descendants see the filter. `blur()` and
|
|
118
129
|
`drop-shadow()` are approximations at the display-list level: blur spreads nine
|
|
119
130
|
translucent copies per shape, drop-shadow is a box/text silhouette. This keeps
|
|
120
|
-
the
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
131
|
+
the ordinary painter single-pass at the cost of group semantics: overlapping
|
|
132
|
+
descendants of a blurred/filtered group can darken, and `backdrop-filter` cannot
|
|
133
|
+
sample what is behind the element, so it parses and cascades but paints nothing.
|
|
134
|
+
|
|
135
|
+
**`mix-blend-mode`** is the exception that does need an offscreen layer. A box
|
|
136
|
+
with a non-`normal` mode is wrapped in `LayerBegin`/`LayerEnd` markers (visible
|
|
137
|
+
in `paintList()` as `layer blend=…` / `end-layer`); the renderer draws that group
|
|
138
|
+
to a full-viewport offscreen texture and composites it over the scene with a
|
|
139
|
+
small GLSL blend shader. All sixteen CSS modes (`multiply`, `screen`, `overlay`,
|
|
140
|
+
`darken`, `lighten`, `color-dodge`, `color-burn`, `hard-light`, `soft-light`,
|
|
141
|
+
`difference`, `exclusion`, `hue`, `saturation`, `color`, `luminosity`) are
|
|
142
|
+
implemented with the compositing-spec formulas. The shader is compiled at run
|
|
143
|
+
time by the bundled glslang (SPIR-V for Vulkan) and cross-compiled to MSL by
|
|
144
|
+
SPIRV-Cross (Metal); the two scene textures per nesting level are reused across
|
|
145
|
+
frames and ping-pong so the backdrop stays sampleable while it is written.
|
|
146
|
+
Backends that consume neither format — the D3D12/DXIL path, which has no shader
|
|
147
|
+
compiler here — keep painting the group with ordinary source-over blending.
|
|
148
|
+
`backdrop-filter` still paints nothing.
|
|
124
149
|
|
|
125
150
|
## Text stack (M4b)
|
|
126
151
|
|
|
@@ -160,3 +185,80 @@ cascades but paints nothing.
|
|
|
160
185
|
- Layout uses these real metrics for text widths, line breaking and
|
|
161
186
|
`line-height: normal`; `measureText`/`fontMetrics` expose them to tests.
|
|
162
187
|
|
|
188
|
+
## Performance (M20)
|
|
189
|
+
|
|
190
|
+
The engine is a retained-mode pipeline: a DOM mutation restyles the document,
|
|
191
|
+
lays it out, rebuilds the display list and uploads vertex arrays; a frame that
|
|
192
|
+
changes nothing does no CPU or GPU work. A document with thousands of elements
|
|
193
|
+
is kept interactive by budgeting each stage, and every stage is measured. Set
|
|
194
|
+
`XT_GUI_PERF=1` to print one line per frame (or `XT_GUI_PERF=<N>` for an
|
|
195
|
+
aggregated line every N frames); `win.stats()` returns the same counters, which
|
|
196
|
+
is what `tests/e2e/gui-perf.test.ts` asserts on.
|
|
197
|
+
|
|
198
|
+
- **Cascade.** An `@media` prelude is evaluated **once per rule** per restyle
|
|
199
|
+
(it used to be parsed once per rule *and* node, which was the largest cost on
|
|
200
|
+
a large document). A sheet without `::before`/`::after` rules skips generated
|
|
201
|
+
content entirely, the declaration candidate list is reused across the
|
|
202
|
+
depth-first walk instead of allocated per element, and `:hover`/`:focus` only
|
|
203
|
+
restyle when the sheet actually has such a rule.
|
|
204
|
+
- **Text.** Layout and paint share a bounded shaping cache (`text_cache.cpp`):
|
|
205
|
+
`(face, text) -> glyphs + advance`. It uses two generations of up to 2 MiB of
|
|
206
|
+
glyphs / 8,192 entries; when a generation is full the *spare* one is dropped
|
|
207
|
+
and becomes current, so the hot path has no LRU bookkeeping. A word is shaped
|
|
208
|
+
once and reused by every later layout pass and repaint that draws it. Primary
|
|
209
|
+
face lookups are cached by (family class, size) as well.
|
|
210
|
+
- **Frame loop.** The media/canvas tables are reconciled with the DOM only when
|
|
211
|
+
the document changed (or on the first frame) instead of walking the tree every
|
|
212
|
+
frame. A frame presents only when something happened — a mutation, a scroll,
|
|
213
|
+
an animation frame, a transition, a new video/canvas frame, an expose/resize
|
|
214
|
+
event — so a static page performs no swapchain acquire and no draw at all.
|
|
215
|
+
An expose is the one present the window system asks for rather than the page,
|
|
216
|
+
and `exposes` counts those frames, so `presents - exposes - deferred` stays
|
|
217
|
+
the document's own work even when a window server maps the window late.
|
|
218
|
+
A frame that cannot get a swapchain image (SDL's non-blocking acquire skips a
|
|
219
|
+
frame while the GPU still holds the image, and a minimized window has none)
|
|
220
|
+
keeps its invalidation pending instead of dropping it, so the paint is
|
|
221
|
+
presented on the next frame; those presents are counted as `deferred`.
|
|
222
|
+
`XT_GUI_ALWAYS_PRESENT=1` restores the old always-present behaviour when
|
|
223
|
+
debugging a missed invalidation.
|
|
224
|
+
- **Paint and upload.** The display list and the vertex staging arrays are kept
|
|
225
|
+
on the window and cleared per repaint, so their capacity survives. All of a
|
|
226
|
+
dirty frame's vertex/atlas uploads share one command buffer (one submit),
|
|
227
|
+
the geometry's staging transfer buffer is reused (cycled while the previous
|
|
228
|
+
copy may still be in flight), and paint skips the z-index sort and temporary
|
|
229
|
+
vector when no child stacks.
|
|
230
|
+
- **Draw.** Consecutive ops with the same pipeline, clip and texture still merge
|
|
231
|
+
into one run, and the renderer now only re-binds a pipeline/vertex
|
|
232
|
+
buffer/scissor when it actually changes. `drawCalls`/`drawMs` in `win.stats()`
|
|
233
|
+
report the run count and its cost; they are the metric for the remaining
|
|
234
|
+
follow-up (an overlap-aware batching pass) — painter order requires
|
|
235
|
+
alternating background and text runs to stay separate until that lands.
|
|
236
|
+
- **Immediate-mode surfaces.** `<canvas>` 2D and WebGL draws are script-driven,
|
|
237
|
+
so their cost is per call rather than per document change; the counters above
|
|
238
|
+
cover the retained pipeline only. `tests/e2e/gui-draw-perf.test.ts` measures
|
|
239
|
+
them: on the reference Windows x64/Vulkan machine a 1280×720 frame with 5,000
|
|
240
|
+
solid `fillRect`s, 200 eight-point strokes, 300 `fillText` runs and 200 1:1
|
|
241
|
+
`drawImage`s fell from 231ms to 158ms (fill 4.3ms, stroke 151ms, text 1.4ms,
|
|
242
|
+
image 1.6ms), and 2,000 WebGL `drawElements` calls with a per-draw matrix went
|
|
243
|
+
from 38.6ms to 27.5ms while the render passes opened per frame dropped from
|
|
244
|
+
2,001 to 1 and a 64 KiB `bufferSubData` into a 4 MiB buffer stopped
|
|
245
|
+
re-uploading the whole buffer. A 100×100 canvas redraw now uploads 40 KB
|
|
246
|
+
rather than the whole 1.2 MB bitmap. The suite asserts the counters (one
|
|
247
|
+
upload per frame, no steady-state pipeline creation, only the dirty bytes), so
|
|
248
|
+
the wall-clock numbers stay informational and a software GPU in CI is not
|
|
249
|
+
penalised.
|
|
250
|
+
|
|
251
|
+
Known limits: a mutation still restyles and relayouts the **whole** document
|
|
252
|
+
(there is no incremental subtree invalidation), and a paint-only change (for
|
|
253
|
+
example a hover colour) currently reflows too; `win.stats()` is what a follow-up
|
|
254
|
+
would be keyed off. Inline `style="…"` attributes are re-parsed on every restyle
|
|
255
|
+
of the element that carries them.
|
|
256
|
+
|
|
257
|
+
As a reference point, `tests/e2e/gui-perf.test.ts` builds a 200-row list (about
|
|
258
|
+
1,000 elements, 400 draw runs) and prints the numbers it measured, e.g.
|
|
259
|
+
`textFrame=5.2ms restyle=3.6ms layout=1.7ms paint=1.0ms upload=0.8ms draw=0.4ms`
|
|
260
|
+
for a one-field `textContent` change on a Windows x64/Vulkan machine. The
|
|
261
|
+
absolute values are host-specific; the test asserts the *counters* (one restyle,
|
|
262
|
+
one layout, cache hits instead of shapes, no work on an idle frame), which are
|
|
263
|
+
what a regression would change.
|
|
264
|
+
|
package/doc/gui/runtime.md
CHANGED
|
@@ -18,11 +18,26 @@ expose an explicit `run()`; **M2 uses the explicit `run()`** so the window is a
|
|
|
18
18
|
plain native call the TypeScript program controls. Each tick it:
|
|
19
19
|
|
|
20
20
|
1. pumps SDL window/input events for every window,
|
|
21
|
-
2.
|
|
21
|
+
2. reconciles the decoder/canvas tables with the DOM **only when the document
|
|
22
|
+
changed** (or on the first frame),
|
|
23
|
+
3. builds/uploads the display list when it changed and renders every open
|
|
22
24
|
window (clear pass + shape geometry + text geometry),
|
|
23
|
-
|
|
25
|
+
4. calls `xt_loop_poll(0)` and `xt_drain_microtasks()` so sockets/timers and
|
|
24
26
|
`await` continuations keep making progress,
|
|
25
|
-
|
|
27
|
+
5. repeats until all windows close or `quit()` is called.
|
|
28
|
+
|
|
29
|
+
A frame **presents only when something happened**: a DOM mutation, a scroll, a
|
|
30
|
+
queued animation frame, a running transition, a new video/canvas frame, an
|
|
31
|
+
expose/resize event, or the first frame. A static document therefore performs no
|
|
32
|
+
swapchain acquire and no draw while the loop keeps servicing events, timers and
|
|
33
|
+
promises; `XT_GUI_ALWAYS_PRESENT=1` restores the old always-present behaviour
|
|
34
|
+
when debugging a missed invalidation. An expose/shown/restore event is the one
|
|
35
|
+
present the *window system* asks for rather than the document, so it is counted
|
|
36
|
+
as `exposes` in `win.stats()`; a present a starved frame had to postpone (no
|
|
37
|
+
swapchain image was available) is counted as `deferred`, and
|
|
38
|
+
`presents - exposes - deferred` is the work the page caused. `XT_GUI_PERF=1`
|
|
39
|
+
prints what each frame did (see
|
|
40
|
+
[Performance](./rendering.md#performance-m20)).
|
|
26
41
|
|
|
27
42
|
The `xt_loop_set_main` hook remains available for hosts that want to own the
|
|
28
43
|
loop themselves.
|
package/doc/gui/webgl.md
CHANGED
|
@@ -36,9 +36,10 @@ reports the type as well.
|
|
|
36
36
|
`height` attributes. `canvas.width = …` recreates them and discards the
|
|
37
37
|
contents, like the DOM rule.
|
|
38
38
|
- The context records into its own SDL_GPU command buffer. `clear`/`draw*`
|
|
39
|
-
keep a render pass open; a buffer/texture upload or a framebuffer
|
|
40
|
-
it and starts a new pass with `LOAD`, so the drawing buffer
|
|
41
|
-
draws just like WebGL's
|
|
39
|
+
keep a render pass open; only a buffer/texture upload or a framebuffer
|
|
40
|
+
change ends it and starts a new pass with `LOAD`, so the drawing buffer
|
|
41
|
+
persists between draws just like WebGL's and a draw that has nothing to
|
|
42
|
+
upload never breaks the pass.
|
|
42
43
|
- Once per frame, before the page's own render pass, the engine submits every
|
|
43
44
|
WebGL command buffer. The image pipeline then samples the colour texture as
|
|
44
45
|
an ordinary `PaintImage`, with no CPU copy.
|
|
@@ -89,6 +90,8 @@ The translator (`runtime/ext_gui/webgl_glsl*.cpp`) handles GLSL ES 1.00 and
|
|
|
89
90
|
| non-sampler uniforms | one `layout(std140) uniform XtUniforms { … }` block |
|
|
90
91
|
| `uniform sampler2D u_tex` | `layout(set = 2, binding = N) uniform sampler2D u_tex` (fragment) or set 0 (vertex) |
|
|
91
92
|
| `gl_FragData[0]` | `xt_FragColor` |
|
|
93
|
+
| `gl_FragDepth` / `gl_FragDepthEXT` | kept (SPIR-V `DepthReplacing`; MSL `[[depth(any)]]`) |
|
|
94
|
+
| `sampler2DShadow` / `samplerCubeShadow` / `sampler2DArrayShadow` | kept; bound as an SDL_GPU comparison sampler |
|
|
92
95
|
| a missing `#version` / `#version 100` | `#version 310 es` |
|
|
93
96
|
|
|
94
97
|
Non-sampler uniforms are merged across both stages and emitted as one block in
|
|
@@ -108,6 +111,14 @@ three.js emits becomes constant-indexed. Shader code inside `#ifdef` is fine;
|
|
|
108
111
|
non-sampler uniform declarations are moved to the enclosing top-level position
|
|
109
112
|
so the block stays unconditional.
|
|
110
113
|
|
|
114
|
+
A fragment shader may write `gl_FragDepth`; glslang marks the SPIR-V module
|
|
115
|
+
`DepthReplacing` and SPIRV-Cross emits `[[depth(any)]]`, so the write reaches the
|
|
116
|
+
depth attachment on both backends. The comparative samplers
|
|
117
|
+
(`sampler2DShadow`, `samplerCubeShadow`, `sampler2DArrayShadow`) use the same
|
|
118
|
+
SDL_GPU sampler objects with `enable_compare` set; `TEXTURE_COMPARE_MODE` and
|
|
119
|
+
`TEXTURE_COMPARE_FUNC` are read from the texture (or from a bound sampler
|
|
120
|
+
object in WebGL 2).
|
|
121
|
+
|
|
111
122
|
### GLSL ES 3.00 (WebGL 2)
|
|
112
123
|
|
|
113
124
|
A `#version 300 es` source is accepted as-is apart from the version bump:
|
|
@@ -177,9 +188,10 @@ available from GLSL ES 3.00, which is what the instanced example uses.
|
|
|
177
188
|
`framebufferTexture2D` (`COLOR_ATTACHMENT0`, `DEPTH_ATTACHMENT`,
|
|
178
189
|
`DEPTH_STENCIL_ATTACHMENT`), `checkFramebufferStatus`, `createRenderbuffer`,
|
|
179
190
|
`bindRenderbuffer`, `renderbufferStorage` (depth or depth-stencil),
|
|
180
|
-
`framebufferRenderbuffer`, `delete*`, and `blitFramebuffer` (colour
|
|
181
|
-
|
|
182
|
-
for render-to-texture,
|
|
191
|
+
`framebufferRenderbuffer`, `delete*`, and `blitFramebuffer` (colour through
|
|
192
|
+
SDL's blit; depth through a sampling pass that writes `gl_FragDepth`; stencil
|
|
193
|
+
bits are accepted but not copied). This is enough for render-to-texture,
|
|
194
|
+
shadow maps and post-processing passes.
|
|
183
195
|
- **State**: `enable`/`disable`/`isEnabled` for `BLEND`, `DEPTH_TEST`,
|
|
184
196
|
`CULL_FACE`, `SCISSOR_TEST` and `STENCIL_TEST`,
|
|
185
197
|
`clearColor`/`clearDepth`/`clearStencil`, `clear` (with `SCISSOR_TEST` it
|
|
@@ -248,12 +260,17 @@ backend's `[0, 1]` clip space rather than GL's `[-1, 1] → [0, 1]` remap:
|
|
|
248
260
|
|
|
249
261
|
## Not implemented
|
|
250
262
|
|
|
251
|
-
Transform feedback (the entry points are no-ops
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
263
|
+
Transform feedback (the entry points are no-ops: SDL_GPU has no transform
|
|
264
|
+
feedback stage) and MSAA/sample buffers (SDL_GPU 3.2 can resolve multisampled
|
|
265
|
+
colour targets, but its Metal resolve returns undefined pixels with scissor
|
|
266
|
+
tests and instanced draws, so contexts stay single-sampled and `SAMPLE_BUFFERS`
|
|
267
|
+
reports 0). `blitFramebuffer` copies colour and depth; stencil bits are accepted
|
|
268
|
+
but not copied because SDL_GPU cannot sample a stencil attachment.
|
|
269
|
+
|
|
270
|
+
Shader limitations that remain: struct-typed uniforms and user uniform blocks
|
|
271
|
+
are flattened, but built-in interface blocks (`gl_PerVertex` redeclarations) are
|
|
272
|
+
not part of the translated subset. A shader that uses one still fails with a
|
|
273
|
+
compile/link log rather than silently misbehaving.
|
|
257
274
|
|
|
258
275
|
## Platform
|
|
259
276
|
|
|
@@ -275,7 +292,10 @@ uses the 2D canvas or the DOM pays no run-time cost beyond the archive size.
|
|
|
275
292
|
- `tests/e2e/gui-webgl.test.ts` compiles GLSL, draws a textured and a
|
|
276
293
|
depth-tested quad, checks face culling and reads the pixels back; it also
|
|
277
294
|
covers blend constants, dynamic buffer usage, vertex-shader texture sampling,
|
|
278
|
-
`gl_FragDepth
|
|
295
|
+
`gl_FragDepth`, context loss/restore and cube maps.
|
|
296
|
+
- `tests/e2e/gui-webgl2-shadow-sampler.test.ts` covers hardware
|
|
297
|
+
`sampler2DShadow` comparisons, a shader-written `gl_FragDepth` that occludes a
|
|
298
|
+
later draw, and a partial `blitFramebuffer` depth copy.
|
|
279
299
|
- `tests/e2e/gui-webgl2.test.ts` covers the WebGL 2 shader/state additions:
|
|
280
300
|
`#version 300 es` shaders, a VAO round trip, instanced draws with a divisor,
|
|
281
301
|
`texStorage2D`, `clearBufferfv`, buffer copies, sampler objects, struct-uniform
|
|
@@ -317,9 +337,8 @@ Canvas2D fallback is bundled any more**. Verified with three.js r160 through SDL
|
|
|
317
337
|
`Sprite`, `Line`, `Points` and `InstancedMesh`.
|
|
318
338
|
|
|
319
339
|
Features outside this engine's subset still cannot be emulated: transform
|
|
320
|
-
feedback and MSAA.
|
|
321
|
-
|
|
322
|
-
three.js shadow maps
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
through the GPU.
|
|
340
|
+
feedback and MSAA. Depth textures, float render targets and compressed textures
|
|
341
|
+
are available, and comparative `sampler2DShadow` sampling is translated, so
|
|
342
|
+
three.js shadow maps can use the hardware depth compare on both backends. A
|
|
343
|
+
scene that needs transform feedback or MSAA will not render correctly;
|
|
344
|
+
everything the previous Canvas2D fallback could show now goes through the GPU.
|