dymokomi/luce-image
Source of release 0.45.0
0.45.0 / src / composite / module.lucb
#==============================================================================================
#
# composite - The compositor
#
# DESCRIPTION:
# Answers a request for one tile of the flattened document at
# a pyramid level, from a cache keyed on what the tile depends on. Level 0 is
# document pixels; level L covers 2^L by 2^L level-0 tiles in one 256 by 256
# texture, composited from every layer's own level-L tiles (luce-canvas's
# pyramid), so a zoomed-out view costs what it shows, not what the document
# holds. The key is an identity digest over the contributing layers (id,
# revision, visibility, effective opacity) plus the cell and level, so a change
# to one layer invalidates only the tiles it touches, and a change to a top
# layer's opacity never re-renders what lies below it in another tile. There is
# one way to produce pixels; export asks for level-0 tiles like the screen.
# A Blur adjustment layer is the one thing that reaches past its cell: it
# flattens what is below it in the eight cells around too, and while a
# document has one every key covers those neighbours. Colors mix as the
# document blends them: as sRGB-encoded values, or in linear light with
# `Document.linear_blend` (part of every key).
#
# Fragments, in ORDER:
#
# module.lucb Composer: requests, keys, gathering, levels and stand-ins
# flatten.lucb a cell flattened: layers, groups, masks, adjustments, blur, styles
# tests.lucb the compositor tests
#
#==============================================================================================
from luce_gpu import gpu
import memory
from luce_canvas.tiles import Gathering, Tiles, Tile, tile_size, min_u32, max_u32, tile_texture, transient_mark, release_transients
from luce_canvas.pyramid import Pyramid, covered_at, tile_bytes, precious_level
from luce_canvas.cache import TileCache
from document import Document, Layer
from digest import fnv_start, fnv_mix
from style import Styler
from luce_raster.errors import invalid, limit
from luce_canvas.half import from_half
from shaders import composite_frag_words, composite_frag_msl, adjust_mix_frag_words, adjust_mix_frag_msl
from adjust import Adjuster, Place, curves, blur
from filter import Filters
from curves import lut_size
from stand_in import StandIn, Made, stand_in_limit
## A styled layer's rendered effects, kept while its pixels and style stand.
struct Effects:
var key: u64
## Drawn under the layer's pixels; and, when the style changes the layer's
## own colors, the layer as it then is, drawn instead of its pixels.
var tiles: Tiles
var over: Tiles
var has_over: bool
var used: u64
var live: bool
## A Curves adjustment layer's lookup table, kept while its curves stand.
struct CurveTable:
var key: u64
var texture: gpu.Texture
var live: bool
## How many Curves layers keep their tables at once.
let curve_table_budget: usize = 4
## How many styled layers keep their effects rendered at once.
let effects_budget: usize = 8
## A coarser composite standing in for a cell whose tiles are coming back:
## its texture (borrowed like a composite) and the texels that cover the cell.
pub struct Coarser:
pub var texture: gpu.Texture
pub var region: gpu.Region
pub struct Composer:
var owner: gpu.Device
## Composited tiles by what they depend on, and every layer's levels.
var cache: TileCache
var pyramid: Pyramid
## The level the tile being made is at.
var level: u32
## Whether the tile being made mixes sRGB-encoded values: 1 or 0, as the shaders take it.
var srgb: f32
var tick: u64
var shader: gpu.Shader
var pipeline: gpu.Pipeline
var blank: gpu.Texture
var white: gpu.Texture
var styler: Styler
## Adjustment layers: the adjust pass over the backdrop, and the mix back by mask and opacity.
var adjuster: Adjuster
var mix_shader: gpu.Shader
var mix: gpu.Pipeline
var effects: Effects[8]
var curve_tables: CurveTable[4]
var next_curve_table: usize
## How many tiles were rendered rather than found, for tests and tuning.
pub var renders: u64
## The document being drawn's size, for adjustments that depend on where a pixel is.
var extent_x: u32
var extent_y: u32
## Blur layers: the document being drawn, the Gaussian, and the layer a
## flatten stops before (0: none) and whether it has.
var drawing: const Document*?
var filters: Filters
var stop_at: u64
var stopped: bool
## Layers shown through a preview's stand-in rather than their tiles.
var stand_ins: StandIn[8]
var stand_in_count: usize
## What was cached while stand-ins showed: keyed by their generations, it
## is stale once they change, and is let go then rather than filling the
## cache until pushed out.
var stand_in_keys: u64[]
var stand_in_key_count: usize
## A compositor keeping at most `budget` composited tiles (512 KiB each),
## and as many bytes again of layer levels.
pub static func create(device: gpu.Device, budget: usize = 1536) -> Composer!:
if budget == 0 or budget > 65536:
error(invalid, "the tile budget must be in 1..65536")
var cache = try TileCache.create(budget * tile_bytes, tile_bytes)
errdefer cache.destroy()
var pyramid = try Pyramid.create(device, budget * tile_bytes)
errdefer pyramid.destroy()
var shader = try gpu.Shader.create(device, composite_frag_words, composite_frag_msl)
errdefer shader.destroy()
var pipeline = try gpu.Pipeline.create(device, shader, gpu.Blend.replace, gpu.Format.rgba16_float)
errdefer pipeline.destroy()
var blank = try tile_texture(device)
errdefer blank.destroy()
let zeros = try new u8[(usize)tile_size * (usize)tile_size * 8] --- in memory.heap
defer free(zeros) in memory.heap
for index in 0..<zeros.length:
zeros[index] = 0
try blank.upload(zeros)
var white = try gpu.Texture.create(device, 1, 1, gpu.Format.rgba16_float)
errdefer white.destroy()
# 1.0 as a half is 0x3c00.
try white.upload([(u8)0, (u8)0x3c, (u8)0, (u8)0x3c, (u8)0, (u8)0x3c, (u8)0, (u8)0x3c])
var styler = try Styler.create(device)
errdefer styler.destroy()
var adjuster = try Adjuster.create(device)
errdefer adjuster.destroy()
var filters = try Filters.create(device)
errdefer filters.destroy()
var mix_shader = try gpu.Shader.create(device, adjust_mix_frag_words, adjust_mix_frag_msl)
errdefer mix_shader.destroy()
var mix = try gpu.Pipeline.create(device, mix_shader, gpu.Blend.replace, gpu.Format.rgba16_float)
errdefer mix.destroy()
var effects: Effects[8]
for index in 0..<effects_budget:
effects[index] = Effects(key = 0, tiles = Tiles(), over = Tiles(), has_over = false, used = 0, live = false)
var stand_ins: StandIn[8] = ---
var tables: CurveTable[4]
for index in 0..<curve_table_budget:
tables[index] = CurveTable(key = 0, texture = gpu.Texture(), live = false)
return Composer(owner = device, cache = cache, pyramid = pyramid, level = 0, srgb = 1.0, tick = 0, shader = shader, pipeline = pipeline, blank = blank, white = white, styler = styler,
adjuster = adjuster, mix_shader = mix_shader, mix = mix, effects = effects, curve_tables = tables, next_curve_table = 0, renders = 0, extent_x = 0, extent_y = 0,
drawing = none, filters = filters, stop_at = 0, stopped = false,
stand_ins = stand_ins, stand_in_count = 0)
## The flattened tile at `column`, `row` of pyramid `level`, borrowed until
## the next call. Straight-alpha rgba16_float, transparent where nothing is.
pub func tile(document: const Document*, column: u32, row: u32, level: u32) -> gpu.Texture!:
if level > 16:
error(invalid, "pyramid levels go up to 16")
let span = 1u32 << level
if column * span * tile_size >= document.width() or row * span * tile_size >= document.height():
error(invalid, "the requested tile lies outside the document")
self.tick += 1
self.extent_x = document.width()
self.extent_y = document.height()
self.drawing = document
self.level = level
self.srgb = document.srgb_flag()
# What this tile fetches stays until the next request.
self.cache.hold()
self.pyramid.hold()
let digest = self.composite_key(document, column, row, level)
if let found = self.cache.find(digest | 1):
return found
let mark = transient_mark()
defer release_transients(mark)
let texture = try self.flatten(document, column, row)
self.renders += 1
# A zoomed-out composite is made from every layer's levels below it:
# precious, so the view at fit keeps it while finer tiles come and go.
try self.cache.put(digest | 1, texture, tile_bytes, precious = precious_level(document.width(), document.height(), level))
try self.note_stand_in_key(digest | 1)
return texture
## Forget the composites and `tiles`' level tiles over row `row` of cells,
## about to change as a picture loads into `tiles` a band at a time: made
## from the rows so far, they would only fill the caches until pushed out.
pub func forget_band(document: const Document*, tiles: const Tiles*, row: u32):
var level: u32 = 0
while level <= 16:
let span = (u64)tile_size << level
let columns = (u32)(((u64)document.width() + span - 1) // span)
for column in 0..<columns:
self.cache.forget(self.composite_key(document, column, row >> level, level) | 1)
if (u64)document.width() <= span and (u64)document.height() <= span:
break
level += 1
self.pyramid.forget_band(tiles, row, false)
## What the composite of cell (`column`, `row`) at `level` is made from, as
## a key: every contributing layer's cells by stamp, and the stand-ins shown.
func composite_key(document: const Document*, column: u32, row: u32, level: u32) -> u64:
let span = 1u32 << level
var digest = fnv_start()
digest = fnv_mix(digest, (u64)level)
digest = fnv_mix(digest, (u64)column)
digest = fnv_mix(digest, (u64)row)
digest = fnv_mix(digest, (u64)document.width())
digest = fnv_mix(digest, (u64)document.height())
digest = fnv_mix(digest, 1 if document.linear_blend else 2)
if has_blur(document.layers()):
# What is below a blur in the cells around shows through it.
let first_column = column * span - 1 if column > 0 else 0
let first_row = row * span - 1 if row > 0 else 0
digest = hash_layers(digest, document.layers(), 1.0, first_column, first_row, span + 2)
else:
digest = hash_layers(digest, document.layers(), 1.0, column * span, row * span, span)
for index in 0..<self.stand_in_count:
digest = fnv_mix(digest, self.stand_ins[index].layer * 2 + (1 if self.stand_ins[index].mask else 0))
digest = fnv_mix(digest, self.stand_ins[index].generation)
return digest
## Bring into RAM together the layer tiles that the composites of cells
## `first_column..<last_column` by `first_row..<last_row` at `level` not
## yet kept would otherwise bring back one at a time, each decoded on this
## thread (luce-canvas tiles/gathering). A draw calls it before asking for
## the cells; a tile it misses (a blur's neighbors) still comes back alone.
pub func gather(document: const Document*, first_column: u32, first_row: u32, last_column: u32, last_row: u32, level: u32) -> !:
var pending = Gathering.create()
for row in first_row..<last_row:
for column in first_column..<last_column:
if self.cache.has(self.composite_key(document, column, row, level) | 1):
continue
try self.gather_layers(document.layers(), column, row, level, &pending)
try pending.finish()
## Whether the composite of cell (`column`, `row`) at `level` is kept.
pub func kept(document: const Document*, column: u32, row: u32, level: u32) -> bool:
return self.cache.has(self.composite_key(document, column, row, level) | 1)
## Add to `pending` (deferred) the layer tiles making that composite would
## bring back; how many it lacks.
pub func lacking(document: const Document*, column: u32, row: u32, level: u32, pending: Gathering*) -> usize!:
let before = pending.missing()
try self.gather_layers(document.layers(), column, row, level, pending)
return pending.missing() - before
## The nearest coarser composite kept that covers cell (`column`, `row`) of
## `level` (whose covered texels are `covered_x` by `covered_y`), and the
## texels of it that stand for the cell; none when no coarser one is kept.
pub func coarser(document: const Document*, column: u32, row: u32, level: u32, covered_x: u32, covered_y: u32) -> Coarser?:
for up in 1..<(u32)8:
let coarse = level + up
if coarse > 16:
break
let found = self.cache.find(self.composite_key(document, column >> up, row >> up, coarse) | 1) else continue
let side = tile_size >> up
let x = (column - ((column >> up) << up)) * side
let y = (row - ((row >> up) << up)) * side
let step = 1u32 << up
return Coarser(texture = found, region = gpu.Region(x, y, max_u32(1, (covered_x + step - 1) >> up), max_u32(1, (covered_y + step - 1) >> up)))
return none
func gather_layers(layers: Layer*[], column: u32, row: u32, level: u32, pending: Gathering*) -> !:
for layer in layers:
if not layer.visible or layer.opacity == 0.0:
continue
if let mask_tiles = layer.active_mask():
try self.pyramid.gather(mask_tiles, column, row, level, true, pending)
if layer.group:
try self.gather_layers(layer.layers(), column, row, level, pending)
elif let tiles = layer.tiles():
try self.pyramid.gather(tiles, column, row, level, false, pending)
## Cell (`column`, `row`) of any store at `level`, for drawing outside a
## composite (thumbnails, marching ants, a layer being moved): borrowed
## until the next `hold` or composite request; none where it is empty.
pub func level_texture(tiles: const Tiles*, column: u32, row: u32, level: u32, mask: bool = false) -> gpu.Texture?!:
return try self.pyramid.texture(tiles, column, row, level, mask)
## Begin a drawing request whose level tiles must stay until it is done.
pub func hold():
self.cache.hold()
self.pyramid.hold()
## A layer's (or mask's) tile at the level being made; none where it is
## empty. A level-0 tile kept in RAM comes up for this composite alone
## (released when `tile` has made it), so compositing a document mostly in
## RAM costs uploads rather than GPU memory.
func source(tiles: const Tiles*, column: u32, row: u32, mask: bool = false) -> gpu.Texture?!:
return try self.pyramid.pass_texture(tiles, column, row, self.level, mask)
## Show layer `stand_in.layer` (or its mask) through `stand_in` until
## `drop_stand_ins`, replacing one it has already; a new generation
## redraws every tile it reaches.
pub func stand_in(stand_in: StandIn) -> !:
for index in 0..<self.stand_in_count:
if self.stand_ins[index].layer == stand_in.layer and self.stand_ins[index].mask == stand_in.mask:
if self.stand_ins[index].generation != stand_in.generation:
self.forget_stand_in_keys()
self.stand_ins[index] = stand_in
return
if self.stand_in_count == stand_in_limit:
error(limit, "a preview shows at most 8 layers and masks")
self.stand_ins[self.stand_in_count] = stand_in
self.stand_in_count += 1
## Show every layer through its own tiles again.
pub func drop_stand_ins():
self.stand_in_count = 0
self.forget_stand_in_keys()
## Remember `key`, cached while stand-ins show, to let it go with them.
func note_stand_in_key(key: u64) -> !:
if self.stand_in_count == 0:
return
if self.stand_in_key_count == self.stand_in_keys.length:
let grown = try new u64[self.stand_in_keys.length * 2 + 64] --- in memory.heap
for index in 0..<self.stand_in_key_count:
grown[index] = self.stand_in_keys[index]
if self.stand_in_keys.length > 0:
free(self.stand_in_keys) in memory.heap
self.stand_in_keys = grown
self.stand_in_keys[self.stand_in_key_count] = key
self.stand_in_key_count += 1
## Let go of what was cached for the stand-ins as they were.
func forget_stand_in_keys():
for index in 0..<self.stand_in_key_count:
self.cache.forget(self.stand_in_keys[index])
self.stand_in_key_count = 0
## The layer levels it keeps: what a stand-in reads, for work made outside a draw.
pub func levels() -> Pyramid*:
return &self.pyramid
## Forget every rendered tile.
pub func clear():
self.cache.clear()
self.pyramid.clear()
for index in 0..<effects_budget:
if self.effects[index].live:
drop_effects(&self.effects[index])
self.effects[index].live = false
pub func destroy():
if self.stand_in_keys.length > 0:
free(self.stand_in_keys) in memory.heap
var no_keys: u64[]
self.stand_in_keys = no_keys
self.stand_in_key_count = 0
self.clear()
self.cache.destroy()
self.pyramid.destroy()
for index in 0..<curve_table_budget:
if self.curve_tables[index].live:
self.curve_tables[index].texture.destroy()
self.curve_tables[index].live = false
self.styler.destroy()
self.mix.destroy()
self.mix_shader.destroy()
self.adjuster.destroy()
self.filters.destroy()
self.blank.destroy()
self.white.destroy()
self.pipeline.destroy()
self.shader.destroy()
## Move a compositor onto the heap, for holders that keep a pointer.
pub func box_composer(composer: Composer) -> Composer*!:
# The whole value at once: a field-by-field copy left new fields zero.
let boxed = try new Composer in memory.heap
*boxed = composer
return boxed
## Destroy a boxed compositor and free the box.
pub func unbox_composer(composer: Composer*):
composer.destroy()
free(composer) in memory.heap