Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-image

Source of release 0.45.1

0.45.1 / src / canvas / memory.lucb

#==============================================================================================
#
#   canvas/memory - Keeping the documents' tiles within the machine's memory
#
#   DESCRIPTION:
#       luce-canvas's governor keeps every tile on the GPU, in RAM, or both, within budgets
#       (a share of the GPU's and the machine's memory; Settings › Memory usage). The
#       canvas budgets it when it binds its device, and settles it as each frame begins:
#       what the frame before drew stays recent, what no document shows (history's tiles)
#       leaves the GPU first, then what no recent frame drew. Nothing is ever dropped:
#       a tile moved to RAM comes back when drawn with, undone to, or read.
#
#==============================================================================================

extend Canvas:
    ## Let the documents' tiles use `fraction` (0.1..0.95) of the GPU's and the
    ## machine's memory, as Photoshop's Memory Usage: past it, the least wanted
    ## tiles move from the GPU to RAM. One setting for every document.
    pub func set_memory_usage(fraction: f64) -> !:
        if not (fraction >= 0.1 and fraction <= 0.95):
            error(invalid, "memory usage must be 0.1..0.95 of what the machine has")
        memory_usage = fraction
        forced = false
        if let device = self.device:
            try configure_memory(device)

    ## Keep tiles spilled past the RAM budget in `directory` (which must
    ## exist); "" for the default, a disk-backed cache. Like Photoshop's
    ## scratch disk; it applies before the first spill.
    pub static func set_scratch_folder(directory: str) -> !:
        try set_scratch_directory(directory)

    ## Frames never wait for tiles to come back from compressed copies, the
    ## scratch file or the document file: a cell lacking some draws from a
    ## coarser level kept, while they decode in the background, and `busy`
    ## says to draw again. Off by default (a frame shows everything at once).
    pub static func set_progressive_loading(on: bool):
        progressive_loading = on

    ## Compress tiles past the RAM budget in RAM before they go to the scratch
    ## file (off by default; see canvas/memory): for a slow or small scratch disk.
    pub static func set_compressed_tier(on: bool):
        compressed_tier = on
        apply_compressed_tier()

    ## On quitting, once every document is closed: the scratch file closes and
    ## its folder goes (on Windows the folder would otherwise stay behind).
    pub static func release_scratch_file():
        release_scratch()

    ## Set the GPU and RAM budgets in bytes directly (0 for none): tests, and
    ## seeing the governor work on a small machine.
    pub func set_memory_budgets(gpu_bytes: i64, ram_bytes: i64) -> !:
        if gpu_bytes < 0 or ram_bytes < 0:
            error(invalid, "memory budgets are bytes, 0 for none")
        force_memory_budgets((usize)gpu_bytes, (usize)ram_bytes)

    ## Begin a new epoch and keep the tiers within their budgets now, as a
    ## frame does: for headless work between steps.
    pub func settle_memory() -> !:
        residency_advance()
        try settle_tiers(&self)

    ## Bytes of layer tiles on the GPU, their copies in RAM, derived tiles
    ## (pyramids and composites) on the GPU, and the two budgets.
    pub func memory_gpu_bytes() -> i64:
        return (i64)residency_report().gpu_tiles

    pub func memory_ram_bytes() -> i64:
        return (i64)residency_report().ram_tiles

    ## What the system says the process holds (macOS footprint, Windows private
    ## bytes, Linux resident pages), which the RAM budget also holds to; 0 where
    ## it cannot tell.
    pub func memory_process_bytes() -> i64:
        return (i64)residency_report().process

    pub func memory_derived_bytes() -> i64:
        return (i64)residency_report().derived

    pub func memory_gpu_budget() -> i64:
        return (i64)residency_report().gpu_budget

    pub func memory_ram_budget() -> i64:
        return (i64)residency_report().ram_budget

    ## Tiles moved so far: uploads back to the GPU (promotions), moves to RAM
    ## (demotions) and one-pass uploads for derived tiles (transient uploads).
    pub func memory_promotions() -> i64:
        return (i64)residency_report().promotions

    pub func memory_demotions() -> i64:
        return (i64)residency_report().demotions

    pub func memory_transient_uploads() -> i64:
        return (i64)residency_report().transient_uploads

    ## Bytes of tiles in the scratch file, and tiles moved out to it and back.
    pub func memory_disk_bytes() -> i64:
        return (i64)residency_report().disk_tiles

    pub func memory_spills() -> i64:
        return (i64)residency_report().spills

    ## Bytes of tiles held compressed in RAM, and tiles compressed so far.
    pub func memory_packed_bytes() -> i64:
        return (i64)residency_report().packed_tiles

    pub func memory_packs() -> i64:
        return (i64)residency_report().packs

    pub func memory_loads() -> i64:
        return (i64)residency_report().loads

