Cleanup

Co-authored-by: Zachary Levy <zachary@sunforge.is>
Reviewed-on: #8

.zed/tasks.json

@@ -32,9 +32,14 @@
     "command": "odin test phased_executor -out=out/debug/test_phased_executor",
     "cwd": "$ZED_WORKTREE_ROOT",
   },
+  {
+    "label": "Test qrcode",
+    "command": "odin test qrcode -out=out/debug/test_qrcode",
+    "cwd": "$ZED_WORKTREE_ROOT",
+  },
   {
     "label": "Test all",
-    "command": "odin test many_bits -out=out/debug/test_many_bits && odin test ring -out=out/debug/test_ring && odin test levsort -out=out/debug/test_levsort && odin test levsync -out=out/debug/test_levsync && odin test levmath -out=out/debug/test_levmath && odin test phased_executor -out=out/debug/test_phased_executor",
+    "command": "odin test many_bits -out=out/debug/test_many_bits && odin test ring -out=out/debug/test_ring && odin test levsort -out=out/debug/test_levsort && odin test levsync -out=out/debug/test_levsync && odin test levmath -out=out/debug/test_levmath && odin test phased_executor -out=out/debug/test_phased_executor && odin test qrcode -out=out/debug/test_qrcode",
     "cwd": "$ZED_WORKTREE_ROOT",
   },
   // ---------------------------------------------------------------------------------------------------------------------
@@ -55,6 +60,41 @@
     "command": "odin run draw/examples -debug -out=out/debug/draw-examples -- hellope-shapes",
     "cwd": "$ZED_WORKTREE_ROOT",
   },
+  {
+    "label": "Run draw hellope-text example",
+    "command": "odin run draw/examples -debug -out=out/debug/draw-examples -- hellope-text",
+    "cwd": "$ZED_WORKTREE_ROOT",
+  },
+  {
+    "label": "Run draw hellope-custom example",
+    "command": "odin run draw/examples -debug -out=out/debug/draw-examples -- hellope-custom",
+    "cwd": "$ZED_WORKTREE_ROOT",
+  },
+  {
+    "label": "Run draw textures example",
+    "command": "odin run draw/examples -debug -out=out/debug/draw-examples -- textures",
+    "cwd": "$ZED_WORKTREE_ROOT",
+  },
+  {
+    "label": "Run qrcode basic example",
+    "command": "odin run qrcode/examples -debug -out=out/debug/qrcode-examples -- basic",
+    "cwd": "$ZED_WORKTREE_ROOT",
+  },
+  {
+    "label": "Run qrcode variety example",
+    "command": "odin run qrcode/examples -debug -out=out/debug/qrcode-examples -- variety",
+    "cwd": "$ZED_WORKTREE_ROOT",
+  },
+  {
+    "label": "Run qrcode segment example",
+    "command": "odin run qrcode/examples -debug -out=out/debug/qrcode-examples -- segment",
+    "cwd": "$ZED_WORKTREE_ROOT",
+  },
+  {
+    "label": "Run qrcode mask example",
+    "command": "odin run qrcode/examples -debug -out=out/debug/qrcode-examples -- mask",
+    "cwd": "$ZED_WORKTREE_ROOT",
+  },
   // ---------------------------------------------------------------------------------------------------------------------
   // ----- Other ------------------------
   // ---------------------------------------------------------------------------------------------------------------------

draw/README.md

@@ -47,68 +47,107 @@ primitives and effects can be added to the library without architectural changes
 
 ### Overview: three pipelines
 
-The 2D renderer will use three GPU pipelines, split by **register pressure compatibility** and
+The 2D renderer uses three GPU pipelines, split by **register pressure** (main vs effects) and
-**render-state requirements**:
+**render-pass structure** (everything vs backdrop):
 
-1. **Main pipeline** — shapes (SDF and tessellated) and text. Low register footprint (~18–22
+1. **Main pipeline** — shapes (SDF and tessellated), text, and textured rectangles. Low register
-   registers per thread). Runs at high GPU occupancy. Handles 90%+ of all fragments in a typical
+   footprint (~18–24 registers per thread). Runs at full GPU occupancy on every architecture.
-   frame.
+   Handles 90%+ of all fragments in a typical frame.
 
 2. **Effects pipeline** — drop shadows, inner shadows, outer glow, and similar ALU-bound blur
    effects. Medium register footprint (~48–60 registers). Each effects primitive includes the base
    shape's SDF so that it can draw both the effect and the shape in a single fragment pass, avoiding
-   redundant overdraw.
+   redundant overdraw. Separated from the main pipeline to protect main-pipeline occupancy on
+   low-end hardware (see register analysis below).
 
-3. **Backdrop-effects pipeline** — frosted glass, refraction, and any effect that samples the current
+3. **Backdrop pipeline** — frosted glass, refraction, and any effect that samples the current render
-   render target as input. High register footprint (~70–80 registers) and structurally requires a
+   target as input. Implemented as a multi-pass sequence (downsample, separable blur, composite),
-   `CopyGPUTextureToTexture` from the render target before drawing. Separated both for register
+   where each individual pass has a low-to-medium register footprint (~15–40 registers). Separated
-   pressure and because the texture-copy requirement forces a render-pass-level state change.
+   from the other pipelines because it structurally requires ending the current render pass and
+   copying the render target before any backdrop-sampling fragment can execute — a command-buffer-
+   level boundary that cannot be avoided regardless of shader complexity.
 
 A typical UI frame with no effects uses 1 pipeline bind and 0 switches. A frame with drop shadows
 uses 2 pipelines and 1 switch. A frame with shadows and frosted glass uses all 3 pipelines and 2
-switches plus 1 texture copy. At ~5μs per pipeline bind on modern APIs, worst-case switching overhead
+switches plus 1 texture copy. At ~1–5μs per pipeline bind on modern APIs, worst-case switching
-is under 0.15% of an 8.3ms (120 FPS) frame budget.
+overhead is negligible relative to an 8.3ms (120 FPS) frame budget.
 
 ### Why three pipelines, not one or seven
 
 The natural question is whether we should use a single unified pipeline (fewer state changes, simpler
 code) or many per-primitive-type pipelines (no branching overhead, lean per-shader register usage).
 
-The dominant cost factor is **GPU register pressure**, not pipeline switching overhead or fragment
+#### Main/effects split: register pressure
-shader branching. A GPU shader core has a fixed register pool shared among all concurrent threads. The
-compiler allocates registers pessimistically based on the worst-case path through the shader. If the
-shader contains both a 20-register RRect SDF and a 72-register frosted-glass blur, _every_ fragment
-— even trivial RRects — is allocated 72 registers. This directly reduces **occupancy** (the number of
-warps that can run simultaneously), which reduces the GPU's ability to hide memory latency.
 
-Concrete example on a modern NVIDIA SM with 65,536 registers:
+A GPU shader core has a fixed register pool shared among all concurrent threads. The compiler
+allocates registers pessimistically based on the worst-case path through the shader. If the shader
+contains both a 20-register RRect SDF and a 48-register drop-shadow blur, _every_ fragment — even
+trivial RRects — is allocated 48 registers. This directly reduces **occupancy** (the number of
+warps/wavefronts that can run simultaneously), which reduces the GPU's ability to hide memory
+latency.
 
-| Register allocation       | Max concurrent threads | Occupancy |
+Each GPU architecture has a **register cliff** — a threshold above which occupancy starts dropping.
-| ------------------------- | ---------------------- | --------- |
+Below the cliff, adding registers has zero occupancy cost.
-| 20 regs (RRect only)      | 3,276                  | ~100%     |
-| 48 regs (+ drop shadow)   | 1,365                  | ~42%      |
-| 72 regs (+ frosted glass) | 910                    | ~28%      |
 
-For a 4K frame (3840×2160) at 1.5× overdraw (~12.4M fragments), running all fragments at 28%
+On consumer Ampere/Ada GPUs (RTX 30xx/40xx, 65,536 regs/SM, max 1,536 threads/SM, cliff at ~43 regs):
-occupancy instead of 100% roughly triples fragment shading time. At 4K this is severe: if the main
-pipeline's fragment work at full occupancy takes ~2ms, a single unified shader containing the glass
-branch would push it to ~6ms — consuming 72% of the 8.3ms budget available at 120 FPS and leaving
-almost nothing for CPU work, uploads, and presentation. This is a per-frame multiplier, not a
-per-primitive cost — it applies even when the heavy branch is never taken.
 
-The three-pipeline split groups primitives by register footprint so that:
+| Register allocation     | Reg-limited threads | Actual (hw-capped) | Occupancy |
+| ----------------------- | ------------------- | ------------------ | --------- |
+| 20 regs (main pipeline) | 3,276               | 1,536              | 100%      |
+| 32 regs                 | 2,048               | 1,536              | 100%      |
+| 48 regs (effects)       | 1,365               | 1,365              | ~89%      |
 
-- Main pipeline (~20 regs): 90%+ of fragments run at near-full occupancy.
+On Volta/A100 GPUs (65,536 regs/SM, max 2,048 threads/SM, cliff at ~32 regs):
-- Effects pipeline (~55 regs): shadow/glow fragments run at moderate occupancy; unavoidable given the
-  blur math complexity.
-- Backdrop-effects pipeline (~75 regs): glass fragments run at low occupancy; also unavoidable, and
-  structurally separated anyway by the texture-copy requirement.
 
-This avoids the register-pressure tax of a single unified shader while keeping pipeline count minimal
+| Register allocation     | Reg-limited threads | Actual (hw-capped) | Occupancy |
-(3 vs. Zed GPUI's 7). The effects that drag occupancy down are isolated to the fragments that
+| ----------------------- | ------------------- | ------------------ | --------- |
-actually need them.
+| 20 regs (main pipeline) | 3,276               | 2,048              | 100%      |
+| 32 regs                 | 2,048               | 2,048              | 100%      |
+| 48 regs (effects)       | 1,365               | 1,365              | ~67%      |
 
-**Why not per-primitive-type pipelines (GPUI's approach)?** Zed's GPUI uses 7 separate shader pairs:
+On low-end mobile (ARM Mali Bifrost/Valhall, 64 regs/thread, cliff fixed at 32 regs):
+
+| Register allocation  | Occupancy                  |
+| -------------------- | -------------------------- |
+| 0–32 regs (main)     | 100% (full thread count)   |
+| 33–64 regs (effects) | ~50% (thread count halves) |
+
+Mali's cliff at 32 registers is the binding constraint. On desktop the occupancy difference between
+20 and 48 registers is modest (89–100%); on Mali it is a hard 2× throughput reduction. The
+main/effects split protects 90%+ of a frame's fragments (shapes, text, textures) from the effects
+pipeline's register cost.
+
+For the effects pipeline's drop-shadow shader — erf-approximation blur math with several texture
+fetches — 50% occupancy on Mali roughly halves throughput. At 4K with 1.5× overdraw (~12.4M
+fragments), a single unified shader containing the shadow branch would cost ~4ms instead of ~2ms on
+low-end mobile. This is a per-frame multiplier even when the heavy branch is never taken, because the
+compiler allocates registers for the worst-case path.
+
+All main-pipeline members (SDF shapes, tessellated geometry, text, textured rectangles) cluster at
+12–24 registers — below the cliff on every architecture — so unifying them costs nothing in
+occupancy.
+
+**Note on Apple M3+ GPUs:** Apple's M3 introduces Dynamic Caching (register file virtualization),
+which allocates registers at runtime based on actual usage rather than worst-case. This weakens the
+static register-pressure argument on M3 and later, but the split remains useful for isolating blur
+ALU complexity and keeping the backdrop texture-copy out of the main render pass.
+
+#### Backdrop split: render-pass structure
+
+The backdrop pipeline (frosted glass, refraction, mirror surfaces) is separated for a structural
+reason unrelated to register pressure. Before any backdrop-sampling fragment can execute, the current
+render target must be copied to a separate texture via `CopyGPUTextureToTexture` — a command-buffer-
+level operation that requires ending the current render pass. This boundary exists regardless of
+shader complexity and cannot be optimized away.
+
+The backdrop pipeline's individual shader passes (downsample, separable blur, composite) are
+register-light (~15–40 regs each), so merging them into the effects pipeline would cause no occupancy
+problem. But the render-pass boundary makes merging structurally impossible — effects draws happen
+inside the main render pass, backdrop draws happen inside their own bracketed pass sequence.
+
+#### Why not per-primitive-type pipelines (GPUI's approach)
+
+Zed's GPUI uses 7 separate shader pairs:
 quad, shadow, underline, monochrome sprite, polychrome sprite, path, surface. This eliminates all
 branching and gives each shader minimal register usage. Three concrete costs make this approach wrong
 for our use case:
@@ -120,7 +159,7 @@ typical UI frame with 15 scissors and 3–4 primitive kinds per scissor, per-kin
 ~45–60 draw calls and pipeline binds; our unified approach produces ~15–20 draw calls and 1–5
 pipeline binds. At ~5μs each for CPU-side command encoding on modern APIs, per-kind splitting adds
 375–500μs of CPU overhead per frame — **4.5–6% of an 8.3ms (120 FPS) budget** — with no
-compensating GPU-side benefit, because the register-pressure savings within the simple-SDF tier are
+compensating GPU-side benefit, because the register-pressure savings within the simple-SDF range are
 negligible (all members cluster at 12–22 registers).
 
 **Z-order preservation forces the API to expose layers.** With a single pipeline drawing all kinds
@@ -159,10 +198,10 @@ in submission order:
   ~60 boundary warps at ~80 extra instructions each), unified divergence costs ~13μs — still 3.5×
   cheaper than the pipeline-switching alternative.
 
-The split we _do_ perform (main / effects / backdrop-effects) is motivated by register-pressure tier
+The split we _do_ perform (main / effects / backdrop) is motivated by register-pressure boundaries
-boundaries where occupancy differences are catastrophic at 4K (see numbers above). Within a tier,
+and structural render-pass requirements (see analysis above). Within a pipeline, unified is
-unified is strictly better by every measure: fewer draw calls, simpler Z-order, lower CPU overhead,
+strictly better by every measure: fewer draw calls, simpler Z-order, lower CPU overhead, and
-and negligible GPU-side branching cost.
+negligible GPU-side branching cost.
 
 **References:**
 
@@ -172,6 +211,16 @@ and negligible GPU-side branching cost.
   https://github.com/zed-industries/zed/blob/cb6fc11/crates/gpui/src/platform/mac/shaders.metal
 - NVIDIA Nsight Graphics 2024.3 documentation on active-threads-per-warp and divergence analysis:
   https://developer.nvidia.com/blog/optimize-gpu-workloads-for-graphics-applications-with-nvidia-nsight-graphics/
+- NVIDIA Ampere GPU Architecture Tuning Guide — SM specs, max warps per SM (48 for cc 8.6, 64 for
+  cc 8.0), register file size (64K), occupancy factors:
+  https://docs.nvidia.com/cuda/ampere-tuning-guide/index.html
+- NVIDIA Ada GPU Architecture Tuning Guide — SM specs, max warps per SM (48 for cc 8.9):
+  https://docs.nvidia.com/cuda/ada-tuning-guide/index.html
+- CUDA Occupancy Calculation walkthrough (register allocation granularity, worked examples):
+  https://leimao.github.io/blog/CUDA-Occupancy-Calculation/
+- Apple M3 GPU architecture — Dynamic Caching (register file virtualization) eliminates static
+  worst-case register allocation, reducing the occupancy penalty for high-register shaders:
+  https://asplos.dev/wiki/m3-chip-explainer/gpu/index.html
 
 ### Why fragment shader branching is safe in this design
 
@@ -442,25 +491,40 @@ Wallace's variant) and vger-rs.
 - Vello's implementation of blurred rounded rectangle as a gradient type:
   https://github.com/linebender/vello/pull/665
 
-### Backdrop-effects pipeline
+### Backdrop pipeline
 
-The backdrop-effects pipeline handles effects that sample the current render target as input: frosted
+The backdrop pipeline handles effects that sample the current render target as input: frosted glass,
-glass, refraction, mirror surfaces. It is structurally separated from the effects pipeline for two
+refraction, mirror surfaces. It is separated from the effects pipeline for a structural reason, not
-reasons:
+register pressure.
 
-1. **Render-state requirement.** Before any backdrop-sampling fragment can run, the current render
+**Render-pass boundary.** Before any backdrop-sampling fragment can run, the current render target
-   target must be copied to a separate texture via `CopyGPUTextureToTexture`. This is a command-
+must be copied to a separate texture via `CopyGPUTextureToTexture`. This is a command-buffer-level
-   buffer-level operation that cannot happen mid-render-pass. The copy naturally creates a pipeline
+operation that cannot happen mid-render-pass. The copy naturally creates a pipeline boundary that no
-   boundary.
+amount of shader optimization can eliminate — it is a fundamental requirement of sampling a surface
+while also writing to it.
 
-2. **Register pressure.** Backdrop-sampling shaders read from a texture with Gaussian kernel weights
+**Multi-pass implementation.** Backdrop effects are implemented as separable multi-pass sequences
-   (multiple texture fetches per fragment), pushing register usage to ~70–80. Including this in the
+(downsample → horizontal blur → vertical blur → composite), following the standard approach used by
-   effects pipeline would reduce occupancy for all shadow/glow fragments from ~30% to ~20%, costing
+iOS `UIVisualEffectView`, Android `RenderEffect`, and Flutter's `BackdropFilter`. Each individual
-   measurable throughput on the common case.
+pass has a low-to-medium register footprint (~15–40 registers), well within the main pipeline's
+occupancy range. The multi-pass approach avoids the monolithic 70+ register shader that a single-pass
+Gaussian blur would require, making backdrop effects viable on low-end mobile GPUs (including
+Mali-G31 and VideoCore VI) where per-thread register limits are tight.
 
-The backdrop-effects pipeline binds a secondary sampler pointing at the captured backdrop texture. When
+**Bracketed execution.** All backdrop draws in a frame share a single bracketed region of the command
-no backdrop effects are present in a frame, this pipeline is never bound and the texture copy never
+buffer: end the current render pass, copy the render target, execute all backdrop sub-passes, then
-happens — zero cost.
+resume normal drawing. The entry/exit cost (texture copy + render-pass break) is paid once per frame
+regardless of how many backdrop effects are visible. When no backdrop effects are present, the bracket
+is never entered and the texture copy never happens — zero cost.
+
+**Why not split the backdrop sub-passes into separate pipelines?** The individual passes range from
+~15 to ~40 registers, which does cross Mali's 32-register cliff. However, the register-pressure argument
+that justifies the main/effects split does not apply here. The main/effects split protects the
+_common path_ (90%+ of frame fragments) from the uncommon path's register cost. Inside the backdrop
+pipeline there is no common-vs-uncommon distinction — if backdrop effects are active, every sub-pass
+runs; if not, none run. The backdrop pipeline either executes as a complete unit or not at all.
+Additionally, backdrop effects cover a small fraction of the frame's total fragments (~5% at typical
+UI scales), so the occupancy variation within the bracket has negligible impact on frame time.
 
 ### Vertex layout
 
@@ -483,19 +547,21 @@ The `Primitive` struct for SDF shapes lives in the storage buffer, not in vertex
 
 ```
 Primitive :: struct {
-    kind:   Shape_Kind,     //  0: enum u8
+    bounds:     [4]f32,         //  0: min_x, min_y, max_x, max_y
-    flags:  Shape_Flags,    //  1: bit_set[Shape_Flag; u8]
+    color:      Color,          // 16: u8x4, unpacked in shader via unpackUnorm4x8
-    _pad:   u16,            //  2: reserved
+    kind_flags: u32,            // 20: (kind as u32) | (flags as u32 << 8)
-    bounds: [4]f32,         //  4: min_x, min_y, max_x, max_y
+    rotation:   f32,            // 24: shader self-rotation in radians
-    color:  Color,          // 20: u8x4
+    _pad:       f32,            // 28: alignment
-    _pad2:  [3]u8,          // 24: alignment
+    params:     Shape_Params,   // 32: raw union, 32 bytes (two vec4s of shape-specific data)
-    params: Shape_Params,   // 28: raw union, 32 bytes
+    uv_rect:    [4]f32,         // 64: texture UV sub-region (u_min, v_min, u_max, v_max)
 }
-// Total: 60 bytes (padded to 64 for GPU alignment)
+// Total: 80 bytes (std430 aligned)
 ```
 
 `Shape_Params` is a `#raw_union` with named variants per shape kind (`rrect`, `circle`, `segment`,
-etc.), ensuring type safety on the CPU side and zero-cost reinterpretation on the GPU side.
+etc.), ensuring type safety on the CPU side and zero-cost reinterpretation on the GPU side. The
+`uv_rect` field is used by textured SDF primitives (Shape_Flag.Textured); non-textured primitives
+leave it zeroed.
 
 ### Draw submission order
 
@@ -506,7 +572,7 @@ Within each scissor region, draws are issued in submission order to preserve the
 2. Bind **main pipeline, tessellated mode** → draw all queued tessellated vertices (non-indexed for
    shapes, indexed for text). Pipeline state unchanged from today.
 3. Bind **main pipeline, SDF mode** → draw all queued SDF primitives (instanced, one draw call).
-4. If backdrop effects are present: copy render target, bind **backdrop-effects pipeline** → draw
+4. If backdrop effects are present: copy render target, bind **backdrop pipeline** → draw
    backdrop primitives.
 
 The exact ordering within a scissor may be refined based on actual Z-ordering requirements. The key
@@ -539,12 +605,180 @@ changes.
 - Valve's original SDF text rendering paper (SIGGRAPH 2007):
   https://steamcdn-a.akamaihd.net/apps/valve/2007/SIGGRAPH2007_AlphaTestedMagnification.pdf
 
