Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-render

Source of release 0.6.2

0.6.2 / src / gpu_player / recorder.lucb

#==============================================================================================
#
#   recorder - DisplayListPlayerGpu: a tile's commands recorded as GPU draws
#
#   DESCRIPTION:
#       A DisplayListPlayer (class id 2, beside the CPU player's 1) that DisplayListPlayer's
#       own loop drives (display_list_player_execute_tile), so visual contexts, culling and
#       scroll offsets are Ladybird's. Each virtual records draws into CPU-side lists that
#       replay.lucb submits as one tile frame:
#
#         - the state is a stack of whole-pixel translations, a scissor rectangle, at most one
#           rounded clip applied analytically by every shader, and the clips around it as a
#           clip mask: a second rounded clip moves the first into a mask (the clips it
#           multiplies, rendered into an r8 texture of the tile at replay) and takes its place;
#         - solid rectangles without a rounded clip or mask append to a batch, one triangle
#           draw for every run of them under one scissor;
#         - rounded rectangles, rectangle strokes and the scroll bar are `fill` draws, glyphs,
#           path coverage and shadows `mask` draws, images `image` draws (recorder_draws.lucb,
#           recorder_shadows.lucb); replay draws runs of them as one instanced draw where it
#           can.
#
#       The recording draws into the tile's texture as it goes when the atlas has to make
#       room (gpu_flush), so a full atlas costs a texture frame, not the tile.
#
#       What it cannot draw like the CPU player (a transform that is not a whole-pixel
#       translation, an effect, a clip path, gradients, text shadows, ellipses, strokes,
#       painted paths, repeated images, nested display lists, external content)
#       makes the recording unsupported: the tile goes to the CPU player, and the reason is
#       counted (GpuPlayerStats.fallbacks).
#
#       Copyright (c) 2026 the luce-browser authors.
#       SPDX-License-Identifier: BSD-2-Clause
#
#==============================================================================================

# mark: Fallbacks ===============================================================================

## Why a tile went to the CPU player.
pub enum GpuFallback as u8:
    transform = 0
    opacity = 1
    clip_path = 2
    nested_rounded_clip = 3
    text = 4
    image = 5
    path = 6
    gradient = 7
    inner_shadow = 8
    line = 9
    ellipse = 10
    backdrop_filter = 11
    nested_display_list = 12
    external_content = 13
    atlas_full = 14
    text_shadow = 15
    blend = 16
    filter = 17
    mask = 18
    fractional_translation = 19
    perspective = 20
    repeated_image = 21
    color_managed_image = 22
    stroke = 23

## How many GpuFallback reasons there are.
pub let gpu_fallback_count: usize = 24

## A fallback's name, for reports.
pub func gpu_fallback_name(kind: usize) -> str:
    let names: str[24] = ["transform", "opacity", "clip path", "nested rounded clip", "text as paths", "image", "painted path", "gradient",
                          "inner shadow", "line", "ellipse", "backdrop filter", "nested display list", "external content", "atlas full",
                          "text shadow", "blend mode", "filter", "mask", "fractional translation", "perspective", "repeated image",
                          "color-managed image", "stroked path"]
    return names[kind] if kind < gpu_fallback_count else "?"

# mark: Draws ===================================================================================

## How a recorded draw is drawn.
pub enum GpuDrawKind as u8:
    rects = 0
    fill = 1
    mask = 2
    image = 3
    layer_begin = 4
    layer_end = 5
    stages = 6

## A solid rectangle of a `rects` draw: whole pixels and a straight color in stored values.
struct GpuRectRecord:
    var rect: GpuRect
    var color: f32[4]

## The kinds of shaders/tile.frag (the header's third control value).
let gpu_kind_shapes: f32 = 0.0
let gpu_kind_rrect: f32 = 1.0
let gpu_kind_mask: f32 = 2.0
let gpu_kind_image: f32 = 3.0
let gpu_kind_composite: f32 = 4.0
let gpu_kind_clip: f32 = 5.0
let gpu_kind_blend: f32 = 6.0
let gpu_kind_stages: f32 = 7.0

## The program table's width and height in texels (rgba32_float): the stage programs of one
## recording (raster's paint_stage_program), 1 MiB.
let gpu_table_width: usize = 1024
let gpu_table_height: usize = 64

