hal/application-capture.lisp
Established once before prepare-capture. A film deliberately keeps
this exact relationship and extent for its whole frame sequence.
Shared resources remain visible to cleanup-capture while still alive.
This lets an application evict target-keyed views or frame state before
the target itself is invalidated.
A deliberately untyped application-owned cell for saving pause state or another small piece of lifecycle information across the transaction.
One screenshot or film transaction around an application-owned frame.
The object is control-plane state, allocated once per capture. TARGET and READBACK-BUFFER are dense GPU resources owned and destroyed by the shared capture implementation.
One shutdown-aware semantic reservation lane for an application's captures.
OPEN admits one capture. SHUTTING-DOWN is terminal: new captures fail and a non-canvas teardown owner may wait for the existing capture to leave.
Reserve capture's application without holding a lock across its work.
Signal after leaving the semantic mutex so a handler may safely inspect the capture identities or choose another application.
Release capture's exact reservation without disturbing a later owner.
Return true once application's capture admission has closed terminally.
Close application's capture admission without waiting for active work.
This is safe on a canvas thread. Return true when this call closed admission, or NIL when shutdown had already been requested.
Atomically call small publication function only while admission is open.
function runs under application's short capture gate lock and must not block or
reenter the capture gate. Return true when it ran, NIL after shutdown began.
Return indicator's value in capture's application-owned option plist.
Return application's open luv canvas for a native GPU capture.
The shared implementation derives the presentation context and device through
canvas-context and context-device; applications do not repeat those hooks.
Close application's capture gate and wait for its active capture to leave.
The caller must run beside the canvas thread while a capture is active. The active capture may still need that thread for its final frame and cache cleanup; waiting on the canvas thread would deadlock it and is rejected explicitly.
Prepare application for capture on the calling thread.
This is the place to wait for application-specific readiness and to quiesce a
normal frame loop. capture's canvas, context, device, extent, and format are
already established, but its shared GPU resources do not exist yet.
cleanup-capture is called even when this method exits by error.
Advance application-owned work before offscreen film frame frame-index.
This runs on the film caller after BEFORE-FRAME and before GPU encoding. A streaming application can publish completed products here without putting its world model or simulation policy into the shared capture loop.
Encode application's complete visible frame into offscreen target.
This method runs on the canvas's native frame thread. encoder is open and
owned by the shared implementation; extent is the fixed two-dimensional
capture extent. The method must not finish or submit encoder and must not
destroy target. Its primary value is optional application metadata returned
by capture-application-screenshot.
Undo application-owned capture preparation on the calling thread.
When shared GPU resources were created they are still alive and visible through CAPTURE-TARGET and CAPTURE-READBACK-BUFFER during this method. Applications with target-keyed GPU caches should synchronously evict those entries on their canvas thread here. Shared resources are destroyed after this method returns. The method must not destroy the shared target or readback buffer.
Application capture requires an RGBA8 or BGRA8 color ~ format, got ~S.
Reject a resize or context replacement before it becomes a GPU mismatch.
Luvcraft copies its resolved presentation image into TARGET, while
luft renders directly through a view. The shared readback needs
COPY-SRC in either case.
Render and synchronously read one frame from an established capture.
Call function with capture while owning its offscreen GPU resources.
cleanup-capture also runs for a partially completed
preparation.
Application cleanup runs first because target-keyed views must not outlive the target. Every shared object still gets an attempt, and a body failure stays primary if any of these steps also fails.
Render application offscreen and write its native-resolution PNG.
options is an application-owned property list interpreted by the capture
protocol methods. Return pathname, packed pixels, width, height, color format,
and the optional metadata value from encode-capture-frame.
Return the wall-clock wait before frame-index's successor deadline.
Write frame-count real-time-paced offscreen frames through writer.
A stop owner has closed admission and is waiting beside the canvas thread. Finish at most the current frame, then let cleanup release the reservation promptly. A film always emits its first frame so ffmpeg receives a valid stream even when shutdown races its preparation.
Absolute deadlines prevent encoding variance from accumulating drift.
Film application offscreen into a real-time-paced H.264 MP4.
The application chooses readiness, advancement, frame meaning, and cleanup;
the shared implementation owns the fixed-size target, readback, ffmpeg writer,
and absolute wall-clock pacing. Return pathname and the encoded frame count.
One screenshot or film transaction around an application-owned frame. The object is control-plane state, allocated once per capture. TARGET and READBACK-BUFFER are dense GPU resources owned and destroyed by the shared capture implementation.
(application capture)Prepare APPLICATION for CAPTURE on the calling thread. This is the place to wait for application-specific readiness and to quiesce a normal frame loop. CAPTURE's canvas, context, device, extent, and format are already established, but its shared GPU resources do not exist yet. CLEANUP-CAPTURE is called even when…
A native destination with a lifetime and frame clock.
A MuPDF context: its allocator, its store, and its error stack.
(application capture)Undo application-owned CAPTURE preparation on the calling thread. When shared GPU resources were created they are still alive and visible through CAPTURE-TARGET and CAPTURE-READBACK-BUFFER during this method. Applications with target-keyed GPU caches should synchronously evict those entries on their canvas thread…
One shutdown-aware semantic reservation lane for an application's captures. OPEN admits one capture. SHUTTING-DOWN is terminal: new captures fail and a non-canvas teardown owner may wait for the existing capture to leave.
(application)Logical disjunction of tests and raw truth values.
(capture)(coordinator capture)(function capture)(application)(application)Close APPLICATION's capture admission without waiting for active work. This is safe on a canvas thread. Return true when this call closed admission, or NIL when shutdown had already been requested.
(application function)Atomically call small publication FUNCTION only while admission is open. FUNCTION runs under APPLICATION's short capture gate lock and must not block or reenter the capture gate. Return true when it ran, NIL after shutdown began.
(options)Test whether two compatible scalars are equal.
Logical conjunction of tests and raw truth values.
((agent application-agent) &key)(capture indicator &optional default)(application)Return APPLICATION's open LUV canvas for a native GPU capture. The shared implementation derives the presentation context and device through CANVAS-CONTEXT and CONTEXT-DEVICE; applications do not repeat those hooks.
A GPU presentation relationship configured for a canvas.
(context)Return the GPU device used by CONTEXT, or NIL before first configuration.
(application)Close APPLICATION's capture gate and wait for its active capture to leave. The caller must run beside the canvas thread while a capture is active. The active capture may still need that thread for its final frame and cache cleanup; waiting on the canvas thread would deadlock it and is rejected explicitly.
(canvas)Return true when the caller is CANVAS's native event/frame thread.
(application capture frame-index)Advance application-owned work before offscreen film frame FRAME-INDEX. This runs on the film caller after BEFORE-FRAME and before GPU encoding. A streaming application can publish completed products here without putting its world model or simulation policy into the shared capture loop.
(application capture encoder target extent)Encode APPLICATION's complete visible frame into offscreen TARGET. This method runs on the canvas's native frame thread. ENCODER is open and owned by the shared implementation; EXTENT is the fixed two-dimensional capture extent. The method must not finish or submit ENCODER and must not destroy TARGET. Its primary…
(application pathname &key options (label "application screenshot"))Render APPLICATION offscreen and write its native-resolution PNG. OPTIONS is an application-owned property list interpreted by the capture protocol methods. Return PATHNAME, packed pixels, width, height, color format, and the optional metadata value from ENCODE-CAPTURE-FRAME.
(format)(extent)A canonical product of symbolic base dimensions raised to rational powers.
(capture)(context)Return CONTEXT's configured drawable extent as (WIDTH HEIGHT), or NIL.
(capture noun)(capture)(device descriptor)Asks the DEVICE for a handle to newly created instance of some object fulfilling the DESCRIPTOR.
(capture)Multiplication and scalar scaling.
(capture)(canvas function)Run FUNCTION with a timestamp on CANVAS's native frame/event thread. The initial native implementation is synchronous: the caller waits for the function's values. The protocol leaves room for a real frame scheduler.
(protected-form &body cleanup-forms)(queue work)Schedule some command buffers on the QUEUE. Submission is asynchronous: returning does not mean the GPU has finished the work, only that the implementation retains everything the work depends on until it completes. Use SUBMITTED-WORK-DONE to wait.
(name &body body)(handle)Logically invalidate HANDLE immediately. Native teardown may be deferred until submitted work which captured HANDLE has completed.
(buffer &key offset size)Wait for BUFFER's device queue and copy mapped bytes back to the host.
(function capture)(pathname pixels width height format)Division of two represented quantities.
Convert one scalar float or unsigned value to a 32-bit float.
(start-seconds frame-index frame-rate now-seconds)Subtraction or unary negation.
Addition over compatible quantities.
(writer capture frame-count frame-rate
&key before-frame progress-function
(clock-function #'capture-clock-seconds)
(sleep-function #'sleep))An explicitly owned AVFrame.
Logical negation of one test or raw truth value.
(application pathname
&key (seconds 8) (frame-rate 30) before-frame progress-function options
(label "application film"))Film APPLICATION offscreen into a real-time-paced H.264 MP4. The application chooses readiness, advancement, frame meaning, and cleanup; the shared implementation owns the fixed-size target, readback, ffmpeg writer, and absolute wall-clock pacing. Return PATHNAME and the encoded frame count.
The maximum of compatible quantities.
(function pathname width height
&key (frame-rate 30)
(format :rgba8-unorm)
(constant-rate-factor 18))Encode a video at PATHNAME from frames FUNCTION writes. FUNCTION receives one argument, a writer to call with each frame's packed pixel bytes in FORMAT at WIDTH by HEIGHT. Frames become an H.264 MP4 at FRAME-RATE via an ffmpeg subprocess; CONSTANT-RATE-FACTOR is x264's quality knob (lower is better, 18 is visually…
GPU-native screenshots and films of live applications.
The application owns what a frame means. This file owns the mechanical capture transaction: one offscreen color target, one readback buffer, command submission, synchronous readback, PNG/video output, real-time film pacing, and cleanup. Nothing here reads a host window or presents a swapchain drawable.