Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-canvas

Source of release 0.5.1

0.5.1 / src / tiles / residency.lucb

#==============================================================================================
#
#   tiles/residency - Where a tile's bytes are: the GPU, RAM, or both
#
#   DESCRIPTION:
#       A tile's content never changes, so any copy of it stays good for as long as the tile
#       lives. A tile is on the GPU (G), in RAM (R, the texture's 256 rows of half floats),
#       or both (G+R). Dropping a copy is free while the other one exists; moving the last
#       copy costs one transfer: G to R a readback, R to G an upload.
#
#       `resident` is the one way to a tile's texture: it pins the tile for the current
#       epoch (tiles/governor) and brings a RAM-only tile back to the GPU. `tile_texture`
#       is the one way to a new tile-sized texture: when the device is out of memory it has
#       the governor move unpinned tiles to RAM and tries again, so running out of GPU
#       memory costs speed rather than an error. `demote` moves tiles to RAM a batch of
#       readbacks at a time. Every tile is in one list, which the governor walks.
#
#       Making a derived tile (a pyramid level, a composite) needs its sources on the GPU for
#       one pass only. `pass_texture` gives a RAM-only tile a transient upload for that pass
#       and leaves the tile in RAM; the maker releases its transients (`release_transients`,
#       back to the mark it took) once the pass is submitted. So a view at fit, or an export,
#       of a document mostly in RAM costs uploads, never a document's worth of GPU memory.
#
#==============================================================================================

## Bytes of one tile's content, on the GPU or in RAM: 256 by 256 half-float RGBA.
pub let tile_bytes: usize = 524288

## The first and last tile made and not yet freed.
var first_tile: Tile*? = none
var last_tile: Tile*? = none

## A new tile holding `texture` (taken over), on the GPU, held once.
func make_tile(texture: gpu.Texture) -> Tile*!:
    var no_ram: u8[]
    var no_packed: u8[]
    let tile = try new Tile(texture = texture, on_gpu = true, ram = no_ram, references = 1, stamp = next_stamp(), used = residency_epoch, live = 0,
                            disk = -1, disk_length = 0, packed = no_packed, raw_only = false, loading = false, source = none, source_offset = 0, source_length = 0, source_rows = 0, previous = last_tile, next = none) in memory.heap
    if let last = last_tile:
        last.next = tile
    else:
        first_tile = tile
    last_tile = tile
    live_tiles += 1
    gpu_tile_bytes += tile_bytes
    return tile

## Free what a tile holds in every tier and take it out of the list; its last
## holder has let go.
func forget_tile(tile: Tile*):
    drop_gpu_copy(tile)
    drop_ram_copy(tile)
    drop_packed(tile)
    release_disk(tile)
    release_backing(tile)
    if let previous = tile.previous:
        previous.next = tile.next
    else:
        first_tile = tile.next
    if let next = tile.next:
        next.previous = tile.previous
    else:
        last_tile = tile.previous

func drop_gpu_copy(tile: Tile*):
    if not tile.on_gpu:
        return
    # Work still in flight keeps the texture alive; the backends defer the free.
    tile.texture.destroy()
    tile.texture = gpu.Texture()
    tile.on_gpu = false
    gpu_tile_bytes -= tile_bytes

func drop_ram_copy(tile: Tile*):
    if tile.ram.length == 0:
        return
    free(tile.ram) in memory.heap
    var no_ram: u8[]
    tile.ram = no_ram
    ram_tile_bytes -= tile_bytes

## Uploads made for one pass, destroyed when their maker releases them.
struct Transients:
    var textures: gpu.Texture[]
    var count: usize

var transient_store: Transients*? = none

## A texture for one pass over `tile`: its own when on the GPU (pinned as
## `resident` pins it), else a transient upload of its RAM copy, the tile
## itself staying in RAM.
func pass_texture(tile: Tile*, device: gpu.Device) -> gpu.Texture!:
    if tile.on_gpu:
        tile.used = residency_epoch
        return tile.texture
    try ensure_ram(tile)
    var texture = try tile_texture(device)
    errdefer texture.destroy()
    try texture.upload(tile.ram)
    try keep_transient(texture)
    residency_transient_uploads += 1
    return texture

func keep_transient(texture: gpu.Texture) -> !:
    if transient_store == none:
        transient_store = try new Transients(textures = try new gpu.Texture[64] --- in memory.heap, count = 0) in memory.heap
    let store = transient_store else trap("made")
    if store.count == store.textures.length:
        let grown = try new gpu.Texture[store.textures.length * 2] --- in memory.heap
        memory.copy(grown, store.textures, store.count)
        free(store.textures) in memory.heap
        store.textures = grown
    store.textures[store.count] = texture
    store.count += 1

