xbintsc 0.5.32 → 0.5.37

package/runtime/ext_gui/listener_options.h

@@ -0,0 +1,43 @@
+/*
+ * xbintsc GUI engine — the `addEventListener` options bag.
+ *
+ * Element and window listeners accept the standard third argument:
+ * `capture` / `once` / `passive` (a boolean third argument is the legacy
+ * `capture` spelling) and `signal` (an `AbortSignal`; an aborted signal means
+ * the listener must not run again). Both delivery sites parse it here so the
+ * two paths cannot drift apart.
+ */
+#ifndef XT_GUI_LISTENER_OPTIONS_H
+#define XT_GUI_LISTENER_OPTIONS_H
+
+#include "gui_engine.h"
+
+struct XtGuiListenerOptions {
+  bool capture = false;
+  bool once = false;
+  bool passive = false;
+  xt_value signal = XT_UNDEFINED;
+};
+
+/** True when `signal` is an already-aborted `AbortSignal`. */
+inline bool xt_gui_signal_aborted(xt_value signal) {
+  if (!XT_IS_OBJECT(signal)) return false;
+  xt_value aborted = xt_object_get_cstr(signal, "aborted");
+  return XT_IS_UNDEFINED(aborted) ? false : (xt_truthy(aborted) != 0);
+}
+
+inline XtGuiListenerOptions xt_gui_listener_options(xt_value options) {
+  XtGuiListenerOptions parsed;
+  if (XT_IS_OBJECT(options)) {
+    parsed.capture = xt_truthy(xt_object_get_cstr(options, "capture")) != 0;
+    parsed.once = xt_truthy(xt_object_get_cstr(options, "once")) != 0;
+    parsed.passive = xt_truthy(xt_object_get_cstr(options, "passive")) != 0;
+    xt_value signal = xt_object_get_cstr(options, "signal");
+    if (XT_IS_OBJECT(signal)) parsed.signal = signal;
+  } else if (XT_IS_BOOL(options)) {
+    parsed.capture = xt_truthy(options) != 0;
+  }
+  return parsed;
+}
+
+#endif /* XT_GUI_LISTENER_OPTIONS_H */

package/runtime/ext_gui/media.cpp

@@ -55,6 +55,38 @@ void xt_media_shutdown() {
   if (g_api != nullptr && g_api->shutdown != nullptr) g_api->shutdown();
 }
 
+bool xt_media_decode_audio(const uint8_t* data, size_t size, DecodedAudio* out,
+                           std::string* error) {
+  if (g_api == nullptr || g_api->decode_audio == nullptr) {
+    if (error) {
+      *error = "cannot decode this audio format; enable the 'media' extension (pass --ext media)";
+    }
+    return false;
+  }
+  XtMediaAudioBuffer decoded = {0, 0, 0, nullptr};
+  char message[kErrorSize] = {0};
+  if (g_api->decode_audio(data, size, &decoded, message, sizeof(message)) == 0 ||
+      decoded.samples == nullptr) {
+    if (decoded.samples != nullptr && g_api->free_audio != nullptr) {
+      g_api->free_audio(decoded.samples);
+    }
+    if (error) *error = message[0] != '\0' ? message : "cannot decode audio data";
+    return false;
+  }
+  if (decoded.channels <= 0 || decoded.frames < 0 || decoded.sample_rate <= 0) {
+    if (g_api->free_audio != nullptr) g_api->free_audio(decoded.samples);
+    if (error) *error = "decoder produced an empty audio buffer";
+    return false;
+  }
+  out->channels = decoded.channels;
+  out->sample_rate = decoded.sample_rate;
+  out->frames = static_cast<uint32_t>(decoded.frames);
+  size_t count = static_cast<size_t>(decoded.frames) * static_cast<size_t>(decoded.channels);
+  out->interleaved.assign(decoded.samples, decoded.samples + count);
+  if (g_api->free_audio != nullptr) g_api->free_audio(decoded.samples);
+  return true;
+}
+
 }  // namespace xtgui
 
 extern "C" void xt_media_install(const XtMediaApi* api) { g_api = api; }

