dymokomi/luce-image
Source of release 0.45.0
0.45.0 / 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)