Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-canvas

Source of release 0.5.1

0.5.1 / src / tiles / compressed.lucb

#==============================================================================================
#
#   tiles/compressed - The compressed tier: tiles past the RAM budget, packed in RAM
#
#   DESCRIPTION:
#       Before a tile past the RAM budget goes to the scratch file, it is compressed in RAM
#       by the application's tile codec (for luce-image the .l2d document's: each sample's
#       difference from its left neighbour, then deflate), which keeps a photograph at about a
#       fifth of its size and a gradient or flat art at a twentieth. Only when the compressed
#       tiles too outgrow the budget do they go to disk, as their compressed bytes (tiles/
#       scratch). A tile that does not compress to three quarters of its size is marked and
#       goes to disk whole. Compressing and decoding run across the processors, a batch of
#       tiles at a time. The compressed copy stays when a tile comes back, so moving it out
#       again is free; drawing into a tile in place drops it. The tier exists only while the
#       application sets a codec (`residency_codec`): on a fast SSD deflate costs more than
#       the writes it saves, so it is for slow or small scratch disks.
#
#==============================================================================================

## Compress a whole tile's rgba16f bytes (`texels`) into `into` (at least the
## codec's bound); how many bytes it took. Runs on worker threads.
pub type TileEncode = func(void*?, const u8[], u8[]) -> usize!

## The application's tile codec; without one there is no compressed tier.
var codec_context: void*? = none
var codec_encode: TileEncode? = none
var codec_decode: TileDecode? = none
var codec_bound: usize = 0

## Bytes of compressed tiles held in RAM, and tiles compressed so far.
var packed_tile_bytes: usize = 0
var residency_packs: u64 = 0

## Compress tiles past the RAM budget with `encode` (into at most `bound`
## bytes) and bring them back with `decode`, both given `context`.
pub func residency_codec(context: void*?, encode: TileEncode, decode: TileDecode, bound: usize):
    codec_context = context
    codec_encode = encode
    codec_decode = decode
    codec_bound = bound

## No compressed tier: tiles past the RAM budget go to disk whole. Tiles held
## compressed now stay so until they come back.
pub func clear_residency_codec():
    codec_encode = none
    codec_bound = 0

## Whether a codec is set.
func has_codec() -> bool:
    return codec_encode != none

## Free `tile`'s compressed copy.
func drop_packed(tile: Tile*):
    if tile.packed.length == 0:
        return
    packed_tile_bytes -= tile.packed.length
    free(tile.packed) in memory.heap
    var no_packed: u8[]
    tile.packed = no_packed

## Decode `tile`'s compressed copy into RAM; the compressed copy stays.
func unpack(tile: Tile*) -> !:
    let decode = codec_decode else error(invalid, "a compressed tile came back without a codec")
    let copy = try new u8[tile_bytes] --- in memory.heap
    errdefer free(copy) in memory.heap
    memory.set(copy, 0)
    try decode(codec_context, tile.packed, tile_size, copy)
    tile.ram = copy
    ram_tile_bytes += tile_bytes
    residency_loads += 1

## One tile compressed, or decoded, on a worker.
struct PackJob:
    var tile: Tile*
    var bytes: u8[]
    var length: usize
    var failed: bool

struct PackShare:
    var jobs: PackJob[]
    var decoding: bool

func pack_entry(context: void*?, index: usize):
    let shares = (PackShare*)(context else return)
    run_pack_jobs(&shares[index])

func run_pack_jobs(share: PackShare*):
    for index in 0..<share.jobs.length:
        let job = &share.jobs[index]
        if share.decoding:
            let decode = codec_decode else return
            decode(codec_context, job.tile.packed, tile_size, job.bytes) catch failure:
                _ = failure
                job.failed = true
            continue
        let encode = codec_encode else return
        job.length = encode(codec_context, job.tile.ram, job.bytes) catch failure:
            _ = failure
            job.failed = true
            recover 0

## `jobs` on up to 16 threads, this one included.
func spread_pack(jobs: PackJob[], decoding: bool) -> !:
    let workers = min_usize(16, min_usize(jobs.length, max_usize(1, (usize)os.cpus())))
    if workers == 0:
        return
    var shares: PackShare[16] = ---
    let per = (jobs.length + workers - 1) // workers
    for index in 0..<workers:
        let first = min_usize(jobs.length, index * per)
        shares[index] = PackShare(jobs = jobs[first..<min_usize(jobs.length, first + per)], decoding = decoding)
    pool.run(workers, pack_entry, (void*)&shares[0])

## Compress `tiles` (RAM copies, not yet compressed) across the processors;
## each that compresses to three quarters of its size or less keeps only its
## compressed copy, the rest are marked to go to disk whole. RAM freed.
func pack_many(tiles: Tile*[]) -> usize!:
    if tiles.length == 0 or not has_codec():
        return 0
    let jobs = try pack_jobs(tiles)
    defer release_pack_jobs(jobs)
    for index in 0..<jobs.length:
        jobs[index].bytes = try new u8[codec_bound] --- in memory.heap
    try spread_pack(jobs, false)
    var freed: usize = 0
    for index in 0..<jobs.length:
        let job = &jobs[index]
        if job.failed or job.length == 0 or job.length > tile_bytes // 4 * 3:
            job.tile.raw_only = true
            continue
        let packed = new u8[job.length] --- in memory.heap catch failure:
            _ = failure
            continue
        memory.copy(packed, job.bytes, job.length)
        job.tile.packed = packed
        packed_tile_bytes += job.length
        drop_ram_copy(job.tile)
        residency_packs += 1
        freed += tile_bytes - job.length
    return freed

## Decode the compressed copies of `tiles` (none in RAM) across the processors.
func unpack_many(tiles: Tile*[]) -> !:
    if tiles.length == 0:
        return
    let jobs = try pack_jobs(tiles)
    defer release_pack_jobs(jobs)
    for index in 0..<jobs.length:
        jobs[index].bytes = try new u8[tile_bytes] --- in memory.heap
        memory.set(jobs[index].bytes, 0)
    try spread_pack(jobs, true)
    for index in 0..<jobs.length:
        if jobs[index].failed:
            error(invalid, "a compressed tile could not be decoded")
    for index in 0..<jobs.length:
        let tile = jobs[index].tile
        tile.ram = jobs[index].bytes
        var taken: u8[]
        jobs[index].bytes = taken
        ram_tile_bytes += tile_bytes
        residency_loads += 1

## A job for each of `tiles`, holding no bytes yet.
func pack_jobs(tiles: Tile*[]) -> PackJob[]!:
    let jobs = try new PackJob[tiles.length] --- in memory.heap
    for index in 0..<tiles.length:
        var no_bytes: u8[]
        jobs[index] = PackJob(tile = tiles[index], bytes = no_bytes, length = 0, failed = false)
    return jobs

## Free the jobs and whatever bytes they still hold.
func release_pack_jobs(jobs: PackJob[]):
    for index in 0..<jobs.length:
        if jobs[index].bytes.length > 0:
            free(jobs[index].bytes) in memory.heap
    free(jobs) in memory.heap