Luce packages
LuceLuce BaseLuciaOS

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