Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-gpu

Source of release 0.5.3

0.5.3 / src / gpu / frame.lucb

#==============================================================================================
#
#   frame - Render regions and recorded frames
#
#   DESCRIPTION:
#       A logical rectangle in points, relative to its parent's render region.
#
#==============================================================================================

## A logical rectangle in points, relative to its parent's render region.
pub struct Rect:
    ## The left edge in points.
    pub var x: f64
    ## The top edge in points.
    pub var y: f64
    ## The width in points.
    pub var width: f64
    ## The height in points.
    pub var height: f64

## Frames begun so far, and how many are recording now: a frame's serial
## tells whether two draws went into one frame, and a count above one means a
## frame (a texture's, say) is recording inside another. Main thread only.
var frames_begun: u64 = 0
var frames_open: usize = 0

## How many frames are recording now: more than one while a texture's frame
## records inside a window's.
pub func open_frames() -> usize:
    return frames_open

struct FrameState:
    var canvas: Canvas
    var size: window.Size
    ## This frame's number among every frame begun, and whether it still
    ## counts as open.
    var serial: u64 = 0
    var counted: bool = false
    # Presentation hooks are installed only by Surface.frame. Portable recording
    # and its ownership metadata therefore have no native backend dependency.
    var presentation: void*?
    # The device a surface or texture frame draws on; a standalone frame has none.
    var device: DeviceState*?
    # A texture frame's texel format; none for a surface or standalone frame.
    var format: Format?
    # How a surface frame's target blends; linear for the others.
    var blending: Blending
    var validate: (func(void*, window.Size) -> unit!)?
    var submit: (func(void*, Canvas, Color) -> PresentResult!)?
    var release: (func(void*) -> unit)?
    var ended: bool

    func check() -> !:
        if self.ended:
            error(frame_finished, "the recording frame is finished")
        if let context = self.presentation:
            try (self.validate else trap("frame presentation has no validator"))(context, self.size)

    func close():
        self.ended = true
        if self.counted:
            self.counted = false
            frames_open -= 1
        self.canvas.destroy()
        if let context = self.presentation:
            self.presentation = none
            (self.release else trap("frame presentation has no release operation"))(context)

let frame_state_type: interop.Type[FrameState] = interop.Type[FrameState]("GPU frame state", FrameState.close, closeable = true)

# mark: Frames and render targets =============================================================

## One recording scope. A standalone Frame records portable commands for a
## supplied extent. Surface.frame attaches one to a presentation surface.
## Base copies borrow; Luce owns the exported object through ordinary ARC.
pub struct Frame:
    var state: interop.Reference[FrameState]?
    var lease: interop.Lease?
    var submitted: Submission

    ## Begin a standalone frame recording commands for `size`.
    pub func init(size: window.Size) -> !:
        try check_frame_size(size)
        frames_begun += 1
        let native = try new FrameState(canvas = Canvas(), size = size, serial = frames_begun, counted = true)
        frames_open += 1
        let state = try interop.Reference[FrameState].adopt(native, frame_state_type)
        errdefer state.release()
        let lease = try state.lease()
        self.state = state
        self.lease = lease
        self.submitted = Submission()

    func state_value() -> interop.Reference[FrameState]!:
        return self.state else error(frame_finished, "the recording frame is finished")

    ## The frame's extent in logical points and backing pixels.
    pub func size() -> window.Size!:
        let state = try self.state_value()
        try state.value().check()
        return state.value().size

    ## The root drawing target covering the whole frame.
    pub func target() -> interop.View[RenderTarget]!:
        let state = (try self.state_value()).value()
        try state.check()
        let lease = self.lease else error(frame_finished, "the recording frame is finished")
        let region = Rect(width = state.size.width, height = state.size.height)
        let clip = Clip(width = (u32)state.size.pixel_width, height = (u32)state.size.pixel_height)
        return try interop.View[RenderTarget].make(RenderTarget(state, lease, region, clip), render_target_type, lease)

    ## End the scope on success or failure. A frame records the extent acquired at
    ## its start; resize requires a new frame instead of stretching stale commands.
    pub func present(color: Color = Color()) -> PresentResult!:
        let state = (try self.state_value()).value()
        defer self.close()
        try state.check()
        try check_color(color)
        let context = state.presentation else error(unavailable, "a standalone frame has no presentation surface")
        let submit = state.submit else trap("frame presentation has no submit operation")
        (self.lease else trap("an open frame has no lease")).invalidate()
        state.ended = true
        let result = try submit(context, state.canvas, color)
        if result == PresentResult.submitted:
            if let device = state.device: self.submitted = backend_latest_submission(device)
        return result

    ## The frame's submission on its device's queue once `present` submitted
    ## it, for `Device.done`, `wait` and `gpu_time`; none (zero) for a skipped
    ## or standalone frame.
    pub func submission() -> Submission:
        return self.submitted

    ## End the recording scope, releasing its resources.
    pub func close():
        if let lease = self.lease:
            self.lease = none
            lease.invalidate()
            lease.release()
        if let state = self.state:
            self.state = none
            state.close()
            state.release()

    ## Visit the frame's owned objects for the interop garbage tracer.
    pub func trace(visit: func(ownership.Object*, void*) -> unit, context: void*):
        if let state = self.state:
            state.trace(visit, context)
        if let lease = self.lease:
            lease.trace(visit, context)

