Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-render

Source of release 0.6.2

0.6.2 / src / gpu_player / compositor.lucb

#==============================================================================================
#
#   compositor - tiles kept across frames, drawn when missing, composited every frame
#
#   DESCRIPTION:
#       A GpuCompositor belongs to one view. Each frame it takes the display list and scroll
#       state the page presented and draws them onto a luce-gpu target:
#
#         1. a new display list is cut into layers (layers.lucb) and every tile is dropped
#            (their textures go back to a pool);
#         2. for each layer, the tiles of its plane that the viewport shows are found by key:
#            the layer's number, what its pixels depend on (gpu_layer_key) and the tile's place.
#            A tile not kept yet is drawn: recorded by the GPU player and replayed, or, when
#            the recording gives up, drawn by the CPU player and uploaded. A tile on which
#            nothing draws keeps no texture;
#         3. every visible tile is composited, layer by layer in paint order, moved by its
#            layer's scroll offset. Layers blend in the encoded space, as the CPU player
#            blends them into one surface: on a target that blends on encoded values (an
#            encoded surface, or an rgba8_linear texture) tiles go straight onto it; on
#            any other they go into a frame texture of the viewport's size, which is then
#            drawn onto the target decoded for its linear-light pixels
#            (shaders/composite.frag).
#
#       A scroll therefore moves tiles and draws only those it uncovers. Tiles not used for a
#       while are released past a budget; textures are reused through a small pool.
#
#       Copyright (c) 2026 the luce-browser authors.
#       SPDX-License-Identifier: BSD-2-Clause
#
#==============================================================================================

## Tiles kept (with textures) before the least recently used are released: 96 tiles of 1 MiB.
pub let gpu_tile_budget: usize = 96

## Textures kept for reuse when tiles are dropped.
let gpu_pool_limit: usize = 16

## One kept tile: its key, its place in its layer's plane, its texture (none when empty), and
## the frame it was last used in.
struct GpuTile:
    var key: u64
    var x: i32
    var y: i32
    var texture: gpu.Texture?
    var used: u64

## The GPU compositor of one view (see the header).
pub struct GpuCompositor:
    var device: gpu.Device?
    ## The pipelines (in memory.heap), which the player draws with too.
    var pipelines: GpuPipelines*?
    var atlas: GpuAtlas
    var images: GpuImageCache
    var player: DisplayListPlayerGpu*?
    ## The allocator the CPU player draws with (the caller's; see gpu_cpu_tile).
    var cpu_allocator: memory.Allocator?
    var pixels: u8[]
    var list: const display_list.DisplayList*?
    var layers: ak.Vector[GpuLayer]
    var tiles: ak.Vector[GpuTile]
    var keys: GpuIndexMap
    var pool: ak.Vector[gpu.Texture]
    var frame: u64
    ## The viewport's frame texture (see step 3), and its size.
    var frame_texture: gpu.Texture?
    var frame_width: i32
    var frame_height: i32

## A compositor with nothing drawn yet.
pub func gpu_compositor_create() -> GpuCompositor*:
    return (new GpuCompositor() in memory.heap) else trap("gpu_player: out of memory")

## Releases everything the compositor holds (main thread, as every GPU call).
pub func gpu_compositor_destroy(this: GpuCompositor*):
    with memory.heap:
        gpu_compositor_drop_device(this)
    if this.pixels.length > 0:
        free(this.pixels) in memory.heap
    free(this) in memory.heap

## Releases the tiles, caches and pipelines (and the device they were on).
func gpu_compositor_drop_device(this: GpuCompositor*):
    gpu_compositor_drop_tiles(this)
    if let texture = this.frame_texture:
        var handle = texture
        handle.destroy()
        this.frame_texture = none
    for texture in ak.vector_span(&this.pool):
        var handle = texture
        handle.destroy()
    ak.vector_clear(&this.pool)
    this.atlas.release()
    this.images.release()
    if let pipelines = this.pipelines:
        pipelines.release()
        free(pipelines) in memory.heap
        this.pipelines = none
    if let player = this.player:
        display_list_player_gpu_destroy(player)
        this.player = none
    if let device = this.device:
        var handle = device
        handle.destroy()
        this.device = none
    gpu_player_stats_the.resident_tiles = 0
    gpu_player_stats_the.resident_bytes = 0

## Drops every tile, keeping up to the pool's limit of their textures.
func gpu_compositor_drop_tiles(this: GpuCompositor*):
    for tile in ak.vector_span(&this.tiles):
        if let texture = tile.texture:
            gpu_compositor_recycle(this, texture)
    ak.vector_clear(&this.tiles)
    this.keys.clear()
    gpu_player_stats_the.resident_tiles = 0