+### Textures
+
+Textures plug into the existing main pipeline — no additional GPU pipeline, no shader rewrite. The
+work is a resource layer (registration, upload, sampling, lifecycle) plus two textured-draw procs
+that route into the existing tessellated and SDF paths respectively.
+
+#### Why draw owns registered textures
+
+A texture's GPU resource (the `^sdl.GPUTexture`, transfer buffer, shader resource view) is created
+and destroyed by draw. The user provides raw bytes and a descriptor at registration time; draw
+uploads synchronously and returns an opaque `Texture_Id` handle. The user can free their CPU-side
+bytes immediately after `register_texture` returns.
+
+This follows the model used by the RAD Debugger's render layer (`src/render/render_core.h` in
+EpicGamesExt/raddebugger, MIT license), where `r_tex2d_alloc` takes `(kind, size, format, data)`
+and returns an opaque handle that the renderer owns and releases. The single-owner model eliminates
+an entire class of lifecycle bugs (double-free, use-after-free across subsystems, unclear cleanup
+responsibility) that dual-ownership designs introduce.
+
+If advanced interop is ever needed (e.g., a future 3D pipeline or compute shader sharing the same
+GPU texture), the clean extension is a borrowed-reference accessor (`get_gpu_texture(id)`) that
+returns the underlying handle without transferring ownership. This is purely additive and does not
+require changing the registration API.
+
+#### Why `Texture_Kind` exists
+
+`Texture_Kind` (Static / Dynamic / Stream) is a driver hint for update frequency, adopted from the
+RAD Debugger's `R_ResourceKind`. It maps directly to SDL3 GPU usage patterns:
+
+- **Static**: uploaded once, never changes. Covers QR codes, decoded PNGs, icons — the 90% case.
+- **Dynamic**: updatable via `update_texture_region`. Covers font atlas growth, procedural updates.
+- **Stream**: frequent full re-uploads. Covers video playback, per-frame procedural generation.
+
+This costs one byte in the descriptor and lets the backend pick optimal memory placement without a
+future API change.
+
+#### Why samplers are per-draw, not per-texture
+
+A sampler describes how to filter and address a texture during sampling — nearest vs bilinear, clamp
+vs repeat. This is a property of the _draw_, not the texture. The same QR code texture should be
+sampled with `Nearest_Clamp` when displayed at native resolution but could reasonably be sampled
+with `Linear_Clamp` in a zoomed-out thumbnail. The same icon atlas might be sampled with
+`Nearest_Clamp` for pixel art or `Linear_Clamp` for smooth scaling.
+
+The RAD Debugger follows this pattern: `R_BatchGroup2DParams` carries `tex_sample_kind` alongside
+the texture handle, chosen per batch group at draw time. We do the same — `Sampler_Preset` is a
+parameter on the draw procs, not a field on `Texture_Desc`.
+
+Internally, draw keeps a small pool of pre-created `^sdl.GPUSampler` objects (one per preset,
+lazily initialized). Sub-batch coalescing keys on `(kind, texture_id, sampler_preset)` — draws
+with the same texture but different samplers produce separate draw calls, which is correct.
+
+#### Textured draw procs
+
+Textured rectangles route through the existing SDF path via `draw.rectangle_texture` and
+`draw.rectangle_texture_corners`, mirroring `draw.rectangle` and `draw.rectangle_corners` exactly —
+same parameters, same naming — with the color parameter replaced by a texture ID plus an optional
+tint.
+
+An earlier iteration of this design considered a separate tessellated `draw.texture` proc for
+"simple" fullscreen quads, on the theory that the tessellated path's lower register count (~16 regs
+vs ~24 for the SDF textured branch) would improve occupancy at large fragment counts. Applying the
+register-pressure analysis from the pipeline-strategy section above shows this is wrong: both 16 and
+24 registers are well below the register cliff (~43 regs on consumer Ampere/Ada, ~32 on Volta/A100),
+so both run at 100% occupancy. The remaining ALU difference (~15 extra instructions for the SDF
+evaluation) amounts to ~20μs at 4K — below noise. Meanwhile, splitting into a separate pipeline
+would add ~1–5μs per pipeline bind on the CPU side per scissor, matching or exceeding the GPU-side
+savings. Within the main pipeline, unified remains strictly better.
+
+The naming convention follows the existing shape API: `rectangle_texture` and
+`rectangle_texture_corners` sit alongside `rectangle` and `rectangle_corners`, mirroring the
+`rectangle_gradient` / `circle_gradient` pattern where the shape is the primary noun and the
+modifier (gradient, texture) is secondary. This groups related procs together in autocomplete
+(`rectangle_*`) and reads as natural English ("draw a rectangle with a texture").
+
+Future per-shape texture variants (`circle_texture`, `ellipse_texture`, `polygon_texture`) are
+reserved by this naming convention and require only a `Shape_Flag.Textured` bit plus a small
+per-shape UV mapping function in the fragment shader. These are additive.
+
+#### What SDF anti-aliasing does and does not do for textured draws
+
+The SDF path anti-aliases the **shape's outer silhouette** — rounded-corner edges, rotated edges,
+stroke outlines. It does not anti-alias or sharpen the texture content. Inside the shape, fragments
+sample through the chosen `Sampler_Preset`, and image quality is whatever the sampler produces from
+the source texels. A low-resolution texture displayed at a large size shows bilinear blur regardless
+of which draw proc is used. This matches the current text-rendering model, where glyph sharpness
+depends on how closely the display size matches the SDL_ttf atlas's rasterized size.
+
+#### Fit modes are a computation layer, not a renderer concept
+
+Standard image-fit behaviors (stretch, fill/cover, fit/contain, tile, center) are expressed as UV
+sub-region computations on top of the `uv_rect` parameter that both textured-draw procs accept. The
+renderer has no knowledge of fit modes — it samples whatever UV region it is given.
+
+A `fit_params` helper computes the appropriate `uv_rect`, sampler preset, and (for letterbox/fit
+mode) shrunken inner rect from a `Fit_Mode` enum, the target rect, and the texture's pixel size.
+Users who need custom UV control (sprite atlas sub-regions, UV animation, nine-patch slicing) skip
+the helper and compute `uv_rect` directly. This keeps the renderer primitive minimal while making
+the common cases convenient.
+
+#### Deferred release
+
+`unregister_texture` does not immediately release the GPU texture. It queues the slot for release at
+the end of the current frame, after `SubmitGPUCommandBuffer` has handed work to the GPU. This
+prevents a race condition where a texture is freed while the GPU is still sampling from it in an
+already-submitted command buffer. The same deferred-release pattern is applied to `clear_text_cache`
+and `clear_text_cache_entry`, fixing a pre-existing latent bug where destroying a cached
+`^sdl_ttf.Text` mid-frame could free an atlas texture still referenced by in-flight draw batches.
+
+This pattern is standard in production renderers — the RAD Debugger's `r_tex2d_release` queues
+textures onto a free list that is processed in `r_end_frame`, not at the call site.
+
+#### Clay integration
+
+Clay's `RenderCommandType.Image` is handled by dereferencing `imageData: rawptr` as a pointer to a
+`Clay_Image_Data` struct containing a `Texture_Id`, `Fit_Mode`, and tint color. Routing mirrors the
+existing rectangle handling: zero `cornerRadius` dispatches to `draw.texture` (tessellated), nonzero
+dispatches to `draw.rectangle_texture_corners` (SDF). A `fit_params` call computes UVs from the fit
+mode before dispatch.
+
+#### Deferred features
+
+The following are plumbed in the descriptor but not implemented in phase 1:
+
+- **Mipmaps**: `Texture_Desc.mip_levels` field exists; generation via SDL3 deferred.
+- **Compressed formats**: `Texture_Desc.format` accepts BC/ASTC; upload path deferred.
+- **Render-to-texture**: `Texture_Desc.usage` accepts `.COLOR_TARGET`; render-pass refactor deferred.
+- **3D textures, arrays, cube maps**: `Texture_Desc.type` and `depth_or_layers` fields exist.
+- **Additional samplers**: anisotropic, trilinear, clamp-to-border — additive enum values.
+- **Atlas packing**: internal optimization for sub-batch coalescing; invisible to callers.
+- **Per-shape texture variants**: `circle_texture`, `ellipse_texture`, etc. — reserved by naming.
+
+**References:**
+
+- RAD Debugger render layer (ownership model, deferred release, sampler-at-draw-time):
+  https://github.com/EpicGamesExt/raddebugger — `src/render/render_core.h`, `src/render/d3d11/render_d3d11.c`
+- Casey Muratori, Handmade Hero day 472 — texture handling as a renderer-owned resource concern,
+  atlases as a separate layer above the renderer.
+
 ## 3D rendering
 
 3D pipeline architecture is under consideration and will be documented separately. The current
 expectation is that 3D rendering will use dedicated pipelines (separate from the 2D pipelines)
 sharing GPU resources (textures, samplers, command buffer lifecycle) with the 2D renderer.
 
+## Multi-window support
+
+The renderer currently assumes a single window via the global `GLOB` state. Multi-window support is
+deferred but anticipated. When revisited, the RAD Debugger's bucket + pass-list model
+(`src/draw/draw.h`, `src/draw/draw.c` in EpicGamesExt/raddebugger) is worth studying as a reference.
+
+RAD separates draw submission from rendering via **buckets**. A `DR_Bucket` is an explicit handle
+that accumulates an ordered list of render passes (`R_PassList`). The user creates a bucket, pushes
+it onto a thread-local stack, issues draw calls (which target the top-of-stack bucket), then submits
+the bucket to a specific window. Multiple buckets can exist simultaneously — one per window, or one
+per UI panel that gets composited into a parent bucket via `dr_sub_bucket`. Implicit draw parameters
+(clip rect, 2D transform, sampler mode, transparency) are managed via push/pop stacks scoped to each
+bucket, so different windows can have independent clip and transform state without interference.
+
+The key properties this gives RAD:
+
+- **Per-window isolation.** Each window builds its own bucket with its own pass list and state stacks.
+  No global contention.
+- **Thread-parallel building.** Each thread has its own draw context and arena. Multiple threads can
+  build buckets concurrently, then submit them to the render backend sequentially.
+- **Compositing.** A pre-built bucket (e.g., a tooltip or overlay) can be injected into another
+  bucket with a transform applied, without rebuilding its draw calls.
+
+For our library, the likely adaptation would be replacing the single `GLOB` with a per-window draw
+context that users create and pass to `begin`/`end`, while keeping the explicit-parameter draw call
+style rather than adopting RAD's implicit state stacks. Texture and sampler resources would remain
+global (shared across windows), with only the per-frame staging buffers and layer/scissor state
+becoming per-context.
+
 ## Building shaders
 
 GLSL shader sources live in `shaders/source/`. Compiled outputs (SPIR-V and Metal Shading Language)