## The interop type of an exported `Frame`.
pub let frame_type: interop.Type[Frame] = interop.Type[Frame]("GPU frame", Frame.close, Frame.trace, closeable = true)

## A checked drawing view. Its private canvas never escapes. Child regions
## intersect their parent's clip, while vertices retain their own clip coordinates.
pub struct RenderTarget:
    var frame: FrameState*
    var lease: interop.Lease
    var rectangle: Rect
    var clipping: Clip

    ## The number of the frame this target draws into: draws sharing it are
    ## one frame's, recorded together and submitted when it presents.
    pub func frame_serial() -> u64:
        return self.frame.serial

    ## The target's extent in logical points and backing pixels.
    pub func size() -> window.Size!:
        try self.frame.check()
        let scale_x = frame_scale(self.frame.size.pixel_width, self.frame.size.width)
        let scale_y = frame_scale(self.frame.size.pixel_height, self.frame.size.height)
        return window.Size(width = self.rectangle.width, height = self.rectangle.height,
                           pixel_width = self.rectangle.width * scale_x, pixel_height = self.rectangle.height * scale_y,
                           scale = self.frame.size.scale)

    ## Where this target lies in its frame, in points: what a client shader
    ## reading `gl_FragCoord` needs to map frame pixels back to this target.
    pub func placement() -> Rect!:
        try self.frame.check()
        return self.rectangle

    ## A child target for `rectangle`, its clip intersected with this target's.
    pub func region(rectangle: Rect) -> interop.View[RenderTarget]!:
        try self.frame.check()
        try check_region(rectangle)
        let absolute = Rect(self.rectangle.x + rectangle.x, self.rectangle.y + rectangle.y, rectangle.width, rectangle.height)
        try check_region(absolute)
        let scale_x = frame_scale(self.frame.size.pixel_width, self.frame.size.width)
        let scale_y = frame_scale(self.frame.size.pixel_height, self.frame.size.height)
        let clip = intersect_clip(self.clipping, absolute, scale_x, scale_y)
        return try interop.View[RenderTarget].make(RenderTarget(self.frame, self.lease, absolute, clip), render_target_type, self.lease)

    ## Narrow drawing without changing the coordinate system. Useful when a
    ## layout clips a child whose geometry is already in its parent's coordinates.
    pub func clipped(rectangle: Rect) -> interop.View[RenderTarget]!:
        try self.frame.check()
        try check_region(rectangle)
        let absolute = Rect(self.rectangle.x + rectangle.x, self.rectangle.y + rectangle.y, rectangle.width, rectangle.height)
        try check_region(absolute)
        let scale_x = frame_scale(self.frame.size.pixel_width, self.frame.size.width)
        let scale_y = frame_scale(self.frame.size.pixel_height, self.frame.size.height)
        let clip = intersect_clip(self.clipping, absolute, scale_x, scale_y)
        return try interop.View[RenderTarget].make(RenderTarget(self.frame, self.lease, self.rectangle, clip), render_target_type, self.lease)

    ## Raise this frame's shared vertex budget, without allocating storage.
    ## Intended for dense 3D targets; ordinary UI frames retain their default.
    pub func allow_vertices(count: usize) -> !:
        try self.frame.check()
        try self.frame.canvas.allow_vertices(count)

    ## Raise this frame's shared draw limit from 4096 up to `count` (at most
    ## 65536), without allocating storage: for a frame several clients fill,
    ## such as a window whose page and interface draw into it together.
    pub func allow_draws(count: usize) -> !:
        try self.frame.check()
        try self.frame.canvas.allow_draws(count)

    ## How the target blends: `encoded` on an encoded surface, `linear` on a
    ## linear one and on textures (whose formats say how they store values).
    pub func blending() -> Blending!:
        try self.frame.check()
        return self.frame.blending

    ## The texel format of the texture this target draws into, or none for a
    ## presentation surface (or a standalone frame): the format a client
    ## pipeline drawing here must be made for.
    pub func pixel_format() -> Format?!:
        try self.frame.check()
        return self.frame.format

    ## Record clip-space triangles. Optional slope_bias is in logical pixels,
    ## scaled to the backing target; zero preserves ordinary surface depth.
    pub func triangles(vertices: const Vertex[], depth: bool = false, slope_bias: f64 = 0.0) -> !:
        try self.frame.check()
        let scale_x = frame_scale(self.frame.size.pixel_width, self.frame.size.width)
        let scale_y = frame_scale(self.frame.size.pixel_height, self.frame.size.height)
        let viewport = Viewport(self.rectangle.x * scale_x, self.rectangle.y * scale_y,
                                self.rectangle.width * scale_x, self.rectangle.height * scale_y)
        try self.frame.canvas.triangles(vertices, self.clipping, depth, viewport, slope_bias * math.max(scale_x,scale_y))

    ## Draw a top-down, tightly packed 8-bit coverage image tinted with a linear
    ## color. Pixels are copied into the frame; the caller can reuse them at once.
    ## Sampling is bilinear and clipped to this target, on every GPU backend.
    pub func mask(pixels: const u8[], width: u32, height: u32, rectangle: Rect, color: Color) -> !:
        try self.frame.check()
        try check_region(rectangle)
        let scale_x = frame_scale(self.frame.size.pixel_width, self.frame.size.width)
        let scale_y = frame_scale(self.frame.size.pixel_height, self.frame.size.height)
        let destination = Rect((self.rectangle.x + rectangle.x) * scale_x,
                               (self.rectangle.y + rectangle.y) * scale_y, rectangle.width * scale_x, rectangle.height * scale_y)
        try canvas_mask(&self.frame.canvas, pixels, width, height, destination, color,
                        self.clipping, self.frame.size.pixel_width, self.frame.size.pixel_height)

