dymokomi/luce-gpu
Source of release 0.5.7
0.5.7 / 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
## Whether the surface or texture still takes this frame's drawing; with
## `extent`, also whether its size is still the one the frame began at.
var validate: (func(void*, window.Size, bool) -> unit!)?
var submit: (func(void*, Canvas, Color) -> PresentResult!)?
var release: (func(void*) -> unit)?
## Takes the canvas back when the frame closes, for the next frame to record
## into: storage regrown from nothing each frame is the alternative.
var keep: (func(void*, Canvas) -> unit)?
var ended: bool
## Whether the frame still records. Draws ask without `extent`: the window's
## size is read once when the frame hands out its target and once at present,
## which drops a frame the window outgrew, not before each of its draws.
func check(extent: bool = false) -> !:
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, extent)
func close():
self.ended = true
if self.counted:
self.counted = false
frames_open -= 1
let canvas = self.canvas
self.canvas = Canvas()
if let context = self.presentation:
self.presentation = none
if let keep = self.keep:
keep(context, canvas)
else:
var dropped = canvas
dropped.destroy()
(self.release else trap("frame presentation has no release operation"))(context)
else:
var dropped = canvas
dropped.destroy()
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(extent = true)
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(extent = true)
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(extent = true)
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)