Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-ui

Source of release 0.19.0

0.19.0 / src / raster.lucb

## A CPU paint surface for simple drawing programs and tests: round brush dabs,
## fills, compositing and pixel reads, drawn to the screen as a texture.
from luce_gpu import gpu
from luce_window import window
import interop
from luce_std import math
import memory
import ownership
import result
from texture_cache import TextureCache

struct Pixel:
    var red: f32
    var green: f32
    var blue: f32
    var alpha: f32

func dimensions(width: i64, height: i64) -> !:
    if width < 1 or width > 16384 or height < 1 or height > 16384:
        error(result.invalid, "raster dimensions must be in 1..16384")
    if width * height > 67108864:
        error(result.invalid, "a raster supports at most 67108864 pixels")

func component(value: f64) -> bool:
    return math.is_finite(value) and value >= 0.0 and value <= 1.0

func over(destination: Pixel, source: Pixel) -> Pixel:
    let remaining = (f32)1.0 - source.alpha
    return Pixel(source.red + destination.red * remaining,
                 source.green + destination.green * remaining,
                 source.blue + destination.blue * remaining,
                 source.alpha + destination.alpha * remaining)

func quantize(value: f64) -> u32:
    return (u32)(math.clamp(value, 0.0, 1.0) * 255.0 + 0.5)

func rgba(pixel: Pixel) -> u32:
    let alpha = quantize((f64)pixel.alpha)
    if alpha == 0:
        return 0
    let inverse = 1.0 / (f64)pixel.alpha
    return quantize((f64)pixel.red * inverse) + quantize((f64)pixel.green * inverse) * 256 + quantize((f64)pixel.blue * inverse) * 65536 + alpha * 16777216