## The interop view type of a `RenderTarget`.
pub let render_target_type: interop.ViewType[RenderTarget] = interop.ViewType[RenderTarget]("GPU render target")

# mark: Base-only drawing on a target ==========================================================
# Textures and devices are Base resources, so these are functions rather than
# methods: a method mentioning them would hide the whole view from Luce.

## An owned handle to the device `target`'s frame draws on, for creating
## textures to draw into it; destroy it like any device handle. A standalone
## frame has no device and returns `unavailable`.
pub func device_of(target: const RenderTarget*) -> Device!:
    try target.frame.check()
    let state = target.frame.device else error(unavailable, "a standalone frame draws on no device")
    state.references += 1
    return Device(state = state)

## Draw `source` texels of `texture` (the whole texture by default) scaled onto
## `rectangle` of `target` in points, multiplied by `opacity`, sampled with
## `filter` and clipped to the target. Texels are straight alpha and composite
## over what is already drawn.
pub func draw_image(target: const RenderTarget*, texture: Texture, rectangle: Rect, source: Region? = none, opacity: f64 = 1.0, filter: Filter = Filter.linear) -> !:
    try target.frame.check()
    try check_region(rectangle)
    let state = try drawable_texture(texture)
    let area = source else Region(0, 0, state.width, state.height)
    let scale_x = frame_scale(target.frame.size.pixel_width, target.frame.size.width)
    let scale_y = frame_scale(target.frame.size.pixel_height, target.frame.size.height)
    let destination = Rect((target.rectangle.x + rectangle.x) * scale_x,
                           (target.rectangle.y + rectangle.y) * scale_y, rectangle.width * scale_x, rectangle.height * scale_y)
    try target.frame.canvas.image(state, area, destination, opacity, filter, target.clipping,
                                  target.frame.size.pixel_width, target.frame.size.pixel_height)