## Where tile.frag's uniforms keep the clip mode, the clip mask flag, the kind, and the kind's
## own values; the analytic clip's rectangle and radii come first.
let gpu_uniform_clip_mode: usize = 12
let gpu_uniform_mask: usize = 13
let gpu_uniform_kind: usize = 14
let gpu_uniform_header: usize = 16

## One recorded draw: its kind, its scissor, its rectangles (`rects`: `first..<first + count` of
## the player's records) or its rectangle, instance values and uniforms for tile.frag (the
## others), the image it samples (`image`), its clip mask (`mask`: 1 + the player's mask, 0 for
## none), and for a `fill` its straight color (ARGB), which instanced shapes carry packed.
struct GpuDraw:
    var kind: GpuDrawKind
    var scissor: GpuRect
    var first: usize
    var count: usize
    var area: GpuRect
    var data: f32[12]
    var uniforms: f32[32]
    var image: gpu.Texture?
    var mask: u32
    var straight: u32

## A rounded clip as the shaders take it: rectangle, radii (top-left x/y, top-right x/y,
## bottom-right x/y, bottom-left x/y) and mode (1 keeps the inside, 2 the outside).
struct GpuRoundedClip:
    var rect: f32[4]
    var radii: f32[8]
    var mode: f32

## The most clips one clip mask multiplies, and the most masks a tile's recording holds.
let gpu_mask_clips: usize = 8
let gpu_mask_limit: usize = 32

## The clips around the analytic one, multiplied into an r8 mask of the tile at replay.
struct GpuMaskJob:
    var clips: GpuRoundedClip[8]
    var count: usize

## The drawing state: a whole-pixel translation, or the whole matrix when the transform is
## anything else (recorder_matrix.lucb), a scissor (in tile pixels), a rounded clip, the clip
## mask around it (1 + the player's mask, 0 for none), and the layer drawn into (1 + the
## player's layer, 0 for the tile).
struct GpuState:
    var dx: i32
    var dy: i32
    var matrix: raster.Transform?
    var clip: GpuRect
    var rounded: GpuRoundedClip?
    var mask: u32
    var layer: u32

## The most layers open at once in a tile's recording.
let gpu_layer_depth: u32 = 8

## A layer (SkCanvas::saveLayer): drawn into its own texture, then composited at `opacity` with
## `blend` (raster.BlendMode's value; 29 the plus-darker blender) under the clips of `outer`,
## the state when it was saved; `depth` counts the layers it lies in, itself included.
struct GpuLayerJob:
    var opacity: f32
    var blend: u32
    var outer: GpuState
    var depth: u32

# mark: The player ==============================================================================

## Web::Painting::DisplayListPlayerGpu (see the header).
pub struct DisplayListPlayerGpu: display_list.IsDisplayListPlayer:
    pub var display_list_player_base: display_list.DisplayListPlayer
    var state: GpuState
    var saved: ak.Vector[GpuState]
    var draws: ak.Vector[GpuDraw]
    var rects: ak.Vector[GpuRectRecord]
    var unsupported: GpuFallback?
    ## Every reason met (a bit per GpuFallback), for reports.
    var reasons: u32
    var masks: ak.Vector[GpuMaskJob]
    var layers: ak.Vector[GpuLayerJob]
    ## The recording's stage programs, four floats a texel, and a buffer one is written into.
    var table: ak.Vector[f32]
    var program: f32[]
    ## What the recording draws with, and the tile it draws into when it has to before it
    ## ends (`flushed` once it has).
    var device: gpu.Device?
    var atlas: GpuAtlas*
    var images: GpuImageCache*
    var atlas_generation: u64
    var pipelines: GpuPipelines*?
    var tile: gpu.Texture?
    var tile_size: i32
    var flushed: bool
    var replay: GpuReplay

    func display_list_player() -> display_list.DisplayListPlayer*: return (display_list.DisplayListPlayer*)&self

    ## Whether the recording draws nothing.
    pub func is_empty() -> bool:
        return ak.vector_is_empty(&self.draws)

    ## Why the tile cannot be drawn on the GPU, if it cannot.
    pub func fallback() -> GpuFallback?:
        return self.unsupported

    ## Every reason met while recording, a bit per GpuFallback.
    pub func fallback_reasons() -> u32:
        return self.reasons

