Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-image

Source of release 0.45.0

0.45.0 / src / document / module.lucb

#==============================================================================================
#
#   document - A layered document
#
#   DESCRIPTION:
#       A tree of layers over a canvas of fixed size, each raster layer holding shared GPU tiles
#       in document space. Groups hold layers bottom to top and are pass-through: their opacity
#       multiplies into their children and their visibility gates them. Editing replaces a
#       layer's tiles; every replacement bumps revisions that the compositor keys its cache on.
#       Fragments, in ORDER:
#
#       module.lucb   the Document: its tree, edits, masks, selection and states for undo
#       style.lucb    a layer's styles (Photoshop's layer effects) and their numbered fields
#       layer.lucb    a Layer, the tree helpers, and TreeState (the tree at one moment)
#
#==============================================================================================

from luce_gpu import gpu
from luce_std import math
import memory
import strings
from luce_canvas.tiles import Tiles, CellRange, box, unbox
from extent import relocate
from selection import Selection
from curves import Curves
from luce_painting.mixing import Mixing
from luce_raster.errors import invalid, limit
from digest import fnv_start, fnv_mix

pub struct Document:
    var owner: gpu.Device
    var extent_x: u32
    var extent_y: u32
    ## The selection, part of the document so history can cover it.
    pub var selection: Selection
    var root: Layer*
    var next_id: u64
    ## Bumps whenever the tree changes shape or a layer's attributes change.
    pub var revision: u64
    ## How many times history has swapped the tree: each swap moves every
    ## layer's revision into a band of its own (see `exchange`).
    var generation: u64
    ## Quick Mask's layer while it is on: outside the tree, so never composited,
    ## exported or saved, but found by its id so every painting tool reaches
    ## its mask, which holds the selection being painted.
    var quick: Layer*? = none
    ## While Quick Mask is on the selection clips nothing.
    pub var selection_suspended: bool = false
    ## Photoshop's "Blend RGB Colors Using Gamma 1.0": colors mix in linear
    ## light. Off (the default), every place colors mix — compositing, painting,
    ## fills, gradients, filters, resampling — mixes their sRGB-encoded values,
    ## as Photoshop does, while the tiles keep holding linear light.
    pub var linear_blend: bool = false

    ## Whether an edit mixes sRGB-encoded values: colors do unless the document
    ## blends in linear light; a mask's values (coverage) mix as they are.
    pub func mixes_encoded(on_mask: bool = false) -> bool:
        return not on_mask and not self.linear_blend

    ## `mixes_encoded` as the mixing shaders take it: 1 or 0.
    pub func srgb_flag(on_mask: bool = false) -> f32:
        return 1.0 if self.mixes_encoded(on_mask) else 0.0

    ## How an edit of this document (on a mask with `on_mask`) mixes (luce-painting's mixing).
    pub func mixing(on_mask: bool = false) -> Mixing:
        return Mixing(srgb = self.mixes_encoded(on_mask), mask = on_mask)

    ## An empty `width` by `height` document with no layers.
    pub static func create(device: gpu.Device, width: u32, height: u32) -> Document!:
        if width == 0 or height == 0 or width > 65536 or height > 65536:
            error(invalid, "document dimensions must be in 1..65536")
        var title: str = ""
        with memory.heap:
            title = try strings.copy("root")
        let root = try new Layer(id = 0, name = title, group = true, pixels = none, revision = 0) in memory.heap
        var selection = try Selection.create(width, height)
        errdefer selection.destroy()
        return Document(owner = device, extent_x = width, extent_y = height, selection = selection, root = root, next_id = 1, revision = 1, generation = 0)

    pub func width() -> u32:
        return self.extent_x

    pub func height() -> u32:
        return self.extent_y

    pub func device() -> gpu.Device:
        return self.owner

    ## The top-level layers, bottom to top.
    pub func layers() -> Layer*[]:
        return self.root.layers()

    ## The layer with `id`, borrowed: Quick Mask's too.
    pub func find(id: u64) -> Layer*?:
        if let quick = self.quick:
            if quick.id == id:
                return quick
        return find_in(self.root, id)

    ## Put Quick Mask's layer up with `mask` (taken) as its mask; its id.
    pub func begin_quick(mask: Tiles) -> u64!:
        var owned_mask = mask
        errdefer owned_mask.destroy()
        if self.quick != none:
            error(invalid, "Quick Mask is already on")
        let pixels = try box(try Tiles.create(self.owner, self.extent_x, self.extent_y))
        var name: str = ""
        with memory.heap:
            name = try strings.copy("Quick Mask")
        let layer = try new Layer(id = self.next_id, name = name, group = false, pixels = pixels, revision = 1) in memory.heap
        layer.mask = try box(owned_mask)
        self.next_id += 1
        self.quick = layer
        self.selection_suspended = true
        return layer.id

    ## Quick Mask's layer, while it is on.
    pub func quick_layer() -> Layer*?:
        return self.quick

    ## Take Quick Mask's layer down.
    pub func end_quick():
        self.selection_suspended = false
        let quick = self.quick else return
        self.quick = none
        layer_destroy(quick)

    ## Add a transparent raster layer on top of `parent` (the root by default).
    pub func add_layer(name: str, parent: u64? = none) -> u64!:
        let tiles = try Tiles.create(self.owner, self.extent_x, self.extent_y)
        return try self.add(name, parent, false, tiles)

    ## Add an adjustment layer of `kind` with `values` (at most 23) on top of
    ## `parent` (the root by default).
    pub func add_adjustment(name: str, kind: i64, values: const f64[], parent: u64? = none) -> u64!:
        let id = try self.add(name, parent, false, none)
        try self.set_adjustment(id, kind, values)
        return id

    ## Give Curves adjustment layer `id` its curves anew.
    pub func set_curves(id: u64, curves: Curves) -> !:
        let layer = self.find(id) else error(invalid, "no such layer")
        if layer.adjustment < 0:
            error(invalid, "only an adjustment layer takes curves")
        layer.curves = curves
        layer.revision += 1
        self.revision += 1

    ## Give adjustment layer `id` its kind and parameters anew.
    pub func set_adjustment(id: u64, kind: i64, values: const f64[]) -> !:
        let layer = self.find(id) else error(invalid, "no such layer")
        if layer.group or layer.pixels != none:
            error(invalid, "only an adjustment layer takes adjustment settings")
        if values.length > 23:
            error(invalid, "an adjustment takes at most 23 parameters")
        layer.adjustment = kind
        for index in 0..<(usize)23:
            layer.adjustment_values[index] = values[index] if index < values.length else 0.0
        layer.revision += 1
        self.revision += 1

    ## Add an empty group on top of `parent` (the root by default).
    pub func add_group(name: str, parent: u64? = none) -> u64!:
        return try self.add(name, parent, true, none)

    ## Give layer `id` a new name.
    pub func rename(id: u64, name: str) -> !:
        let layer = self.find(id) else error(invalid, "no such layer")
        var copied: str = ""
        with memory.heap:
            copied = try strings.copy(name)
        strings.release(layer.name)
        layer.name = copied

    func add(name: str, parent: u64?, group: bool, tiles: Tiles?) -> u64!:
        var holder: Tiles*? = none
        if let owned = tiles:
            holder = try box(owned)
        errdefer release_tiles(&holder)
        var target = self.root
        if let id = parent:
            target = self.find(id) else error(invalid, "no such parent layer")
            if not target.group:
                error(invalid, "only a group can hold layers")
        try make_room(target)
        var copied: str = ""
        with memory.heap:
            copied = try strings.copy(name)
        errdefer strings.release(copied)
        let id = self.next_id
        let layer = try new Layer(id = id, name = copied, group = group, pixels = holder, revision = 1) in memory.heap
        holder = none
        target.children[target.child_count] = layer
        target.child_count += 1
        self.next_id += 1
        self.revision += 1
        return id

    ## Move a layer — a group with everything in it — into group `parent` (the
    ## top level when none) at `position` among its layers, 0 the bottom; past
    ## the top it goes on top. A group cannot go inside itself.
    pub func move_to(id: u64, parent: u64?, position: usize) -> !:
        let moving = self.find(id) else error(invalid, "no such layer")
        var target = self.root
        if let parent_id = parent:
            target = self.find(parent_id) else error(invalid, "no such parent layer")
            if not target.group:
                error(invalid, "only a group can hold layers")
            if parent_id == id or find_in(moving, parent_id) != none:
                error(invalid, "a group cannot go inside itself")
        # Room first, so a failed allocation leaves the tree as it was.
        try make_room(target)
        let source = parent_of(self.root, id) else error(invalid, "no such layer")
        var index: usize = 0
        while source.children[index].id != id:
            index += 1
        for shift in index..<(source.child_count - 1):
            source.children[shift] = source.children[shift + 1]
        source.child_count -= 1
        let at = position if position < target.child_count else target.child_count
        var shift = target.child_count
        while shift > at:
            target.children[shift] = target.children[shift - 1]
            shift -= 1
        target.children[at] = moving
        target.child_count += 1
        self.revision += 1

    ## The group holding `id`, or none at the top level.
    pub func parent_id(id: u64) -> u64?:
        let parent = parent_of(self.root, id) else return none
        return none if parent == self.root else parent.id

    ## Where `id` sits among its parent's layers, 0 the bottom.
    pub func position(id: u64) -> usize!:
        let parent = parent_of(self.root, id) else error(invalid, "no such layer")
        var index: usize = 0
        while parent.children[index].id != id:
            index += 1
        return index

    ## A copy of layer `id` and all it holds, its tiles shared (cheap), for
    ## the layer clipboard; `release_snapshot` frees it.
    pub func snapshot(id: u64) -> Layer*!:
        let layer = self.find(id) else error(invalid, "no such layer")
        return try clone_layer(layer)

    ## Put a copy of `layer` — a snapshot from this document or another, with
    ## all it holds — into group `parent` (the top level when none) at
    ## `position`, its pixels and mask moved by (`offset_x`, `offset_y`) onto
    ## this document's canvas. Every layer in it gets a new id, in pre-order
    ## from the one returned.
    pub func adopt(layer: const Layer*, parent: u64?, position: usize, offset_x: f64, offset_y: f64) -> u64!:
        var target = self.root
        if let parent_id = parent:
            target = self.find(parent_id) else error(invalid, "no such parent layer")
            if not target.group:
                error(invalid, "only a group can hold layers")
        try make_room(target)
        let first = self.next_id
        let copy = try self.transplant(layer, offset_x, offset_y)
        let at = position if position < target.child_count else target.child_count
        var shift = target.child_count
        while shift > at:
            target.children[shift] = target.children[shift - 1]
            shift -= 1
        target.children[at] = copy
        target.child_count += 1
        self.revision += 1
        return first

    ## `layer` copied onto this canvas with new ids: tiles shared when they
    ## land as they are, else drawn anew where they land.
    func transplant(layer: const Layer*, offset_x: f64, offset_y: f64) -> Layer*!:
        var copied: str = ""
        with memory.heap:
            copied = try strings.copy(layer.name)
        errdefer strings.release(copied)
        var pixels: Tiles*? = none
        if let tiles = layer.pixels:
            pixels = try box(try self.landed(tiles, offset_x, offset_y, false))
        errdefer release_tiles(&pixels)
        let copy = try new Layer(id = self.next_id, name = copied, group = layer.group, pixels = pixels, revision = 1) in memory.heap
        self.next_id += 1
        errdefer layer_destroy(copy)
        copy.visible = layer.visible
        copy.opacity = layer.opacity
        copy.blend = layer.blend
        copy.clipped = layer.clipped
        copy.style = layer.style
        copy.mask_enabled = layer.mask_enabled
        copy.adjustment = layer.adjustment
        copy.adjustment_values = layer.adjustment_values
        copy.curves = layer.curves
        if let mask = layer.mask:
            copy.mask = try box(try self.landed(mask, offset_x, offset_y, true))
        if layer.child_count > 0:
            copy.children = try new Layer*[layer.child_count] --- in memory.heap
            for index in 0..<layer.child_count:
                copy.children[index] = try self.transplant(layer.children[index], offset_x, offset_y)
                copy.child_count += 1
        return copy

    ## `tiles` as they land on this canvas moved by (`offset_x`, `offset_y`);
    ## a `mask` reads white where nothing lands.
    func landed(tiles: const Tiles*, offset_x: f64, offset_y: f64, mask: bool) -> Tiles!:
        let device = tiles.device()
        if not device.same(&self.owner):
            error(invalid, "layers move only between documents on one GPU device")
        if tiles.width() == self.extent_x and tiles.height() == self.extent_y and offset_x == 0.0 and offset_y == 0.0:
            return try tiles.clone()
        var moved = try Tiles.create(self.owner, self.extent_x, self.extent_y)
        errdefer moved.destroy()
        let empty = 1.0 if mask else 0.0
        try relocate(tiles, &moved, 1.0, 1.0, offset_x, offset_y, false, gpu.Color(empty, empty, empty, empty))
        return moved

    ## Keep a layer's mask but stop it hiding anything, or bring it back.
    pub func enable_mask(id: u64, enabled: bool) -> !:
        let layer = self.find(id) else error(invalid, "no such layer")
        layer.mask_enabled = enabled
        layer.revision += 1
        self.revision += 1

    ## Move a layer one step up (`step` 1) or down (-1) among its siblings.
    pub func reorder(id: u64, step: i64) -> !:
        let parent = parent_of(self.root, id) else error(invalid, "no such layer")
        var index: usize = 0
        while parent.children[index].id != id:
            index += 1
        let target = (i64)index + step
        if target < 0 or target >= (i64)parent.child_count:
            return
        let moved = parent.children[index]
        parent.children[index] = parent.children[(usize)target]
        parent.children[(usize)target] = moved
        self.revision += 1

    ## Copy a raster layer with its mask and appearance, placed just above it.
    pub func duplicate(id: u64, name: str) -> u64!:
        let source = self.find(id) else error(invalid, "no such layer")
        if source.group:
            error(invalid, "groups cannot be duplicated yet")
        let tiles = source.tiles() else error(invalid, "no pixels to duplicate")
        var copy = try tiles.clone()
        errdefer copy.destroy()
        let parent = parent_of(self.root, id) else error(invalid, "no such layer")
        let created = try self.add(name, none if parent == self.root else parent.id, false, copy)
        let layer = self.find(created) else trap("just added")
        layer.visible = source.visible
        layer.opacity = source.opacity
        layer.blend = source.blend
        layer.clipped = source.clipped
        if let mask = source.mask_tiles():
            var mask_copy = try mask.clone()
            errdefer mask_copy.destroy()
            layer.mask = try box(mask_copy)
        # Place it right above the source.
        var origin: usize = 0
        while parent.children[origin].id != created:
            origin += 1
        var to: usize = 0
        while parent.children[to].id != id:
            to += 1
        let moved = parent.children[origin]
        var index = origin
        while index > to + 1:
            parent.children[index] = parent.children[index - 1]
            index -= 1
        parent.children[to + 1] = moved
        self.revision += 1
        return created

    ## The sibling directly below `id`, if any.
    pub func below(id: u64) -> Layer*?:
        let parent = parent_of(self.root, id) else return none
        var index: usize = 0
        while parent.children[index].id != id:
            index += 1
        if index == 0:
            return none
        return parent.children[index - 1]

    ## Remove a layer or a group with everything in it.
    pub func remove(id: u64) -> !:
        if not remove_in(self.root, id):
            error(invalid, "no such layer")
        self.revision += 1

    ## Replace a raster layer's pixels, taking ownership of `tiles`.
    pub func set_tiles(id: u64, tiles: Tiles) -> !:
        var holder: Tiles*? = try box(tiles)
        errdefer release_tiles(&holder)
        let layer = self.find(id) else error(invalid, "no such layer")
        if layer.group or tiles.width() != self.extent_x or tiles.height() != self.extent_y:
            error(invalid, "tiles must match a raster layer of the document's size")
        if let previous = layer.pixels:
            unbox(previous)
        layer.pixels = holder
        layer.revision += 1

    ## Replace a raster layer's pixels with `tiles` and hand back the pixels it
    ## had, for history.
    pub func take_tiles(id: u64, tiles: Tiles) -> Tiles!:
        var holder: Tiles*? = try box(tiles)
        errdefer release_tiles(&holder)
        let layer = self.find(id) else error(invalid, "no such layer")
        let previous = layer.pixels else error(invalid, "a group has no pixels")
        if tiles.width() != self.extent_x or tiles.height() != self.extent_y:
            error(invalid, "tiles must match the document's size")
        layer.pixels = holder
        layer.revision += 1
        let taken = *previous
        free(previous) in memory.heap
        return taken

    ## Adopt new extents after every layer has been rebuilt for them.
    ## The tree, extent and selection as they are, for undo.
    pub func capture() -> TreeState!:
        let root = try clone_layer(self.root)
        errdefer layer_destroy(root)
        var selection = try self.selection.copy()
        errdefer selection.destroy()
        var quick: Layer*? = none
        if let layer = self.quick:
            quick = try clone_layer(layer)
        return TreeState(root = root, next_id = self.next_id, extent_x = self.extent_x, extent_y = self.extent_y, selection = selection, quick = quick,
                         linear_blend = self.linear_blend)

    ## The document as it is now, on the heap, sharing its tiles: what a
    ## stroke reads while it paints (a Clone Stamp sampling every layer).
    ## `unbox_document` frees it.
    pub func frozen() -> Document*!:
        let root = try clone_layer(self.root)
        errdefer layer_destroy(root)
        var selection = try self.selection.copy()
        errdefer selection.destroy()
        return try new Document(owner = self.owner, extent_x = self.extent_x, extent_y = self.extent_y, selection = selection,
                                root = root, next_id = self.next_id, revision = self.revision, generation = self.generation,
                                linear_blend = self.linear_blend) in memory.heap

    ## Take `state` as the document and leave what was in its place: undo and
    ## redo swap, never copy.
    pub func exchange(state: TreeState*):
        let root = self.root
        self.root = state.root
        state.root = root
        let next_id = self.next_id
        self.next_id = state.next_id
        state.next_id = next_id
        let width = self.extent_x
        self.extent_x = state.extent_x
        state.extent_x = width
        let height = self.extent_y
        self.extent_y = state.extent_y
        state.extent_y = height
        let selection = self.selection
        self.selection = state.selection
        state.selection = selection
        # Quick Mask comes and goes with the steps that turned it on and off.
        let quick = self.quick
        self.quick = state.quick
        state.quick = quick
        self.selection_suspended = self.quick != none
        let linear_blend = self.linear_blend
        self.linear_blend = state.linear_blend
        state.linear_blend = linear_blend
        # History keeps the cells alone, not their GPU tiles.
        state.selection.drop_gpu_tiles()
        self.revision += 1
        # The layers coming back carry the revisions they had when taken, and
        # counting on from there would reach numbers the compositor's cache
        # holds for other pixels: move them into a band of their own.
        self.generation += 1
        restamp(self.root, self.generation)

    pub func set_extent(width: u32, height: u32) -> !:
        self.extent_x = width
        self.extent_y = height
        var replacement = try Selection.create(width, height)
        self.selection.destroy()
        self.selection = replacement
        self.revision += 1

    ## The selection's GPU tiles, or none when nothing is selected.
    pub func selection_tiles() -> Tiles*?!:
        if self.selection_suspended:
            return none
        return try self.selection.gpu_tiles(self.owner)

    ## As `selection_tiles`, catching up only the cells in `wanted` and `extra`
    ## more (see `Selection.gpu_tiles_within`): for drawing the ants.
    pub func selection_tiles_within(wanted: CellRange, extra: usize) -> Tiles*?!:
        if self.selection_suspended:
            return none
        return try self.selection.gpu_tiles_within(self.owner, wanted, extra)

    ## Whether the selection's GPU tiles still lag it somewhere.
    pub func selection_behind() -> bool:
        return self.selection.gpu_behind()

    ## Give a layer or a group an empty mask (revealing everything) or take it away.
    pub func set_mask(id: u64, present: bool) -> !:
        let layer = self.find(id) else error(invalid, "no such layer")
        if present and layer.mask == none:
            let tiles = try Tiles.create(self.owner, self.extent_x, self.extent_y)
            layer.mask = try box(tiles)
        elif not present:
            if let tiles = layer.mask:
                unbox(tiles)
            layer.mask = none
        layer.revision += 1
        self.revision += 1

    ## Replace a layer's mask with `tiles` and hand back the mask it had.
    pub func take_mask(id: u64, tiles: Tiles) -> Tiles!:
        var holder: Tiles*? = try box(tiles)
        errdefer release_tiles(&holder)
        let layer = self.find(id) else error(invalid, "no such layer")
        let previous = layer.mask else error(invalid, "the layer has no mask")
        if tiles.width() != self.extent_x or tiles.height() != self.extent_y:
            error(invalid, "tiles must match the document's size")
        layer.mask = holder
        layer.revision += 1
        let taken = *previous
        free(previous) in memory.heap
        return taken

    ## Clip a layer to the one below, or unclip it.
    pub func set_clipped(id: u64, clipped: bool) -> !:
        let layer = self.find(id) else error(invalid, "no such layer")
        layer.clipped = clipped
        self.revision += 1

    ## Set a layer's visibility, opacity and blend mode.
    pub func set_appearance(id: u64, visible: bool, opacity: f64, blend: u32 = 0) -> !:
        if not (opacity >= 0.0 and opacity <= 1.0):
            error(invalid, "opacity must be in 0..1")
        if blend > blend_mode_count - 1:
            error(invalid, "no such blend mode")
        let layer = self.find(id) else error(invalid, "no such layer")
        layer.visible = visible
        layer.opacity = opacity
        layer.blend = blend
        self.revision += 1

    pub func destroy():
        self.end_quick()
        self.selection.destroy()
        layer_destroy(self.root)