## Copy `source` texels of `texture` (the whole texture by default) scaled onto
## `rectangle` of `target` in points, sampled with `filter`, written as they are
## stored: straight alpha stays straight and premultiplied stays premultiplied,
## where `draw_image` would premultiply straight texels. With `straighten`, the
## texels are premultiplied and are written straight. Nothing composites: this
## fills a target cleared to transparent with pieces that do not overlap, as
## when tiles are moved, flattened or resampled.
pub func copy_image(target: const RenderTarget*, texture: Texture, rectangle: Rect, source: Region? = none, filter: Filter = Filter.nearest, straighten: bool = false) -> !:
    try target.frame.check()
    try check_region(rectangle)
    let state = try drawable_texture(texture)
    let area = source else Region(0, 0, state.width, state.height)
    let scale_x = frame_scale(target.frame.size.pixel_width, target.frame.size.width)
    let scale_y = frame_scale(target.frame.size.pixel_height, target.frame.size.height)
    let destination = Rect((target.rectangle.x + rectangle.x) * scale_x,
                           (target.rectangle.y + rectangle.y) * scale_y, rectangle.width * scale_x, rectangle.height * scale_y)
    try target.frame.canvas.image(state, area, destination, 1.0, filter, target.clipping,
                                  target.frame.size.pixel_width, target.frame.size.pixel_height, draw_straightened if straighten else draw_copied)

## A texture image draws can sample as color: any format but r32_uint.
func drawable_texture(texture: Texture) -> TextureState*!:
    let state = try texture.checked()
    if state.format == Format.r32_uint:
        error(invalid_geometry, "an r32_uint texture holds integers; draw it through a kernel or a shader")
    return state

func frame_scale(pixels: f64, points: f64) -> f64:
    return pixels / points if points > 0.0 else 0.0

func check_frame_size(size: window.Size) -> !:
    if not (size.width >= 0.0 and size.width <= 16384.0 and size.height >= 0.0 and size.height <= 16384.0 and size.pixel_width >= 0.0 and size.pixel_width <= 16384.0 and size.pixel_height >= 0.0 and size.pixel_height <= 16384.0 and size.scale > 0.0 and size.scale <= 16.0):
        error(invalid_geometry, "frame extents must be finite, nonnegative and at most 16384 pixels/points")
    if math.floor(size.pixel_width) != size.pixel_width or math.floor(size.pixel_height) != size.pixel_height:
        error(invalid_geometry, "frame backing extents must be whole pixels")
    if (size.width == 0.0) != (size.pixel_width == 0.0) or (size.height == 0.0) != (size.pixel_height == 0.0):
        error(invalid_geometry, "empty logical and backing dimensions must agree")

func check_region(region: Rect) -> !:
    if not (region.x >= -16384.0 and region.x <= 16384.0 and region.y >= -16384.0 and region.y <= 16384.0 and region.width >= 0.0 and region.width <= 16384.0 and region.height >= 0.0 and region.height <= 16384.0):
        error(invalid_geometry, "render regions need finite origins and nonnegative extents")