## A GPU player drawing with `atlas` and `images`.
pub func display_list_player_gpu_create(atlas: GpuAtlas*, images: GpuImageCache*) -> DisplayListPlayerGpu*:
    let base = display_list.DisplayListPlayer(vtable = &display_list_player_gpu_vtable, class_id = display_list_player_gpu_class.first_id)
    return (new DisplayListPlayerGpu(display_list_player_base = base, state = GpuState(), atlas = atlas, images = images) in memory.heap) else trap("gpu_player: out of memory")

## Releases the player (not its atlas and images).
pub func display_list_player_gpu_destroy(this: DisplayListPlayerGpu*):
    ak.vector_clear(&this.draws)
    ak.vector_clear(&this.rects)
    ak.vector_clear(&this.saved)
    ak.vector_clear(&this.masks)
    ak.vector_clear(&this.layers)
    ak.vector_clear(&this.table)
    if this.program.length > 0:
        free(this.program) in memory.heap
    this.replay.release()
    free(this) in memory.heap

## Starts a recording for `tile`, `size` pixels square, on `device`, drawn with `pipelines`.
pub func display_list_player_gpu_begin(this: DisplayListPlayerGpu*, device: gpu.Device, pipelines: GpuPipelines*, tile: gpu.Texture, size: i32):
    ak.vector_clear(&this.draws)
    ak.vector_clear(&this.rects)
    ak.vector_clear(&this.saved)
    ak.vector_clear(&this.masks)
    ak.vector_clear(&this.layers)
    ak.vector_clear(&this.table)
    this.state = GpuState(clip = GpuRect(width = size, height = size))
    this.unsupported = none
    this.reasons = 0
    this.device = device
    this.pipelines = pipelines
    this.tile = tile
    this.tile_size = size
    this.flushed = false
    this.atlas_generation = this.atlas.generation

## Whether the recording has drawn into its tile already (the rest then draws over it).
pub func display_list_player_gpu_flushed(this: const DisplayListPlayerGpu*) -> bool:
    return this.flushed

## Draws what is recorded into the tile now and starts the list again; the state, masks
## and atlas entries stay. A failure gives the tile up.
func gpu_flush(this: DisplayListPlayerGpu*):
    if ak.vector_is_empty(&this.draws):
        return
    # A layer still open cannot be drawn in parts.
    if this.state.layer != 0:
        gpu_give_up(this, GpuFallback.atlas_full)
        return
    let pipelines = this.pipelines else return
    let tile = this.tile else return
    gpu_replay_tile(this, pipelines, tile, this.tile_size, this.flushed) catch failure:
        gpu_give_up(this, GpuFallback.atlas_full)
        return
    this.flushed = true
    ak.vector_clear(&this.draws)
    ak.vector_clear(&this.rects)
    ak.vector_clear(&this.table)

## Places `coverage` in the atlas, first drawing what is recorded and making room when it
## does not fit (see atlas.lucb). None when it cannot be placed (the tile is given up).
func gpu_place(this: DisplayListPlayerGpu*, device: gpu.Device, key: u64?, coverage: const u8[], width: i32, height: i32, left: i32, top: i32, nine: GpuNine? = none) -> GpuAtlasEntry?:
    _ = this.atlas.texture_on(device) catch failure:
        gpu_give_up(this, GpuFallback.atlas_full)
        return none
    if not this.atlas.fits(width, height):
        gpu_flush(this)
        if this.unsupported != none:
            return none
        this.atlas.make_room(device) catch failure:
            gpu_give_up(this, GpuFallback.atlas_full)
            return none
        this.atlas_generation = this.atlas.generation
    let placed = this.atlas.place(device, key, coverage, width, height, left, top, nine) catch failure:
        gpu_give_up(this, GpuFallback.atlas_full)
        return none
    if placed == none:
        # Larger than the atlas.
        gpu_give_up(this, GpuFallback.atlas_full)
    return placed

## Gives the tile up to the CPU player for `reason` (the first reason decides; every one met
## is remembered for reports).
func gpu_give_up(this: DisplayListPlayerGpu*, reason: GpuFallback):
    this.reasons |= (u32)1 << (u32)reason
    if this.unsupported == none:
        this.unsupported = reason

## Whether recording goes on: nothing unsupported met, and the atlas still holds what the
## recorded draws read.
func gpu_recording(this: DisplayListPlayerGpu*) -> bool:
    if this.unsupported == none and this.atlas.generation != this.atlas_generation:
        this.unsupported = GpuFallback.atlas_full
    return this.unsupported == none

## Appends `draw` under the state's clip mask.
func gpu_append(this: DisplayListPlayerGpu*, draw: GpuDraw):
    var masked = draw
    masked.mask = this.state.mask
    ak.vector_append_t(&this.draws, masked)