## Gives a tile's texture back: to the pool, or released when the pool is full.
func gpu_compositor_recycle(this: GpuCompositor*, texture: gpu.Texture):
    if ak.vector_size(&this.pool) < gpu_pool_limit:
        ak.vector_append_t(&this.pool, texture)
        return
    var handle = texture
    handle.destroy()

## A tile texture: from the pool, or new.
func gpu_compositor_texture(this: GpuCompositor*, device: gpu.Device) -> gpu.Texture!:
    if not ak.vector_is_empty(&this.pool):
        return ak.vector_take_last(&this.pool)
    return try gpu.Texture.create(device, (u32)gpu_tile_size, (u32)gpu_tile_size, gpu.Format.rgba8_linear)

## Opens what drawing needs on `target`'s device the first time (or after a device change).
func gpu_compositor_open(this: GpuCompositor*, target: const gpu.RenderTarget*) -> gpu.Device!:
    var device = try gpu.device_of(target)
    if let current = this.device:
        if current.same(&device):
            device.destroy()
            return current
        gpu_compositor_drop_device(this)
        this.list = none
    this.device = device
    let made = try gpu_pipelines_create(device)
    let stored = try new GpuPipelines() in memory.heap
    *stored = made
    this.pipelines = stored
    this.player = display_list_player_gpu_create(&this.atlas, &this.images)
    if this.pixels.length == 0:
        this.pixels = try new u8[(usize)(gpu_tile_size * gpu_tile_size * 4)] --- in memory.heap
    return device

# mark: Drawing a frame ==========================================================================

## Draws `list` at `snapshot`'s scroll offsets onto `target`, the page's device pixel (0, 0) at
## the target's top left, one device pixel a backing pixel of the target, covering `width` by
## `height` device pixels.
## Everything the compositor keeps is in the process heap (an engine's collected heap would not
## see the compositor's pointers into it); tiles the CPU player draws are drawn with
## `cpu_allocator`, the heap the engine's painting uses (the process heap when none).
pub func gpu_compositor_draw(this: GpuCompositor*, list: display_list.DisplayList*, snapshot: const display_list.ScrollStateSnapshot*, target: const gpu.RenderTarget*,
                             width: i32, height: i32, cpu_allocator: memory.Allocator? = none) -> !:
    if width <= 0 or height <= 0:
        return
    this.cpu_allocator = cpu_allocator
    # The frame's CPU player and tile surface, here where the engine's collector sees them.
    var scratch = GpuCpuScratch()
    with memory.heap:
        try gpu_compositor_draw_frame(this, &scratch, list, snapshot, target, width, height)

## gpu_compositor_draw's work, in the process heap.
func gpu_compositor_draw_frame(this: GpuCompositor*, scratch: GpuCpuScratch*, list: display_list.DisplayList*, snapshot: const display_list.ScrollStateSnapshot*, target: const gpu.RenderTarget*,
                               width: i32, height: i32) -> !:
    let extent = try target.size()
    let scale = extent.pixel_width / extent.width if extent.width > 0.0 else 1.0
    let device = try gpu_compositor_open(this, target)
    let target_format = try target.pixel_format()
    let direct = target_format == gpu.Format.rgba8_linear or (try target.blending()) == gpu.Blending.encoded
    let pipelines = this.pipelines else trap("gpu_player: no pipelines")
    let copy = try pipelines.composite_for(device, gpu.Format.rgba8_linear)
    let present = try pipelines.composite_for(device, target_format)
    if this.list != list:
        gpu_compositor_drop_tiles(this)
        ak.vector_clear(&this.layers)
        this.layers = gpu_layers_of(list)
        this.list = list
    this.frame += 1
    this.images.frame = this.frame
    let viewport = GpuRect(width = width, height = height)
    if direct:
        # Tiles straight onto the target, kept to the viewport, at the target's pixels.
        if let texture = this.frame_texture:
            var handle = texture
            handle.destroy()
            this.frame_texture = none
            this.frame_width = 0
            this.frame_height = 0
        let placement = try target.placement()
        let page = try target.clipped(gpu.Rect(0.0, 0.0, (f64)width / scale, (f64)height / scale))
        defer page.release()
        let origin = gfx.IntPoint(m_x = (i32)(placement.x * scale), m_y = (i32)(placement.y * scale))
        for layer_index in 0..<ak.vector_size(&this.layers):
            let layer = *ak.vector_at(&this.layers, layer_index)
            try gpu_compositor_layer(this, scratch, device, list, snapshot, &layer, layer_index, viewport, page.value(), present, origin, scale)
        gpu_compositor_evict(this)
        return
    let frame_texture = try gpu_compositor_frame_texture(this, device, width, height)
    let frame = try frame_texture.frame()
    defer frame.release()
    let canvas = try frame.value().target()
    defer canvas.release()
    for layer_index in 0..<ak.vector_size(&this.layers):
        let layer = *ak.vector_at(&this.layers, layer_index)
        try gpu_compositor_layer(this, scratch, device, list, snapshot, &layer, layer_index, viewport, canvas.value(), copy, gfx.IntPoint(), 1.0)
    _ = try frame.value().present(gpu.Color(0.0, 0.0, 0.0, 0.0))
    # The frame onto the target, decoded.
    let placement = try target.placement()
    var params = gpu_composite_uniforms((f32)(placement.x * scale), (f32)(placement.y * scale), true)
    try gpu.shade(target, present, gpu.Rect(0.0, 0.0, (f64)width / scale, (f64)height / scale), u8[]((u8*)&params[0], 12), [frame_texture], gpu.Filter.nearest)
    gpu_compositor_evict(this)