## A CPU raster of linear premultiplied pixels. Drawing uploads it to a texture
## on the target's device, created on first draw and refreshed only when the
## pixels changed since the last upload.
pub struct Raster:
    var columns: i64
    var rows: i64
    var pixels: Pixel[]
    var cache: TextureCache
    var revision: u64 = 1

    ## A transparent `width` by `height` raster, each dimension in 1..16384 and at
    ## most 67108864 pixels in all.
    pub func init(width: i64, height: i64) -> !:
        try dimensions(width, height)
        let pixels = try new Pixel[(usize)(width * height)] --- in memory.heap
        for index in 0..<pixels.length:
            pixels[index] = Pixel()
        self.columns = width
        self.rows = height
        self.pixels = pixels
        self.cache = TextureCache()
        self.revision = 1

    pub func width() -> i64:
        return self.columns

    pub func height() -> i64:
        return self.rows

    func require_open() -> !:
        if self.pixels.length == 0:
            error(result.invalid, "raster is closed")

    ## Stamp one round brush mark centered at `x`, `y` (pixel centers sit at half
    ## coordinates). `diameter` is in 1..512 pixels. `hardness` 0..1 is the fraction
    ## of the radius painted at full coverage; beyond it coverage falls smoothly to
    ## zero at the edge. The mark is composited source-over in `color`, whose alpha
    ## is ignored; with `erase` it removes that much coverage instead, and `color`
    ## is validated but unused. Pixels outside the raster are skipped.
    pub func dab(x: f64, y: f64, diameter: f64, hardness: f64, color: gpu.Color, erase: bool = false) -> !:
        self.revision += 1
        try self.require_open()
        if not math.is_finite(x) or not math.is_finite(y):
            error(result.invalid, "brush coordinates must be finite")
        if not math.is_finite(diameter) or diameter < 1.0 or diameter > 512.0:
            error(result.invalid, "brush diameter must be in 1..512")
        if not component(hardness) or not component(color.red) or not component(color.green) or not component(color.blue):
            error(result.invalid, "brush hardness and color components must be in 0..1")
        let radius = diameter * 0.5
        let left = (i64)math.clamp(math.floor(x - radius), 0.0, (f64)self.columns)
        let right = (i64)math.clamp(math.ceil(x + radius), 0.0, (f64)self.columns)
        let top = (i64)math.clamp(math.floor(y - radius), 0.0, (f64)self.rows)
        let bottom = (i64)math.clamp(math.ceil(y + radius), 0.0, (f64)self.rows)
        let inner = hardness * radius
        for row in top..<bottom:
            let dy = (f64)row + 0.5 - y
            for column in left..<right:
                let dx = (f64)column + 0.5 - x
                let distance = math.sqrt(dx * dx + dy * dy)
                if distance >= radius:
                    continue
                var coverage = 1.0
                if distance > inner:
                    let t = (radius - distance) / (radius - inner)
                    coverage = t * t * (3.0 - 2.0 * t)
                let alpha = (f32)coverage
                let index = (usize)(row * self.columns + column)
                let previous = self.pixels[index]
                if erase:
                    let remaining = (f32)1.0 - alpha
                    self.pixels[index] = Pixel(previous.red * remaining, previous.green * remaining, previous.blue * remaining, previous.alpha * remaining)
                else:
                    self.pixels[index] = over(previous, Pixel((f32)color.red * alpha, (f32)color.green * alpha, (f32)color.blue * alpha, alpha))

    ## Make every pixel transparent.
    pub func clear():
        self.revision += 1
        for index in 0..<self.pixels.length:
            self.pixels[index] = Pixel()

    ## Write one opaque pixel in linear-light 0..1. Out of range coordinates fail.
    pub func set_pixel(x: i64, y: i64, color: gpu.Color) -> !:
        self.revision += 1
        try self.require_open()
        if x < 0 or y < 0 or x >= self.columns or y >= self.rows:
            error(result.invalid, "raster pixel is out of bounds")
        if not component(color.red) or not component(color.green) or not component(color.blue):
            error(result.invalid, "raster color components must be in 0..1")
        self.pixels[(usize)(y * self.columns + x)] = Pixel((f32)color.red, (f32)color.green, (f32)color.blue, (f32)1.0)

    ## Write one opaque pixel by linear offset. The span bounds-check is the check.
    pub func put(offset: usize, color: gpu.Color) -> !:
        self.revision += 1
        try self.require_open()
        if not component(color.red) or not component(color.green) or not component(color.blue):
            error(result.invalid, "raster color components must be in 0..1")
        self.pixels[offset] = Pixel((f32)color.red, (f32)color.green, (f32)color.blue, (f32)1.0)

    ## Set every pixel to opaque `color`.
    pub func fill(color: gpu.Color) -> !:
        self.revision += 1
        try self.require_open()
        if not component(color.red) or not component(color.green) or not component(color.blue):
            error(result.invalid, "raster color components must be in 0..1")
        let pixel = Pixel((f32)color.red, (f32)color.green, (f32)color.blue, (f32)1.0)
        for index in 0..<self.pixels.length:
            self.pixels[index] = pixel

    ## Set the pixels of a rectangle to opaque `color`, clipped to the raster.
    pub func fill_rect(x: i64, y: i64, width: i64, height: i64, color: gpu.Color) -> !:
        self.revision += 1
        try self.require_open()
        if not component(color.red) or not component(color.green) or not component(color.blue):
            error(result.invalid, "raster color components must be in 0..1")
        if width < 0 or height < 0:
            error(result.invalid, "raster fill size must be nonnegative")
        let left = math.imax(x, 0)
        let top = math.imax(y, 0)
        let right = math.imin(x + width, self.columns)
        let bottom = math.imin(y + height, self.rows)
        if left >= right or top >= bottom:
            return
        let pixel = Pixel((f32)color.red, (f32)color.green, (f32)color.blue, (f32)1.0)
        for row in top..<bottom:
            let start = (usize)(row * self.columns)
            for column in left..<right:
                self.pixels[start + (usize)column] = pixel

    ## The pixel's premultiplied color, without alpha; see `alpha_at`.
    pub func color_at(x: i64, y: i64) -> gpu.Color!:
        try self.require_open()
        if x < 0 or y < 0 or x >= self.columns or y >= self.rows:
            error(result.invalid, "raster pixel is out of bounds")
        let pixel = self.pixels[(usize)(y * self.columns + x)]
        return gpu.Color((f64)pixel.red, (f64)pixel.green, (f64)pixel.blue)

    ## A new raster with the same size and pixels.
    pub func copy() -> interop.Reference[Raster]!:
        return try self.resized(self.columns, self.rows)

    ## A new `width` by `height` raster holding this one's pixels anchored at the
    ## top-left: cropped where it is smaller, transparent where it is larger. No
    ## resampling.
    pub func resized(width: i64, height: i64) -> interop.Reference[Raster]!:
        try self.require_open()
        let copied = try interop.Reference[Raster].adopt(new Raster(width, height) in memory.heap, raster_type, memory.heap)
        let destination = copied.value()
        let columns = (usize)math.imin(width, self.columns)
        let rows = math.imin(height, self.rows)
        for row in 0..<rows:
            let source_start = (usize)(row * self.columns)
            let destination_start = (usize)(row * width)
            for column in 0..<columns:
                destination.pixels[destination_start + column] = self.pixels[source_start + column]
        return copied

    ## Composite `source`, scaled by `opacity`, over this raster. Both must have the
    ## same dimensions; `source` may be this raster itself.
    pub func composite(source: interop.Reference[Raster], opacity: f64 = 1.0) -> !:
        self.revision += 1
        try self.require_open()
        if not component(opacity):
            error(result.invalid, "raster opacity must be in 0..1")
        let raster = try source.get()
        try raster.require_open()
        if self.columns != raster.columns or self.rows != raster.rows:
            error(result.invalid, "composited rasters must have equal dimensions")
        if opacity == 0.0:
            return
        let alpha = (f32)opacity
        for index in 0..<self.pixels.length:
            let pixel = raster.pixels[index]
            self.pixels[index] = over(self.pixels[index], Pixel(pixel.red * alpha, pixel.green * alpha, pixel.blue * alpha, pixel.alpha * alpha))

    pub func alpha_at(x: i64, y: i64) -> f64!:
        try self.require_open()
        if x < 0 or y < 0 or x >= self.columns or y >= self.rows:
            error(result.invalid, "raster pixel is out of bounds")
        return (f64)self.pixels[(usize)(y * self.columns + x)].alpha

    ## Draw the raster scaled onto `rectangle` of `target`, nearest-sampled so
    ## pixels stay crisp when magnified.
    pub func draw(target: interop.View[gpu.RenderTarget], rectangle: gpu.Rect, filter: gpu.Filter = gpu.Filter.nearest) -> !:
        try self.require_open()
        let checked = try target.get()
        if not math.is_finite(rectangle.x) or not math.is_finite(rectangle.y) or not math.is_finite(rectangle.width) or not math.is_finite(rectangle.height) or not math.is_finite(rectangle.x + rectangle.width) or not math.is_finite(rectangle.y + rectangle.height):
            error(result.invalid, "raster rectangle must be finite")
        if rectangle.width <= 0.0 or rectangle.height <= 0.0:
            return
        # A standalone frame has no device to hold a texture; it records nothing here.
        let texture = (try self.refresh(checked)) else return
        try gpu.draw_image(checked, texture, rectangle, none, 1.0, filter)

    ## Make the texture match the pixels, on the device `target` draws on.
    func refresh(target: const gpu.RenderTarget*) -> gpu.Texture?!:
        let texture = (try self.cache.texture_for(target, (u32)self.columns, (u32)self.rows, gpu.Format.rgba8_linear)) else return none
        if not self.cache.stale(self.revision):
            return texture
        let count = self.pixels.length
        let bytes = try new u8[count * 4] --- in memory.heap
        defer free(bytes) in memory.heap
        for index in 0..<count:
            let packed = rgba(self.pixels[index])
            bytes[index * 4] = (u8)(packed % 256)
            bytes[index * 4 + 1] = (u8)(packed // 256 % 256)
            bytes[index * 4 + 2] = (u8)(packed // 65536 % 256)
            bytes[index * 4 + 3] = (u8)(packed // 16777216)
        try texture.upload(bytes)
        self.cache.mark_uploaded(self.revision)
        return texture

    ## Release the texture, the device reference and the pixels; later calls fail.
    ## Closing twice is harmless.
    pub func close():
        self.cache.release()
        if self.pixels.length > 0:
            free(self.pixels) in memory.heap
        var empty: Pixel[]
        self.pixels = empty
        self.columns = 0
        self.rows = 0

    func trace(visit: func(ownership.Object*, void*) -> unit, context: void*):
        _ = self
        _ = visit
        _ = context

pub let raster_type: interop.Type[Raster] = interop.Type[Raster]("Raster", Raster.close, Raster.trace, closeable = true, main_thread = true)

struct AllocationTracker: memory.Allocator:
    var upstream: memory.Allocator
    var live: usize
    var remaining: usize?

    pub func allocate(size: usize, alignment: usize) -> u8[]?:
        if let remaining = self.remaining:
            if remaining == 0:
                return none
            self.remaining = remaining - 1
        let block = self.upstream.allocate(size, alignment) else return none
        self.live += 1
        return block

    pub func resize(block: u8[], size: usize) -> bool:
        return self.upstream.resize(block, size)

    pub func release(block: u8[]):
        assert(self.live > 0)
        self.live -= 1
        self.upstream.release(block)

func restore_heap(previous: memory.Allocator):
    memory.heap = previous

func check_allocations(tracker: AllocationTracker*) -> !:
    var raster = try Raster(2, 2)
    defer raster.close()
    try raster.dab(0.5, 0.5, 1.0, 1.0, gpu.Color(1.0, 0.0, 0.0))
    let baseline = tracker.live
    var succeeded = false
    for stage in 0..<8:
        tracker.remaining = (usize)stage
        let copied: interop.Reference[Raster]? = raster.copy() catch failure:
            assert(failure.code == memory.exhausted)
            recover none
        tracker.remaining = none
        if let reference = copied:
            reference.release()
            succeeded = true
        assert(tracker.live == baseline)
        assert((try raster.alpha_at(0, 0)) == 1.0)
        if succeeded:
            break
    assert(succeeded)
    let copied = try raster.copy()
    copied.close()
    copied.close()
    copied.release()
    assert(tracker.live == baseline)

test "raster allocation failures and repeated close release all storage":
    var tracker = AllocationTracker(upstream = memory.heap)
    let previous = memory.heap
    memory.heap = &tracker
    defer restore_heap(previous)
    with tracker:
        try check_allocations(&tracker)
        assert(tracker.live == 0)

test "raster pixel writes, fill and clipped fill_rect":
    var raster = try Raster(4, 3)
    defer raster.close()
    try raster.fill(gpu.Color(0.0, 0.0, 1.0))
    let filled = try raster.color_at(3, 2)
    assert(filled.red == 0.0 and filled.green == 0.0 and filled.blue == 1.0)
    try raster.set_pixel(1, 1, gpu.Color(1.0, 0.0, 0.0))
    let painted = try raster.color_at(1, 1)
    assert(painted.red == 1.0 and painted.green == 0.0 and painted.blue == 0.0)
    try raster.put(0, gpu.Color(0.0, 1.0, 0.0))
    let first = try raster.color_at(0, 0)
    assert(first.green == 1.0)
    try raster.fill_rect(-2, 1, 3, 8, gpu.Color(1.0, 1.0, 0.0))
    let clipped = try raster.color_at(0, 1)
    assert(clipped.red == 1.0 and clipped.green == 1.0 and clipped.blue == 0.0)
    assert((try raster.color_at(1, 1)).red == 1.0)
    assert((try raster.color_at(1, 0)).blue == 1.0)
    var rejected = false
    raster.set_pixel(4, 0, gpu.Color()) catch failure:
        assert(failure.code == result.invalid)
        rejected = true
    assert(rejected)
    rejected = false
    raster.fill(gpu.Color(-0.1, 0.0, 0.0)) catch failure:
        assert(failure.code == result.invalid)
        rejected = true
    assert(rejected)

test "raster brush falloff, source over, erasing and clearing":
    var raster = try Raster(5, 3)
    defer raster.close()
    assert(raster.width() == 5 and raster.height() == 3)
    assert((try raster.alpha_at(0, 0)) == 0.0)
    try raster.dab(2.5, 1.5, 4.0, 0.0, gpu.Color(1.0, 0.0, 0.0))
    assert((try raster.alpha_at(2, 1)) == 1.0)
    assert((try raster.alpha_at(1, 1)) == 0.5)
    assert((try raster.alpha_at(0, 1)) == 0.0)
    try raster.dab(2.5, 1.5, 4.0, 0.0, gpu.Color(0.0, 0.0, 1.0))
    let mixed = raster.pixels[6]
    assert(mixed.red == (f32)0.25 and mixed.blue == (f32)0.5 and mixed.alpha == (f32)0.75)
    try raster.dab(2.5, 1.5, 4.0, 0.0, gpu.Color(), erase = true)
    assert((try raster.alpha_at(1, 1)) == 0.375)
    assert((try raster.alpha_at(2, 1)) == 0.0)
    assert(raster.pixels[6].red == (f32)0.125 and raster.pixels[6].blue == (f32)0.25)
    raster.clear()
    for pixel in raster.pixels:
        assert(rgba(pixel) == 0 and pixel.alpha == (f32)0.0)
    try raster.dab(-1.0e300, 1.0e300, 512.0, 1.0, gpu.Color())
    try raster.dab(0.5, 0.5, 1.0, 1.0, gpu.Color(0.0, 1.0, 0.0))
    assert((try raster.alpha_at(0, 0)) == 1.0)
    assert((try raster.alpha_at(1, 0)) == 0.0)

test "raster draw on a standalone frame records nothing":
    var raster = try Raster(3, 2)
    defer raster.close()
    try raster.fill(gpu.Color(1.0, 0.0, 0.0))
    var frame = try gpu.Frame(window.Size(160.0, 120.0, 320.0, 240.0, 2.0))
    defer frame.close()
    let target = try frame.target()
    defer target.release()
    # A standalone frame has no device: the draw records nothing and succeeds.
    try raster.draw(target, gpu.Rect(0.0, 0.0, 160.0, 120.0))
    assert(not raster.cache.has_texture())

test "raster deep copies, resizing, composite opacity and self composite":
    let source = try interop.Reference[Raster].adopt(new Raster(2, 2) in memory.heap, raster_type, memory.heap)
    defer source.release()
    try source.value().dab(0.5, 0.5, 1.0, 1.0, gpu.Color(1.0, 0.0, 0.0))
    try source.value().dab(1.5, 1.5, 1.0, 1.0, gpu.Color(0.0, 0.0, 1.0))
    let copied = try source.value().copy()
    defer copied.release()
    let grown = try source.value().resized(3, 4)
    defer grown.release()
    assert(grown.value().width() == 3 and grown.value().height() == 4)
    assert((try grown.value().alpha_at(1, 1)) == 1.0)
    assert((try grown.value().alpha_at(2, 1)) == 0.0 and (try grown.value().alpha_at(0, 3)) == 0.0)
    assert(grown.value().pixels[4].blue == (f32)1.0)
    let shrunk = try source.value().resized(1, 1)
    defer shrunk.release()
    assert(shrunk.value().pixels[0].red == (f32)1.0)
    source.value().clear()
    assert((try copied.value().alpha_at(0, 0)) == 1.0)
    try source.value().composite(copied, 0.5)
    assert((try source.value().alpha_at(0, 0)) == 0.5)
    try source.value().composite(source, 0.5)
    assert((try source.value().alpha_at(0, 0)) == 0.625)
    assert(source.value().pixels[0].red == (f32)0.625)
    try source.value().composite(copied, 0.0)
    assert((try source.value().alpha_at(0, 0)) == 0.625)
    try source.value().composite(copied)
    assert((try source.value().alpha_at(0, 0)) == 1.0)

test "raster rejects invalid dimensions, coordinates and brush parameters":
    for width in [-1, 0, 16385, 9223372036854775807]:
        var rejected = false
        var raster = Raster(width, 1) catch failure:
            assert(failure.code == result.invalid)
            rejected = true
            recover try Raster(1, 1)
        assert(rejected)
        raster.close()
    var rejected = false
    var oversized = Raster(16384, 4097) catch failure:
        assert(failure.code == result.invalid)
        rejected = true
        recover try Raster(1, 1)
    assert(rejected)
    oversized.close()
    var maximum = try Raster(2048, 512)
    defer maximum.close()
    var raster = try Raster(1, 1)
    defer raster.close()
    for diameter in [0.0, 513.0, math.nan, math.infinity]:
        rejected = false
        raster.dab(0.5, 0.5, diameter, 1.0, gpu.Color()) catch failure:
            assert(failure.code == result.invalid)
            rejected = true
        assert(rejected)
    for hardness in [-0.1, 1.1, math.nan, math.infinity]:
        rejected = false
        raster.dab(0.5, 0.5, 1.0, hardness, gpu.Color()) catch failure:
            assert(failure.code == result.invalid)
            rejected = true
        assert(rejected)
    for coordinate in [math.nan, math.infinity]:
        rejected = false
        raster.dab(coordinate, 0.5, 1.0, 1.0, gpu.Color()) catch failure:
            assert(failure.code == result.invalid)
            rejected = true
        assert(rejected)
    for color in [gpu.Color(-0.1, 0.0, 0.0), gpu.Color(0.0, math.nan, 0.0), gpu.Color(0.0, 0.0, 1.1)]:
        rejected = false
        raster.dab(0.5, 0.5, 1.0, 1.0, color) catch failure:
            assert(failure.code == result.invalid)
            rejected = true
        assert(rejected)
    let same = try raster.copy()
    defer same.release()
    for opacity in [-0.1, 1.1, math.nan, math.infinity]:
        rejected = false
        raster.composite(same, opacity) catch failure:
            assert(failure.code == result.invalid)
            rejected = true
        assert(rejected)
    for coordinate in [-1, 1]:
        rejected = false
        _ = raster.alpha_at(coordinate, 0) catch failure:
            assert(failure.code == result.invalid)
            rejected = true
            recover 0.0
        assert(rejected)
    let other = try interop.Reference[Raster].adopt(new Raster(2, 1) in memory.heap, raster_type, memory.heap)
    defer other.release()
    rejected = false
    raster.composite(other) catch failure:
        assert(failure.code == result.invalid)
        rejected = true
    assert(rejected)
    other.close()
    rejected = false
    raster.composite(other) catch failure:
        assert(failure.code == interop.invalid)
        rejected = true
    assert(rejected)
    raster.close()
    raster.close()
    rejected = false
    _ = raster.alpha_at(0, 0) catch failure:
        assert(failure.code == result.invalid)
        rejected = true
        recover 0.0
    assert(rejected)