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