## Opens a layer composited at `opacity` with `blend` (see GpuLayerJob): what is drawn until the
## restore that ends it goes into the layer, clipped by the scissor only (Skia clips a layer's
## contents to its bounds, the prior clip's, and applies the clip when it draws the layer back).
## `reason` gives the tile up past the depth limit.
func gpu_begin_layer(this: DisplayListPlayerGpu*, opacity: f32, blend: u32, reason: GpuFallback):
    if not gpu_recording(this):
        return
    var depth: u32 = 1
    if this.state.layer != 0:
        depth = ak.vector_at(&this.layers, (usize)this.state.layer - 1).depth + 1
    if depth > gpu_layer_depth:
        gpu_give_up(this, reason)
        return
    ak.vector_append_t(&this.layers, GpuLayerJob(opacity = opacity, blend = blend, outer = this.state, depth = depth))
    let index = ak.vector_size(&this.layers)
    ak.vector_append_t(&this.draws, GpuDraw(kind = GpuDrawKind.layer_begin, scissor = this.state.clip, first = index - 1))
    this.state.layer = (u32)index
    this.state.rounded = none
    this.state.mask = 0

## Ends the open layer: replay composites it into what it was saved over.
func gpu_end_layer(this: DisplayListPlayerGpu*):
    let index = (usize)this.state.layer - 1
    let job = ak.vector_at(&this.layers, index)
    ak.vector_append_t(&this.draws, GpuDraw(kind = GpuDrawKind.layer_end, scissor = job.outer.clip, first = index))

## Moves the analytic rounded clip into the clip mask (one more clip multiplied), leaving
## no analytic clip; reuses a mask of the same clips. False (the tile is given up) past the
## limits.
func gpu_push_mask(this: DisplayListPlayerGpu*) -> bool:
    let rounded = this.state.rounded else return true
    var job = GpuMaskJob()
    if this.state.mask != 0:
        job = *ak.vector_at(&this.masks, (usize)this.state.mask - 1)
    if job.count == gpu_mask_clips:
        gpu_give_up(this, GpuFallback.nested_rounded_clip)
        return false
    job.clips[job.count] = rounded
    job.count += 1
    this.state.rounded = none
    for index in 0..<ak.vector_size(&this.masks):
        let known = ak.vector_at(&this.masks, index)
        if gpu_same_mask(known, &job):
            this.state.mask = (u32)index + 1
            return true
    if ak.vector_size(&this.masks) == gpu_mask_limit:
        gpu_give_up(this, GpuFallback.nested_rounded_clip)
        return false
    ak.vector_append_t(&this.masks, job)
    this.state.mask = (u32)ak.vector_size(&this.masks)
    return true

## Whether two masks multiply the same clips.
func gpu_same_mask(a: const GpuMaskJob*, b: const GpuMaskJob*) -> bool:
    if a.count != b.count:
        return false
    for i in 0..<a.count:
        let x = a.clips[i]
        let y = b.clips[i]
        if x.mode != y.mode:
            return false
        for j in 0..<(usize)4:
            if x.rect[j] != y.rect[j]:
                return false
        for j in 0..<(usize)8:
            if x.radii[j] != y.radii[j]:
                return false
    return true

## The player behind the DisplayListPlayer the loop hands a virtual.
func gpu_player_of(base: display_list.DisplayListPlayer*) -> DisplayListPlayerGpu*:
    return (DisplayListPlayerGpu*)base

# mark: Recording shapes =========================================================================

## Straight color components of `color` in stored values (0..1).
func gpu_straight(color: gfx.Color) -> f32[4]:
    let v = color.m_value
    return [(f32)((v >> 16) & 0xff) / 255.0, (f32)((v >> 8) & 0xff) / 255.0, (f32)(v & 0xff) / 255.0, (f32)((v >> 24) & 0xff) / 255.0]

## `color` premultiplied, in stored values.
func gpu_premultiplied(color: gfx.Color) -> f32[4]:
    let rgba = gpu_straight(color)
    return [rgba[0] * rgba[3], rgba[1] * rgba[3], rgba[2] * rgba[3], rgba[3]]