package/runtime/ext_gui/media.h

@@ -35,11 +35,24 @@
 #include <memory>
 #include <string>
 
+#include "audio_decode.h"
 #include "image.h"
 #include "media_api.h"
 
 namespace xtgui {
 
+/**
+ * Decode an in-memory audio file (`decodeAudioData`).
+ *
+ * The engine has its own WAV decoder (`audio_decode.cpp`); this entry point is
+ * the fallback for compressed containers and codecs, which only the optional
+ * `media` extension can decode. Without that extension it fails with a message
+ * naming the extension. Implemented in `media.cpp`, which forwards to the
+ * backend table installed by the media bridge.
+ */
+bool xt_media_decode_audio(const uint8_t* data, size_t size, DecodedAudio* out,
+                           std::string* error);
+
 /** DOM events a media element may fire after `tick()`. */
 enum MediaEvent {
   kMediaEventLoadedMetadata = 1 << 0,

package/runtime/ext_gui/media_api.h

@@ -40,10 +40,30 @@ typedef XtMediaPlayerHandle (*XtMediaByIdFn)(uint64_t id);
 /** Tear down every decoder and process-wide media state. */
 typedef void (*XtMediaShutdownFn)(void);
 
+/** Interleaved float PCM returned by the memory decoder.
+ *
+ * `samples` is allocated by the backend and must be released with the table's
+ * `free_audio` entry point (both archives use the same static CRT). */
+typedef struct XtMediaAudioBuffer {
+  int channels;
+  int sample_rate;
+  int frames;
+  float *samples;
+} XtMediaAudioBuffer;
+
+/** Decode an in-memory audio file (`decodeAudioData`). Returns 1 on success and
+ * fills `out`; on failure returns 0 and copies a message into `error`. */
+typedef int (*XtMediaDecodeAudioFn)(const unsigned char *data, size_t size,
+                                    XtMediaAudioBuffer *out, char *error, size_t error_size);
+/** Release the `samples` a successful `decode_audio` allocated. */
+typedef void (*XtMediaFreeAudioFn)(void *samples);
+
 typedef struct XtMediaApi {
   XtMediaOpenFn open;
   XtMediaByIdFn by_id;
   XtMediaShutdownFn shutdown;
+  XtMediaDecodeAudioFn decode_audio;
+  XtMediaFreeAudioFn free_audio;
 } XtMediaApi;
 
 /** Install a decoder table. Implemented by the GUI engine; called once by the
@@ -57,6 +77,9 @@ XtMediaPlayerHandle xt_media_backend_open(const char *path, char *error,
                                           size_t error_size, void *audio_sink);
 XtMediaPlayerHandle xt_media_backend_by_id(uint64_t id);
 void xt_media_backend_shutdown(void);
+int xt_media_backend_decode_audio(const unsigned char *data, size_t size,
+                                  XtMediaAudioBuffer *out, char *error, size_t error_size);
+void xt_media_backend_free_audio(void *samples);
 
 #ifdef __cplusplus
 }

package/runtime/ext_gui/paint.cpp

@@ -246,6 +246,34 @@ void xt_paint_build(const LayoutBox *root, DisplayList &out, float viewportWidth
   paintBox(root, out, none, chain, viewportWidth, viewportHeight);
 }
 
+void xt_paint_translate(DisplayList &list, float dx, float dy) {
+  if (dx == 0.0f && dy == 0.0f) return;
+  for (PaintRect &rect : list.rects) {
+    rect.x += dx;
+    rect.y += dy;
+  }
+  for (PaintText &text : list.texts) {
+    text.x += dx;
+    text.baseline += dy;
+  }
+  for (PaintImage &image : list.images) {
+    image.x += dx;
+    image.y += dy;
+  }
+  for (PaintOp &op : list.ops) {
+    op.clip.x += dx;
+    op.clip.y += dy;
+  }
+  for (ClipPathGeometry &path : list.clip_paths) {
+    for (ClipTriangle &triangle : path.triangles) {
+      for (int i = 0; i < 3; i++) {
+        triangle.x[i] += dx;
+        triangle.y[i] += dy;
+      }
+    }
+  }
+}
+
 std::string DisplayList::dump() const {
   std::string text;
   char buffer[320];

package/runtime/ext_gui/paint.h

@@ -140,6 +140,10 @@ struct DisplayList {
 void xt_paint_build(const LayoutBox *root, DisplayList &out, float viewportWidth = 0.0f,
                     float viewportHeight = 0.0f);
 
+/** Shift every shape and clip in `list` by `(dx, dy)`. Used for page scroll:
+ * the layout stays at document coordinates and painting moves the viewport. */
+void xt_paint_translate(DisplayList &list, float dx, float dy);
+
 }  // namespace xtgui
 
 #endif /* XT_GUI_PAINT_H */

package/runtime/ext_gui/webgl.h

@@ -33,11 +33,13 @@
 #include "webgl_constants.h"
 #include "webgl2_constants.h"
 #include "webgl_glsl.h"
+#include "webgl_uniform_block.h"
 
 namespace xtgui {
 
 constexpr int kWebGLMaxAttribs = 16;
 constexpr int kWebGLMaxTextureUnits = 16;
+constexpr int kWebGLMaxDrawBuffers = 4;
 
 struct WebGLShader {
   uint32_t id = 0;
@@ -64,6 +66,7 @@ struct WebGLProgram {
   bool linked = false;
   std::string log;
   std::vector<WebGLUniform> uniforms;
+  std::vector<WebGLUniformBlock> blocks;
   std::vector<GlslUniformDecl> attribs;
   std::unordered_map<std::string, int> attrib_locations;  // name -> location
   std::unordered_map<std::string, int> attrib_bindings;   // bindAttribLocation overrides
@@ -87,6 +90,8 @@ struct WebGLBuffer {
   SDL_GPUBuffer *gpu = nullptr;
   uint32_t capacity = 0;
   bool dirty = true;
+  /** `bufferData` usage hint, reported by `getBufferParameter`. */
+  int usage = GL_STATIC_DRAW;
 };
 
 struct WebGLTexture {
@@ -94,9 +99,20 @@ struct WebGLTexture {
   int width = 0;
   int height = 0;
   int levels = 1;
+  /** The binding target this texture was created for. */
+  int target = GL_TEXTURE_2D;
+  /** Layers for a cube/2D-array texture, depth for a 3D texture. */
+  int layers = 1;
   SDL_GPUTexture *gpu = nullptr;
   SDL_GPUTextureFormat format = SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM;
-  bool as_target = false;
+  /** Depth(-stencil) formats can only be depth attachments. */
+  bool depth = false;
+  /** Block-compressed textures are sample-only, with one mip level. */
+  bool compressed = false;
+  /** Usage flags the current `gpu` texture was created with. */
+  uint32_t usage = 0;
+  bool as_target = false;        // bound as a colour attachment
+  bool as_depth_target = false;  // bound as a depth attachment
   bool has_mipmaps = false;
   int min_filter = 0;
   int mag_filter = 0;
@@ -117,11 +133,16 @@ struct WebGLRenderbuffer {
 
 struct WebGLFramebuffer {
   uint32_t id = 0;
-  uint32_t color_texture = 0;
+  uint32_t color_textures[kWebGLMaxDrawBuffers] = {};
+  /** Layer rendered to for an array/cube colour attachment. */
+  int color_layers[kWebGLMaxDrawBuffers] = {};
+  /** `COLOR_ATTACHMENTi` or `NONE` per draw-buffer slot. */
+  int draw_buffers[kWebGLMaxDrawBuffers] = {GL_COLOR_ATTACHMENT0, GL_NONE, GL_NONE, GL_NONE};
+  uint32_t depth_texture = 0;
   uint32_t depth_renderbuffer = 0;
   int width = 0;
   int height = 0;
-  SDL_GPUTexture *depth = nullptr;  // owned when no renderbuffer supplies one
+  SDL_GPUTexture *depth = nullptr;  // owned when no renderbuffer/texture supplies one
 };
 
 /** Per-attribute array state. */
@@ -138,9 +159,7 @@ struct WebGLAttribState {
   float current[4] = {0.0f, 0.0f, 0.0f, 1.0f};
 };
 
-/** A WebGL 2 vertex-array object: the attribute table plus its element buffer.
- * SDL_GPU has no VAO concept, so binding one restores this state into the live
- * `attribs_` array. */
+/** A WebGL 2 vertex-array object; binding one restores this state. */
 struct WebGLVertexArray {
   uint32_t id = 0;
   WebGLAttribState attribs[kWebGLMaxAttribs];
@@ -165,6 +184,17 @@ struct WebGLSync {
   uint32_t id = 0;
 };
 
+/** One face's stencil test and update state. */
+struct WebGLStencilFace {
+  int func = GL_ALWAYS;
+  int ref = 0;
+  uint32_t value_mask = 0xFFFFFFFFu;  // compare mask
+  uint32_t write_mask = 0xFFFFFFFFu;
+  int fail = GL_KEEP;
+  int zfail = GL_KEEP;
+  int zpass = GL_KEEP;
+};
+
 /** The fixed-function state a pipeline depends on. */
 struct WebGLDrawState {
   bool blend = false;
@@ -177,10 +207,19 @@ struct WebGLDrawState {
   bool depth_test = false;
   bool depth_write = true;
   int depth_func = GL_LESS;
+  bool stencil = false;
+  WebGLStencilFace stencil_front;
+  WebGLStencilFace stencil_back;
   bool cull = false;
   int cull_face = GL_BACK;
   int front_face = GL_CCW;
   bool color_mask[4] = {true, true, true, true};
+  /** Attachment formats of the bound target; pipelines are format-specific. */
+  int color_formats[kWebGLMaxDrawBuffers] = {
+      SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM, SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM,
+      SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM, SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM};
+  int color_target_count = 1;
+  int depth_format = SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT;
 };
 
 class WebGLContext {
@@ -195,11 +234,15 @@ class WebGLContext {
   /** Resize the drawing buffer; GL semantics discard its contents. */
   void resize(int width, int height);
 
-  /** End the current pass and submit the queued commands (called once per
-   * frame, before the page's own render pass samples the colour texture). */
+  /** End the pass and submit (once per frame, before sampling). */
   void submit();
   SDL_GPUTexture *color_texture();
   bool lost() const { return lost_; }
+  /** Lose/restore the GPU device, dropping every WebGL object. */
+  void lose_context();
+  void restore_context();
+  /** `drawingBufferStorage`: fix the size across canvas resizes. */
+  void drawing_buffer_storage(int width, int height);
 
   /* -- object lookups ---------------------------------------------------- */
   WebGLShader *shader(uint32_t id);
@@ -223,10 +266,20 @@ class WebGLContext {
   void color_mask(bool r, bool g, bool b, bool a);
   void depth_mask(bool write) { state_.depth_write = write; }
   void depth_func(int func) { state_.depth_func = func; }
+  void stencil_func(int func, int ref, uint32_t mask);
+  void stencil_func_separate(int face, int func, int ref, uint32_t mask);
+  void stencil_op(int fail, int zfail, int zpass);
+  void stencil_op_separate(int face, int fail, int zfail, int zpass);
+  void stencil_mask(uint32_t mask);
+  void stencil_mask_separate(int face, uint32_t mask);
+  const WebGLStencilFace &stencil_face(int face) const;
+  int stencil_reference() const;  // the value the GPU test sees
   void blend_func(int src, int dst);
   void blend_func_separate(int src_rgb, int dst_rgb, int src_alpha, int dst_alpha);
   void blend_equation(int mode);
   void blend_equation_separate(int rgb, int alpha);
+  void blend_color(float r, float g, float b, float a);
+  void blend_color_value(float out[4]) const;
   void cull_face(int mode);
   void front_face(int mode);
   void viewport(int x, int y, int w, int h);
@@ -261,8 +314,7 @@ class WebGLContext {
   int attrib_location(uint32_t program, const std::string &name);
   void bind_attrib_location(uint32_t program, int index, const std::string &name);
 
-  /* Uniform uploads: `location` is an index into the program's uniform table
-   * (the DOM layer wraps it in the `WebGLUniformLocation` handle). */
+  /* Uniform uploads; `location` indexes the program's uniform table. */
   void uniform_floats(uint32_t program, int location, int components, const double *values,
                       int count);
   void uniform_ints(uint32_t program, int location, int components, const int *values, int count);
@@ -314,6 +366,12 @@ class WebGLContext {
   void delete_sync(uint32_t id);
   bool is_sync(uint32_t id) const;
   uint32_t uniform_block_index(uint32_t program, const std::string &name) const;
+  WebGLUniformBlock *uniform_block(uint32_t program, uint32_t index);
+  int uniform_block_parameter(uint32_t program, uint32_t index, int pname) const;
+  std::string uniform_block_name(uint32_t program, uint32_t index) const;
+  void uniform_block_binding(uint32_t program, uint32_t index, int binding);
+  void bind_buffer_base(int target, int index, uint32_t buffer, uint32_t offset, uint32_t size);
+  uint32_t uniform_buffer_binding(int index) const;
 
   /* -- textures ---------------------------------------------------------- */
   uint32_t create_texture();
@@ -324,18 +382,50 @@ class WebGLContext {
   int tex_parameter_value(uint32_t id, int pname);
   bool tex_image_rgba(uint32_t id, int width, int height, const uint8_t *rgba);
   bool tex_sub_image_rgba(uint32_t id, int x, int y, int width, int height, const uint8_t *rgba);
+  /** Level-0 upload; `pixels` is tightly packed RGBA or expanded already. */
+  bool tex_image_format(uint32_t id, int width, int height, SDL_GPUTextureFormat format,
+                        const uint8_t *pixels, int layer = -1);
+  bool tex_sub_image_format(uint32_t id, int x, int y, int width, int height,
+                            const uint8_t *pixels, int layer = 0);
   bool generate_mipmap(uint32_t id);
-  /** WebGL 2 `texStorage2D`: allocate immutable storage at `width`×`height`.
-   * The backend always allocates the full mip chain, so `levels` is a hint. */
+  /** `texStorage2D`; the backend allocates the full mip chain. */
   bool tex_storage_2d(uint32_t id, int levels, int width, int height);
+  bool tex_storage_format(uint32_t id, int levels, int width, int height,
+                          SDL_GPUTextureFormat format);
+  /** Allocate (and optionally upload) a 3D or 2D-array texture. */
+  bool tex_storage_3d(uint32_t id, int levels, int width, int height, int depth,
+                      SDL_GPUTextureFormat format, int target);
+  bool tex_image_3d(uint32_t id, int width, int height, int depth,
+                    SDL_GPUTextureFormat format, const uint8_t *pixels, int target);
+  bool tex_sub_image_3d(uint32_t id, int x, int y, int z, int width, int height, int depth,
+                        const uint8_t *pixels);
+  /** Upload a block-compressed region. */
+  bool tex_image_compressed(uint32_t id, int width, int height, SDL_GPUTextureFormat format,
+                            int x, int y, int region_width, int region_height,
+                            const uint8_t *data, uint32_t size);
+  /** Whether the device can sample `internalformat` (compressed formats). */
+  bool supports_texture_format(int internalformat);
   int texture_width(uint32_t id);
+  int texture_height(uint32_t id);
+  /** The SDL_GPU format of a texture (RGBA8 before `texImage2D`). */
+  int texture_format(uint32_t id);
 
   /* -- framebuffers ------------------------------------------------------ */
   uint32_t create_framebuffer();
   void delete_framebuffer(uint32_t id);
-  void bind_framebuffer(uint32_t id);
-  bool framebuffer_texture(uint32_t framebuffer, uint32_t texture);
+  void bind_framebuffer(int target, uint32_t id);
+  uint32_t bound_read_framebuffer_id() const { return read_framebuffer_; }
+  bool blit_framebuffer(const int source[4], const int destination[4], int mask, int filter);
+  bool framebuffer_texture(uint32_t framebuffer, uint32_t texture,
+                           int attachment = GL_COLOR_ATTACHMENT0);
+  bool framebuffer_texture_layer(uint32_t framebuffer, uint32_t texture, int attachment,
+                                 int layer);
   bool framebuffer_status(uint32_t id);
+  /** WebGL 2 `drawBuffers` / `readBuffer`. */
+  void draw_buffers(int count, const int *buffers);
+  void read_buffer(int mode) { read_buffer_ = mode; }
+  int read_buffer_value() const { return read_buffer_; }
+  int draw_buffer_value(int index);
   uint32_t create_renderbuffer();
   void delete_renderbuffer(uint32_t id);
   void bind_renderbuffer(uint32_t id) { bound_renderbuffer_ = id; }
@@ -357,6 +447,9 @@ class WebGLContext {
   std::string string_parameter(int pname);
   uint32_t bound_buffer(int target) const;
   uint32_t bound_texture(int unit) const;
+  uint32_t bound_cube_texture(int unit) const;
+  uint32_t bound_array_texture(int unit) const;
+  uint32_t bound_3d_texture(int unit) const;
   uint32_t current_program_id() const { return current_program_; }
   uint32_t bound_framebuffer_id() const { return bound_framebuffer_; }
   uint32_t bound_renderbuffer_id() const { return bound_renderbuffer_; }
@@ -377,9 +470,24 @@ class WebGLContext {
   void ensure_command();
   void end_pass();
   void flush_uploads();
-  void begin_pass(bool clear_color, bool clear_depth);
+  void begin_pass(bool clear_color, bool clear_depth, bool clear_stencil);
+  /** Scissored depth/stencil clear via a masked fullscreen triangle. */
+  void scissored_clear(int mask);
+  /** The 1×1 texture a scissored colour clear blits from. */
+  SDL_GPUTexture *clear_color_texture();
+  SDL_GPUTexture *framebuffer_color(uint32_t id);
+  void framebuffer_size(uint32_t id, int *width, int *height);
+  /** Release every GPU handle this context owns, keeping the CPU-side object
+   * table. Used by the destructor and by `lose_context`. */
+  void release_gpu_resources();
   SDL_GPUTexture *target_color();
   SDL_GPUTexture *target_depth();
+  int target_color_format();
+  int target_depth_format();
+  /** The texture rendered to for draw-buffer slot `slot`, or null. */
+  SDL_GPUTexture *draw_color_texture(int slot);
+  int draw_color_format(int slot);
+  int draw_color_layer(int slot);
   SDL_GPUTexture *ensure_texture_gpu(WebGLTexture *texture, bool as_target);
   SDL_GPUSampler *sampler_for(WebGLTexture *texture);
   SDL_GPUBuffer *ensure_buffer_gpu(WebGLBuffer *buffer);
@@ -415,15 +523,22 @@ class WebGLContext {
   SDL_GPUTexture *depth_ = nullptr;
   SDL_GPUTexture *fallback_texture_ = nullptr;
   SDL_GPUSampler *fallback_sampler_ = nullptr;
+  /** 1×1 RGBA8 source for a scissored colour clear. */
+  SDL_GPUTexture *clear_texture_ = nullptr;
+  /** Internal program/buffer for a scissored depth/stencil clear. */
+  uint32_t clear_program_ = 0;
+  uint32_t clear_buffer_ = 0;
 
   float clear_color_[4] = {0.0f, 0.0f, 0.0f, 0.0f};
   float clear_depth_ = 1.0f;
   int clear_stencil_ = 0;
+  float blend_color_[4] = {0.0f, 0.0f, 0.0f, 0.0f};
+  /** Set by `drawingBufferStorage`; canvas resizes then leave the size. */
+  bool fixed_storage_ = false;
   WebGLDrawState state_;
   int viewport_[4] = {0, 0, 0, 0};
   int scissor_box_[4] = {0, 0, 0, 0};
   bool scissor_test_ = false;
-  bool stencil_test_ = false;
 
   std::unordered_map<uint32_t, std::unique_ptr<WebGLShader>> shaders_;
   std::unordered_map<uint32_t, std::unique_ptr<WebGLProgram>> programs_;
@@ -435,16 +550,27 @@ class WebGLContext {
   std::unordered_map<uint32_t, std::unique_ptr<WebGLSampler>> samplers_;
   std::unordered_map<uint32_t, std::unique_ptr<WebGLQuery>> queries_;
   std::unordered_map<uint32_t, std::unique_ptr<WebGLSync>> syncs_;
-  /** GPU buffers created for this context's transient draws (constant vertex
-   * attributes, expanded index data); released with the context. */
+  /** GPU buffers for transient draws (constant attributes, expanded indices). */
   std::vector<SDL_GPUBuffer *> temp_buffers_;
 
   uint32_t current_program_ = 0;
   uint32_t bound_array_ = 0;
   uint32_t bound_element_ = 0;
+  uint32_t bound_uniform_ = 0;
+  uint32_t bound_transform_feedback_ = 0;
   uint32_t bound_framebuffer_ = 0;
+  uint32_t read_framebuffer_ = 0;
+  int read_buffer_ = GL_BACK;
+  int default_draw_buffers_[kWebGLMaxDrawBuffers] = {GL_BACK, GL_NONE, GL_NONE, GL_NONE};
   uint32_t bound_renderbuffer_ = 0;
+  WebGLUniformBinding uniform_bindings_[16];
   uint32_t bound_textures_[kWebGLMaxTextureUnits] = {};
+  uint32_t bound_cube_textures_[kWebGLMaxTextureUnits] = {};
+  uint32_t bound_array_textures_[kWebGLMaxTextureUnits] = {};
+  uint32_t bound_3d_textures_[kWebGLMaxTextureUnits] = {};
+  /** The target of the most recent `bindTexture` on each unit, so the existing
+   * per-unit entry points operate on the object the page just bound. */
+  int active_texture_target_[kWebGLMaxTextureUnits] = {};
   uint32_t bound_samplers_[kWebGLMaxTextureUnits] = {};
   uint32_t bound_vertex_array_ = 0;
   WebGLVertexArray default_vertex_array_;
@@ -461,6 +587,14 @@ class WebGLContext {
  * a `<canvas>`). */
 WebGLContext *xt_webgl_by_id(uint64_t id);
 
+/** Map a WebGL internal format to the SDL_GPU texture format the engine uses
+ * (RGBA8 for formats without a special backend representation). */
+SDL_GPUTextureFormat webgl_storage_format(int internalformat);
+
+/** Map a WebGL compressed-texture internal format to its SDL_GPU format, or
+ * `SDL_GPU_TEXTUREFORMAT_INVALID` for anything else. */
+SDL_GPUTextureFormat webgl_compressed_format(int internalformat);
+
 }  // namespace xtgui
 
 #endif /* XT_GUI_WEBGL_H */

package/runtime/ext_gui/webgl_blit.cpp

@@ -0,0 +1,95 @@
+/*
+ * xbintsc GUI engine — `blitFramebuffer`.
+ *
+ * SDL_GPU's blit copies a colour texture region to another colour texture, so
+ * the colour bit maps directly. Depth/stencil blits are not supported by the
+ * backend; those bits are ignored (the call is still accepted, like a driver
+ * that cannot expand the blit). Sources must be single-sampled, which is what
+ * this engine allocates today.
+ */
+
+#include "webgl.h"
+
+#include <algorithm>
+#include <cstring>
+
+#include "gui_internal.h"
+
+namespace xtgui {
+
+bool WebGLContext::blit_framebuffer(const int source[4], const int destination[4], int mask,
+                                    int filter) {
+  if ((mask & GL_COLOR_BUFFER_BIT) == 0) return true;
+  end_pass();
+  ensure_command();
+  if (cmd_ == nullptr) return false;
+  SDL_GPUTexture *source_texture = framebuffer_color(read_framebuffer_);
+  SDL_GPUTexture *destination_texture = framebuffer_color(bound_framebuffer_);
+  if (source_texture == nullptr || destination_texture == nullptr ||
+      source_texture == destination_texture) {
+    return false;
+  }
+  int source_width = 0;
+  int source_height = 0;
+  int destination_width = 0;
+  int destination_height = 0;
+  framebuffer_size(read_framebuffer_, &source_width, &source_height);
+  framebuffer_size(bound_framebuffer_, &destination_width, &destination_height);
+  if (source_width <= 0 || source_height <= 0 || destination_width <= 0 ||
+      destination_height <= 0) {
+    return false;
+  }
+  int sx0 = source[0];
+  int sy0 = source[1];
+  int sx1 = source[2];
+  int sy1 = source[3];
+  int dx0 = destination[0];
+  int dy0 = destination[1];
+  int dx1 = destination[2];
+  int dy1 = destination[3];
+  if (sx1 < sx0) std::swap(sx0, sx1);
+  if (sy1 < sy0) std::swap(sy0, sy1);
+  if (dx1 < dx0) std::swap(dx0, dx1);
+  if (dy1 < dy0) std::swap(dy0, dy1);
+  sx0 = std::max(0, std::min(sx0, source_width));
+  sx1 = std::max(0, std::min(sx1, source_width));
+  sy0 = std::max(0, std::min(sy0, source_height));
+  sy1 = std::max(0, std::min(sy1, source_height));
+  dx0 = std::max(0, std::min(dx0, destination_width));
+  dx1 = std::max(0, std::min(dx1, destination_width));
+  dy0 = std::max(0, std::min(dy0, destination_height));
+  dy1 = std::max(0, std::min(dy1, destination_height));
+  if (sx1 <= sx0 || sy1 <= sy0 || dx1 <= dx0 || dy1 <= dy0) return true;
+
+  SDL_GPUBlitRegion source_region;
+  memset(&source_region, 0, sizeof(source_region));
+  source_region.texture = source_texture;
+  source_region.x = (Uint32)sx0;
+  /* GL's origin is bottom-left; SDL's regions are top-down. */
+  source_region.y = (Uint32)(source_height - sy1);
+  source_region.w = (Uint32)(sx1 - sx0);
+  source_region.h = (Uint32)(sy1 - sy0);
+
+  SDL_GPUBlitRegion destination_region;
+  memset(&destination_region, 0, sizeof(destination_region));
+  destination_region.texture = destination_texture;
+  destination_region.x = (Uint32)dx0;
+  destination_region.y = (Uint32)(destination_height - dy1);
+  destination_region.w = (Uint32)(dx1 - dx0);
+  destination_region.h = (Uint32)(dy1 - dy0);
+
+  SDL_GPUBlitInfo info;
+  memset(&info, 0, sizeof(info));
+  info.source = source_region;
+  info.destination = destination_region;
+  /* A blit only writes the destination rectangle; everything outside it keeps
+   * its previous contents, as `blitFramebuffer` requires. DONT_CARE lets a
+   * backend (Metal's MTLLoadActionDontCare) discard the attachment and leave
+   * those pixels undefined, so load it. */
+  info.load_op = SDL_GPU_LOADOP_LOAD;
+  info.filter = filter == GL_LINEAR ? SDL_GPU_FILTER_LINEAR : SDL_GPU_FILTER_NEAREST;
+  SDL_BlitGPUTexture(cmd_, &info);
+  return true;
+}
+
+}  // namespace xtgui