@@ -555,3 +789,26 @@ odin run meta -- gen-shaders
 ```
 
 Requires `glslangValidator` and `spirv-cross` on PATH.
+
+### Shader format selection
+
+The library embeds shader bytecode per compile target — MSL + `main0` entry point on Darwin (via
+`spirv-cross --msl`, which renames `main` because it is reserved in Metal), SPIR-V + `main` entry
+point elsewhere. Three compile-time constants in `draw.odin` expose the build's shader configuration:
+
+| Constant                      | Type                      | Darwin    | Other      |
+| ----------------------------- | ------------------------- | --------- | ---------- |
+| `PLATFORM_SHADER_FORMAT_FLAG` | `sdl.GPUShaderFormatFlag` | `.MSL`    | `.SPIRV`   |
+| `PLATFORM_SHADER_FORMAT`      | `sdl.GPUShaderFormat`     | `{.MSL}`  | `{.SPIRV}` |
+| `SHADER_ENTRY`                | `cstring`                 | `"main0"` | `"main"`   |
+
+Pass `PLATFORM_SHADER_FORMAT` to `sdl.CreateGPUDevice` so SDL selects a backend compatible with the
+embedded bytecode:
+
+```
+gpu := sdl.CreateGPUDevice(draw.PLATFORM_SHADER_FORMAT, true, nil)
+```
+
+At init time the library calls `sdl.GetGPUShaderFormats(device)` to verify the active backend
+accepts `PLATFORM_SHADER_FORMAT_FLAG`. If it does not, `draw.init` returns `false` with a
+descriptive log message showing both the embedded and active format sets.

draw/draw.odin

@@ -1,21 +1,27 @@
 package draw
 
-import clay "../vendor/clay"
 import "base:runtime"
 import "core:c"
 import "core:log"
-
+import "core:math"
 import "core:strings"
 import sdl "vendor:sdl3"
 import sdl_ttf "vendor:sdl3/ttf"
 
+import clay "../vendor/clay"
+
 when ODIN_OS == .Darwin {
-	SHADER_TYPE :: sdl.GPUShaderFormat{.MSL}
+	PLATFORM_SHADER_FORMAT_FLAG :: sdl.GPUShaderFormatFlag.MSL
-	ENTRY_POINT :: "main0"
+	SHADER_ENTRY :: cstring("main0")
+	BASE_VERT_2D_RAW :: #load("shaders/generated/base_2d.vert.metal")
+	BASE_FRAG_2D_RAW :: #load("shaders/generated/base_2d.frag.metal")
 } else {
-	SHADER_TYPE :: sdl.GPUShaderFormat{.SPIRV}
+	PLATFORM_SHADER_FORMAT_FLAG :: sdl.GPUShaderFormatFlag.SPIRV
-	ENTRY_POINT :: "main"
+	SHADER_ENTRY :: cstring("main")
+	BASE_VERT_2D_RAW :: #load("shaders/generated/base_2d.vert.spv")
+	BASE_FRAG_2D_RAW :: #load("shaders/generated/base_2d.frag.spv")
 }
+PLATFORM_SHADER_FORMAT :: sdl.GPUShaderFormat{PLATFORM_SHADER_FORMAT_FLAG}
 
 BUFFER_INIT_SIZE :: 256
 INITIAL_LAYER_SIZE :: 5
@@ -35,14 +41,14 @@ BLUE :: Color{0, 0, 255, 255}
 BLANK :: Color{0, 0, 0, 0}
 
 // Convert clay.Color ([4]c.float in 0–255 range) to Color.
-color_from_clay :: proc(cc: clay.Color) -> Color {
+color_from_clay :: proc(clay_color: clay.Color) -> Color {
-	return Color{u8(cc[0]), u8(cc[1]), u8(cc[2]), u8(cc[3])}
+	return Color{u8(clay_color[0]), u8(clay_color[1]), u8(clay_color[2]), u8(clay_color[3])}
 }
 
 // Convert Color to [4]f32 in 0.0–1.0 range. Useful for SDL interop (e.g. clear color).
-color_to_f32 :: proc(c: Color) -> [4]f32 {
+color_to_f32 :: proc(color: Color) -> [4]f32 {
 	INV :: 1.0 / 255.0
-	return {f32(c[0]) * INV, f32(c[1]) * INV, f32(c[2]) * INV, f32(c[3]) * INV}
+	return {f32(color[0]) * INV, f32(color[1]) * INV, f32(color[2]) * INV, f32(color[3]) * INV}
 }
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -52,20 +58,22 @@ color_to_f32 :: proc(c: Color) -> [4]f32 {
 Rectangle :: struct {
 	x:      f32,
 	y:      f32,
-	w: f32,
+	width:  f32,
-	h: f32,
+	height: f32,
 }
 
 Sub_Batch_Kind :: enum u8 {
-	Shapes, // non-indexed, white texture, mode 0
+	Shapes, // non-indexed, white texture or user texture, mode 0
 	Text, // indexed, atlas texture, mode 0
-	SDF,    // instanced unit quad, white texture, mode 1
+	SDF, // instanced unit quad, white texture or user texture, mode 1
 }
 
 Sub_Batch :: struct {
 	kind:       Sub_Batch_Kind,
 	offset:     u32, // Shapes: vertex offset; Text: text_batch index; SDF: primitive index
 	count:      u32, // Shapes: vertex count; Text: always 1; SDF: primitive count
+	texture_id: Texture_Id,
+	sampler:    Sampler_Preset,
 }
 
 Layer :: struct {
@@ -89,21 +97,50 @@ Scissor :: struct {
 GLOB: Global
 
 Global :: struct {
-	odin_context:      runtime.Context,
+	// -- Per-frame staging (hottest — touched by every prepare/upload/clear cycle) --
-	pipeline_2d_base:  Pipeline_2D_Base,
+	tmp_shape_verts:          [dynamic]Vertex, // Tessellated shape vertices staged for GPU upload.
-	text_cache:        Text_Cache,
+	tmp_text_verts:           [dynamic]Vertex, // Text vertices staged for GPU upload.
-	layers:            [dynamic]Layer,
+	tmp_text_indices:         [dynamic]c.int, // Text index buffer staged for GPU upload.
-	scissors:          [dynamic]Scissor,
+	tmp_text_batches:         [dynamic]TextBatch, // Text atlas batch metadata for indexed drawing.
-	tmp_shape_verts:   [dynamic]Vertex,
+	tmp_primitives:           [dynamic]Primitive, // SDF primitives staged for GPU storage buffer upload.
-	tmp_text_verts:    [dynamic]Vertex,
+	tmp_sub_batches:          [dynamic]Sub_Batch, // Sub-batch records that drive draw call dispatch.
-	tmp_text_indices:  [dynamic]c.int,
+	tmp_uncached_text:        [dynamic]^sdl_ttf.Text, // Uncached TTF_Text objects destroyed after end() submits.
-	tmp_text_batches:  [dynamic]TextBatch,
+	layers:                   [dynamic]Layer, // Draw layers, each with its own scissor stack.
-	tmp_primitives:    [dynamic]Primitive,
+	scissors:                 [dynamic]Scissor, // Scissor rects that clip drawing within each layer.
-	tmp_sub_batches:   [dynamic]Sub_Batch,
+
-	clay_mem:          [^]u8,
+	// -- Per-frame scalars (accessed during prepare and draw_layer) --
-	msaa_texture:      ^sdl.GPUTexture,
+	curr_layer_index:         uint, // Index of the currently active layer.
-	curr_layer_index:  uint,
+	dpi_scaling:              f32, // Window DPI scale factor applied to all pixel coordinates.
-	max_layers:        int,
+	clay_z_index:             i16, // Tracks z-index for layer splitting during Clay batch processing.
+	cleared:                  bool, // Whether the render target has been cleared this frame.
+
+	// -- Pipeline (accessed every draw_layer call) --
+	pipeline_2d_base:         Pipeline_2D_Base, // The unified 2D GPU pipeline (shaders, buffers, samplers).
+	device:                   ^sdl.GPUDevice, // GPU device handle, stored at init.
+	samplers:                 [SAMPLER_PRESET_COUNT]^sdl.GPUSampler, // Lazily-created sampler objects, one per Sampler_Preset.
+
+	// -- Deferred release (processed once per frame at frame boundary) --
+	pending_texture_releases: [dynamic]Texture_Id, // Deferred GPU texture releases, processed next frame.
+	pending_text_releases:    [dynamic]^sdl_ttf.Text, // Deferred TTF_Text destroys, processed next frame.
+
+	// -- Textures (registration is occasional, binding is per draw call) --
+	texture_slots:            [dynamic]Texture_Slot, // Registered texture slots indexed by Texture_Id.
+	texture_free_list:        [dynamic]u32, // Recycled slot indices available for reuse.
+
+	// -- MSAA (once per frame in end()) --
+	msaa_texture:             ^sdl.GPUTexture, // Intermediate render target for multi-sample resolve.
+	msaa_width:               u32, // Cached width to detect when MSAA texture needs recreation.
+	msaa_height:              u32, // Cached height to detect when MSAA texture needs recreation.
+	sample_count:             sdl.GPUSampleCount, // Sample count chosen at init (._1 means MSAA disabled).
+
+	// -- Clay (once per frame in prepare_clay_batch) --
+	clay_memory:              [^]u8, // Raw memory block backing Clay's internal arena.
+
+	// -- Text (occasional — font registration and text cache lookups) --
+	text_cache:               Text_Cache, // Font registry, SDL_ttf engine, and cached TTF_Text objects.
+
+	// -- Resize tracking (cold — checked once per frame in resize_global) --
+	max_layers:               int, // High-water marks for dynamic array shrink heuristic.
 	max_scissors:             int,
 	max_shape_verts:          int,
 	max_text_verts:           int,
@@ -111,12 +148,9 @@ Global :: struct {
 	max_text_batches:         int,
 	max_primitives:           int,
 	max_sub_batches:          int,
-	dpi_scaling:       f32,
+
-	msaa_w:            u32,
+	// -- Init-only (coldest — set once at init, never written again) --
-	msaa_h:            u32,
+	odin_context:             runtime.Context, // Odin context captured at init for use in callbacks.
-	sample_count:      sdl.GPUSampleCount,
-	clay_z_index:      i16,
-	cleared:           bool,
 }
 
 Init_Options :: struct {
@@ -169,25 +203,34 @@ init :: proc(
 		tmp_text_batches         = make([dynamic]TextBatch, 0, BUFFER_INIT_SIZE, allocator = allocator),
 		tmp_primitives           = make([dynamic]Primitive, 0, BUFFER_INIT_SIZE, allocator = allocator),
 		tmp_sub_batches          = make([dynamic]Sub_Batch, 0, BUFFER_INIT_SIZE, allocator = allocator),
+		tmp_uncached_text        = make([dynamic]^sdl_ttf.Text, 0, 16, allocator = allocator),
+		device                   = device,
+		texture_slots            = make([dynamic]Texture_Slot, 0, 16, allocator = allocator),
+		texture_free_list        = make([dynamic]u32, 0, 16, allocator = allocator),
+		pending_texture_releases = make([dynamic]Texture_Id, 0, 16, allocator = allocator),
+		pending_text_releases    = make([dynamic]^sdl_ttf.Text, 0, 16, allocator = allocator),
 		odin_context             = odin_context,
 		dpi_scaling              = sdl.GetWindowDisplayScale(window),
-		clay_mem         = make([^]u8, min_memory_size, allocator = allocator),
+		clay_memory              = make([^]u8, min_memory_size, allocator = allocator),
 		sample_count             = resolved_sample_count,
 		pipeline_2d_base         = pipeline,
 		text_cache               = text_cache,
 	}
+
+	// Reserve slot 0 for INVALID_TEXTURE
+	append(&GLOB.texture_slots, Texture_Slot{})
 	log.debug("Window DPI scaling:", GLOB.dpi_scaling)
-	arena := clay.CreateArenaWithCapacityAndMemory(min_memory_size, GLOB.clay_mem)
+	arena := clay.CreateArenaWithCapacityAndMemory(min_memory_size, GLOB.clay_memory)
 	window_width, window_height: c.int
 	sdl.GetWindowSize(window, &window_width, &window_height)
 
 	clay.Initialize(arena, {f32(window_width), f32(window_height)}, {handler = clay_error_handler})
-	clay.SetMeasureTextFunction(measure_text, nil)
+	clay.SetMeasureTextFunction(measure_text_clay, nil)
 	return true
 }
 
-// TODO every x frames nuke max values in case of edge cases where max gets set very high
+// TODO Either every x frames nuke max values in case of edge cases where max gets set very high
-// Called at the end of every frame
+// or leave to application code to decide the right time for resize
 resize_global :: proc() {
 	if len(GLOB.layers) > GLOB.max_layers do GLOB.max_layers = len(GLOB.layers)
 	shrink(&GLOB.layers, GLOB.max_layers)
@@ -216,19 +259,35 @@ destroy :: proc(device: ^sdl.GPUDevice, allocator := context.allocator) {
 	delete(GLOB.tmp_text_batches)
 	delete(GLOB.tmp_primitives)
 	delete(GLOB.tmp_sub_batches)
-	free(GLOB.clay_mem, allocator)
+	for ttf_text in GLOB.tmp_uncached_text do sdl_ttf.DestroyText(ttf_text)
+	delete(GLOB.tmp_uncached_text)
+	free(GLOB.clay_memory, allocator)
 	if GLOB.msaa_texture != nil {
 		sdl.ReleaseGPUTexture(device, GLOB.msaa_texture)
 	}
+	process_pending_texture_releases()
+	destroy_all_textures()
+	destroy_sampler_pool()
+	for ttf_text in GLOB.pending_text_releases do sdl_ttf.DestroyText(ttf_text)
+	delete(GLOB.pending_text_releases)
 	destroy_pipeline_2d_base(device, &GLOB.pipeline_2d_base)
 	destroy_text_cache()
 }
 
 // Internal
 clear_global :: proc() {
+	// Process deferred texture releases from the previous frame
+	process_pending_texture_releases()
+	// Process deferred text releases from the previous frame
+	for ttf_text in GLOB.pending_text_releases do sdl_ttf.DestroyText(ttf_text)
+	clear(&GLOB.pending_text_releases)
+
 	GLOB.curr_layer_index = 0
 	GLOB.clay_z_index = 0
 	GLOB.cleared = false
+	// Destroy uncached TTF_Text objects from the previous frame (after end() has submitted draw data)
+	for ttf_text in GLOB.tmp_uncached_text do sdl_ttf.DestroyText(ttf_text)
+	clear(&GLOB.tmp_uncached_text)
 	clear(&GLOB.layers)
 	clear(&GLOB.scissors)
 	clear(&GLOB.tmp_shape_verts)
@@ -244,7 +303,7 @@ clear_global :: proc() {
 // ---------------------------------------------------------------------------------------------------------------------
 
 @(private = "file")
-measure_text :: proc "c" (
+measure_text_clay :: proc "c" (
 	text: clay.StringSlice,
 	config: ^clay.TextElementConfig,
 	user_data: rawptr,
@@ -252,12 +311,13 @@ measure_text :: proc "c" (
 	context = GLOB.odin_context
 	text := string(text.chars[:text.length])
 	c_text := strings.clone_to_cstring(text, context.temp_allocator)
-	w, h: c.int
+	defer delete(c_text, context.temp_allocator)
-	if !sdl_ttf.GetStringSize(get_font(config.fontId, config.fontSize), c_text, 0, &w, &h) {
+	width, height: c.int
+	if !sdl_ttf.GetStringSize(get_font(config.fontId, config.fontSize), c_text, 0, &width, &height) {
 		log.panicf("Failed to measure text: %s", sdl.GetError())
 	}
 
-	return clay.Dimensions{width = f32(w) / GLOB.dpi_scaling, height = f32(h) / GLOB.dpi_scaling}
+	return clay.Dimensions{width = f32(width) / GLOB.dpi_scaling, height = f32(height) / GLOB.dpi_scaling}
 }
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -274,8 +334,8 @@ begin :: proc(bounds: Rectangle) -> ^Layer {
 		bounds = sdl.Rect {
 			x = i32(bounds.x * GLOB.dpi_scaling),
 			y = i32(bounds.y * GLOB.dpi_scaling),
-			w = i32(bounds.w * GLOB.dpi_scaling),
+			w = i32(bounds.width * GLOB.dpi_scaling),
-			h = i32(bounds.h * GLOB.dpi_scaling),
+			h = i32(bounds.height * GLOB.dpi_scaling),
 		},
 	}
 	append(&GLOB.scissors, scissor)
@@ -305,8 +365,8 @@ new_layer :: proc(prev_layer: ^Layer, bounds: Rectangle) -> ^Layer {
 		bounds = sdl.Rect {
 			x = i32(bounds.x * GLOB.dpi_scaling),
 			y = i32(bounds.y * GLOB.dpi_scaling),
-			w = i32(bounds.w * GLOB.dpi_scaling),
+			w = i32(bounds.width * GLOB.dpi_scaling),
-			h = i32(bounds.h * GLOB.dpi_scaling),
+			h = i32(bounds.height * GLOB.dpi_scaling),
 		},
 	}
 	append(&GLOB.scissors, scissor)
@@ -336,14 +396,19 @@ prepare_sdf_primitive :: proc(layer: ^Layer, prim: Primitive) {
 
 // Submit a text element to the given layer for rendering.
 // Copies SDL_ttf vertices directly (with baked position) and copies indices for indexed drawing.
-prepare_text :: proc(layer: ^Layer, txt: Text) {
+prepare_text :: proc(layer: ^Layer, text: Text) {
-	data := sdl_ttf.GetGPUTextDrawData(txt.ref)
+	data := sdl_ttf.GetGPUTextDrawData(text.sdl_text)
 	if data == nil {
 		return // nil is normal for empty text
 	}
 
 	scissor := &GLOB.scissors[layer.scissor_start + layer.scissor_len - 1]
 
+	// Snap base position to integer physical pixels to avoid atlas sub-pixel
+	// sampling blur (and the off-by-one bottom-row clip that comes with it).
+	base_x := math.round(text.position[0] * GLOB.dpi_scaling)
+	base_y := math.round(text.position[1] * GLOB.dpi_scaling)
+
 	for data != nil {
 		vertex_start := u32(len(GLOB.tmp_text_verts))
 		index_start := u32(len(GLOB.tmp_text_indices))
@@ -354,11 +419,7 @@ prepare_text :: proc(layer: ^Layer, txt: Text) {
 			uv := data.uv[i]
 			append(
 				&GLOB.tmp_text_verts,
-				Vertex {
+				Vertex{position = {pos.x + base_x, -pos.y + base_y}, uv = {uv.x, uv.y}, color = text.color},
-					position = {pos.x + txt.position[0] * GLOB.dpi_scaling, -pos.y + txt.position[1] * GLOB.dpi_scaling},
-					uv = {uv.x, uv.y},
-					color = txt.color,
-				},
 			)
 		}
 
@@ -384,6 +445,54 @@ prepare_text :: proc(layer: ^Layer, txt: Text) {
 	}
 }
 
+// Submit a text element with a 2D affine transform applied to vertices.
+// Used by the high-level `text` proc when rotation or a non-zero origin is specified.
+// NOTE: xform must be in physical (DPI-scaled) pixel space — the caller pre-scales
+// pos and origin by GLOB.dpi_scaling before building the transform.
+prepare_text_transformed :: proc(layer: ^Layer, text: Text, transform: Transform_2D) {
+	data := sdl_ttf.GetGPUTextDrawData(text.sdl_text)
+	if data == nil {
+		return
+	}
+
+	scissor := &GLOB.scissors[layer.scissor_start + layer.scissor_len - 1]
+
+	for data != nil {
+		vertex_start := u32(len(GLOB.tmp_text_verts))
+		index_start := u32(len(GLOB.tmp_text_indices))
+
+		for i in 0 ..< data.num_vertices {
+			pos := data.xy[i]
+			uv := data.uv[i]
+			// SDL_ttf gives glyph positions in physical pixels relative to text origin.
+			// The transform is already in physical-pixel space (caller pre-scaled),
+			// so we apply directly — no per-vertex DPI divide/multiply.
+			append(
+				&GLOB.tmp_text_verts,
+				Vertex{position = apply_transform(transform, {pos.x, -pos.y}), uv = {uv.x, uv.y}, color = text.color},
+			)
+		}
+
+		append(&GLOB.tmp_text_indices, ..data.indices[:data.num_indices])
+
+		batch_idx := u32(len(GLOB.tmp_text_batches))
+		append(
+			&GLOB.tmp_text_batches,
+			TextBatch {
+				atlas_texture = data.atlas_texture,
+				vertex_start = vertex_start,
+				vertex_count = u32(data.num_vertices),
+				index_start = index_start,
+				index_count = u32(data.num_indices),
+			},
+		)
+
+		append_or_extend_sub_batch(scissor, layer, .Text, batch_idx, 1)
+
+		data = data.next
+	}
+}
+
 // Append a new sub-batch or extend the last one if same kind and contiguous.
 @(private)
 append_or_extend_sub_batch :: proc(
@@ -392,15 +501,24 @@ append_or_extend_sub_batch :: proc(
 	kind: Sub_Batch_Kind,
 	offset: u32,
 	count: u32,
+	texture_id: Texture_Id = INVALID_TEXTURE,
+	sampler: Sampler_Preset = .Linear_Clamp,
 ) {
 	if scissor.sub_batch_len > 0 {
 		last := &GLOB.tmp_sub_batches[scissor.sub_batch_start + scissor.sub_batch_len - 1]
-		if last.kind == kind && kind != .Text && last.offset + last.count == offset {
+		if last.kind == kind &&
+		   kind != .Text &&
+		   last.offset + last.count == offset &&
+		   last.texture_id == texture_id &&
+		   last.sampler == sampler {
 			last.count += count
 			return
 		}
 	}
-	append(&GLOB.tmp_sub_batches, Sub_Batch{kind = kind, offset = offset, count = count})
+	append(
+		&GLOB.tmp_sub_batches,
+		Sub_Batch{kind = kind, offset = offset, count = count, texture_id = texture_id, sampler = sampler},
+	)
 	scissor.sub_batch_len += 1
 	layer.sub_batch_len += 1
 }
@@ -415,6 +533,19 @@ clay_error_handler :: proc "c" (errorData: clay.ErrorData) {
 	log.error("Clay error:", errorData.errorType, errorData.errorText)
 }
 
+// Called for each Clay `RenderCommandType.Custom` render command that
+// `prepare_clay_batch` encounters.
+//
+// - `layer` is the layer the command belongs to (post-z-index promotion).
+// - `bounds` is already translated into the active layer's coordinate system
+//   and pre-DPI, matching what the built-in shape procs expect.
+// - `render_data` is Clay's `CustomRenderData` for the element, exposing
+//   `backgroundColor`, `cornerRadius`, and the `customData` pointer the caller
+//   attached to `clay.CustomElementConfig.customData`.
+//
+// The callback must not call `new_layer` or `prepare_clay_batch`.
+Custom_Draw :: #type proc(layer: ^Layer, bounds: Rectangle, render_data: clay.CustomRenderData)
+
 ClayBatch :: struct {
 	bounds: Rectangle,
 	cmds:   clay.ClayArray(clay.RenderCommand),
@@ -426,6 +557,8 @@ prepare_clay_batch :: proc(
 	batch: ^ClayBatch,
 	mouse_wheel_delta: [2]f32,
 	frame_time: f32 = 0,
+	custom_draw: Custom_Draw = nil,
+	temp_allocator := context.temp_allocator,
 ) {
 	mouse_pos: [2]f32
 	mouse_flags := sdl.GetMouseState(&mouse_pos.x, &mouse_pos.y)
@@ -447,8 +580,8 @@ prepare_clay_batch :: proc(
 		bounds := Rectangle {
 			x      = render_command.boundingBox.x + layer.bounds.x,
 			y      = render_command.boundingBox.y + layer.bounds.y,
-			w = render_command.boundingBox.width,
+			width  = render_command.boundingBox.width,
-			h = render_command.boundingBox.height,
+			height = render_command.boundingBox.height,
 		}
 
 		if render_command.zIndex > GLOB.clay_z_index {
@@ -465,33 +598,59 @@ prepare_clay_batch :: proc(
 		case clay.RenderCommandType.Text:
 			render_data := render_command.renderData.text
 			txt := string(render_data.stringContents.chars[:render_data.stringContents.length])
-			c_text := strings.clone_to_cstring(txt, context.temp_allocator)
+			c_text := strings.clone_to_cstring(txt, temp_allocator)
-			sdl_text := GLOB.text_cache.cache[render_command.id]
+			defer delete(c_text, temp_allocator)
-
+			// Clay render-command IDs are derived via Clay's internal HashNumber (Jenkins-family)
-			if sdl_text == nil {
+			// and namespaced with .Clay so they can never collide with user-provided custom text IDs.
-				// Cache a SDL text object
+			sdl_text := cache_get_or_update(
-				sdl_text = sdl_ttf.CreateText(
+				Cache_Key{render_command.id, .Clay},
-					GLOB.text_cache.engine,
-					get_font(render_data.fontId, render_data.fontSize),
 				c_text,
-					0,
+				get_font(render_data.fontId, render_data.fontSize),
 			)
-				if sdl_text == nil {
-					log.panicf("Failed to create SDL text for clay render command: %s", sdl.GetError())
-				}
-				GLOB.text_cache.cache[render_command.id] = sdl_text
-			} else {
-				if !sdl_ttf.SetTextString(sdl_text, c_text, 0) {
-					log.panicf("Failed to update SDL text string: %s", sdl.GetError())
-				}
-			}
-
 			prepare_text(layer, Text{sdl_text, {bounds.x, bounds.y}, color_from_clay(render_data.textColor)})
 		case clay.RenderCommandType.Image:
-		case clay.RenderCommandType.ScissorStart:
+			render_data := render_command.renderData.image
-			if bounds.w == 0 || bounds.h == 0 {
+			if render_data.imageData == nil do continue
-				continue
+			img_data := (^Clay_Image_Data)(render_data.imageData)^
+			cr := render_data.cornerRadius
+			radii := [4]f32{cr.topLeft, cr.topRight, cr.bottomRight, cr.bottomLeft}
+
+			// Background color behind the image (Clay allows it)
+			bg := color_from_clay(render_data.backgroundColor)
+			if bg[3] > 0 {
+				if radii == {0, 0, 0, 0} {
+					rectangle(layer, bounds, bg)
+				} else {
+					rectangle_corners(layer, bounds, radii, bg)
 				}
+			}
+
+			// Compute fit UVs
+			uv, sampler, inner := fit_params(img_data.fit, bounds, img_data.texture_id)
+
+			// Draw the image — route by cornerRadius
+			if radii == {0, 0, 0, 0} {
+				rectangle_texture(
+					layer,
+					inner,
+					img_data.texture_id,
+					tint = img_data.tint,
+					uv_rect = uv,
+					sampler = sampler,
+				)
+			} else {
+				rectangle_texture_corners(
+					layer,
+					inner,
+					radii,
+					img_data.texture_id,
+					tint = img_data.tint,
+					uv_rect = uv,
+					sampler = sampler,
+				)
+			}
+		case clay.RenderCommandType.ScissorStart:
+			if bounds.width == 0 || bounds.height == 0 do continue
 
 			curr_scissor := &GLOB.scissors[layer.scissor_start + layer.scissor_len - 1]
 
@@ -502,8 +661,8 @@ prepare_clay_batch :: proc(
 					bounds          = sdl.Rect {
 						c.int(bounds.x * GLOB.dpi_scaling),
 						c.int(bounds.y * GLOB.dpi_scaling),
-						c.int(bounds.w * GLOB.dpi_scaling),
+						c.int(bounds.width * GLOB.dpi_scaling),
-						c.int(bounds.h * GLOB.dpi_scaling),
+						c.int(bounds.height * GLOB.dpi_scaling),
 					},
 				}
 				append(&GLOB.scissors, new)
@@ -512,8 +671,8 @@ prepare_clay_batch :: proc(
 				curr_scissor.bounds = sdl.Rect {
 					c.int(bounds.x * GLOB.dpi_scaling),
 					c.int(bounds.y * GLOB.dpi_scaling),
-					c.int(bounds.w * GLOB.dpi_scaling),
+					c.int(bounds.width * GLOB.dpi_scaling),
-					c.int(bounds.h * GLOB.dpi_scaling),
+					c.int(bounds.height * GLOB.dpi_scaling),
 				}
 			}
 		case clay.RenderCommandType.ScissorEnd:
@@ -532,25 +691,23 @@ prepare_clay_batch :: proc(
 			render_data := render_command.renderData.border
 			cr := render_data.cornerRadius
 			color := color_from_clay(render_data.color)
-			thick := f32(render_data.width.top)
+			thickness := f32(render_data.width.top)
 			radii := [4]f32{cr.topLeft, cr.topRight, cr.bottomRight, cr.bottomLeft}
 
 			if radii == {0, 0, 0, 0} {
-				rectangle_lines(layer, bounds, color, thick)
+				rectangle_lines(layer, bounds, color, thickness)
 			} else {
-				rectangle_corners_lines(layer, bounds, radii, color, thick)
+				rectangle_corners_lines(layer, bounds, radii, color, thickness)
+			}
+		case clay.RenderCommandType.Custom: if custom_draw != nil {
+					custom_draw(layer, bounds, render_command.renderData.custom)
 				}
-		case clay.RenderCommandType.Custom:
 		}
 	}
 }
 
 // Render primitives. clear_color is the background fill before any layers are drawn.
-end :: proc(
+end :: proc(device: ^sdl.GPUDevice, window: ^sdl.Window, clear_color: Color = BLACK) {
-	device: ^sdl.GPUDevice,
-	window: ^sdl.Window,
-	clear_color: Color = BLACK,
-) {
 	cmd_buffer := sdl.AcquireGPUCommandBuffer(device)
 	if cmd_buffer == nil {
 		log.panicf("Failed to acquire GPU command buffer: %s", sdl.GetError())
@@ -561,13 +718,9 @@ end :: proc(
 	upload(device, copy_pass)
 	sdl.EndGPUCopyPass(copy_pass)
 
-	// Resize dynamic arrays
-	// TODO: This should only be called occasionally, not every frame.
-	resize_global()
-
 	swapchain_texture: ^sdl.GPUTexture
-	w, h: u32
+	width, height: u32
-	if !sdl.WaitAndAcquireGPUSwapchainTexture(cmd_buffer, window, &swapchain_texture, &w, &h) {
+	if !sdl.WaitAndAcquireGPUSwapchainTexture(cmd_buffer, window, &swapchain_texture, &width, &height) {
 		log.panicf("Failed to acquire swapchain texture: %s", sdl.GetError())
 	}
 
@@ -583,16 +736,16 @@ end :: proc(
 	render_texture := swapchain_texture
 
 	if use_msaa {
-		ensure_msaa_texture(device, sdl.GetGPUSwapchainTextureFormat(device, window), w, h)
+		ensure_msaa_texture(device, sdl.GetGPUSwapchainTextureFormat(device, window), width, height)
 		render_texture = GLOB.msaa_texture
 	}
 
-	cc := color_to_f32(clear_color)
+	clear_color_f32 := color_to_f32(clear_color)
 
 	// Draw layers. One render pass per layer; sub-batches draw in submission order within each scissor.
 	for &layer, index in GLOB.layers {
 		log.debug("Drawing layer", index)
-		draw_layer(device, window, cmd_buffer, render_texture, w, h, cc, &layer)
+		draw_layer(device, window, cmd_buffer, render_texture, width, height, clear_color_f32, &layer)
 	}
 
 	// Resolve MSAA render texture to the swapchain.
@@ -624,15 +777,15 @@ end :: proc(
 max_sample_count :: proc(device: ^sdl.GPUDevice, window: ^sdl.Window) -> sdl.GPUSampleCount {
 	format := sdl.GetGPUSwapchainTextureFormat(device, window)
 	counts := [?]sdl.GPUSampleCount{._8, ._4, ._2}
-	for sc in counts {
+	for count in counts {
-		if sdl.GPUTextureSupportsSampleCount(device, format, sc) do return sc
+		if sdl.GPUTextureSupportsSampleCount(device, format, count) do return count
 	}
 	return ._1
 }
 
 @(private = "file")
-ensure_msaa_texture :: proc(device: ^sdl.GPUDevice, format: sdl.GPUTextureFormat, w, h: u32) {
+ensure_msaa_texture :: proc(device: ^sdl.GPUDevice, format: sdl.GPUTextureFormat, width, height: u32) {
-	if GLOB.msaa_texture != nil && GLOB.msaa_w == w && GLOB.msaa_h == h {
+	if GLOB.msaa_texture != nil && GLOB.msaa_width == width && GLOB.msaa_height == height {
 		return
 	}
 	if GLOB.msaa_texture != nil {
@@ -644,18 +797,18 @@ ensure_msaa_texture :: proc(device: ^sdl.GPUDevice, format: sdl.GPUTextureFormat
 			type = .D2,
 			format = format,
 			usage = {.COLOR_TARGET},
-			width = w,
+			width = width,
-			height = h,
+			height = height,
 			layer_count_or_depth = 1,
 			num_levels = 1,
 			sample_count = GLOB.sample_count,
 		},
 	)
 	if GLOB.msaa_texture == nil {
-		log.panicf("Failed to create MSAA texture (%dx%d): %s", w, h, sdl.GetError())
+		log.panicf("Failed to create MSAA texture (%dx%d): %s", width, height, sdl.GetError())
 	}
-	GLOB.msaa_w = w
+	GLOB.msaa_width = width
-	GLOB.msaa_h = h
+	GLOB.msaa_height = height
 }
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -683,9 +836,21 @@ Vertex_Uniforms :: struct {
 }
 
 // Push projection, dpi scale, and rendering mode as a single uniform block (slot 0).
-push_globals :: proc(cmd_buffer: ^sdl.GPUCommandBuffer, w: f32, h: f32, mode: Draw_Mode = .Tessellated) {
+push_globals :: proc(
+	cmd_buffer: ^sdl.GPUCommandBuffer,
+	width: f32,
+	height: f32,
+	mode: Draw_Mode = .Tessellated,
+) {
 	globals := Vertex_Uniforms {
-		projection = ortho_rh(left = 0.0, top = 0.0, right = f32(w), bottom = f32(h), near = -1.0, far = 1.0),
+		projection = ortho_rh(
+			left = 0.0,
+			top = 0.0,
+			right = f32(width),
+			bottom = f32(height),
+			near = -1.0,
+			far = 1.0,
+		),
 		scale      = GLOB.dpi_scaling,
 		mode       = mode,
 	}
@@ -757,3 +922,115 @@ destroy_buffer :: proc(device: ^sdl.GPUDevice, buffer: ^Buffer) {
 	sdl.ReleaseGPUBuffer(device, buffer.gpu)
 	sdl.ReleaseGPUTransferBuffer(device, buffer.transfer)
 }
+
+// ---------------------------------------------------------------------------------------------------------------------
+// ----- Transform ------------------------
+// ---------------------------------------------------------------------------------------------------------------------
+
+// 2x3 affine transform for 2D pivot-rotation.
+// Used internally by rotation-aware drawing procs.
+Transform_2D :: struct {
+	m00, m01: f32, // row 0: rotation/scale
+	m10, m11: f32, // row 1: rotation/scale
+	tx, ty:   f32, // translation
+}
+
+// Build a pivot-rotation transform.
+//
+// Semantics (raylib-style):
+//   The point whose local coordinates equal `origin` lands at `pos` in world space.
+//   The rest of the shape rotates around that pivot.
+//
+// Formula:  p_world = pos + R(θ) · (p_local - origin)
+//
+// Parameters:
+//   pos          – world-space position where the pivot lands.
+//   origin       – pivot point in local space (measured from the shape's natural reference point).
+//   rotation_deg – rotation in degrees, counter-clockwise.
+//
+build_pivot_rotation :: proc(position: [2]f32, origin: [2]f32, rotation_deg: f32) -> Transform_2D {
+	radians := math.to_radians(rotation_deg)
+	cos_angle := math.cos(radians)
+	sin_angle := math.sin(radians)
+	return Transform_2D {
+		m00 = cos_angle,
+		m01 = -sin_angle,
+		m10 = sin_angle,
+		m11 = cos_angle,
+		tx = position.x - (cos_angle * origin.x - sin_angle * origin.y),
+		ty = position.y - (sin_angle * origin.x + cos_angle * origin.y),
+	}
+}
+
+// Apply the transform to a local-space point, producing a world-space point.
+apply_transform :: #force_inline proc(transform: Transform_2D, point: [2]f32) -> [2]f32 {
+	return {
+		transform.m00 * point.x + transform.m01 * point.y + transform.tx,
+		transform.m10 * point.x + transform.m11 * point.y + transform.ty,
+	}
+}
+
+// Fast-path check callers use BEFORE building a transform.
+// Returns true if either the origin is non-zero or rotation is non-zero,
+// meaning a transform actually needs to be computed.
+needs_transform :: #force_inline proc(origin: [2]f32, rotation: f32) -> bool {
+	return origin != {0, 0} || rotation != 0
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// ----- Procedure Groups ------------------------
+// ---------------------------------------------------------------------------------------------------------------------
+
+center_of :: proc {
+	center_of_rectangle,
+	center_of_triangle,
+	center_of_text,
+}
+
+top_left_of :: proc {
+	top_left_of_rectangle,
+	top_left_of_triangle,
+	top_left_of_text,
+}
+
+top_of :: proc {
+	top_of_rectangle,
+	top_of_triangle,
+	top_of_text,
+}
+
+top_right_of :: proc {
+	top_right_of_rectangle,
+	top_right_of_triangle,
+	top_right_of_text,
+}
+
+left_of :: proc {
+	left_of_rectangle,
+	left_of_triangle,
+	left_of_text,
+}
+
+right_of :: proc {
+	right_of_rectangle,
+	right_of_triangle,
+	right_of_text,
+}
+
+bottom_left_of :: proc {
+	bottom_left_of_rectangle,
+	bottom_left_of_triangle,
+	bottom_left_of_text,
+}
+
+bottom_of :: proc {
+	bottom_of_rectangle,
+	bottom_of_triangle,
+	bottom_of_text,
+}
+
+bottom_right_of :: proc {
+	bottom_right_of_rectangle,
+	bottom_right_of_triangle,
+	bottom_right_of_text,
+}

draw/draw_qr/draw_qr.odin

@@ -0,0 +1,175 @@
+package draw_qr
+
+import draw ".."
+import "../../qrcode"
+
+// Returns the number of bytes to_texture will write for the given encoded
+// QR buffer. Equivalent to size*size*4 where size = qrcode.get_size(qrcode_buf).
+texture_size :: #force_inline proc(qrcode_buf: []u8) -> int {
+	size := qrcode.get_size(qrcode_buf)
+	return size * size * 4
+}
+
+// Decodes an encoded QR buffer into tightly-packed RGBA pixel data written to
+// texture_buf. No allocations, no GPU calls. Returns the Texture_Desc the
+// caller should pass to draw.register_texture alongside texture_buf.
+//
+// Returns ok=false when:
+//   - qrcode_buf is invalid (qrcode.get_size returns 0).
+//   - texture_buf is smaller than to_texture_size(qrcode_buf).
+@(require_results)
+to_texture :: proc(
+	qrcode_buf: []u8,
+	texture_buf: []u8,
+	dark: draw.Color = draw.BLACK,
+	light: draw.Color = draw.WHITE,
+) -> (
+	desc: draw.Texture_Desc,
+	ok: bool,
+) {
+	size := qrcode.get_size(qrcode_buf)
+	if size == 0 do return {}, false
+	if len(texture_buf) < size * size * 4 do return {}, false
+
+	for y in 0 ..< size {
+		for x in 0 ..< size {
+			i := (y * size + x) * 4
+			c := dark if qrcode.get_module(qrcode_buf, x, y) else light
+			texture_buf[i + 0] = c[0]
+			texture_buf[i + 1] = c[1]
+			texture_buf[i + 2] = c[2]
+			texture_buf[i + 3] = c[3]
+		}
+	}
+
+	return draw.Texture_Desc {
+			width = u32(size),
+			height = u32(size),
+			depth_or_layers = 1,
+			type = .D2,
+			format = .R8G8B8A8_UNORM,
+			usage = {.SAMPLER},
+			mip_levels = 1,
+			kind = .Static,
+		},
+		true
+}
+
+// Allocates pixel buffer via temp_allocator, decodes qrcode_buf into it, and
+// registers with the GPU. The pixel allocation is freed before return.
+//
+// Returns ok=false when:
+//   - qrcode_buf is invalid (qrcode.get_size returns 0).
+//   - temp_allocator fails to allocate the pixel buffer.
+//   - GPU texture registration fails.
+@(require_results)
+register_texture_from_raw :: proc(
+	qrcode_buf: []u8,
+	dark: draw.Color = draw.BLACK,
+	light: draw.Color = draw.WHITE,
+	temp_allocator := context.temp_allocator,
+) -> (
+	texture: draw.Texture_Id,
+	ok: bool,
+) {
+	tex_size := texture_size(qrcode_buf)
+	if tex_size == 0 do return draw.INVALID_TEXTURE, false
+
+	pixels, alloc_err := make([]u8, tex_size, temp_allocator)
+	if alloc_err != nil do return draw.INVALID_TEXTURE, false
+	defer delete(pixels, temp_allocator)
+
+	desc := to_texture(qrcode_buf, pixels, dark, light) or_return
+	return draw.register_texture(desc, pixels)
+}
+
+// Encodes text as a QR Code and registers the result as an RGBA texture.
+//
+// Returns ok=false when:
+//   - temp_allocator fails to allocate.
+//   - The text cannot fit in any version within [min_version, max_version] at the given ECL.
+//   - GPU texture registration fails.
+@(require_results)
+register_texture_from_text :: proc(
+	text: string,
+	ecl: qrcode.Ecc = .Low,
+	min_version: int = qrcode.VERSION_MIN,
+	max_version: int = qrcode.VERSION_MAX,
+	mask: Maybe(qrcode.Mask) = nil,
+	boost_ecl: bool = true,
+	dark: draw.Color = draw.BLACK,
+	light: draw.Color = draw.WHITE,
+	temp_allocator := context.temp_allocator,
+) -> (
+	texture: draw.Texture_Id,
+	ok: bool,
+) {
+	qrcode_buf, alloc_err := make([]u8, qrcode.buffer_len_for_version(max_version), temp_allocator)
+	if alloc_err != nil do return draw.INVALID_TEXTURE, false
+	defer delete(qrcode_buf, temp_allocator)
+
+	qrcode.encode_auto(
+		text,
+		qrcode_buf,
+		ecl,
+		min_version,
+		max_version,
+		mask,
+		boost_ecl,
+		temp_allocator,
+	) or_return
+
+	return register_texture_from_raw(qrcode_buf, dark, light, temp_allocator)
+}
+
+// Encodes arbitrary binary data as a QR Code and registers the result as an RGBA texture.
+//
+// Returns ok=false when:
+//   - temp_allocator fails to allocate.
+//   - The payload cannot fit in any version within [min_version, max_version] at the given ECL.
+//   - GPU texture registration fails.
+@(require_results)
+register_texture_from_binary :: proc(
+	bin_data: []u8,
+	ecl: qrcode.Ecc = .Low,
+	min_version: int = qrcode.VERSION_MIN,
+	max_version: int = qrcode.VERSION_MAX,
+	mask: Maybe(qrcode.Mask) = nil,
+	boost_ecl: bool = true,
+	dark: draw.Color = draw.BLACK,
+	light: draw.Color = draw.WHITE,
+	temp_allocator := context.temp_allocator,
+) -> (
+	texture: draw.Texture_Id,
+	ok: bool,
+) {
+	qrcode_buf, alloc_err := make([]u8, qrcode.buffer_len_for_version(max_version), temp_allocator)
+	if alloc_err != nil do return draw.INVALID_TEXTURE, false
+	defer delete(qrcode_buf, temp_allocator)
+
+	qrcode.encode_auto(
+		bin_data,
+		qrcode_buf,
+		ecl,
+		min_version,
+		max_version,
+		mask,
+		boost_ecl,
+		temp_allocator,
+	) or_return
+
+	return register_texture_from_raw(qrcode_buf, dark, light, temp_allocator)
+}
+
+register_texture_from :: proc {
+	register_texture_from_text,
+	register_texture_from_binary
+}
+
+// Default fit=.Fit preserves the QR's square aspect; override as needed.
+clay_image :: #force_inline proc(
+	texture: draw.Texture_Id,
+	tint: draw.Color = draw.WHITE,
+) -> draw.Clay_Image_Data {
+	return draw.clay_image_data(texture, fit = .Fit, tint = tint)
+}

draw/examples/hellope.odin

@@ -2,10 +2,9 @@ package examples
 
 import "../../draw"
 import "../../vendor/clay"
-import "core:c"
+import "core:math"
 import "core:os"
 import sdl "vendor:sdl3"
-import sdl_ttf "vendor:sdl3/ttf"
 
 JETBRAINS_MONO_REGULAR_RAW :: #load("fonts/JetBrainsMono-Regular.ttf")
 JETBRAINS_MONO_REGULAR: draw.Font_Id = max(draw.Font_Id) // Max so we crash if registration is forgotten
@@ -13,25 +12,28 @@ JETBRAINS_MONO_REGULAR: draw.Font_Id = max(draw.Font_Id) // Max so we crash if r
 hellope_shapes :: proc() {
 	if !sdl.Init({.VIDEO}) do os.exit(1)
 	window := sdl.CreateWindow("Hellope!", 500, 500, {.HIGH_PIXEL_DENSITY})
-	gpu := sdl.CreateGPUDevice({.MSL}, true, nil)
+	gpu := sdl.CreateGPUDevice(draw.PLATFORM_SHADER_FORMAT, true, nil)
 	if !sdl.ClaimWindowForGPUDevice(gpu, window) do os.exit(1)
 	if !draw.init(gpu, window) do os.exit(1)
 
+	spin_angle: f32 = 0
+
 	for {
 		defer free_all(context.temp_allocator)
 		ev: sdl.Event
 		for sdl.PollEvent(&ev) {
 			if ev.type == .QUIT do return
 		}
-		base_layer := draw.begin({w = 500, h = 500})
+		spin_angle += 1
+		base_layer := draw.begin({width = 500, height = 500})
 
 		// Background
 		draw.rectangle(base_layer, {0, 0, 500, 500}, {40, 40, 40, 255})
 
-		// Shapes demo
+		// ----- Shapes without rotation (existing demo) -----
 		draw.rectangle(base_layer, {20, 20, 200, 120}, {80, 120, 200, 255})
-		draw.rectangle_lines(base_layer, {20, 20, 200, 120}, draw.WHITE, thick = 2)
+		draw.rectangle_lines(base_layer, {20, 20, 200, 120}, draw.WHITE, thickness = 2)
-		draw.rectangle_rounded(base_layer, {240, 20, 240, 120}, 0.3, {200, 80, 80, 255})
+		draw.rectangle(base_layer, {240, 20, 240, 120}, {200, 80, 80, 255}, roundness = 0.3)
 		draw.rectangle_gradient(
 			base_layer,
 			{20, 160, 460, 60},
@@ -41,33 +43,87 @@ hellope_shapes :: proc() {
 			{255, 255, 0, 255},
 		)
 
-		draw.circle(base_layer, {120, 320}, 60, {100, 200, 100, 255})
+		// ----- Rotation demos -----
-		draw.circle_lines(base_layer, {120, 320}, 60, draw.WHITE, thick = 2)
-		draw.circle_gradient(base_layer, {300, 320}, 60, {255, 200, 50, 255}, {200, 50, 50, 255})
-		draw.ring(base_layer, {430, 320}, 30, 55, 0, 270, {100, 100, 220, 255})
 
-		draw.triangle(base_layer, {60, 420}, {180, 480}, {20, 480}, {220, 180, 60, 255})
+		// Rectangle rotating around its center
-		draw.line(base_layer, {220, 420}, {460, 480}, {255, 255, 100, 255}, thick = 3)
+		rect := draw.Rectangle{100, 320, 80, 50}
-		draw.poly(base_layer, {350, 450}, 6, 40, {180, 100, 220, 255}, rotation = 30)
+		draw.rectangle(
-		draw.poly_lines(base_layer, {350, 450}, 6, 40, draw.WHITE, rotation = 30, thick = 2)
+			base_layer,
+			rect,
+			{100, 200, 100, 255},
+			origin = draw.center_of(rect),
+			rotation = spin_angle,
+		)
+		draw.rectangle_lines(
+			base_layer,
+			rect,
+			draw.WHITE,
+			thickness = 2,
+			origin = draw.center_of(rect),
+			rotation = spin_angle,
+		)
+
+		// Rounded rectangle rotating around its center
+		rrect := draw.Rectangle{230, 300, 100, 80}
+		draw.rectangle(
+			base_layer,
+			rrect,
+			{200, 100, 200, 255},
+			roundness = 0.4,
+			origin = draw.center_of(rrect),
+			rotation = spin_angle,
+		)
+
+		// Ellipse rotating around its center (tilted ellipse)
+		draw.ellipse(base_layer, {410, 340}, 50, 30, {255, 200, 50, 255}, rotation = spin_angle)
+
+		// Circle orbiting a point (moon orbiting planet)
+		// Convention B: center = pivot point (planet), origin = offset from moon center to pivot.
+		// Moon's visual center at rotation=0: planet_pos - origin = (100, 450) - (0, 40) = (100, 410).
+		planet_pos := [2]f32{100, 450}
+		draw.circle(base_layer, planet_pos, 8, {200, 200, 200, 255}) // planet (stationary)
+		draw.circle(base_layer, planet_pos, 5, {100, 150, 255, 255}, origin = {0, 40}, rotation = spin_angle) // moon orbiting
+
+		// Ring arc rotating in place
+		draw.ring(base_layer, {250, 450}, 15, 30, 0, 270, {100, 100, 220, 255}, rotation = spin_angle)
+
+		// Triangle rotating around its center
+		tv1 := [2]f32{350, 420}
+		tv2 := [2]f32{420, 480}
+		tv3 := [2]f32{340, 480}
+		draw.triangle(
+			base_layer,
+			tv1,
+			tv2,
+			tv3,
+			{220, 180, 60, 255},
+			origin = draw.center_of(tv1, tv2, tv3),
+			rotation = spin_angle,
+		)
+
+		// Polygon rotating around its center (already had rotation; now with origin for orbit)
+		draw.polygon(base_layer, {460, 450}, 6, 30, {180, 100, 220, 255}, rotation = spin_angle)
+		draw.polygon_lines(base_layer, {460, 450}, 6, 30, draw.WHITE, rotation = spin_angle, thickness = 2)
 
 		draw.end(gpu, window)
 	}
 }
 
 hellope_text :: proc() {
+	HELLOPE_ID :: 1
+	ROTATING_SENTENCE_ID :: 2
+	MEASURED_ID :: 3
+	CORNER_SPIN_ID :: 4
+
 	if !sdl.Init({.VIDEO}) do os.exit(1)
-	window := sdl.CreateWindow("Hellope!", 500, 500, {.HIGH_PIXEL_DENSITY})
+	window := sdl.CreateWindow("Hellope!", 600, 600, {.HIGH_PIXEL_DENSITY})
-	gpu := sdl.CreateGPUDevice({.MSL}, true, nil)
+	gpu := sdl.CreateGPUDevice(draw.PLATFORM_SHADER_FORMAT, true, nil)
 	if !sdl.ClaimWindowForGPUDevice(gpu, window) do os.exit(1)
 	if !draw.init(gpu, window) do os.exit(1)
 	JETBRAINS_MONO_REGULAR = draw.register_font(JETBRAINS_MONO_REGULAR_RAW)
 
 	FONT_SIZE :: u16(24)
-	TEXT_ID :: u32(1)
+	spin_angle: f32 = 0
-
-	font := draw.get_font(JETBRAINS_MONO_REGULAR, FONT_SIZE)
-	dpi := sdl.GetWindowDisplayScale(window)
 
 	for {
 		defer free_all(context.temp_allocator)
@@ -75,28 +131,74 @@ hellope_text :: proc() {
 		for sdl.PollEvent(&ev) {
 			if ev.type == .QUIT do return
 		}
-		base_layer := draw.begin({w = 500, h = 500})
+		spin_angle += 0.5
+		base_layer := draw.begin({width = 600, height = 600})
 
 		// Grey background
-		draw.rectangle(base_layer, {0, 0, 500, 500}, {127, 127, 127, 255})
+		draw.rectangle(base_layer, {0, 0, 600, 600}, {127, 127, 127, 255})
 
-		// Measure and center text
+		// ----- Text API demos -----
-		tw, th: c.int
-		sdl_ttf.GetStringSize(font, "Hellope!", 0, &tw, &th)
-		text_w := f32(tw) / dpi
-		text_h := f32(th) / dpi
-		pos_x := (500.0 - text_w) / 2.0
-		pos_y := (500.0 - text_h) / 2.0
 
-		txt := draw.text(
+		// Cached text with id — TTF_Text reused across frames (good for text-heavy apps)
-			TEXT_ID,
+		draw.text(
+			base_layer,
 			"Hellope!",
-			{pos_x, pos_y},
+			{300, 80},
+			JETBRAINS_MONO_REGULAR,
+			FONT_SIZE,
 			color = draw.WHITE,
-			font_id = JETBRAINS_MONO_REGULAR,
+			origin = draw.center_of("Hellope!", JETBRAINS_MONO_REGULAR, FONT_SIZE),
-			font_size = FONT_SIZE,
+			id = HELLOPE_ID,
+		)
+
+		// Rotating sentence — verifies multi-word text rotation around center
+		draw.text(
+			base_layer,
+			"Hellope World!",
+			{300, 250},
+			JETBRAINS_MONO_REGULAR,
+			FONT_SIZE,
+			color = {255, 200, 50, 255},
+			origin = draw.center_of("Hellope World!", JETBRAINS_MONO_REGULAR, FONT_SIZE),
+			rotation = spin_angle,
+			id = ROTATING_SENTENCE_ID,
+		)
+
+		// Uncached text (no id) — created and destroyed each frame, simplest usage
+		draw.text(
+			base_layer,
+			"Top-left anchored",
+			{20, 450},
+			JETBRAINS_MONO_REGULAR,
+			FONT_SIZE,
+			color = draw.WHITE,
+		)
+
+		// Measure text for manual layout
+		size := draw.measure_text("Measured!", JETBRAINS_MONO_REGULAR, FONT_SIZE)
+		draw.rectangle(base_layer, {300 - size.x / 2, 380, size.x, size.y}, {60, 60, 60, 200})
+		draw.text(
+			base_layer,
+			"Measured!",
+			{300, 380},
+			JETBRAINS_MONO_REGULAR,
+			FONT_SIZE,
+			color = draw.WHITE,
+			origin = draw.top_of("Measured!", JETBRAINS_MONO_REGULAR, FONT_SIZE),
+			id = MEASURED_ID,
+		)
+
+		// Rotating text anchored at top-left (no origin offset) — spins around top-left corner
+		draw.text(
+			base_layer,
+			"Corner spin",
+			{150, 530},
+			JETBRAINS_MONO_REGULAR,
+			FONT_SIZE,
+			color = {100, 200, 255, 255},
+			rotation = spin_angle,
+			id = CORNER_SPIN_ID,
 		)
-		draw.prepare_text(base_layer, txt)
 
 		draw.end(gpu, window)
 	}
@@ -105,14 +207,14 @@ hellope_text :: proc() {
 hellope_clay :: proc() {
 	if !sdl.Init({.VIDEO}) do os.exit(1)
 	window := sdl.CreateWindow("Hellope!", 500, 500, {.HIGH_PIXEL_DENSITY})
-	gpu := sdl.CreateGPUDevice({.MSL}, true, nil)
+	gpu := sdl.CreateGPUDevice(draw.PLATFORM_SHADER_FORMAT, true, nil)
 	if !sdl.ClaimWindowForGPUDevice(gpu, window) do os.exit(1)
 	if !draw.init(gpu, window) do os.exit(1)
 	JETBRAINS_MONO_REGULAR = draw.register_font(JETBRAINS_MONO_REGULAR_RAW)
 
 	text_config := clay.TextElementConfig {
 		fontId    = JETBRAINS_MONO_REGULAR,
-		fontSize  = 24,
+		fontSize  = 36,
 		textColor = {255, 255, 255, 255},
 	}
 
@@ -122,8 +224,8 @@ hellope_clay :: proc() {
 		for sdl.PollEvent(&ev) {
 			if ev.type == .QUIT do return
 		}
-		base_layer := draw.begin({w = 500, h = 500})
+		base_layer := draw.begin({width = 500, height = 500})
-		clay.SetLayoutDimensions({width = base_layer.bounds.w, height = base_layer.bounds.h})
+		clay.SetLayoutDimensions({width = base_layer.bounds.width, height = base_layer.bounds.height})
 		clay.BeginLayout()
 		if clay.UI()(
 		{
@@ -145,3 +247,106 @@ hellope_clay :: proc() {
 		draw.end(gpu, window)
 	}
 }
+
+hellope_custom :: proc() {
+	if !sdl.Init({.VIDEO}) do os.exit(1)
+	window := sdl.CreateWindow("Hellope Custom!", 600, 400, {.HIGH_PIXEL_DENSITY})
+	gpu := sdl.CreateGPUDevice(draw.PLATFORM_SHADER_FORMAT, true, nil)
+	if !sdl.ClaimWindowForGPUDevice(gpu, window) do os.exit(1)
+	if !draw.init(gpu, window) do os.exit(1)
+	JETBRAINS_MONO_REGULAR = draw.register_font(JETBRAINS_MONO_REGULAR_RAW)
+
+	text_config := clay.TextElementConfig {
+		fontId    = JETBRAINS_MONO_REGULAR,
+		fontSize  = 24,
+		textColor = {255, 255, 255, 255},
+	}
+
+	gauge := Gauge {
+		value = 0.73,
+		color = {50, 200, 100, 255},
+	}
+	gauge2 := Gauge {
+		value = 0.45,
+		color = {200, 100, 50, 255},
+	}
+	spin_angle: f32 = 0
+
+	for {
+		defer free_all(context.temp_allocator)
+		ev: sdl.Event
+		for sdl.PollEvent(&ev) {
+			if ev.type == .QUIT do return
+		}
+
+		spin_angle += 1
+		gauge.value = (math.sin(spin_angle * 0.02) + 1) * 0.5
+		gauge2.value = (math.cos(spin_angle * 0.03) + 1) * 0.5
+
+		base_layer := draw.begin({width = 600, height = 400})
+		clay.SetLayoutDimensions({width = base_layer.bounds.width, height = base_layer.bounds.height})
+		clay.BeginLayout()
+
+		if clay.UI()(
+		{
+			id = clay.ID("outer"),
+			layout = {
+				sizing = {clay.SizingGrow({}), clay.SizingGrow({})},
+				childAlignment = {x = .Center, y = .Center},
+				layoutDirection = .TopToBottom,
+				childGap = 20,
+			},
+			backgroundColor = {50, 50, 50, 255},
+		},
+		) {
+			if clay.UI()({id = clay.ID("title"), layout = {sizing = {clay.SizingFit({}), clay.SizingFit({})}}}) {
+				clay.Text("Custom Draw Demo", &text_config)
+			}
+
+			if clay.UI()(
+			{
+				id = clay.ID("gauge"),
+				layout = {sizing = {clay.SizingFixed(300), clay.SizingFixed(30)}},
+				custom = {customData = &gauge},
+				backgroundColor = {80, 80, 80, 255},
+			},
+			) {}
+
+			if clay.UI()(
+			{
+				id = clay.ID("gauge2"),
+				layout = {sizing = {clay.SizingFixed(300), clay.SizingFixed(30)}},
+				custom = {customData = &gauge2},
+				backgroundColor = {80, 80, 80, 255},
+			},
+			) {}
+		}
+
+		clay_batch := draw.ClayBatch {
+			bounds = base_layer.bounds,
+			cmds   = clay.EndLayout(),
+		}
+		draw.prepare_clay_batch(base_layer, &clay_batch, {0, 0}, custom_draw = draw_custom)
+		draw.end(gpu, window)
+	}
+
+	Gauge :: struct {
+		value: f32,
+		color: draw.Color,
+	}
+
+	draw_custom :: proc(layer: ^draw.Layer, bounds: draw.Rectangle, render_data: clay.CustomRenderData) {
+		gauge := cast(^Gauge)render_data.customData
+
+		// Background from clay's backgroundColor
+		draw.rectangle(layer, bounds, draw.color_from_clay(render_data.backgroundColor), roundness = 0.25)
+
+		// Fill bar
+		fill := bounds
+		fill.width *= gauge.value
+		draw.rectangle(layer, fill, gauge.color, roundness = 0.25)
+
+		// Border
+		draw.rectangle_lines(layer, bounds, draw.WHITE, thickness = 2, roundness = 0.25)
+	}
+}

draw/examples/main.odin

@@ -57,17 +57,19 @@ main :: proc() {
 	args := os.args
 	if len(args) < 2 {
 		fmt.eprintln("Usage: examples <example_name>")
-		fmt.eprintln("Available examples: hellope-shapes, hellope-text, hellope-clay")
+		fmt.eprintln("Available examples: hellope-shapes, hellope-text, hellope-clay, hellope-custom, textures")
 		os.exit(1)
 	}
 
 	switch args[1] {
 	case "hellope-clay": hellope_clay()
+	case "hellope-custom": hellope_custom()
 	case "hellope-shapes": hellope_shapes()
 	case "hellope-text": hellope_text()
+	case "textures": textures()
 	case:
 		fmt.eprintf("Unknown example: %v\n", args[1])
-		fmt.eprintln("Available examples: hellope-shapes, hellope-text, hellope-clay")
+		fmt.eprintln("Available examples: hellope-shapes, hellope-text, hellope-clay, hellope-custom, textures")
 		os.exit(1)
 	}
 }

draw/examples/textures.odin

@@ -0,0 +1,272 @@
+package examples
+
+import "../../draw"
+import "../../draw/draw_qr"
+import "core:os"
+import sdl "vendor:sdl3"
+
+textures :: proc() {
+	if !sdl.Init({.VIDEO}) do os.exit(1)
+	window := sdl.CreateWindow("Textures", 800, 600, {.HIGH_PIXEL_DENSITY})
+	gpu := sdl.CreateGPUDevice(draw.PLATFORM_SHADER_FORMAT, true, nil)
+	if !sdl.ClaimWindowForGPUDevice(gpu, window) do os.exit(1)
+	if !draw.init(gpu, window) do os.exit(1)
+	JETBRAINS_MONO_REGULAR = draw.register_font(JETBRAINS_MONO_REGULAR_RAW)
+
+	FONT_SIZE :: u16(14)
+	LABEL_OFFSET :: f32(8) // gap between item and its label
+
+	//----- Texture registration ----------------------------------
+
+	checker_size :: 8
+	checker_pixels: [checker_size * checker_size * 4]u8
+	for y in 0 ..< checker_size {
+		for x in 0 ..< checker_size {
+			i := (y * checker_size + x) * 4
+			is_dark := ((x + y) % 2) == 0
+			val: u8 = 40 if is_dark else 220
+			checker_pixels[i + 0] = val // R
+			checker_pixels[i + 1] = val / 2 // G — slight color tint
+			checker_pixels[i + 2] = val // B
+			checker_pixels[i + 3] = 255 // A
+		}
+	}
+	checker_texture, _ := draw.register_texture(
+		draw.Texture_Desc {
+			width = checker_size,
+			height = checker_size,
+			depth_or_layers = 1,
+			type = .D2,
+			format = .R8G8B8A8_UNORM,
+			usage = {.SAMPLER},
+			mip_levels = 1,
+		},
+		checker_pixels[:],
+	)
+	defer draw.unregister_texture(checker_texture)
+
+	stripe_w :: 16
+	stripe_h :: 8
+	stripe_pixels: [stripe_w * stripe_h * 4]u8
+	for y in 0 ..< stripe_h {
+		for x in 0 ..< stripe_w {
+			i := (y * stripe_w + x) * 4
+			stripe_pixels[i + 0] = u8(x * 255 / (stripe_w - 1)) // R gradient left→right
+			stripe_pixels[i + 1] = u8(y * 255 / (stripe_h - 1)) // G gradient top→bottom
+			stripe_pixels[i + 2] = 128 // B constant
+			stripe_pixels[i + 3] = 255 // A
+		}
+	}
+	stripe_texture, _ := draw.register_texture(
+		draw.Texture_Desc {
+			width = stripe_w,
+			height = stripe_h,
+			depth_or_layers = 1,
+			type = .D2,
+			format = .R8G8B8A8_UNORM,
+			usage = {.SAMPLER},
+			mip_levels = 1,
+		},
+		stripe_pixels[:],
+	)
+	defer draw.unregister_texture(stripe_texture)
+
+	qr_texture, _ := draw_qr.register_texture_from("https://x.com/miiilato/status/1880241066471051443")
+	defer draw.unregister_texture(qr_texture)
+
+	spin_angle: f32 = 0
+
+	//----- Draw loop ----------------------------------
+
+	for {
+		defer free_all(context.temp_allocator)
+		ev: sdl.Event
+		for sdl.PollEvent(&ev) {
+			if ev.type == .QUIT do return
+		}
+		spin_angle += 1
+
+		base_layer := draw.begin({width = 800, height = 600})
+
+		// Background
+		draw.rectangle(base_layer, {0, 0, 800, 600}, {30, 30, 30, 255})
+
+		//----- Row 1: Sampler presets (y=30) ----------------------------------
+
+		ROW1_Y :: f32(30)
+		ITEM_SIZE :: f32(120)
+		COL1 :: f32(30)
+		COL2 :: f32(180)
+		COL3 :: f32(330)
+		COL4 :: f32(480)
+
+		// Nearest (sharp pixel edges)
+		draw.rectangle_texture(
+			base_layer,
+			{COL1, ROW1_Y, ITEM_SIZE, ITEM_SIZE},
+			checker_texture,
+			sampler = .Nearest_Clamp,
+		)
+		draw.text(
+			base_layer,
+			"Nearest",
+			{COL1, ROW1_Y + ITEM_SIZE + LABEL_OFFSET},
+			JETBRAINS_MONO_REGULAR,
+			FONT_SIZE,
+			color = draw.WHITE,
+		)
+
+		// Linear (bilinear blur)
+		draw.rectangle_texture(
+			base_layer,
+			{COL2, ROW1_Y, ITEM_SIZE, ITEM_SIZE},
+			checker_texture,
+			sampler = .Linear_Clamp,
+		)
+		draw.text(
+			base_layer,
+			"Linear",
+			{COL2, ROW1_Y + ITEM_SIZE + LABEL_OFFSET},
+			JETBRAINS_MONO_REGULAR,
+			FONT_SIZE,
+			color = draw.WHITE,
+		)
+
+		// Tiled (4x repeat)
+		draw.rectangle_texture(
+			base_layer,
+			{COL3, ROW1_Y, ITEM_SIZE, ITEM_SIZE},
+			checker_texture,
+			sampler = .Nearest_Repeat,
+			uv_rect = {0, 0, 4, 4},
+		)
+		draw.text(
+			base_layer,
+			"Tiled 4x",
+			{COL3, ROW1_Y + ITEM_SIZE + LABEL_OFFSET},
+			JETBRAINS_MONO_REGULAR,
+			FONT_SIZE,
+			color = draw.WHITE,
+		)
+
+		//----- Row 2: Sampler presets (y=190) ----------------------------------
+
+		ROW2_Y :: f32(190)
+
+		// QR code (RGBA texture with baked colors, nearest sampling)
+		draw.rectangle(base_layer, {COL1, ROW2_Y, ITEM_SIZE, ITEM_SIZE}, {255, 255, 255, 255}) // white bg
+		draw.rectangle_texture(
+			base_layer,
+			{COL1, ROW2_Y, ITEM_SIZE, ITEM_SIZE},
+			qr_texture,
+			sampler = .Nearest_Clamp,
+		)
+		draw.text(
+			base_layer,
+			"QR Code",
+			{COL1, ROW2_Y + ITEM_SIZE + LABEL_OFFSET},
+			JETBRAINS_MONO_REGULAR,
+			FONT_SIZE,
+			color = draw.WHITE,
+		)
+
+		// Rounded corners
+		draw.rectangle_texture(
+			base_layer,
+			{COL2, ROW2_Y, ITEM_SIZE, ITEM_SIZE},
+			checker_texture,
+			sampler = .Nearest_Clamp,
+			roundness = 0.3,
+		)
+		draw.text(
+			base_layer,
+			"Rounded",
+			{COL2, ROW2_Y + ITEM_SIZE + LABEL_OFFSET},
+			JETBRAINS_MONO_REGULAR,
+			FONT_SIZE,
+			color = draw.WHITE,
+		)
+
+		// Rotating
+		rot_rect := draw.Rectangle{COL3, ROW2_Y, ITEM_SIZE, ITEM_SIZE}
+		draw.rectangle_texture(
+			base_layer,
+			rot_rect,
+			checker_texture,
+			sampler = .Nearest_Clamp,
+			origin = draw.center_of(rot_rect),
+			rotation = spin_angle,
+		)
+		draw.text(
+			base_layer,
+			"Rotating",
+			{COL3, ROW2_Y + ITEM_SIZE + LABEL_OFFSET},
+			JETBRAINS_MONO_REGULAR,
+			FONT_SIZE,
+			color = draw.WHITE,
+		)
+
+		//----- Row 3: Fit modes + Per-corner radii (y=360) ----------------------------------
+
+		ROW3_Y :: f32(360)
+		FIT_SIZE :: f32(120) // square target rect
+
+		// Stretch
+		uv_s, sampler_s, inner_s := draw.fit_params(.Stretch, {COL1, ROW3_Y, FIT_SIZE, FIT_SIZE}, stripe_texture)
+		draw.rectangle(base_layer, {COL1, ROW3_Y, FIT_SIZE, FIT_SIZE}, {60, 60, 60, 255}) // bg
+		draw.rectangle_texture(base_layer, inner_s, stripe_texture, uv_rect = uv_s, sampler = sampler_s)
+		draw.text(
+			base_layer,
+			"Stretch",
+			{COL1, ROW3_Y + FIT_SIZE + LABEL_OFFSET},
+			JETBRAINS_MONO_REGULAR,
+			FONT_SIZE,
+			color = draw.WHITE,
+		)
+
+		// Fill (center-crop)
+		uv_f, sampler_f, inner_f := draw.fit_params(.Fill, {COL2, ROW3_Y, FIT_SIZE, FIT_SIZE}, stripe_texture)
+		draw.rectangle(base_layer, {COL2, ROW3_Y, FIT_SIZE, FIT_SIZE}, {60, 60, 60, 255})
+		draw.rectangle_texture(base_layer, inner_f, stripe_texture, uv_rect = uv_f, sampler = sampler_f)
+		draw.text(
+			base_layer,
+			"Fill",
+			{COL2, ROW3_Y + FIT_SIZE + LABEL_OFFSET},
+			JETBRAINS_MONO_REGULAR,
+			FONT_SIZE,
+			color = draw.WHITE,
+		)
+
+		// Fit (letterbox)
+		uv_ft, sampler_ft, inner_ft := draw.fit_params(.Fit, {COL3, ROW3_Y, FIT_SIZE, FIT_SIZE}, stripe_texture)
+		draw.rectangle(base_layer, {COL3, ROW3_Y, FIT_SIZE, FIT_SIZE}, {60, 60, 60, 255}) // visible margin bg
+		draw.rectangle_texture(base_layer, inner_ft, stripe_texture, uv_rect = uv_ft, sampler = sampler_ft)
+		draw.text(
+			base_layer,
+			"Fit",
+			{COL3, ROW3_Y + FIT_SIZE + LABEL_OFFSET},
+			JETBRAINS_MONO_REGULAR,
+			FONT_SIZE,
+			color = draw.WHITE,
+		)
+
+		// Per-corner radii
+		draw.rectangle_texture_corners(
+			base_layer,
+			{COL4, ROW3_Y, FIT_SIZE, FIT_SIZE},
+			{20, 0, 20, 0},
+			checker_texture,
+			sampler = .Nearest_Clamp,
+		)
+		draw.text(
+			base_layer,
+			"Per-corner",
+			{COL4, ROW3_Y + FIT_SIZE + LABEL_OFFSET},
+			JETBRAINS_MONO_REGULAR,
+			FONT_SIZE,
+			color = draw.WHITE,
+		)
+
+		draw.end(gpu, window)
+	}
+}

draw/pipeline_2d_base.odin

@@ -35,6 +35,7 @@ Shape_Kind :: enum u8 {
 
 Shape_Flag :: enum u8 {
 	Stroke,
+	Textured,
 }
 
 Shape_Flags :: bit_set[Shape_Flag;u8]
@@ -103,11 +104,13 @@ Primitive :: struct {
 	bounds:     [4]f32, //  0: min_x, min_y, max_x, max_y (world-space, pre-DPI)
 	color:      Color, // 16: u8x4, unpacked in shader via unpackUnorm4x8
 	kind_flags: u32, // 20: (kind as u32) | (flags as u32 << 8)
-	_pad:        [2]f32,       // 24: alignment to vec4 boundary
+	rotation:   f32, // 24: shader self-rotation in radians (used by RRect, Ellipse)
+	_pad:       f32, // 28: alignment to vec4 boundary
 	params:     Shape_Params, // 32: two vec4s of shape params
+	uv_rect:    [4]f32, // 64: u_min, v_min, u_max, v_max (default {0,0,1,1})
 }
 
-#assert(size_of(Primitive) == 64)
+#assert(size_of(Primitive) == 80)
 
 pack_kind_flags :: #force_inline proc(kind: Shape_Kind, flags: Shape_Flags) -> u32 {
 	return u32(kind) | (u32(transmute(u8)flags) << 8)
@@ -143,32 +146,34 @@ create_pipeline_2d_base :: proc(
 		if pipeline.sdl_pipeline != nil do sdl.ReleaseGPUGraphicsPipeline(device, pipeline.sdl_pipeline)
 	}
 
-	when ODIN_OS == .Darwin {
+	active_shader_formats := sdl.GetGPUShaderFormats(device)
-		base_2d_vert_raw := #load("shaders/generated/base_2d.vert.metal")
+	if PLATFORM_SHADER_FORMAT_FLAG not_in active_shader_formats {
-		base_2d_frag_raw := #load("shaders/generated/base_2d.frag.metal")
+		log.errorf(
-	} else {
+			"draw: no embedded shader matches active GPU formats; this build supports %v but device reports %v",
-		base_2d_vert_raw := #load("shaders/generated/base_2d.vert.spv")
+			PLATFORM_SHADER_FORMAT,
-		base_2d_frag_raw := #load("shaders/generated/base_2d.frag.spv")
+			active_shader_formats,
+		)
+		return pipeline, false
 	}
 
-	log.debug("Loaded", len(base_2d_vert_raw), "vert bytes")
+	log.debug("Loaded", len(BASE_VERT_2D_RAW), "vert bytes")
-	log.debug("Loaded", len(base_2d_frag_raw), "frag bytes")
+	log.debug("Loaded", len(BASE_FRAG_2D_RAW), "frag bytes")
 
 	vert_info := sdl.GPUShaderCreateInfo {
-		code_size           = len(base_2d_vert_raw),
+		code_size           = len(BASE_VERT_2D_RAW),
-		code                = raw_data(base_2d_vert_raw),
+		code                = raw_data(BASE_VERT_2D_RAW),
-		entrypoint          = ENTRY_POINT,
+		entrypoint          = SHADER_ENTRY,
-		format              = SHADER_TYPE,
+		format              = {PLATFORM_SHADER_FORMAT_FLAG},
 		stage               = .VERTEX,
 		num_uniform_buffers = 1,
 		num_storage_buffers = 1,
 	}
 
 	frag_info := sdl.GPUShaderCreateInfo {
-		code_size    = len(base_2d_frag_raw),
+		code_size    = len(BASE_FRAG_2D_RAW),
-		code         = raw_data(base_2d_frag_raw),
+		code         = raw_data(BASE_FRAG_2D_RAW),
-		entrypoint   = ENTRY_POINT,
+		entrypoint   = SHADER_ENTRY,
-		format       = SHADER_TYPE,
+		format       = {PLATFORM_SHADER_FORMAT_FLAG},
 		stage        = .FRAGMENT,
 		num_samplers = 1,
 	}
@@ -239,31 +244,31 @@ create_pipeline_2d_base :: proc(
 	}
 
 	// Create vertex buffer
-	vb_ok: bool
+	vert_buf_ok: bool
-	pipeline.vertex_buffer, vb_ok = create_buffer(
+	pipeline.vertex_buffer, vert_buf_ok = create_buffer(
 		device,
 		size_of(Vertex) * BUFFER_INIT_SIZE,
 		sdl.GPUBufferUsageFlags{.VERTEX},
 	)
-	if !vb_ok do return pipeline, false
+	if !vert_buf_ok do return pipeline, false
 
 	// Create index buffer (used by text)
-	ib_ok: bool
+	idx_buf_ok: bool
-	pipeline.index_buffer, ib_ok = create_buffer(
+	pipeline.index_buffer, idx_buf_ok = create_buffer(
 		device,
 		size_of(c.int) * BUFFER_INIT_SIZE,
 		sdl.GPUBufferUsageFlags{.INDEX},
 	)
-	if !ib_ok do return pipeline, false
+	if !idx_buf_ok do return pipeline, false
 
 	// Create primitive storage buffer (used by SDF instanced drawing)
-	pb_ok: bool
+	prim_buf_ok: bool
-	pipeline.primitive_buffer, pb_ok = create_buffer(
+	pipeline.primitive_buffer, prim_buf_ok = create_buffer(
 		device,
 		size_of(Primitive) * BUFFER_INIT_SIZE,
 		sdl.GPUBufferUsageFlags{.GRAPHICS_STORAGE_READ},
 	)
-	if !pb_ok do return pipeline, false
+	if !prim_buf_ok do return pipeline, false
 
 	// Create static 6-vertex unit quad buffer (two triangles, TRIANGLELIST)
 	pipeline.unit_quad_buffer = sdl.CreateGPUBuffer(
@@ -296,73 +301,73 @@ create_pipeline_2d_base :: proc(
 
 	// Upload white pixel and unit quad data in a single command buffer
 	white_pixel := [4]u8{255, 255, 255, 255}
-	white_transfer := sdl.CreateGPUTransferBuffer(
+	white_transfer_buf := sdl.CreateGPUTransferBuffer(
 		device,
 		sdl.GPUTransferBufferCreateInfo{usage = .UPLOAD, size = size_of(white_pixel)},
 	)
-	if white_transfer == nil {
+	if white_transfer_buf == nil {
 		log.errorf("Failed to create white pixel transfer buffer: %s", sdl.GetError())
 		return pipeline, false
 	}
-	defer sdl.ReleaseGPUTransferBuffer(device, white_transfer)
+	defer sdl.ReleaseGPUTransferBuffer(device, white_transfer_buf)
 
-	white_ptr := sdl.MapGPUTransferBuffer(device, white_transfer, false)
+	white_ptr := sdl.MapGPUTransferBuffer(device, white_transfer_buf, false)
 	if white_ptr == nil {
 		log.errorf("Failed to map white pixel transfer buffer: %s", sdl.GetError())
 		return pipeline, false
 	}
 	mem.copy(white_ptr, &white_pixel, size_of(white_pixel))
-	sdl.UnmapGPUTransferBuffer(device, white_transfer)
+	sdl.UnmapGPUTransferBuffer(device, white_transfer_buf)
 
-	quad_verts := [6]Vertex{
+	quad_verts := [6]Vertex {
-		{position = {0, 0}}, {position = {1, 0}}, {position = {0, 1}},
+		{position = {0, 0}},
-		{position = {0, 1}}, {position = {1, 0}}, {position = {1, 1}},
+		{position = {1, 0}},
+		{position = {0, 1}},
+		{position = {0, 1}},
+		{position = {1, 0}},
+		{position = {1, 1}},
 	}
-	quad_transfer := sdl.CreateGPUTransferBuffer(
+	quad_transfer_buf := sdl.CreateGPUTransferBuffer(
 		device,
 		sdl.GPUTransferBufferCreateInfo{usage = .UPLOAD, size = size_of(quad_verts)},
 	)
-	if quad_transfer == nil {
+	if quad_transfer_buf == nil {
 		log.errorf("Failed to create unit quad transfer buffer: %s", sdl.GetError())
 		return pipeline, false
 	}
-	defer sdl.ReleaseGPUTransferBuffer(device, quad_transfer)
+	defer sdl.ReleaseGPUTransferBuffer(device, quad_transfer_buf)
 
-	quad_ptr := sdl.MapGPUTransferBuffer(device, quad_transfer, false)
+	quad_ptr := sdl.MapGPUTransferBuffer(device, quad_transfer_buf, false)
 	if quad_ptr == nil {
 		log.errorf("Failed to map unit quad transfer buffer: %s", sdl.GetError())
 		return pipeline, false
 	}
 	mem.copy(quad_ptr, &quad_verts, size_of(quad_verts))
-	sdl.UnmapGPUTransferBuffer(device, quad_transfer)
+	sdl.UnmapGPUTransferBuffer(device, quad_transfer_buf)
 
-	upload_cmd := sdl.AcquireGPUCommandBuffer(device)
+	upload_cmd_buffer := sdl.AcquireGPUCommandBuffer(device)
-	if upload_cmd == nil {
+	if upload_cmd_buffer == nil {
 		log.errorf("Failed to acquire command buffer for init upload: %s", sdl.GetError())
 		return pipeline, false
 	}
-	upload_pass := sdl.BeginGPUCopyPass(upload_cmd)
+	upload_pass := sdl.BeginGPUCopyPass(upload_cmd_buffer)
 
 	sdl.UploadToGPUTexture(
 		upload_pass,
-		sdl.GPUTextureTransferInfo{transfer_buffer = white_transfer},
+		sdl.GPUTextureTransferInfo{transfer_buffer = white_transfer_buf},
 		sdl.GPUTextureRegion{texture = pipeline.white_texture, w = 1, h = 1, d = 1},
 		false,
 	)
 
 	sdl.UploadToGPUBuffer(
 		upload_pass,
-		sdl.GPUTransferBufferLocation{transfer_buffer = quad_transfer},
+		sdl.GPUTransferBufferLocation{transfer_buffer = quad_transfer_buf},
-		sdl.GPUBufferRegion{
+		sdl.GPUBufferRegion{buffer = pipeline.unit_quad_buffer, offset = 0, size = size_of(quad_verts)},
-			buffer = pipeline.unit_quad_buffer,
-			offset = 0,
-			size   = size_of(quad_verts),
-		},
 		false,
 	)
 
 	sdl.EndGPUCopyPass(upload_pass)
-	if !sdl.SubmitGPUCommandBuffer(upload_cmd) {
+	if !sdl.SubmitGPUCommandBuffer(upload_cmd_buffer) {
 		log.errorf("Failed to submit init upload command buffer: %s", sdl.GetError())
 		return pipeline, false
 	}
@@ -409,16 +414,16 @@ upload :: proc(device: ^sdl.GPUDevice, pass: ^sdl.GPUCopyPass) {
 			sdl.GPUBufferUsageFlags{.VERTEX},
 		)
 
-		v_array := sdl.MapGPUTransferBuffer(device, GLOB.pipeline_2d_base.vertex_buffer.transfer, false)
+		vert_array := sdl.MapGPUTransferBuffer(device, GLOB.pipeline_2d_base.vertex_buffer.transfer, false)
-		if v_array == nil {
+		if vert_array == nil {
 			log.panicf("Failed to map vertex transfer buffer: %s", sdl.GetError())
 		}
 		if shape_vert_size > 0 {
-			mem.copy(v_array, raw_data(GLOB.tmp_shape_verts), int(shape_vert_size))
+			mem.copy(vert_array, raw_data(GLOB.tmp_shape_verts), int(shape_vert_size))
 		}
 		if text_vert_size > 0 {
 			mem.copy(
-				rawptr(uintptr(v_array) + uintptr(shape_vert_size)),
+				rawptr(uintptr(vert_array) + uintptr(shape_vert_size)),
 				raw_data(GLOB.tmp_text_verts),
 				int(text_vert_size),
 			)
@@ -428,11 +433,7 @@ upload :: proc(device: ^sdl.GPUDevice, pass: ^sdl.GPUCopyPass) {
 		sdl.UploadToGPUBuffer(
 			pass,
 			sdl.GPUTransferBufferLocation{transfer_buffer = GLOB.pipeline_2d_base.vertex_buffer.transfer},
-			sdl.GPUBufferRegion{
+			sdl.GPUBufferRegion{buffer = GLOB.pipeline_2d_base.vertex_buffer.gpu, offset = 0, size = total_vert_size},
-				buffer = GLOB.pipeline_2d_base.vertex_buffer.gpu,
-				offset = 0,
-				size   = total_vert_size,
-			},
 			false,
 		)
 	}
@@ -449,21 +450,17 @@ upload :: proc(device: ^sdl.GPUDevice, pass: ^sdl.GPUCopyPass) {
 			sdl.GPUBufferUsageFlags{.INDEX},
 		)
 
-		i_array := sdl.MapGPUTransferBuffer(device, GLOB.pipeline_2d_base.index_buffer.transfer, false)
+		idx_array := sdl.MapGPUTransferBuffer(device, GLOB.pipeline_2d_base.index_buffer.transfer, false)
-		if i_array == nil {
+		if idx_array == nil {
 			log.panicf("Failed to map index transfer buffer: %s", sdl.GetError())
 		}
-		mem.copy(i_array, raw_data(GLOB.tmp_text_indices), int(index_size))
+		mem.copy(idx_array, raw_data(GLOB.tmp_text_indices), int(index_size))
 		sdl.UnmapGPUTransferBuffer(device, GLOB.pipeline_2d_base.index_buffer.transfer)
 
 		sdl.UploadToGPUBuffer(
 			pass,
 			sdl.GPUTransferBufferLocation{transfer_buffer = GLOB.pipeline_2d_base.index_buffer.transfer},
-			sdl.GPUBufferRegion{
+			sdl.GPUBufferRegion{buffer = GLOB.pipeline_2d_base.index_buffer.gpu, offset = 0, size = index_size},
-				buffer = GLOB.pipeline_2d_base.index_buffer.gpu,
-				offset = 0,
-				size   = index_size,
-			},
 			false,
 		)
 	}
@@ -480,25 +477,17 @@ upload :: proc(device: ^sdl.GPUDevice, pass: ^sdl.GPUCopyPass) {
 			sdl.GPUBufferUsageFlags{.GRAPHICS_STORAGE_READ},
 		)
 
-		p_array := sdl.MapGPUTransferBuffer(
+		prim_array := sdl.MapGPUTransferBuffer(device, GLOB.pipeline_2d_base.primitive_buffer.transfer, false)
-			device, GLOB.pipeline_2d_base.primitive_buffer.transfer, false,
+		if prim_array == nil {
-		)
-		if p_array == nil {
 			log.panicf("Failed to map primitive transfer buffer: %s", sdl.GetError())
 		}
-		mem.copy(p_array, raw_data(GLOB.tmp_primitives), int(prim_size))
+		mem.copy(prim_array, raw_data(GLOB.tmp_primitives), int(prim_size))
 		sdl.UnmapGPUTransferBuffer(device, GLOB.pipeline_2d_base.primitive_buffer.transfer)
 
 		sdl.UploadToGPUBuffer(
 			pass,
-			sdl.GPUTransferBufferLocation{
+			sdl.GPUTransferBufferLocation{transfer_buffer = GLOB.pipeline_2d_base.primitive_buffer.transfer},
-				transfer_buffer = GLOB.pipeline_2d_base.primitive_buffer.transfer,
+			sdl.GPUBufferRegion{buffer = GLOB.pipeline_2d_base.primitive_buffer.gpu, offset = 0, size = prim_size},
-			},
-			sdl.GPUBufferRegion{
-				buffer = GLOB.pipeline_2d_base.primitive_buffer.gpu,
-				offset = 0,
-				size   = prim_size,
-			},
 			false,
 		)
 	}
@@ -510,8 +499,8 @@ draw_layer :: proc(
 	window: ^sdl.Window,
 	cmd_buffer: ^sdl.GPUCommandBuffer,
 	render_texture: ^sdl.GPUTexture,
-	swapchain_w: u32,
+	swapchain_width: u32,
-	swapchain_h: u32,
+	swapchain_height: u32,
 	clear_color: [4]f32,
 	layer: ^Layer,
 ) {
@@ -521,9 +510,7 @@ draw_layer :: proc(
 				cmd_buffer,
 				&sdl.GPUColorTargetInfo {
 					texture = render_texture,
-					clear_color = sdl.FColor {
+					clear_color = sdl.FColor{clear_color[0], clear_color[1], clear_color[2], clear_color[3]},
-						clear_color[0], clear_color[1], clear_color[2], clear_color[3],
-					},
 					load_op = .CLEAR,
 					store_op = .STORE,
 				},
@@ -540,9 +527,7 @@ draw_layer :: proc(
 		cmd_buffer,
 		&sdl.GPUColorTargetInfo {
 			texture = render_texture,
-			clear_color = sdl.FColor {
+			clear_color = sdl.FColor{clear_color[0], clear_color[1], clear_color[2], clear_color[3]},
-				clear_color[0], clear_color[1], clear_color[2], clear_color[3],
-			},
 			load_op = GLOB.cleared ? .LOAD : .CLEAR,
 			store_op = .STORE,
 		},
@@ -569,22 +554,21 @@ draw_layer :: proc(
 	)
 
 	// Shorthand aliases for frequently-used pipeline resources
-	main_vbuf := GLOB.pipeline_2d_base.vertex_buffer.gpu
+	main_vert_buf := GLOB.pipeline_2d_base.vertex_buffer.gpu
 	unit_quad := GLOB.pipeline_2d_base.unit_quad_buffer
-	white     := GLOB.pipeline_2d_base.white_texture
+	white_texture := GLOB.pipeline_2d_base.white_texture
 	sampler := GLOB.pipeline_2d_base.sampler
-	w         := f32(swapchain_w)
+	width := f32(swapchain_width)
-	h         := f32(swapchain_h)
+	height := f32(swapchain_height)
 
 	// Initial GPU state: tessellated mode, main vertex buffer, no atlas bound yet
-	push_globals(cmd_buffer, w, h, .Tessellated)
+	push_globals(cmd_buffer, width, height, .Tessellated)
-	sdl.BindGPUVertexBuffers(
+	sdl.BindGPUVertexBuffers(render_pass, 0, &sdl.GPUBufferBinding{buffer = main_vert_buf, offset = 0}, 1)
-		render_pass, 0, &sdl.GPUBufferBinding{buffer = main_vbuf, offset = 0}, 1,
-	)
 
 	current_mode: Draw_Mode = .Tessellated
-	current_vbuf := main_vbuf
+	current_vert_buf := main_vert_buf
 	current_atlas: ^sdl.GPUTexture
+	current_sampler := sampler
 
 	// Text vertices live after shape vertices in the GPU vertex buffer
 	text_vertex_gpu_base := u32(len(GLOB.tmp_shape_verts))
@@ -596,76 +580,89 @@ draw_layer :: proc(
 			switch batch.kind {
 			case .Shapes:
 				if current_mode != .Tessellated {
-					push_globals(cmd_buffer, w, h, .Tessellated)
+					push_globals(cmd_buffer, width, height, .Tessellated)
 					current_mode = .Tessellated
 				}
-				if current_vbuf != main_vbuf {
+				if current_vert_buf != main_vert_buf {
-					sdl.BindGPUVertexBuffers(
+					sdl.BindGPUVertexBuffers(render_pass, 0, &sdl.GPUBufferBinding{buffer = main_vert_buf, offset = 0}, 1)
-						render_pass, 0,
+					current_vert_buf = main_vert_buf
-						&sdl.GPUBufferBinding{buffer = main_vbuf, offset = 0}, 1,
-					)
-					current_vbuf = main_vbuf
 				}
-				if current_atlas != white {
+				// Determine texture and sampler for this batch
+				batch_texture: ^sdl.GPUTexture = white_texture
+				batch_sampler: ^sdl.GPUSampler = sampler
+				if batch.texture_id != INVALID_TEXTURE {
+					if bound_texture := texture_gpu_handle(batch.texture_id); bound_texture != nil {
+						batch_texture = bound_texture
+					}
+					batch_sampler = get_sampler(batch.sampler)
+				}
+				if current_atlas != batch_texture || current_sampler != batch_sampler {
 					sdl.BindGPUFragmentSamplers(
-						render_pass, 0,
+						render_pass,
-						&sdl.GPUTextureSamplerBinding{texture = white, sampler = sampler}, 1,
+						0,
+						&sdl.GPUTextureSamplerBinding{texture = batch_texture, sampler = batch_sampler},
+						1,
 					)
-					current_atlas = white
+					current_atlas = batch_texture
+					current_sampler = batch_sampler
 				}
 				sdl.DrawGPUPrimitives(render_pass, batch.count, 1, batch.offset, 0)
 
 			case .Text:
 				if current_mode != .Tessellated {
-					push_globals(cmd_buffer, w, h, .Tessellated)
+					push_globals(cmd_buffer, width, height, .Tessellated)
 					current_mode = .Tessellated
 				}
-				if current_vbuf != main_vbuf {
+				if current_vert_buf != main_vert_buf {
-					sdl.BindGPUVertexBuffers(
+					sdl.BindGPUVertexBuffers(render_pass, 0, &sdl.GPUBufferBinding{buffer = main_vert_buf, offset = 0}, 1)
-						render_pass, 0,
+					current_vert_buf = main_vert_buf
-						&sdl.GPUBufferBinding{buffer = main_vbuf, offset = 0}, 1,
-					)
-					current_vbuf = main_vbuf
 				}
-				chunk := &GLOB.tmp_text_batches[batch.offset]
+				text_batch := &GLOB.tmp_text_batches[batch.offset]
-				if current_atlas != chunk.atlas_texture {
+				if current_atlas != text_batch.atlas_texture {
 					sdl.BindGPUFragmentSamplers(
-						render_pass, 0,
+						render_pass,
-						&sdl.GPUTextureSamplerBinding {
+						0,
-							texture = chunk.atlas_texture,
+						&sdl.GPUTextureSamplerBinding{texture = text_batch.atlas_texture, sampler = sampler},
-							sampler = sampler,
-						},
 						1,
 					)
-					current_atlas = chunk.atlas_texture
+					current_atlas = text_batch.atlas_texture
 				}
 				sdl.DrawGPUIndexedPrimitives(
 					render_pass,
-					chunk.index_count,
+					text_batch.index_count,
 					1,
-					chunk.index_start,
+					text_batch.index_start,
-					i32(text_vertex_gpu_base + chunk.vertex_start),
+					i32(text_vertex_gpu_base + text_batch.vertex_start),
 					0,
 				)
 
 			case .SDF:
 				if current_mode != .SDF {
-					push_globals(cmd_buffer, w, h, .SDF)
+					push_globals(cmd_buffer, width, height, .SDF)
 					current_mode = .SDF
 				}
-				if current_vbuf != unit_quad {
+				if current_vert_buf != unit_quad {
-					sdl.BindGPUVertexBuffers(
+					sdl.BindGPUVertexBuffers(render_pass, 0, &sdl.GPUBufferBinding{buffer = unit_quad, offset = 0}, 1)
-						render_pass, 0,
+					current_vert_buf = unit_quad
-						&sdl.GPUBufferBinding{buffer = unit_quad, offset = 0}, 1,
-					)
-					current_vbuf = unit_quad
 				}
-				if current_atlas != white {
+				// Determine texture and sampler for this batch
+				batch_texture: ^sdl.GPUTexture = white_texture
+				batch_sampler: ^sdl.GPUSampler = sampler
+				if batch.texture_id != INVALID_TEXTURE {
+					if bound_texture := texture_gpu_handle(batch.texture_id); bound_texture != nil {
+						batch_texture = bound_texture
+					}
+					batch_sampler = get_sampler(batch.sampler)
+				}
+				if current_atlas != batch_texture || current_sampler != batch_sampler {
 					sdl.BindGPUFragmentSamplers(
-						render_pass, 0,
+						render_pass,
-						&sdl.GPUTextureSamplerBinding{texture = white, sampler = sampler}, 1,
+						0,
+						&sdl.GPUTextureSamplerBinding{texture = batch_texture, sampler = batch_sampler},
+						1,
 					)
-					current_atlas = white
+					current_atlas = batch_texture
+					current_sampler = batch_sampler
 				}
 				sdl.DrawGPUPrimitives(render_pass, 6, batch.count, 0, batch.offset)
 			}

draw/shaders/generated/base_2d.frag.metal

@@ -24,32 +24,42 @@ struct main0_in
     float4 f_params [[user(locn2)]];
     float4 f_params2 [[user(locn3)]];
     uint f_kind_flags [[user(locn4)]];
+    float f_rotation [[user(locn5), flat]];
+    float4 f_uv_rect [[user(locn6), flat]];
 };
 
+static inline __attribute__((always_inline))
+float2 apply_rotation(thread const float2& p, thread const float& angle)
+{
+    float cr = cos(-angle);
+    float sr = sin(-angle);
+    return float2x2(float2(cr, sr), float2(-sr, cr)) * p;
+}
+
 static inline __attribute__((always_inline))
 float sdRoundedBox(thread const float2& p, thread const float2& b, thread float4& r)
 {
-    float2 _56;
+    float2 _61;
     if (p.x > 0.0)
     {
-        _56 = r.xy;
+        _61 = r.xy;
     }
     else
     {
-        _56 = r.zw;
+        _61 = r.zw;
     }
-    r.x = _56.x;
+    r.x = _61.x;
-    r.y = _56.y;
+    r.y = _61.y;
-    float _73;
+    float _78;
     if (p.y > 0.0)
     {
-        _73 = r.x;
+        _78 = r.x;
     }
     else
     {
-        _73 = r.y;
+        _78 = r.y;
     }
-    r.x = _73;
+    r.x = _78;
     float2 q = (abs(p) - b) + float2(r.x);
     return (fast::min(fast::max(q.x, q.y), 0.0) + length(fast::max(q, float2(0.0)))) - r.x;
 }
@@ -60,6 +70,12 @@ float sdf_stroke(thread const float& d, thread const float& stroke_width)
     return abs(d) - (stroke_width * 0.5);
 }
 
+static inline __attribute__((always_inline))
+float sdf_alpha(thread const float& d, thread const float& soft)
+{
+    return 1.0 - smoothstep(-soft, soft, d);
+}
+
 static inline __attribute__((always_inline))
 float sdCircle(thread const float2& p, thread const float& r)
 {
@@ -118,12 +134,6 @@ float sdSegment(thread const float2& p, thread const float2& a, thread const flo
     return length(pa - (ba * h));
 }
 
-static inline __attribute__((always_inline))
-float sdf_alpha(thread const float& d, thread const float& soft)
-{
-    return 1.0 - smoothstep(-soft, soft, d);
-}
-
 fragment main0_out main0(main0_in in [[stage_in]], texture2d<float> tex [[texture(0)]], sampler texSmplr [[sampler(0)]])
 {
     main0_out out = {};
@@ -142,17 +152,43 @@ fragment main0_out main0(main0_in in [[stage_in]], texture2d<float> tex [[textur
         float4 r = float4(in.f_params.zw, in.f_params2.xy);
         soft = fast::max(in.f_params2.z, 1.0);
         float stroke_px = in.f_params2.w;
-        float2 param = in.f_local_or_uv;
+        float2 p_local = in.f_local_or_uv;
-        float2 param_1 = b;
+        if (in.f_rotation != 0.0)
-        float4 param_2 = r;
+        {
-        float _453 = sdRoundedBox(param, param_1, param_2);
+            float2 param = p_local;
-        d = _453;
+            float param_1 = in.f_rotation;
+            p_local = apply_rotation(param, param_1);
+        }
+        float2 param_2 = p_local;
+        float2 param_3 = b;
+        float4 param_4 = r;
+        float _491 = sdRoundedBox(param_2, param_3, param_4);
+        d = _491;
         if ((flags & 1u) != 0u)
         {
-            float param_3 = d;
+            float param_5 = d;
-            float param_4 = stroke_px;
+            float param_6 = stroke_px;
-            d = sdf_stroke(param_3, param_4);
+            d = sdf_stroke(param_5, param_6);
         }
+        float4 shape_color = in.f_color;
+        if ((flags & 2u) != 0u)
+        {
+            float2 p_for_uv = in.f_local_or_uv;
+            if (in.f_rotation != 0.0)
+            {
+                float2 param_7 = p_for_uv;
+                float param_8 = in.f_rotation;
+                p_for_uv = apply_rotation(param_7, param_8);
+            }
+            float2 local_uv = ((p_for_uv / b) * 0.5) + float2(0.5);
+            float2 uv = mix(in.f_uv_rect.xy, in.f_uv_rect.zw, local_uv);
+            shape_color *= tex.sample(texSmplr, uv);
+        }
+        float param_9 = d;
+        float param_10 = soft;
+        float alpha = sdf_alpha(param_9, param_10);
+        out.out_color = float4(shape_color.xyz, shape_color.w * alpha);
+        return out;
     }
     else
     {
@@ -161,14 +197,14 @@ fragment main0_out main0(main0_in in [[stage_in]], texture2d<float> tex [[textur
             float radius = in.f_params.x;
             soft = fast::max(in.f_params.y, 1.0);
             float stroke_px_1 = in.f_params.z;
-            float2 param_5 = in.f_local_or_uv;
+            float2 param_11 = in.f_local_or_uv;
-            float param_6 = radius;
+            float param_12 = radius;
-            d = sdCircle(param_5, param_6);
+            d = sdCircle(param_11, param_12);
             if ((flags & 1u) != 0u)
             {
-                float param_7 = d;
+                float param_13 = d;
-                float param_8 = stroke_px_1;
+                float param_14 = stroke_px_1;
-                d = sdf_stroke(param_7, param_8);
+                d = sdf_stroke(param_13, param_14);
             }
         }
         else
@@ -178,15 +214,22 @@ fragment main0_out main0(main0_in in [[stage_in]], texture2d<float> tex [[textur
                 float2 ab = in.f_params.xy;
                 soft = fast::max(in.f_params.z, 1.0);
                 float stroke_px_2 = in.f_params.w;
-                float2 param_9 = in.f_local_or_uv;
+                float2 p_local_1 = in.f_local_or_uv;
-                float2 param_10 = ab;
+                if (in.f_rotation != 0.0)
-                float _511 = sdEllipse(param_9, param_10);
+                {
-                d = _511;
+                    float2 param_15 = p_local_1;
+                    float param_16 = in.f_rotation;
+                    p_local_1 = apply_rotation(param_15, param_16);
+                }
+                float2 param_17 = p_local_1;
+                float2 param_18 = ab;
+                float _616 = sdEllipse(param_17, param_18);
+                d = _616;
                 if ((flags & 1u) != 0u)
                 {
-                    float param_11 = d;
+                    float param_19 = d;
-                    float param_12 = stroke_px_2;
+                    float param_20 = stroke_px_2;
-                    d = sdf_stroke(param_11, param_12);
+                    d = sdf_stroke(param_19, param_20);
                 }
             }
             else
@@ -197,10 +240,10 @@ fragment main0_out main0(main0_in in [[stage_in]], texture2d<float> tex [[textur
                     float2 b_1 = in.f_params.zw;
                     float width = in.f_params2.x;
                     soft = fast::max(in.f_params2.y, 1.0);
-                    float2 param_13 = in.f_local_or_uv;
+                    float2 param_21 = in.f_local_or_uv;
-                    float2 param_14 = a;
+                    float2 param_22 = a;
-                    float2 param_15 = b_1;
+                    float2 param_23 = b_1;
-                    d = sdSegment(param_13, param_14, param_15) - (width * 0.5);
+                    d = sdSegment(param_21, param_22, param_23) - (width * 0.5);
                 }
                 else
                 {
@@ -218,26 +261,18 @@ fragment main0_out main0(main0_in in [[stage_in]], texture2d<float> tex [[textur
                         {
                             angle += 6.283185482025146484375;
                         }
-                        float ang_start = start_rad;
+                        float ang_start = mod(start_rad, 6.283185482025146484375);
-                        float ang_end = end_rad;
+                        float ang_end = mod(end_rad, 6.283185482025146484375);
-                        if (ang_start < 0.0)
+                        float _710;
-                        {
-                            ang_start += 6.283185482025146484375;
-                        }
-                        if (ang_end < 0.0)
-                        {
-                            ang_end += 6.283185482025146484375;
-                        }
-                        float _615;
                         if (ang_end > ang_start)
                         {
-                            _615 = float((angle >= ang_start) && (angle <= ang_end));
+                            _710 = float((angle >= ang_start) && (angle <= ang_end));
                         }
                         else
                         {
-                            _615 = float((angle >= ang_start) || (angle <= ang_end));
+                            _710 = float((angle >= ang_start) || (angle <= ang_end));
                         }
-                        float in_arc = _615;
+                        float in_arc = _710;
                         if (abs(ang_end - ang_start) >= 6.282185077667236328125)
                         {
                             in_arc = 1.0;
@@ -262,9 +297,9 @@ fragment main0_out main0(main0_in in [[stage_in]], texture2d<float> tex [[textur
                             d = (length(p) * cos(bn)) - radius_1;
                             if ((flags & 1u) != 0u)
                             {
-                                float param_16 = d;
+                                float param_24 = d;
-                                float param_17 = stroke_px_3;
+                                float param_25 = stroke_px_3;
-                                d = sdf_stroke(param_16, param_17);
+                                d = sdf_stroke(param_24, param_25);
                             }
                         }
                     }
@@ -272,10 +307,9 @@ fragment main0_out main0(main0_in in [[stage_in]], texture2d<float> tex [[textur
             }
         }
     }
-    float param_18 = d;
+    float param_26 = d;
-    float param_19 = soft;
+    float param_27 = soft;
-    float alpha = sdf_alpha(param_18, param_19);
+    float alpha_1 = sdf_alpha(param_26, param_27);
-    out.out_color = float4(in.f_color.xyz, in.f_color.w * alpha);
+    out.out_color = float4(in.f_color.xyz, in.f_color.w * alpha_1);
     return out;
 }
-

draw/shaders/generated/base_2d.vert.metal

@@ -15,9 +15,11 @@ struct Primitive
     float4 bounds;
     uint color;
     uint kind_flags;
-    float2 _pad;
+    float rotation;
+    float _pad;
     float4 params;
     float4 params2;
+    float4 uv_rect;
 };
 
 struct Primitive_1
@@ -25,9 +27,11 @@ struct Primitive_1
     float4 bounds;
     uint color;
     uint kind_flags;
-    float2 _pad;
+    float rotation;
+    float _pad;
     float4 params;
     float4 params2;
+    float4 uv_rect;
 };
 
 struct Primitives
@@ -42,6 +46,8 @@ struct main0_out
     float4 f_params [[user(locn2)]];
     float4 f_params2 [[user(locn3)]];
     uint f_kind_flags [[user(locn4)]];
+    float f_rotation [[user(locn5)]];
+    float4 f_uv_rect [[user(locn6)]];
     float4 gl_Position [[position]];
 };
 
@@ -52,7 +58,7 @@ struct main0_in
     float4 v_color [[attribute(2)]];
 };
 
-vertex main0_out main0(main0_in in [[stage_in]], constant Uniforms& _12 [[buffer(0)]], const device Primitives& _70 [[buffer(1)]], uint gl_InstanceIndex [[instance_id]])
+vertex main0_out main0(main0_in in [[stage_in]], constant Uniforms& _12 [[buffer(0)]], const device Primitives& _74 [[buffer(1)]], uint gl_InstanceIndex [[instance_id]])
 {
     main0_out out = {};
     if (_12.mode == 0u)
@@ -62,17 +68,21 @@ vertex main0_out main0(main0_in in [[stage_in]], constant Uniforms& _12 [[buffer
         out.f_params = float4(0.0);
         out.f_params2 = float4(0.0);
         out.f_kind_flags = 0u;
+        out.f_rotation = 0.0;
+        out.f_uv_rect = float4(0.0, 0.0, 1.0, 1.0);
         out.gl_Position = _12.projection * float4(in.v_position * _12.dpi_scale, 0.0, 1.0);
     }
     else
     {
         Primitive p;
-        p.bounds = _70.primitives[int(gl_InstanceIndex)].bounds;
+        p.bounds = _74.primitives[int(gl_InstanceIndex)].bounds;
-        p.color = _70.primitives[int(gl_InstanceIndex)].color;
+        p.color = _74.primitives[int(gl_InstanceIndex)].color;
-        p.kind_flags = _70.primitives[int(gl_InstanceIndex)].kind_flags;
+        p.kind_flags = _74.primitives[int(gl_InstanceIndex)].kind_flags;
-        p._pad = _70.primitives[int(gl_InstanceIndex)]._pad;
+        p.rotation = _74.primitives[int(gl_InstanceIndex)].rotation;
-        p.params = _70.primitives[int(gl_InstanceIndex)].params;
+        p._pad = _74.primitives[int(gl_InstanceIndex)]._pad;
-        p.params2 = _70.primitives[int(gl_InstanceIndex)].params2;
+        p.params = _74.primitives[int(gl_InstanceIndex)].params;
+        p.params2 = _74.primitives[int(gl_InstanceIndex)].params2;
+        p.uv_rect = _74.primitives[int(gl_InstanceIndex)].uv_rect;
         float2 corner = in.v_position;
         float2 world_pos = mix(p.bounds.xy, p.bounds.zw, corner);
         float2 center = (p.bounds.xy + p.bounds.zw) * 0.5;
@@ -81,8 +91,9 @@ vertex main0_out main0(main0_in in [[stage_in]], constant Uniforms& _12 [[buffer
         out.f_params = p.params;
         out.f_params2 = p.params2;
         out.f_kind_flags = p.kind_flags;
+        out.f_rotation = p.rotation;
+        out.f_uv_rect = p.uv_rect;
         out.gl_Position = _12.projection * float4(world_pos * _12.dpi_scale, 0.0, 1.0);
     }
     return out;
 }
-

draw/shaders/source/base_2d.frag

@@ -6,6 +6,8 @@ layout(location = 1) in vec2 f_local_or_uv;
 layout(location = 2) in vec4 f_params;
 layout(location = 3) in vec4 f_params2;
 layout(location = 4) flat in uint f_kind_flags;
+layout(location = 5) flat in float f_rotation;
+layout(location = 6) flat in vec4 f_uv_rect;
 
 // --- Output ---
 layout(location = 0) out vec4 out_color;
@@ -82,6 +84,15 @@ float sdf_stroke(float d, float stroke_width) {
     return abs(d) - stroke_width * 0.5;
 }
 
+// Rotate a 2D point by the negative of the given angle (inverse rotation).
+// Used to rotate the sampling frame opposite to the shape's rotation so that
+// the SDF evaluates correctly for the rotated shape.
+vec2 apply_rotation(vec2 p, float angle) {
+    float cr = cos(-angle);
+    float sr = sin(-angle);
+    return mat2(cr, sr, -sr, cr) * p;
+}
+
 // ---------------------------------------------------------------------------
 // main
 // ---------------------------------------------------------------------------
@@ -113,11 +124,33 @@ void main() {
         soft = max(f_params2.z, 1.0);
         float stroke_px = f_params2.w;
 
-        d = sdRoundedBox(f_local_or_uv, b, r);
+        vec2 p_local = f_local_or_uv;
+        if (f_rotation != 0.0) {
+            p_local = apply_rotation(p_local, f_rotation);
+        }
+
+        d = sdRoundedBox(p_local, b, r);
         if ((flags & 1u) != 0u) d = sdf_stroke(d, stroke_px);
+
+        // Texture sampling for textured SDF primitives
+        vec4 shape_color = f_color;
+        if ((flags & 2u) != 0u) {
+            // Compute UV from local position and half_size
+            vec2 p_for_uv = f_local_or_uv;
+            if (f_rotation != 0.0) {
+                p_for_uv = apply_rotation(p_for_uv, f_rotation);
+            }
+            vec2 local_uv = p_for_uv / b * 0.5 + 0.5;
+            vec2 uv = mix(f_uv_rect.xy, f_uv_rect.zw, local_uv);
+            shape_color *= texture(tex, uv);
+        }
+
+        float alpha = sdf_alpha(d, soft);
+        out_color = vec4(shape_color.rgb, shape_color.a * alpha);
+        return;
     }
     else if (kind == 2u) {
-        // Circle
+        // Circle — rotationally symmetric, no rotation needed
         float radius = f_params.x;
         soft = max(f_params.y, 1.0);
         float stroke_px = f_params.z;
@@ -131,11 +164,16 @@ void main() {
         soft = max(f_params.z, 1.0);
         float stroke_px = f_params.w;
 
-        d = sdEllipse(f_local_or_uv, ab);
+        vec2 p_local = f_local_or_uv;
+        if (f_rotation != 0.0) {
+            p_local = apply_rotation(p_local, f_rotation);
+        }
+
+        d = sdEllipse(p_local, ab);
         if ((flags & 1u) != 0u) d = sdf_stroke(d, stroke_px);
     }
     else if (kind == 4u) {
-        // Segment (capsule line)
+        // Segment (capsule line) — no rotation (excluded)
         vec2 a = f_params.xy; // already in local physical pixels
         vec2 b = f_params.zw;
         float width = f_params2.x;
@@ -144,7 +182,7 @@ void main() {
         d = sdSegment(f_local_or_uv, a, b) - width * 0.5;
     }
     else if (kind == 5u) {
-        // Ring / Arc
+        // Ring / Arc — rotation handled by CPU angle offset, no shader rotation
         float inner = f_params.x;
         float outer = f_params.y;
         float start_rad = f_params.z;
@@ -157,10 +195,8 @@ void main() {
         // Angular clip
         float angle = atan(f_local_or_uv.y, f_local_or_uv.x);
         if (angle < 0.0) angle += 2.0 * PI;
-        float ang_start = start_rad;
+        float ang_start = mod(start_rad, 2.0 * PI);
-        float ang_end = end_rad;
+        float ang_end = mod(end_rad, 2.0 * PI);
-        if (ang_start < 0.0) ang_start += 2.0 * PI;
-        if (ang_end < 0.0) ang_end += 2.0 * PI;
 
         float in_arc = (ang_end > ang_start)
             ? ((angle >= ang_start && angle <= ang_end) ? 1.0 : 0.0) : ((angle >= ang_start || angle <= ang_end) ? 1.0 : 0.0);
@@ -169,7 +205,7 @@ void main() {
         d = in_arc > 0.5 ? d_ring : 1e30;
     }
     else if (kind == 6u) {
-        // Regular N-gon
+        // Regular N-gon — has its own rotation in params, no Primitive.rotation used
         float radius = f_params.x;
         float rotation = f_params.y;
         float sides = f_params.z;

draw/shaders/source/base_2d.vert

@@ -11,6 +11,8 @@ layout(location = 1) out vec2 f_local_or_uv;
 layout(location = 2) out vec4 f_params;
 layout(location = 3) out vec4 f_params2;
 layout(location = 4) flat out uint f_kind_flags;
+layout(location = 5) flat out float f_rotation;
+layout(location = 6) flat out vec4 f_uv_rect;
 
 // ---------- Uniforms (single block — avoids spirv-cross reordering on Metal) ----------
 layout(set = 1, binding = 0) uniform Uniforms {
@@ -24,9 +26,11 @@ struct Primitive {
     vec4 bounds; // 0-15:  min_x, min_y, max_x, max_y
     uint color; // 16-19: packed u8x4 (unpack with unpackUnorm4x8)
     uint kind_flags; // 20-23: kind | (flags << 8)
-    vec2 _pad; // 24-31: padding
+    float rotation; // 24-27: shader self-rotation in radians
+    float _pad; // 28-31: alignment padding
     vec4 params; // 32-47: shape params part 1
     vec4 params2; // 48-63: shape params part 2
+    vec4 uv_rect; // 64-79: u_min, v_min, u_max, v_max
 };
 
 layout(std430, set = 0, binding = 0) readonly buffer Primitives {
@@ -42,6 +46,8 @@ void main() {
         f_params = vec4(0.0);
         f_params2 = vec4(0.0);
         f_kind_flags = 0u;
+        f_rotation = 0.0;
+        f_uv_rect = vec4(0.0, 0.0, 1.0, 1.0);
 
         gl_Position = projection * vec4(v_position * dpi_scale, 0.0, 1.0);
     } else {
@@ -57,6 +63,8 @@ void main() {
         f_params = p.params;
         f_params2 = p.params2;
         f_kind_flags = p.kind_flags;
+        f_rotation = p.rotation;
+        f_uv_rect = p.uv_rect;
 
         gl_Position = projection * vec4(world_pos * dpi_scale, 0.0, 1.0);
     }

draw/text.odin

@@ -1,6 +1,8 @@
 package draw
 
+import "core:c"
 import "core:log"
+import "core:strings"
 import sdl "vendor:sdl3"
 import sdl_ttf "vendor:sdl3/ttf"
 
@@ -11,11 +13,21 @@ Font_Key :: struct {
 	size: u16,
 }
 
+Cache_Source :: enum u8 {
+	Custom,
+	Clay,
+}
+
+Cache_Key :: struct {
+	id:     u32,
+	source: Cache_Source,
+}
+
 Text_Cache :: struct {
 	engine:     ^sdl_ttf.TextEngine,
 	font_bytes: [dynamic][]u8,
 	sdl_fonts:  map[Font_Key]^sdl_ttf.Font,
-	cache:      map[u32]^sdl_ttf.Text,
+	cache:      map[Cache_Key]^sdl_ttf.Text,
 }
 
 // Internal for fetching SDL TTF font pointer for rendering
@@ -66,37 +78,196 @@ register_font :: proc(bytes: []u8) -> (id: Font_Id, ok: bool) #optional_ok {
 }
 
 Text :: struct {
-	ref:      ^sdl_ttf.Text,
+	sdl_text: ^sdl_ttf.Text,
 	position: [2]f32,
 	color:    Color,
 }
 
-text :: proc(
+// ---------------------------------------------------------------------------------------------------------------------
-	id: u32,
+// ----- Text cache lookup -------------
-	txt: cstring,
+// ---------------------------------------------------------------------------------------------------------------------
-	pos: [2]f32,
+
-	font_id: Font_Id,
+// Shared cache lookup/create/update logic used by both the `text` proc and the Clay render path.
-	font_size: u16 = 44,
+// Returns the cached (or newly created) TTF_Text pointer.
-	color: Color = {0, 0, 0, 255},
+@(private)
-) -> Text {
+cache_get_or_update :: proc(key: Cache_Key, c_str: cstring, font: ^sdl_ttf.Font) -> ^sdl_ttf.Text {
-	sdl_text := GLOB.text_cache.cache[id]
+	existing, found := GLOB.text_cache.cache[key]
-	if sdl_text == nil {
+	if !found {
-		sdl_text = sdl_ttf.CreateText(GLOB.text_cache.engine, get_font(font_id, font_size), txt, 0)
+		sdl_text := sdl_ttf.CreateText(GLOB.text_cache.engine, font, c_str, 0)
 		if sdl_text == nil {
 			log.panicf("Failed to create SDL text: %s", sdl.GetError())
 		}
-		GLOB.text_cache.cache[id] = sdl_text
+		GLOB.text_cache.cache[key] = sdl_text
+		return sdl_text
 	} else {
-		//TODO if IDs are always unique and never change the underlying text
+		if !sdl_ttf.SetTextString(existing, c_str, 0) {
-		// can get rid of this
-		if !sdl_ttf.SetTextString(sdl_text, txt, 0) {
 			log.panicf("Failed to update SDL text string: %s", sdl.GetError())
 		}
+		return existing
+	}
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// ----- Text drawing ------------------
+// ---------------------------------------------------------------------------------------------------------------------
+
+// Draw text at a position with optional rotation and origin.
+//
+// When `id` is nil (the default), the text is created and destroyed each frame — simple and
+// leak-free, appropriate for HUDs and moderate UI (up to ~50 text elements per frame).
+//
+// When `id` is set, the TTF_Text object is cached across frames keyed by the provided u32.
+// This avoids per-frame HarfBuzz shaping and allocation, which matters for text-heavy apps
+// (editors, terminals, chat). The user is responsible for choosing unique IDs per logical text
+// element and calling `clear_text_cache` or `clear_text_cache_entry` when cached entries are
+// no longer needed. Custom text IDs occupy a separate namespace from Clay text IDs, so
+// collisions between the two are impossible.
+//
+// `origin` is in pixels from the text block's top-left corner (raylib convention).
+// The point whose local coords equal `origin` lands at `pos` in world space.
+// `rotation` is in degrees, counter-clockwise.
+text :: proc(
+	layer: ^Layer,
+	text_string: string,
+	position: [2]f32,
+	font_id: Font_Id,
+	font_size: u16 = 44,
+	color: Color = BLACK,
+	origin: [2]f32 = {0, 0},
+	rotation: f32 = 0,
+	id: Maybe(u32) = nil,
+	temp_allocator := context.temp_allocator,
+) {
+	c_str := strings.clone_to_cstring(text_string, temp_allocator)
+	defer delete(c_str, temp_allocator)
+
+	sdl_text: ^sdl_ttf.Text
+	cached := false
+
+	if cache_id, ok := id.?; ok {
+		cached = true
+		sdl_text = cache_get_or_update(Cache_Key{cache_id, .Custom}, c_str, get_font(font_id, font_size))
+	} else {
+		sdl_text = sdl_ttf.CreateText(GLOB.text_cache.engine, get_font(font_id, font_size), c_str, 0)
+		if sdl_text == nil {
+			log.panicf("Failed to create SDL text: %s", sdl.GetError())
+		}
 	}
 
-	return Text{sdl_text, pos, color}
+	if needs_transform(origin, rotation) {
+		dpi_scale := GLOB.dpi_scaling
+		transform := build_pivot_rotation(position * dpi_scale, origin * dpi_scale, rotation)
+		prepare_text_transformed(layer, Text{sdl_text, {0, 0}, color}, transform)
+	} else {
+		prepare_text(layer, Text{sdl_text, position, color})
+	}
+
+	if !cached {
+		// Don't destroy now — the draw data (atlas texture, vertices) is still referenced
+		// by the batch buffers until end() submits to the GPU. Deferred to clear_global().
+		append(&GLOB.tmp_uncached_text, sdl_text)
+	}
 }
 
+// ---------------------------------------------------------------------------------------------------------------------
+// ----- Public text measurement -------
+// ---------------------------------------------------------------------------------------------------------------------
+
+// Measure a string in logical pixels (pre-DPI-scaling) using the same font backend as the renderer.
+measure_text :: proc(
+	text_string: string,
+	font_id: Font_Id,
+	font_size: u16 = 44,
+	allocator := context.temp_allocator,
+) -> [2]f32 {
+	c_str := strings.clone_to_cstring(text_string, allocator)
+	defer delete(c_str, allocator)
+	width, height: c.int
+	if !sdl_ttf.GetStringSize(get_font(font_id, font_size), c_str, 0, &width, &height) {
+		log.panicf("Failed to measure text: %s", sdl.GetError())
+	}
+	return {f32(width) / GLOB.dpi_scaling, f32(height) / GLOB.dpi_scaling}
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// ----- Text anchor helpers -----------
+// ---------------------------------------------------------------------------------------------------------------------
+
+center_of_text :: proc(text_string: string, font_id: Font_Id, font_size: u16 = 44) -> [2]f32 {
+	size := measure_text(text_string, font_id, font_size)
+	return size * 0.5
+}
+
+top_left_of_text :: proc(text_string: string, font_id: Font_Id, font_size: u16 = 44) -> [2]f32 {
+	return {0, 0}
+}
+
+top_of_text :: proc(text_string: string, font_id: Font_Id, font_size: u16 = 44) -> [2]f32 {
+	size := measure_text(text_string, font_id, font_size)
+	return {size.x * 0.5, 0}
+}
+
+top_right_of_text :: proc(text_string: string, font_id: Font_Id, font_size: u16 = 44) -> [2]f32 {
+	size := measure_text(text_string, font_id, font_size)
+	return {size.x, 0}
+}
+
+left_of_text :: proc(text_string: string, font_id: Font_Id, font_size: u16 = 44) -> [2]f32 {
+	size := measure_text(text_string, font_id, font_size)
+	return {0, size.y * 0.5}
+}
+
+right_of_text :: proc(text_string: string, font_id: Font_Id, font_size: u16 = 44) -> [2]f32 {
+	size := measure_text(text_string, font_id, font_size)
+	return {size.x, size.y * 0.5}
+}
+
+bottom_left_of_text :: proc(text_string: string, font_id: Font_Id, font_size: u16 = 44) -> [2]f32 {
+	size := measure_text(text_string, font_id, font_size)
+	return {0, size.y}
+}
+
+bottom_of_text :: proc(text_string: string, font_id: Font_Id, font_size: u16 = 44) -> [2]f32 {
+	size := measure_text(text_string, font_id, font_size)
+	return {size.x * 0.5, size.y}
+}
+
+bottom_right_of_text :: proc(text_string: string, font_id: Font_Id, font_size: u16 = 44) -> [2]f32 {
+	size := measure_text(text_string, font_id, font_size)
+	return size
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// ----- Cache management --------------
+// ---------------------------------------------------------------------------------------------------------------------
+
+// Destroy all cached text objects (both custom and Clay entries). Call on scene transitions,
+// view changes, or periodically in apps that produce many distinct cached text entries over time.
+// After calling this, subsequent text draws with an `id` will re-create their cache entries.
+clear_text_cache :: proc() {
+	for _, sdl_text in GLOB.text_cache.cache {
+		append(&GLOB.pending_text_releases, sdl_text)
+	}
+	clear(&GLOB.text_cache.cache)
+}
+
+// Destroy a specific cached custom text entry by its u32 id (the same value passed to the
+// `text` proc's `id` parameter). This only affects custom text entries — Clay text entries
+// are managed internally and are not addressable by the user.
+// No-op if the id is not in the cache.
+clear_text_cache_entry :: proc(id: u32) {
+	key := Cache_Key{id, .Custom}
+	sdl_text, ok := GLOB.text_cache.cache[key]
+	if ok {
+		append(&GLOB.pending_text_releases, sdl_text)
+		delete_key(&GLOB.text_cache.cache, key)
+	}
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// ----- Internal cache lifecycle ------
+// ---------------------------------------------------------------------------------------------------------------------
+
 @(private, require_results)
 init_text_cache :: proc(
 	device: ^sdl.GPUDevice,
@@ -121,7 +292,7 @@ init_text_cache :: proc(
 
 	text_cache = Text_Cache {
 		engine = engine,
-		cache  = make(map[u32]^sdl_ttf.Text, allocator = allocator),
+		cache  = make(map[Cache_Key]^sdl_ttf.Text, allocator = allocator),
 	}
 
 	log.debug("Done initializing text cache")
@@ -132,6 +303,9 @@ destroy_text_cache :: proc() {
 	for _, font in GLOB.text_cache.sdl_fonts {
 		sdl_ttf.CloseFont(font)
 	}
+	for _, sdl_text in GLOB.text_cache.cache {
+		sdl_ttf.DestroyText(sdl_text)
+	}
 	delete(GLOB.text_cache.sdl_fonts)
 	delete(GLOB.text_cache.font_bytes)
 	delete(GLOB.text_cache.cache)

draw/textures.odin

@@ -0,0 +1,414 @@
+package draw
+
+import "core:log"
+import "core:mem"
+import sdl "vendor:sdl3"
+
+Texture_Id :: distinct u32
+INVALID_TEXTURE :: Texture_Id(0) // Slot 0 is reserved/unused
+
+Texture_Kind :: enum u8 {
+	Static, // Uploaded once, never changes (QR codes, decoded PNGs, icons)
+	Dynamic, // Updatable via update_texture_region
+	Stream, // Frequent full re-uploads (video, procedural)
+}
+
+Sampler_Preset :: enum u8 {
+	Nearest_Clamp,
+	Linear_Clamp,
+	Nearest_Repeat,
+	Linear_Repeat,
+}
+
+SAMPLER_PRESET_COUNT :: 4
+
+Fit_Mode :: enum u8 {
+	Stretch, // Fill rect, may distort aspect ratio (default)
+	Fit, // Preserve aspect, letterbox (may leave margins)
+	Fill, // Preserve aspect, center-crop (may crop edges)
+	Tile, // Repeat at native texture size
+	Center, // 1:1 pixel size, centered, no scaling
+}
+
+Texture_Desc :: struct {
+	width:           u32,
+	height:          u32,
+	depth_or_layers: u32,
+	type:            sdl.GPUTextureType,
+	format:          sdl.GPUTextureFormat,
+	usage:           sdl.GPUTextureUsageFlags,
+	mip_levels:      u32,
+	kind:            Texture_Kind,
+}
+
+// Internal slot — not exported.
+@(private)
+Texture_Slot :: struct {
+	gpu_texture: ^sdl.GPUTexture,
+	desc:        Texture_Desc,
+	generation:  u32,
+}
+
+// State stored in GLOB
+// This file references:
+//   GLOB.device                 : ^sdl.GPUDevice
+//   GLOB.texture_slots          : [dynamic]Texture_Slot
+//   GLOB.texture_free_list      : [dynamic]u32
+//   GLOB.pending_texture_releases : [dynamic]Texture_Id
+//   GLOB.samplers               : [SAMPLER_PRESET_COUNT]^sdl.GPUSampler
+
+Clay_Image_Data :: struct {
+	texture_id: Texture_Id,
+	fit:        Fit_Mode,
+	tint:       Color,
+}
+
+clay_image_data :: proc(id: Texture_Id, fit: Fit_Mode = .Stretch, tint: Color = WHITE) -> Clay_Image_Data {
+	return {texture_id = id, fit = fit, tint = tint}
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// ----- Registration -------------
+// ---------------------------------------------------------------------------------------------------------------------
+
+// Register a texture. Draw owns the GPU resource and releases it on unregister.
+// `data` is tightly-packed row-major bytes matching desc.format.
+// The caller may free `data` immediately after this proc returns.
+@(require_results)
+register_texture :: proc(desc: Texture_Desc, data: []u8) -> (id: Texture_Id, ok: bool) {
+	device := GLOB.device
+	if device == nil {
+		log.error("register_texture called before draw.init()")
+		return INVALID_TEXTURE, false
+	}
+
+	assert(desc.width > 0, "Texture_Desc.width must be > 0")
+	assert(desc.height > 0, "Texture_Desc.height must be > 0")
+	assert(desc.depth_or_layers > 0, "Texture_Desc.depth_or_layers must be > 0")
+	assert(desc.mip_levels > 0, "Texture_Desc.mip_levels must be > 0")
+	assert(desc.usage != {}, "Texture_Desc.usage must not be empty (e.g. {.SAMPLER})")
+
+	// Create the GPU texture
+	gpu_texture := sdl.CreateGPUTexture(
+		device,
+		sdl.GPUTextureCreateInfo {
+			type = desc.type,
+			format = desc.format,
+			usage = desc.usage,
+			width = desc.width,
+			height = desc.height,
+			layer_count_or_depth = desc.depth_or_layers,
+			num_levels = desc.mip_levels,
+			sample_count = ._1,
+		},
+	)
+	if gpu_texture == nil {
+		log.errorf("Failed to create GPU texture (%dx%d): %s", desc.width, desc.height, sdl.GetError())
+		return INVALID_TEXTURE, false
+	}
+
+	// Upload pixel data via a transfer buffer
+	if len(data) > 0 {
+		data_size := u32(len(data))
+		transfer := sdl.CreateGPUTransferBuffer(
+			device,
+			sdl.GPUTransferBufferCreateInfo{usage = .UPLOAD, size = data_size},
+		)
+		if transfer == nil {
+			log.errorf("Failed to create texture transfer buffer: %s", sdl.GetError())
+			sdl.ReleaseGPUTexture(device, gpu_texture)
+			return INVALID_TEXTURE, false
+		}
+		defer sdl.ReleaseGPUTransferBuffer(device, transfer)
+
+		mapped := sdl.MapGPUTransferBuffer(device, transfer, false)
+		if mapped == nil {
+			log.errorf("Failed to map texture transfer buffer: %s", sdl.GetError())
+			sdl.ReleaseGPUTexture(device, gpu_texture)
+			return INVALID_TEXTURE, false
+		}
+		mem.copy(mapped, raw_data(data), int(data_size))
+		sdl.UnmapGPUTransferBuffer(device, transfer)
+
+		cmd_buffer := sdl.AcquireGPUCommandBuffer(device)
+		if cmd_buffer == nil {
+			log.errorf("Failed to acquire command buffer for texture upload: %s", sdl.GetError())
+			sdl.ReleaseGPUTexture(device, gpu_texture)
+			return INVALID_TEXTURE, false
+		}
+		copy_pass := sdl.BeginGPUCopyPass(cmd_buffer)
+		sdl.UploadToGPUTexture(
+			copy_pass,
+			sdl.GPUTextureTransferInfo{transfer_buffer = transfer},
+			sdl.GPUTextureRegion{texture = gpu_texture, w = desc.width, h = desc.height, d = desc.depth_or_layers},
+			false,
+		)
+		sdl.EndGPUCopyPass(copy_pass)
+		if !sdl.SubmitGPUCommandBuffer(cmd_buffer) {
+			log.errorf("Failed to submit texture upload: %s", sdl.GetError())
+			sdl.ReleaseGPUTexture(device, gpu_texture)
+			return INVALID_TEXTURE, false
+		}
+	}
+
+	// Allocate a slot (reuse from free list or append)
+	slot_index: u32
+	if len(GLOB.texture_free_list) > 0 {
+		slot_index = pop(&GLOB.texture_free_list)
+		GLOB.texture_slots[slot_index] = Texture_Slot {
+			gpu_texture = gpu_texture,
+			desc        = desc,
+			generation  = GLOB.texture_slots[slot_index].generation + 1,
+		}
+	} else {
+		slot_index = u32(len(GLOB.texture_slots))
+		append(&GLOB.texture_slots, Texture_Slot{gpu_texture = gpu_texture, desc = desc, generation = 1})
+	}
+
+	return Texture_Id(slot_index), true
+}
+
+// Queue a texture for release at the end of the current frame.
+// The GPU resource is not freed immediately — see "Deferred release" in the README.
+unregister_texture :: proc(id: Texture_Id) {
+	if id == INVALID_TEXTURE do return
+	append(&GLOB.pending_texture_releases, id)
+}
+
+// Re-upload a sub-region of a Dynamic texture.
+update_texture_region :: proc(id: Texture_Id, region: Rectangle, data: []u8) {
+	if id == INVALID_TEXTURE do return
+	slot := &GLOB.texture_slots[u32(id)]
+	if slot.gpu_texture == nil do return
+
+	device := GLOB.device
+	data_size := u32(len(data))
+	if data_size == 0 do return
+
+	transfer := sdl.CreateGPUTransferBuffer(
+		device,
+		sdl.GPUTransferBufferCreateInfo{usage = .UPLOAD, size = data_size},
+	)
+	if transfer == nil {
+		log.errorf("Failed to create transfer buffer for texture region update: %s", sdl.GetError())
+		return
+	}
+	defer sdl.ReleaseGPUTransferBuffer(device, transfer)
+
+	mapped := sdl.MapGPUTransferBuffer(device, transfer, false)
+	if mapped == nil {
+		log.errorf("Failed to map transfer buffer for texture region update: %s", sdl.GetError())
+		return
+	}
+	mem.copy(mapped, raw_data(data), int(data_size))
+	sdl.UnmapGPUTransferBuffer(device, transfer)
+
+	cmd_buffer := sdl.AcquireGPUCommandBuffer(device)
+	if cmd_buffer == nil {
+		log.errorf("Failed to acquire command buffer for texture region update: %s", sdl.GetError())
+		return
+	}
+	copy_pass := sdl.BeginGPUCopyPass(cmd_buffer)
+	sdl.UploadToGPUTexture(
+		copy_pass,
+		sdl.GPUTextureTransferInfo{transfer_buffer = transfer},
+		sdl.GPUTextureRegion {
+			texture = slot.gpu_texture,
+			x = u32(region.x),
+			y = u32(region.y),
+			w = u32(region.width),
+			h = u32(region.height),
+			d = 1,
+		},
+		false,
+	)
+	sdl.EndGPUCopyPass(copy_pass)
+	if !sdl.SubmitGPUCommandBuffer(cmd_buffer) {
+		log.errorf("Failed to submit texture region update: %s", sdl.GetError())
+	}
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// ----- Helpers -------------
+// ---------------------------------------------------------------------------------------------------------------------
+
+// Compute UV rect, recommended sampler, and inner rect for a given fit mode.
+// `rect` is the target drawing area; `texture_id` identifies the texture whose
+// pixel dimensions are looked up via texture_size().
+// For Fit mode, `inner_rect` is smaller than `rect` (centered). For all other modes, `inner_rect == rect`.
+fit_params :: proc(
+	fit: Fit_Mode,
+	rect: Rectangle,
+	texture_id: Texture_Id,
+) -> (
+	uv_rect: Rectangle,
+	sampler: Sampler_Preset,
+	inner_rect: Rectangle,
+) {
+	size := texture_size(texture_id)
+	texture_width := f32(size.x)
+	texture_height := f32(size.y)
+	rect_width := rect.width
+	rect_height := rect.height
+	inner_rect = rect
+
+	if texture_width == 0 || texture_height == 0 || rect_width == 0 || rect_height == 0 {
+		return {0, 0, 1, 1}, .Linear_Clamp, inner_rect
+	}
+
+	texture_aspect := texture_width / texture_height
+	rect_aspect := rect_width / rect_height
+
+	switch fit {
+	case .Stretch: return {0, 0, 1, 1}, .Linear_Clamp, inner_rect
+
+	case .Fill: if texture_aspect > rect_aspect {
+				// Texture wider than rect — crop sides
+				scale := rect_aspect / texture_aspect
+				margin := (1 - scale) * 0.5
+				return {margin, 0, 1 - margin, 1}, .Linear_Clamp, inner_rect
+			} else {
+				// Texture taller than rect — crop top/bottom
+				scale := texture_aspect / rect_aspect
+				margin := (1 - scale) * 0.5
+				return {0, margin, 1, 1 - margin}, .Linear_Clamp, inner_rect
+			}
+
+	case .Fit:
+		// Preserve aspect, fit inside rect. Returns a shrunken inner_rect.
+		if texture_aspect > rect_aspect {
+			// Image wider — letterbox top/bottom
+			fit_height := rect_width / texture_aspect
+			padding := (rect_height - fit_height) * 0.5
+			inner_rect = Rectangle{rect.x, rect.y + padding, rect_width, fit_height}
+		} else {
+			// Image taller — letterbox left/right
+			fit_width := rect_height * texture_aspect
+			padding := (rect_width - fit_width) * 0.5
+			inner_rect = Rectangle{rect.x + padding, rect.y, fit_width, rect_height}
+		}
+		return {0, 0, 1, 1}, .Linear_Clamp, inner_rect
+
+	case .Tile:
+		uv_width := rect_width / texture_width
+		uv_height := rect_height / texture_height
+		return {0, 0, uv_width, uv_height}, .Linear_Repeat, inner_rect
+
+	case .Center:
+		u_half := rect_width / (2 * texture_width)
+		v_half := rect_height / (2 * texture_height)
+		return {0.5 - u_half, 0.5 - v_half, 0.5 + u_half, 0.5 + v_half}, .Nearest_Clamp, inner_rect
+	}
+
+	return {0, 0, 1, 1}, .Linear_Clamp, inner_rect
+}
+
+texture_size :: proc(id: Texture_Id) -> [2]u32 {
+	if id == INVALID_TEXTURE do return {0, 0}
+	slot := &GLOB.texture_slots[u32(id)]
+	return {slot.desc.width, slot.desc.height}
+}
+
+texture_format :: proc(id: Texture_Id) -> sdl.GPUTextureFormat {
+	if id == INVALID_TEXTURE do return .INVALID
+	return GLOB.texture_slots[u32(id)].desc.format
+}
+
+texture_kind :: proc(id: Texture_Id) -> Texture_Kind {
+	if id == INVALID_TEXTURE do return .Static
+	return GLOB.texture_slots[u32(id)].desc.kind
+}
+
+// Internal: get the raw GPU texture pointer for binding during draw.
+@(private)
+texture_gpu_handle :: proc(id: Texture_Id) -> ^sdl.GPUTexture {
+	if id == INVALID_TEXTURE do return nil
+	idx := u32(id)
+	if idx >= u32(len(GLOB.texture_slots)) do return nil
+	return GLOB.texture_slots[idx].gpu_texture
+}
+
+// Deferred release (called from draw.end / clear_global)
+@(private)
+process_pending_texture_releases :: proc() {
+	device := GLOB.device
+	for id in GLOB.pending_texture_releases {
+		idx := u32(id)
+		if idx >= u32(len(GLOB.texture_slots)) do continue
+		slot := &GLOB.texture_slots[idx]
+		if slot.gpu_texture != nil {
+			sdl.ReleaseGPUTexture(device, slot.gpu_texture)
+			slot.gpu_texture = nil
+		}
+		slot.generation += 1
+		append(&GLOB.texture_free_list, idx)
+	}
+	clear(&GLOB.pending_texture_releases)
+}
+
+@(private)
+get_sampler :: proc(preset: Sampler_Preset) -> ^sdl.GPUSampler {
+	idx := int(preset)
+	if GLOB.samplers[idx] != nil do return GLOB.samplers[idx]
+
+	// Lazily create
+	min_filter, mag_filter: sdl.GPUFilter
+	address_mode: sdl.GPUSamplerAddressMode
+
+	switch preset {
+	case .Nearest_Clamp:
+		min_filter = .NEAREST; mag_filter = .NEAREST; address_mode = .CLAMP_TO_EDGE
+	case .Linear_Clamp:
+		min_filter = .LINEAR; mag_filter = .LINEAR; address_mode = .CLAMP_TO_EDGE
+	case .Nearest_Repeat:
+		min_filter = .NEAREST; mag_filter = .NEAREST; address_mode = .REPEAT
+	case .Linear_Repeat:
+		min_filter = .LINEAR; mag_filter = .LINEAR; address_mode = .REPEAT
+	}
+
+	sampler := sdl.CreateGPUSampler(
+		GLOB.device,
+		sdl.GPUSamplerCreateInfo {
+			min_filter = min_filter,
+			mag_filter = mag_filter,
+			mipmap_mode = .LINEAR,
+			address_mode_u = address_mode,
+			address_mode_v = address_mode,
+			address_mode_w = address_mode,
+		},
+	)
+	if sampler == nil {
+		log.errorf("Failed to create sampler preset %v: %s", preset, sdl.GetError())
+		return GLOB.pipeline_2d_base.sampler // fallback to existing default sampler
+	}
+
+	GLOB.samplers[idx] = sampler
+	return sampler
+}
+
+// Internal: destroy all sampler pool entries. Called from draw.destroy().
+@(private)
+destroy_sampler_pool :: proc() {
+	device := GLOB.device
+	for &s in GLOB.samplers {
+		if s != nil {
+			sdl.ReleaseGPUSampler(device, s)
+			s = nil
+		}
+	}
+}
+
+// Internal: destroy all registered textures. Called from draw.destroy().
+@(private)
+destroy_all_textures :: proc() {
+	device := GLOB.device
+	for &slot in GLOB.texture_slots {
+		if slot.gpu_texture != nil {
+			sdl.ReleaseGPUTexture(device, slot.gpu_texture)
+			slot.gpu_texture = nil
+		}
+	}
+	delete(GLOB.texture_slots)
+	delete(GLOB.texture_free_list)
+	delete(GLOB.pending_texture_releases)
+}

qrcode/examples/examples.odin

@@ -0,0 +1,285 @@
+package examples
+
+import "core:fmt"
+import "core:mem"
+import "core:os"
+
+import qr ".."
+
+main :: proc() {
+	//----- Tracking allocator ----------------------------------
+	{
+		tracking_temp_allocator := false
+		// Temp
+		track_temp: mem.Tracking_Allocator
+		if tracking_temp_allocator {
+			mem.tracking_allocator_init(&track_temp, context.temp_allocator)
+			context.temp_allocator = mem.tracking_allocator(&track_temp)
+		}
+		// Default
+		track: mem.Tracking_Allocator
+		mem.tracking_allocator_init(&track, context.allocator)
+		context.allocator = mem.tracking_allocator(&track)
+		defer {
+			// Temp allocator
+			if tracking_temp_allocator {
+				if len(track_temp.allocation_map) > 0 {
+					fmt.eprintf("=== %v allocations not freed - temp allocator: ===\n", len(track_temp.allocation_map))
+					for _, entry in track_temp.allocation_map {
+						fmt.eprintf("- %v bytes @ %v\n", entry.size, entry.location)
+					}
+				}
+				if len(track_temp.bad_free_array) > 0 {
+					fmt.eprintf("=== %v incorrect frees - temp allocator: ===\n", len(track_temp.bad_free_array))
+					for entry in track_temp.bad_free_array {
+						fmt.eprintf("- %p @ %v\n", entry.memory, entry.location)
+					}
+				}
+				mem.tracking_allocator_destroy(&track_temp)
+			}
+			// Default allocator
+			if len(track.allocation_map) > 0 {
+				fmt.eprintf("=== %v allocations not freed - main allocator: ===\n", len(track.allocation_map))
+				for _, entry in track.allocation_map {
+					fmt.eprintf("- %v bytes @ %v\n", entry.size, entry.location)
+				}
+			}
+			if len(track.bad_free_array) > 0 {
+				fmt.eprintf("=== %v incorrect frees - main allocator: ===\n", len(track.bad_free_array))
+				for entry in track.bad_free_array {
+					fmt.eprintf("- %p @ %v\n", entry.memory, entry.location)
+				}
+			}
+			mem.tracking_allocator_destroy(&track)
+		}
+	}
+
+	args := os.args
+	if len(args) < 2 {
+		fmt.eprintln("Usage: examples <example_name>")
+		fmt.eprintln("Available examples: basic, variety, segment, mask")
+		os.exit(1)
+	}
+
+	switch args[1] {
+	case "basic": basic()
+	case "variety": variety()
+	case "segment": segment()
+	case "mask": mask()
+	case:
+		fmt.eprintf("Unknown example: %v\n", args[1])
+		fmt.eprintln("Available examples: basic, variety, segment, mask")
+		os.exit(1)
+	}
+}
+
+// Creates a single QR Code, then prints it to the console.
+basic :: proc() {
+	text :: "Hello, world!"
+	ecl :: qr.Ecc.Low
+
+	qrcode: [qr.BUFFER_LEN_MAX]u8
+	ok := qr.encode_auto(text, qrcode[:], ecl)
+	if ok do print_qr(qrcode[:])
+}
+
+// Creates a variety of QR Codes that exercise different features of the library.
+variety :: proc() {
+	qrcode: [qr.BUFFER_LEN_MAX]u8
+
+	{ 	// Numeric mode encoding (3.33 bits per digit)
+		ok := qr.encode_auto("314159265358979323846264338327950288419716939937510", qrcode[:], qr.Ecc.Medium)
+		if ok do print_qr(qrcode[:])
+	}
+
+	{ 	// Alphanumeric mode encoding (5.5 bits per character)
+		ok := qr.encode_auto("DOLLAR-AMOUNT:$39.87 PERCENTAGE:100.00% OPERATIONS:+-*/", qrcode[:], qr.Ecc.High)
+		if ok do print_qr(qrcode[:])
+	}
+
+	{ 	// Unicode text as UTF-8
+		ok := qr.encode_auto(
+			"\xE3\x81\x93\xE3\x82\x93\xE3\x81\xAB\xE3\x81\xA1wa\xE3\x80\x81" +
+			"\xE4\xB8\x96\xE7\x95\x8C\xEF\xBC\x81\x20\xCE\xB1\xCE\xB2\xCE\xB3\xCE\xB4",
+			qrcode[:],
+			qr.Ecc.Quartile,
+		)
+		if ok do print_qr(qrcode[:])
+	}
+
+	{ 	// Moderately large QR Code using longer text (from Lewis Carroll's Alice in Wonderland)
+		ok := qr.encode_auto(
+			"Alice was beginning to get very tired of sitting by her sister on the bank, " +
+			"and of having nothing to do: once or twice she had peeped into the book her sister was reading, " +
+			"but it had no pictures or conversations in it, 'and what is the use of a book,' thought Alice " +
+			"'without pictures or conversations?' So she was considering in her own mind (as well as she could, " +
+			"for the hot day made her feel very sleepy and stupid), whether the pleasure of making a " +
+			"daisy-chain would be worth the trouble of getting up and picking the daisies, when suddenly " +
+			"a White Rabbit with pink eyes ran close by her.",
+			qrcode[:],
+			qr.Ecc.High,
+		)
+		if ok do print_qr(qrcode[:])
+	}
+}
+
+// Creates QR Codes with manually specified segments for better compactness.
+segment :: proc() {
+	qrcode: [qr.BUFFER_LEN_MAX]u8
+
+	{ 	// Illustration "silver"
+		silver0 :: "THE SQUARE ROOT OF 2 IS 1."
+		silver1 :: "41421356237309504880168872420969807856967187537694807317667973799"
+
+		// Encode as single text (auto mode selection)
+		{
+			concat :: silver0 + silver1
+			ok := qr.encode_auto(concat, qrcode[:], qr.Ecc.Low)
+			if ok do print_qr(qrcode[:])
+		}
+
+		// Encode as two manual segments (alphanumeric + numeric) for better compactness
+		{
+			seg_buf0: [qr.BUFFER_LEN_MAX]u8
+			seg_buf1: [qr.BUFFER_LEN_MAX]u8
+			segs := [2]qr.Segment{qr.make_alphanumeric(silver0, seg_buf0[:]), qr.make_numeric(silver1, seg_buf1[:])}
+			ok := qr.encode_auto(segs[:], qr.Ecc.Low, qrcode[:])
+			if ok do print_qr(qrcode[:])
+		}
+	}
+
+	{ 	// Illustration "golden"
+		golden0 :: "Golden ratio \xCF\x86 = 1."
+		golden1 :: "6180339887498948482045868343656381177203091798057628621354486227052604628189024497072072041893911374"
+		golden2 :: "......"
+
+		// Encode as single text (auto mode selection)
+		{
+			concat :: golden0 + golden1 + golden2
+			ok := qr.encode_auto(concat, qrcode[:], qr.Ecc.Low)
+			if ok do print_qr(qrcode[:])
+		}
+
+		// Encode as three manual segments (byte + numeric + alphanumeric) for better compactness
+		{
+			golden0_str: string = golden0
+			golden0_bytes := transmute([]u8)golden0_str
+			seg_buf0: [qr.BUFFER_LEN_MAX]u8
+			seg_buf1: [qr.BUFFER_LEN_MAX]u8
+			seg_buf2: [qr.BUFFER_LEN_MAX]u8
+			segs := [3]qr.Segment {
+				qr.make_bytes(golden0_bytes, seg_buf0[:]),
+				qr.make_numeric(golden1, seg_buf1[:]),
+				qr.make_alphanumeric(golden2, seg_buf2[:]),
+			}
+			ok := qr.encode_auto(segs[:], qr.Ecc.Low, qrcode[:])
+			if ok do print_qr(qrcode[:])
+		}
+	}
+
+	{ 	// Illustration "Madoka": kanji, kana, Cyrillic, full-width Latin, Greek characters
+		// Encode as text (auto mode — byte mode)
+		{
+			madoka ::
+				"\xE3\x80\x8C\xE9\xAD\x94\xE6\xB3\x95\xE5" +
+				"\xB0\x91\xE5\xA5\xB3\xE3\x81\xBE\xE3\x81" +
+				"\xA9\xE3\x81\x8B\xE2\x98\x86\xE3\x83\x9E" +
+				"\xE3\x82\xAE\xE3\x82\xAB\xE3\x80\x8D\xE3" +
+				"\x81\xA3\xE3\x81\xA6\xE3\x80\x81\xE3\x80" +
+				"\x80\xD0\x98\xD0\x90\xD0\x98\xE3\x80\x80" +
+				"\xEF\xBD\x84\xEF\xBD\x85\xEF\xBD\x93\xEF" +
+				"\xBD\x95\xE3\x80\x80\xCE\xBA\xCE\xB1\xEF" +
+				"\xBC\x9F"
+			ok := qr.encode_auto(madoka, qrcode[:], qr.Ecc.Low)
+			if ok do print_qr(qrcode[:])
+		}
+
+		// Encode with manual kanji mode (13 bits per character)
+		{
+					//odinfmt: disable
+			kanji_chars :: [29]int{
+				0x0035, 0x1002, 0x0FC0, 0x0AED, 0x0AD7,
+				0x015C, 0x0147, 0x0129, 0x0059, 0x01BD,
+				0x018D, 0x018A, 0x0036, 0x0141, 0x0144,
+				0x0001, 0x0000, 0x0249, 0x0240, 0x0249,
+				0x0000, 0x0104, 0x0105, 0x0113, 0x0115,
+				0x0000, 0x0208, 0x01FF, 0x0008,
+			}
+			//odinfmt: enable
+
+			seg_buf: [qr.BUFFER_LEN_MAX]u8
+			for &b in seg_buf {
+				b = 0
+			}
+
+			seg: qr.Segment
+			seg.mode = .Kanji
+			seg.num_chars = len(kanji_chars)
+			seg.bit_length = 0
+			for ch in kanji_chars {
+				for j := 12; j >= 0; j -= 1 {
+					seg_buf[seg.bit_length >> 3] |= u8(((ch >> uint(j)) & 1)) << uint(7 - (seg.bit_length & 7))
+					seg.bit_length += 1
+				}
+			}
+			seg.data = seg_buf[:(seg.bit_length + 7) / 8]
+
+			segs := [1]qr.Segment{seg}
+			ok := qr.encode_auto(segs[:], qr.Ecc.Low, qrcode[:])
+			if ok do print_qr(qrcode[:])
+		}
+	}
+}
+
+// Creates QR Codes with the same size and contents but different mask patterns.
+mask :: proc() {
+	qrcode: [qr.BUFFER_LEN_MAX]u8
+
+	{ 	// Project Nayuki URL
+		ok: bool
+
+		ok = qr.encode_auto("https://www.nayuki.io/", qrcode[:], qr.Ecc.High)
+		if ok do print_qr(qrcode[:])
+
+		ok = qr.encode_auto("https://www.nayuki.io/", qrcode[:], qr.Ecc.High, mask = qr.Mask.M3)
+		if ok do print_qr(qrcode[:])
+	}
+
+	{ 	// Chinese text as UTF-8
+		text ::
+			"\xE7\xB6\xAD\xE5\x9F\xBA\xE7\x99\xBE\xE7\xA7\x91\xEF\xBC\x88\x57\x69\x6B\x69\x70" +
+			"\x65\x64\x69\x61\xEF\xBC\x8C\xE8\x81\x86\xE8\x81\xBD\x69\x2F\xCB\x8C\x77\xC9\xAA" +
+			"\x6B\xE1\xB5\xBB\xCB\x88\x70\x69\xCB\x90\x64\x69\x2E\xC9\x99\x2F\xEF\xBC\x89\xE6" +
+			"\x98\xAF\xE4\xB8\x80\xE5\x80\x8B\xE8\x87\xAA\xE7\x94\xB1\xE5\x85\xA7\xE5\xAE\xB9" +
+			"\xE3\x80\x81\xE5\x85\xAC\xE9\x96\x8B\xE7\xB7\xA8\xE8\xBC\xAF\xE4\xB8\x94\xE5\xA4" +
+			"\x9A\xE8\xAA\x9E\xE8\xA8\x80\xE7\x9A\x84\xE7\xB6\xB2\xE8\xB7\xAF\xE7\x99\xBE\xE7" +
+			"\xA7\x91\xE5\x85\xA8\xE6\x9B\xB8\xE5\x8D\x94\xE4\xBD\x9C\xE8\xA8\x88\xE7\x95\xAB"
+
+		ok: bool
+
+		ok = qr.encode_auto(text, qrcode[:], qr.Ecc.Medium, mask = qr.Mask.M0)
+		if ok do print_qr(qrcode[:])
+
+		ok = qr.encode_auto(text, qrcode[:], qr.Ecc.Medium, mask = qr.Mask.M1)
+		if ok do print_qr(qrcode[:])
+
+		ok = qr.encode_auto(text, qrcode[:], qr.Ecc.Medium, mask = qr.Mask.M5)
+		if ok do print_qr(qrcode[:])
+
+		ok = qr.encode_auto(text, qrcode[:], qr.Ecc.Medium, mask = qr.Mask.M7)
+		if ok do print_qr(qrcode[:])
+	}
+}
+
+// Prints the given QR Code to the console.
+print_qr :: proc(qrcode: []u8) {
+	size := qr.get_size(qrcode)
+	border :: 4
+	for y in -border ..< size + border {
+		for x in -border ..< size + border {
+			fmt.print("##" if qr.get_module(qrcode, x, y) else "  ")
+		}
+		fmt.println()
+	}
+	fmt.println()
+}