## Where the transient list stands now: what a maker releases back to.
pub func transient_mark() -> usize:
    let store = transient_store else return 0
    return store.count

## Destroy the transient uploads made since `mark`: the passes using them
## have been submitted (work in flight keeps them alive until it completes).
pub func release_transients(mark: usize):
    let store = transient_store else return
    while store.count > mark:
        store.count -= 1
        store.textures[store.count].destroy()

## The tile's texture on `device`, pinned for the current epoch; a tile kept
## only in RAM is uploaded again first (its RAM copy stays, so evicting it
## once more is free).
func resident(tile: Tile*, device: gpu.Device) -> gpu.Texture!:
    tile.used = residency_epoch
    if tile.on_gpu:
        return tile.texture
    try ensure_ram(tile)
    var texture = try tile_texture(device)
    errdefer texture.destroy()
    try texture.upload(tile.ram)
    tile.texture = texture
    tile.on_gpu = true
    gpu_tile_bytes += tile_bytes
    residency_promotions += 1
    return texture

## A new 256 by 256 rgba16_float texture on `device`, its content undefined.
## When the device is out of memory, the governor moves unpinned tiles to RAM
## (and trims derived caches) and it tries again; only when nothing is left to
## move does it fail, with `gpu.out_of_memory`.
pub func tile_texture(device: gpu.Device) -> gpu.Texture!:
    var attempts: usize = 0
    while attempts < 8:
        attempts += 1
        if let texture = try try_tile_texture(device):
            return texture
        if (try relieve(device, tile_bytes * 64)) == 0:
            break
    error(gpu.out_of_memory, "the GPU has no memory left for a tile, and nothing more can move to RAM")

## A new tile texture, or none when the device is out of memory.
func try_tile_texture(device: gpu.Device) -> gpu.Texture?!:
    if residency_failures > 0:
        # A test's simulated shortage.
        residency_failures -= 1
        return none
    let texture = gpu.Texture.create(device, tile_size, tile_size, gpu.Format.rgba16_float) catch failure:
        if failure.code == gpu.out_of_memory:
            return none
        error(failure.code, failure.message)
    return texture

## Keep `bytes` (a whole tile read back from the GPU anyway) as the tile's RAM
## copy too, while the governor has room for it.
func keep_warm(tile: Tile*, bytes: const u8[]):
    if tile.ram.length > 0 or bytes.length != tile_bytes or not warm_room():
        return
    let copy = new u8[tile_bytes] --- in memory.heap catch failure:
        _ = failure
        return
    memory.copy(copy, bytes, tile_bytes)
    tile.ram = copy
    ram_tile_bytes += tile_bytes

## Move `tiles` (on the GPU, unpinned) to RAM: those with a RAM copy just drop
## their texture; the rest are read back a batch at a time first. A tile whose
## RAM copy cannot be allocated stays on the GPU. How many bytes of GPU memory
## were freed.
func demote(device: gpu.Device, tiles: Tile*[]) -> usize!:
    var freed: usize = 0
    var batch = try gpu.ReadBatch.begin(device)
    defer batch.finish()
    let per_batch = batch.capacity() // tile_bytes
    if per_batch == 0:
        error(invalid, "a read batch cannot hold one tile")
    let offsets = try new usize[per_batch] --- in memory.heap
    defer free(offsets) in memory.heap
    let waiting = try new Tile*[per_batch] --- in memory.heap
    defer free(waiting) in memory.heap
    var at: usize = 0
    while at < tiles.length:
        try batch.reset()
        var count: usize = 0
        while at < tiles.length and count < per_batch:
            let tile = tiles[at]
            at += 1
            if not tile.on_gpu or tile.used == residency_epoch:
                continue
            # A copy in RAM (whole or compressed), in a slot or in the document file:
            # nothing to read back.
            if tile.ram.length > 0 or tile.packed.length > 0 or tile.disk >= 0 or backed(tile):
                drop_gpu_copy(tile)
                residency_demotions += 1
                freed += tile_bytes
                continue
            let offset = (try batch.reserve(tile_bytes)) else break
            try batch.copy(tile.texture, gpu.Region(0, 0, tile_size, tile_size), offset)
            offsets[count] = offset
            waiting[count] = tile
            count += 1
        if count == 0:
            continue
        try batch.submit()
        try batch.wait()
        for index in 0..<count:
            let tile = waiting[index]
            let copy = new u8[tile_bytes] --- in memory.heap catch failure:
                _ = failure
                continue
            memory.copy(copy, try batch.bytes(offsets[index], tile_bytes), tile_bytes)
            tile.ram = copy
            ram_tile_bytes += tile_bytes
            drop_gpu_copy(tile)
            residency_demotions += 1
            freed += tile_bytes
    return freed