## The frame texture for a viewport of `width` by `height` pixels, made again when it changes.
func gpu_compositor_frame_texture(this: GpuCompositor*, device: gpu.Device, width: i32, height: i32) -> gpu.Texture!:
    if let texture = this.frame_texture:
        if this.frame_width == width and this.frame_height == height:
            return texture
        var handle = texture
        handle.destroy()
        this.frame_texture = none
    let texture = try gpu.Texture.create(device, (u32)width, (u32)height, gpu.Format.rgba8_linear)
    this.frame_texture = texture
    this.frame_width = width
    this.frame_height = height
    return texture

## Draws the tiles `layer` shows in `viewport` (drawing those not kept) into `canvas` with the
## `copy` pipeline: the frame texture's target, or the target itself, whose backing pixels
## start at `origin` and are `scale` to a point.
func gpu_compositor_layer(this: GpuCompositor*, scratch: GpuCpuScratch*, device: gpu.Device, list: display_list.DisplayList*, snapshot: const display_list.ScrollStateSnapshot*, layer: const GpuLayer*,
                          layer_index: usize, viewport: GpuRect, canvas: const gpu.RenderTarget*, copy: gpu.Pipeline, origin: gfx.IntPoint, scale: f64) -> !:
    let offset = gpu_layer_offset(layer, snapshot)
    let key = gpu_hash(gpu_layer_key(layer, snapshot), (u64)layer_index)
    var plane = gpu_layer_snapshot(layer, snapshot)
    defer ak.vector_clear(&plane.m_device_offsets)
    # The part of the layer's plane the viewport shows.
    let visible = viewport.translated(-offset.m_x, -offset.m_y)
    let first_column = gpu_floor_div(visible.x, gpu_tile_size)
    let first_row = gpu_floor_div(visible.y, gpu_tile_size)
    let last_column = gpu_floor_div(visible.x + visible.width - 1, gpu_tile_size)
    let last_row = gpu_floor_div(visible.y + visible.height - 1, gpu_tile_size)
    let side = (f64)gpu_tile_size / scale
    for row in first_row..<last_row + 1:
        for column in first_column..<last_column + 1:
            let tile = try gpu_compositor_tile(this, scratch, device, list, &plane, layer, key, column * gpu_tile_size, row * gpu_tile_size)
            let texture = tile.texture else continue
            let x = tile.x + offset.m_x
            let y = tile.y + offset.m_y
            var params = gpu_composite_uniforms((f32)(x + origin.m_x), (f32)(y + origin.m_y), false)
            try gpu.shade(canvas, copy, gpu.Rect((f64)x / scale, (f64)y / scale, side, side), u8[]((u8*)&params[0], 12), [texture], gpu.Filter.nearest)
            gpu_player_stats_the.composited_tiles += 1