func intersect_clip(parent: Clip, region: Rect, scale_x: f64, scale_y: f64) -> Clip:
    let left = math.floor(math.max((f64)parent.x, region.x * scale_x))
    let top = math.floor(math.max((f64)parent.y, region.y * scale_y))
    let right = math.ceil(math.min((f64)parent.x + (f64)parent.width, (region.x + region.width) * scale_x))
    let bottom = math.ceil(math.min((f64)parent.y + (f64)parent.height, (region.y + region.height) * scale_y))
    if right <= left or bottom <= top:
        return Clip()
    return Clip((u32)left, (u32)top, (u32)(right - left), (u32)(bottom - top))

## One rectangle of an instanced draw (`shade_instances`): where it goes, in
## points of the target like `shade`'s rectangle (x, y, width, height), and 12
## floats its fragment stage reads flat at locations 1..3 (a vec4 each).
pub struct ShadeInstance:
    ## The rectangle: x, y, width and height in points.
    pub var rect: f32[4]
    ## The instance's values for the fragment stage, locations 1..3.
    pub var data: f32[12]

## Draw every rectangle of `instances` on `target` with a client `pipeline` in
## one draw: as `shade` draws one rectangle, with the same uniforms, images and
## filter for all, and each instance's `data` at the fragment's locations 1..3
## (flat; `shade` leaves them zero). The vertex color is opaque white. One call
## counts as one draw against the frame's draw limit, however many rectangles
## it holds (at most 1,048,576 in a frame); rectangles draw in order, clipped
## like every other draw. Instances are copied; the caller may reuse them.
pub func shade_instances(target: const RenderTarget*, pipeline: Pipeline, instances: const ShadeInstance[], uniforms: const u8[]? = none,
                         images: const Texture[]? = none, filter: Filter = Filter.linear) -> !:
    try target.frame.check()
    let state = try pipeline.checked()
    var sampled: TextureState*?[4]
    var count: usize = 0
    if let list = images:
        for image in list:
            if count == image_limit:
                error(invalid_geometry, "a draw samples at most 4 images")
            sampled[count] = try image.checked()
            count += 1
    var bytes: u8[128]
    var byte_count: usize = 0
    if let data = uniforms:
        if data.length > uniform_limit:
            error(invalid_geometry, "a draw carries at most 128 uniform bytes")
        memory.copy(bytes[..<data.length], data, data.length)
        byte_count = data.length
    if instances.length == 0:
        return
    let pixel_width = target.frame.size.pixel_width
    let pixel_height = target.frame.size.pixel_height
    if pixel_width <= 0.0 or pixel_height <= 0.0:
        return
    let scale_x = frame_scale(pixel_width, target.frame.size.width)
    let scale_y = frame_scale(pixel_height, target.frame.size.height)
    # Rectangles to clip space (y up, as triangles take them), in place in a copy.
    let placed = try new ShadeInstance[instances.length] --- in memory.heap
    defer free(placed) in memory.heap
    for index in 0..<instances.length:
        let instance = instances[index]
        let r = instance.rect
        if not (math32.is_finite(r[0]) and math32.is_finite(r[1]) and r[2] >= 0.0 and r[2] <= 16384.0 and r[3] >= 0.0 and r[3] <= 16384.0 and r[0] >= -16384.0 and r[0] <= 16384.0 and r[1] >= -16384.0 and r[1] <= 16384.0):
            error(invalid_geometry, "instance rectangles need finite origins and extents in 0..16384")
        for value in instance.data:
            if not math32.is_finite(value):
                error(invalid_geometry, "instance data must be finite")
        let x = (target.rectangle.x + (f64)r[0]) * scale_x
        let y = (target.rectangle.y + (f64)r[1]) * scale_y
        let right = x + (f64)r[2] * scale_x
        let bottom = y + (f64)r[3] * scale_y
        placed[index] = ShadeInstance(rect = [(f32)(x * 2.0 / pixel_width - 1.0), (f32)(1.0 - y * 2.0 / pixel_height),
                                              (f32)(right * 2.0 / pixel_width - 1.0), (f32)(1.0 - bottom * 2.0 / pixel_height)], data = instance.data)
    try target.frame.canvas.shade_instances(state, placed, bytes[..<byte_count], sampled[..<count], filter, target.clipping)