## Move a document onto the heap, for holders that keep a pointer.
pub func box_document(document: Document) -> Document*!:
    # Not zeroable, so field by field: a new field must be added here too.
    return try new Document(owner = document.owner, extent_x = document.extent_x, extent_y = document.extent_y, selection = document.selection,
                            root = document.root, next_id = document.next_id, revision = document.revision, generation = document.generation,
                            linear_blend = document.linear_blend) in memory.heap

## Destroy a boxed document and free the box.
pub func unbox_document(document: Document*):
    document.destroy()
    free(document) in memory.heap

test "document layers, groups, removal and appearance":
    var device = gpu.Device.open() catch failure:
        assert(failure.code == gpu.unavailable)
        return
    defer device.destroy()
    var document = try Document.create(device, 64, 48)
    defer document.destroy()
    let background = try document.add_layer("Background")
    let group = try document.add_group("Group")
    let inner = try document.add_layer("Inner", group)
    assert(document.layers().length == 2 and document.layers()[1].id == group)
    let found = document.find(inner) else trap("missing layer")
    assert(found.name == "Inner" and found.tiles() != none and found.revision == 1)
    assert((document.find(group) else trap("missing group")).layers()[0].id == inner)
    try document.set_appearance(background, false, 0.5)
    assert(not (document.find(background) else trap("missing")).visible)
    var rejected = false
    _ = document.add_layer("Bad", inner) catch failure:
        assert(failure.code == invalid)
        rejected = true
        recover 0
    assert(rejected)
    let replacement = try Tiles.create(device, 64, 48)
    try document.set_tiles(inner, replacement)
    assert(found.revision == 2)
    try document.remove(group)
    assert(document.find(inner) == none and document.layers().length == 1)
    let second = try document.add_layer("Second")
    try document.set_appearance(second, true, 0.5, 6)
    let copy = try document.duplicate(second, "Second copy")
    assert(document.layers().length == 3 and document.layers()[2].id == copy and (document.find(copy) else trap("copy")).blend == 6)
    try document.reorder(copy, -3)
    assert(document.layers()[2].id == copy)
    try document.reorder(copy, -1)
    assert(document.layers()[1].id == copy and document.layers()[2].id == second)
    assert((document.below(second) else trap("below")).id == copy and document.below(background) == none)