## The tile of `layer` at (`x`, `y`) in its plane for `key`: kept, or drawn now.
func gpu_compositor_tile(this: GpuCompositor*, scratch: GpuCpuScratch*, device: gpu.Device, list: display_list.DisplayList*, plane: const display_list.ScrollStateSnapshot*, layer: const GpuLayer*,
                         key: u64, x: i32, y: i32) -> GpuTile!:
    let tile_key = gpu_hash(gpu_hash(key, (u64)(u32)x), (u64)(u32)y)
    if let index = this.keys.get(tile_key):
        let kept = ak.vector_at(&this.tiles, (usize)index)
        kept.used = this.frame
        return *kept
    var tile = GpuTile(key = tile_key, x = x, y = y, used = this.frame)
    let player = this.player else trap("gpu_player: no player")
    # The recording may draw into the tile before it ends (when the atlas makes room).
    let texture = try gpu_compositor_texture(this, device)
    display_list_player_gpu_begin(player, device, this.pipelines else trap("gpu_player: no pipelines"), texture, gpu_tile_size)
    display_list.display_list_player_execute_tile((display_list.DisplayListPlayer*)player, list, plane, none, layer.first, layer.end, gfx.IntPoint(m_x = x, m_y = y))
    if let reason = player.fallback():
        gpu_player_stats_the.fallbacks[(usize)reason] += 1
        let met = player.fallback_reasons()
        for kind in 0..<gpu_fallback_count:
            if (met >> (u32)kind) & 1 != 0:
                gpu_player_stats_the.reasons[kind] += 1
        gpu_player_stats_the.cpu_tiles += 1
        tile.texture = texture
        let origin = gfx.IntPoint(m_x = x, m_y = y)
        if let allocator = this.cpu_allocator:
            with allocator:
                try gpu_cpu_tile(scratch, list, plane, layer, origin, texture, this.pixels)
        else:
            try gpu_cpu_tile(scratch, list, plane, layer, origin, texture, this.pixels)
    elif player.is_empty() and not display_list_player_gpu_flushed(player):
        gpu_player_stats_the.empty_tiles += 1
        gpu_compositor_recycle(this, texture)
    else:
        gpu_player_stats_the.gpu_tiles += 1
        tile.texture = texture
        if not player.is_empty():
            let pipelines = this.pipelines else trap("gpu_player: no pipelines")
            try gpu_replay_tile(player, pipelines, texture, gpu_tile_size, display_list_player_gpu_flushed(player))
    this.keys.put(tile_key, (u32)ak.vector_size(&this.tiles))
    ak.vector_append_t(&this.tiles, tile)
    return tile

## Releases the least recently used tiles past the budget (never this frame's: a page whose
## frame needs more keeps them), and forgets empty tiles not used for a while.
func gpu_compositor_evict(this: GpuCompositor*):
    # When the older tiles were last used, newest first.
    var stamps: ak.Vector[u64]
    defer ak.vector_clear(&stamps)
    var resident: usize = 0
    var stale = false
    for tile in ak.vector_span_const(&this.tiles):
        if tile.texture != none:
            resident += 1
            if tile.used < this.frame:
                ak.vector_append_t(&stamps, tile.used)
        elif this.frame - tile.used > 64:
            stale = true
    let older = ak.vector_span(&stamps)
    let current = resident - older.length
    let allowed = gpu_tile_budget - current if gpu_tile_budget > current else 0
    if older.length <= allowed and not stale:
        gpu_compositor_note_memory(this, resident)
        return
    for i in 1..<older.length:
        let value = older[i]
        var j = i
        while j > 0 and older[j - 1] < value:
            older[j] = older[j - 1]
            j -= 1
        older[j] = value
    # Tiles last used at or before `cutoff` go (none when the budget holds them all).
    let cutoff: u64 = older[allowed] if allowed < older.length else 0
    let dropping = allowed < older.length
    var kept: ak.Vector[GpuTile]
    resident = 0
    for tile in ak.vector_span_const(&this.tiles):
        if let texture = tile.texture:
            if dropping and tile.used <= cutoff:
                gpu_compositor_recycle(this, texture)
                continue
            resident += 1
        elif this.frame - tile.used > 64:
            continue
        ak.vector_append_t(&kept, tile)
    ak.vector_clear(&this.tiles)
    this.tiles = kept
    this.keys.clear()
    for index in 0..<ak.vector_size(&this.tiles):
        this.keys.put(ak.vector_at(&this.tiles, index).key, (u32)index)
    gpu_compositor_note_memory(this, resident)

## Counts the GPU memory held: resident tiles, pooled textures, images, the atlas and the frame.
func gpu_compositor_note_memory(this: const GpuCompositor*, resident: usize):
    let tile_bytes = (u64)(gpu_tile_size * gpu_tile_size * 4)
    gpu_player_stats_the.resident_tiles = (u64)resident
    let tiles = (u64)(resident + ak.vector_size(&this.pool)) * tile_bytes
    let frame = (u64)this.frame_width * (u64)this.frame_height * 4
    gpu_player_stats_the.resident_bytes = tiles + this.images.resident_bytes() + (u64)(this.atlas.size * this.atlas.size) + frame

## `a` divided by `b` (positive), rounded down.
func gpu_floor_div(a: i32, b: i32) -> i32:
    return a // b if a >= 0 else -((-a + b - 1) // b)