## The share of the GPU's and the machine's memory tiles may use: Settings ›
## Memory usage, one setting for every open document.
var memory_usage: f64 = 0.6

## Budgets set in bytes (`Canvas.set_memory_budgets`), which a later bind
## keeps rather than replacing with the memory usage's; zero for none set.
var forced_gpu: usize = 0
var forced_ram: usize = 0
var forced: bool = false

## Budget the governor for `device` at the current memory usage, or at the
## budgets set in bytes.
func configure_memory(device: gpu.Device) -> !:
    try residency_configure(device, memory_usage)
    apply_compressed_tier()
    if forced:
        residency_budgets(forced_gpu, forced_ram)

## Whether tiles past the RAM budget are compressed before they go to disk
## (`Canvas.set_compressed_tier`). Off: with the .l2d codec, compressing makes
## the scratch file about 4.5 times smaller but, on a fast SSD, a document
## built past its budget takes 2.7 times as long (deflate costs more than the
## write it saves) and a cold pan 1.5 times as long. It pays on a slow or
## nearly full scratch disk.
var compressed_tier: bool = false

## Register the .l2d document's tile codec with the governor, or none.
func apply_compressed_tier():
    if compressed_tier:
        residency_codec(none, encode_tile_record, decode_record, flate.deflate_bound((usize)tile_size * tile_row_bytes))
    else:
        clear_residency_codec()

## `Canvas.set_memory_budgets`: bytes, kept across binds.
func force_memory_budgets(gpu_bytes: usize, ram_bytes: usize):
    forced = true
    forced_gpu = gpu_bytes
    forced_ram = ram_bytes
    residency_budgets(gpu_bytes, ram_bytes)

## A draw into frame `serial`: whether it is the first into a new frame, which
## begins the frame's epoch. That draw settles the tiers once it has drawn
## (`settle_tiers`), so what it drew with (a new layer's tiles, making its
## levels) stays on the GPU for it; later draws into the same frame (the
## Navigator after the view) keep what the first pinned.
func begin_frame(serial: u64) -> bool:
    return residency_frame(serial)

## A step of a job that runs outside frames (an export's band, a saved layer):
## what it has finished with may leave, so the tiers stay within their budgets
## while it runs and after it ends, not only at the next frame (an idle
## application draws none). Cheap within budget.
func settle_job(canvas: Canvas*) -> !:
    if not residency_over_budget():
        return
    residency_advance()
    try settle_tiers(canvas)

## `settle_job` while `loading` (a layer's tiles coming from a file, not yet
## in the document) is filled: it counts as shown, so its tiles do not leave
## first as history's would.
func settle_loading(canvas: Canvas*, loading: const Tiles*) -> !:
    if not residency_over_budget():
        return
    let device = canvas.device else return
    let document = canvas.document else return
    residency_advance()
    residency_begin_marking()
    for layer in document.layers():
        mark_layer(layer)
    residency_mark_live(loading)
    try residency_settle(device)

## When the tiers hold too much, mark what every layer and mask of the
## document shows and move the least wanted tiles down a tier. Cheap within
## budget: one comparison.
func settle_tiers(canvas: Canvas*) -> !:
    if not residency_over_budget():
        return
    let device = canvas.device else return
    let document = canvas.document else return
    residency_begin_marking()
    for layer in document.layers():
        mark_layer(layer)
    try residency_settle(device)

func mark_layer(layer: Layer*):
    if let tiles = layer.tiles():
        residency_mark_live(tiles)
    if let mask = layer.mask_tiles():
        residency_mark_live(mask)
    for child in layer.layers():
        mark_layer(child)