## Draw clip-space `vertices` (whole triangles, mapped onto `target` as
## `RenderTarget.triangles` maps them) with a client `pipeline`: `uniforms`
## fill its push-constant block, `images` its sampled bindings 1.., and each
## vertex's color (finite, 0..1) reaches the fragment stage at location 0,
## interpolated with perspective. A pipeline made with `depth_test` is hidden
## behind nearer depth-tested draws and writes no depth. Clipped like every
## other draw; vertices are copied.
pub func shade_triangles(target: const RenderTarget*, pipeline: Pipeline, vertices: const Vertex[], uniforms: const u8[]? = none,
                         images: const Texture[]? = none, filter: Filter = Filter.linear) -> !:
    try target.frame.check()
    let state = try pipeline.checked()
    var sampled: TextureState*?[4]
    var count: usize = 0
    if let list = images:
        for image in list:
            if count == image_limit:
                error(invalid_geometry, "a draw samples at most 4 images")
            sampled[count] = try image.checked()
            count += 1
    var bytes: u8[128]
    var byte_count: usize = 0
    if let data = uniforms:
        if data.length > uniform_limit:
            error(invalid_geometry, "a draw carries at most 128 uniform bytes")
        memory.copy(bytes[..<data.length], data, data.length)
        byte_count = data.length
    let scale_x = frame_scale(target.frame.size.pixel_width, target.frame.size.width)
    let scale_y = frame_scale(target.frame.size.pixel_height, target.frame.size.height)
    let viewport = Viewport(target.rectangle.x * scale_x, target.rectangle.y * scale_y,
                            target.rectangle.width * scale_x, target.rectangle.height * scale_y)
    try target.frame.canvas.shade_triangles(state, vertices, bytes[..<byte_count], sampled[..<count], filter, target.clipping, viewport)

## Draw `rectangle` of `target` (in points) with a client `pipeline`: `uniforms`
## fill its push-constant block, `images` its sampled bindings 1.., all with
## `filter`; `color` is the vertex color each fragment starts from. Clipped
## like every other draw.
pub func shade(target: const RenderTarget*, pipeline: Pipeline, rectangle: Rect, uniforms: const u8[]? = none, images: const Texture[]? = none,
               filter: Filter = Filter.linear, color: Color = Color(1.0, 1.0, 1.0, 1.0)) -> !:
    try target.frame.check()
    try check_region(rectangle)
    let state = try pipeline.checked()
    var sampled: TextureState*?[4]
    var count: usize = 0
    if let list = images:
        for image in list:
            if count == image_limit:
                error(invalid_geometry, "a draw samples at most 4 images")
            sampled[count] = try image.checked()
            count += 1
    var bytes: u8[128]
    var byte_count: usize = 0
    if let data = uniforms:
        if data.length > uniform_limit:
            error(invalid_geometry, "a draw carries at most 128 uniform bytes")
        memory.copy(bytes[..<data.length], data, data.length)
        byte_count = data.length
    let scale_x = frame_scale(target.frame.size.pixel_width, target.frame.size.width)
    let scale_y = frame_scale(target.frame.size.pixel_height, target.frame.size.height)
    let destination = Rect((target.rectangle.x + rectangle.x) * scale_x,
                           (target.rectangle.y + rectangle.y) * scale_y, rectangle.width * scale_x, rectangle.height * scale_y)
    try target.frame.canvas.shade(state, destination, color, bytes[..<byte_count], sampled[..<count], filter, target.clipping,
                                  target.frame.size.pixel_width, target.frame.size.pixel_height)