## A solid whole-pixel rectangle: joins the last `rects` draw when it has the same scissor.
func gpu_solid_rect(this: DisplayListPlayerGpu*, rect: GpuRect, color: gfx.Color):
    if (color.m_value >> 24) == 0:
        return
    if this.state.mask != 0:
        gpu_fill_shape(this, rect, gpu_no_radii(), color, 0.0, false)
        return
    ak.vector_append_t(&this.rects, GpuRectRecord(rect = rect, color = gpu_straight(color)))
    let count = ak.vector_size(&this.draws)
    if count > 0:
        let last = ak.vector_at(&this.draws, count - 1)
        if last.kind == GpuDrawKind.rects and last.scissor == this.state.clip:
            last.count += 1
            return
    gpu_append(this, GpuDraw(kind = GpuDrawKind.rects, scissor = this.state.clip, first = ak.vector_size(&this.rects) - 1, count = 1))

## A draw of tile.frag's `kind` with the header of the state's clips: the rounded clip's
## rectangle, radii and mode, and whether the clip mask applies.
func gpu_shader_draw(this: const DisplayListPlayerGpu*, kind: GpuDrawKind, shader_kind: f32, area: GpuRect) -> GpuDraw:
    var draw = GpuDraw(kind = kind, scissor = this.state.clip, area = area)
    draw.uniforms[gpu_uniform_mask] = 1.0 if this.state.mask != 0 else 0.0
    draw.uniforms[gpu_uniform_kind] = shader_kind
    let clip = this.state.rounded else return draw
    for i in 0..<(usize)4:
        draw.uniforms[i] = clip.rect[i]
    for i in 0..<(usize)8:
        draw.uniforms[4 + i] = clip.radii[i]
    draw.uniforms[gpu_uniform_clip_mode] = clip.mode
    return draw

## A `fill` draw: `rect` with `radii`, filled (`stroke` 0) or stroked `stroke` pixels wide,
## anti-aliased unless `aliased`.
func gpu_fill_shape(this: DisplayListPlayerGpu*, rect: GpuRect, radii: f32[8], color: gfx.Color, stroke: f32, aliased: bool):
    if (color.m_value >> 24) == 0:
        return
    let reach = (i32)math32.ceil(stroke) + 1
    let area = GpuRect(x = rect.x - reach, y = rect.y - reach, width = rect.width + 2 * reach, height = rect.height + 2 * reach)
    if not area.intersects(this.state.clip):
        return
    var draw = gpu_shader_draw(this, GpuDrawKind.fill, gpu_kind_rrect, area)
    draw.straight = color.m_value
    draw.data[0] = (f32)rect.x
    draw.data[1] = (f32)rect.y
    draw.data[2] = (f32)rect.width
    draw.data[3] = (f32)rect.height
    for i in 0..<(usize)8:
        draw.data[4 + i] = radii[i]
    let rgba = gpu_premultiplied(color)
    for i in 0..<(usize)4:
        draw.uniforms[gpu_uniform_header + i] = rgba[i]
    draw.uniforms[gpu_uniform_header + 4] = stroke
    draw.uniforms[gpu_uniform_header + 5] = 1.0 if aliased else 0.0
    gpu_append(this, draw)

## No rounded corners.
func gpu_no_radii() -> f32[8]:
    return [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]

## CornerRadii fitted to `rect` as SkRRect::setRectRadii fits them (the CPU player's
## cpu_normalize_radii), in the shaders' order.
func gpu_normalized_radii(rect: GpuRect, corner_radii: const display_list.CornerRadii*) -> f32[8]:
    let bounds = raster.Rect.from_xywh((f32)rect.x, (f32)rect.y, (f32)rect.width, (f32)rect.height) else return gpu_no_radii()
    let r = display_list.cpu_normalize_radii(bounds, display_list.cpu_radii(corner_radii))
    return [r.x[0], r.y[0], r.x[1], r.y[1], r.x[2], r.y[2], r.x[3], r.y[3]]

## The same radius `radius` at every corner, fitted to `rect`.
func gpu_normalized_uniform_radii(rect: GpuRect, radius: f32) -> f32[8]:
    let bounds = raster.Rect.from_xywh((f32)rect.x, (f32)rect.y, (f32)rect.width, (f32)rect.height) else return gpu_no_radii()
    let r = display_list.cpu_normalize_radii(bounds, display_list.CpuRadii(x = [radius, radius, radius, radius], y = [radius, radius, radius, radius]))
    return [r.x[0], r.y[0], r.x[1], r.y[1], r.x[2], r.y[2], r.x[3], r.y[3]]