hal/canvas.lisp
How long a cross-thread canvas call waits before deciding it is stuck.
Work handed to the canvas thread is serviced once a frame, so it completes in milliseconds whenever that thread is running at all. Anything approaching this many seconds does not mean slow, it means the thread is not coming back -- and a caller that waited forever would take a REPL, a screenshot, or an editor session down with it, silently. Bind it larger only for an operation known to be genuinely long.
The canvas thread did not service ~S on ~S within ~,1F seconds.~@ It is not servicing requests at all: it is blocked, and every later call will ~ queue behind the same block. The usual cause is the render loop parked in ~ presentation -- vkQueuePresentKHR waits forever when the compositor will not ~ take frames, which is what a headless, locked, or unmapped session looks ~ like. Get a backtrace of the canvas thread before restarting anything.
A cross-thread canvas call gave up rather than hang.
This is deliberately an error and not a longer wait. A silent unbounded wait on the canvas thread is indistinguishable from a crash and destroys the one thing an interactive image is for.
A clock which samples its source once, then retains that time until cleared.
An event-loop turn therefore has one coherent NOW. Rendering may temporarily override it with a predicted presentation time without changing the source.
Sample clock's source without consulting or changing its remembered time.
Call function while clock consistently denotes timestamp.
A policy object deciding when a canvas should run frames.
A clock whose frames happen only when explicitly requested.
A clock which owns a continuously animated frame function.
A clock which calls a frame function at a regular cadence.
A clock paced by presentation availability inside its frame function.
It requests exactly one frame per event-loop turn. A direct-display backend blocks acquiring that frame until FIFO scanout releases an image, so no independent host timer competes with the display's cadence.
Construct a clock which calls frame-function with canvas and timestamp.
Construct a clock whose frame acquisition supplies its cadence.
Return milliseconds until clock is due, or NIL to wait indefinitely.
Run any frame clock has made due at timestamp; true if one ran.
SDL's event timeout has millisecond resolution. Rounding upward makes a 60 Hz deadline (16.667 ms) late by construction; on a 120 Hz display that can miss the intended presentation refresh. Wake on the last whole millisecond before the deadline and let the event loop poll through the sub-millisecond remainder.
Deliberately do not accumulate missed frames. A cadence is a pacing policy, not a demand to replay time spent in a debugger.
A native destination with a lifetime and frame clock.
Return the one stable time shared by canvas's current event-loop turn.
Sample canvas's underlying monotonic time without changing logical NOW.
Predict when a frame acquired now will become visible on canvas.
A GPU presentation relationship configured for a canvas.
Return the stable presentation slot key for surface-texture in context.
Applications use this to retain per-frame resources without assuming that a backend returns the same Lisp wrapper every time it revisits a native drawable.
Portable input vocabulary. Native backends translate into these objects; consumers never need to know the SDL event ABI.
Protocol class for objects receiving canvas events.
A scroll, carrying where the pointer was and how far the wheel turned.
The amounts are in wheel notches rather than pixels, positive up and right, already corrected for a natural-scrolling platform -- what the window system says the user asked for, not what the hardware reported.
A portable physical-key event with logical modifiers and layout text.
Deliver portable event from canvas to handler.
True on a canvas loop while its frames are held or parked by a failure: the window is still pumped, but no event reaches the application.
The small portable portion of a canvas presentation configuration.
Native-place protocol.
Realize canvas in its native window system.
Close canvas and all presentation contexts attached to it.
Return true when the caller is canvas's native event/frame thread.
Return canvas's native title.
Return canvas's drawable width and height as two values.
Return canvas's logical width and height as two values.
Return canvas's native x and y position as two values.
Return whether canvas is intended to be visible.
Return a plist describing whether canvas's native loop is still alive.
The keys are :STATE, :PHASE, :PHASE-SECONDS, :TICKS, and :STALLED-P. A caller reads this to answer the question a beachballing window raises -- is anything servicing that window at all -- without attaching a debugger.
Return how long canvas's loop has been in one phase past its deadline.
NIL means the loop is healthy: either it is cycling, or it is parked in a bounded wait that the window system is pumping for it.
Return whether canvas occupies its display.
The text on the system clipboard, or NIL when there is none or the window system has no clipboard to ask.
Give canvas its whole display, or hand it back to the window manager.
Capture or release relative pointer motion for canvas.
Make an open canvas visible.
Hide canvas without destroying its native resources.
Move canvas to native position X, Y.
Request that the native host raise canvas.
Request that the native host minimize canvas.
Restore a minimized or maximized canvas.
Return the native lifecycle state of canvas.
Return canvas's presentation context, or NIL.
Presentation-relationship protocol.
Create a GPU presentation relationship between canvas and gpu-provider.
When configuration is omitted, return the context unconfigured.
Return the native canvas presented by context.
Return the GPU device used by context, or NIL before first configuration.
Return context's configured presentation format, or NIL.
Configure or reconfigure context for presentation.
Release context's current presentation configuration.
Destroy context and its backend relationship.
Return the borrowed GPU texture current during a canvas frame.
Acquire a frame texture, call function with texture, encoder, and predicted
presentation time, then complete presentation. function runs on the canvas's
native frame thread, with canvas-time overridden to that same prediction.
Clear and present one frame through context.
A native destination with a lifetime and frame clock.
A GPU presentation relationship configured for a canvas.
How long a cross-thread canvas call waits before deciding it is stuck. Work handed to the canvas thread is serviced once a frame, so it completes in milliseconds whenever that thread is running at all. Anything approaching this many seconds does not mean slow, it means the thread is not coming back -- and a caller…
A cross-thread canvas call gave up rather than hang. This is deliberately an error and not a longer wait. A silent unbounded wait on the canvas thread is indistinguishable from a crash and destroys the one thing an interactive image is for.
Logical disjunction of tests and raw truth values.
Division of two represented quantities.
A clock which samples its source once, then retains that time until cleared. An event-loop turn therefore has one coherent NOW. Rendering may temporarily override it with a predicted presentation time without changing the source.
(&key (source #'monotonic-seconds))(clock)(clock)(clock timestamp function)A policy object deciding when a canvas should run frames.
A clock whose frames happen only when explicitly requested.
A clock which owns a continuously animated frame function.
A clock which calls a frame function at a regular cadence.
A clock paced by presentation availability inside its frame function. It requests exactly one frame per event-loop turn. A direct-display backend blocks acquiring that frame until FIFO scanout releases an image, so no independent host timer competes with the display's cadence.
((agent application-agent) &key)Logical conjunction of tests and raw truth values.
(frame-function &key (frames-per-second 60))(frame-function)(clock timestamp)Return milliseconds until CLOCK is due, or NIL to wait indefinitely.
(clock canvas timestamp)Run any frame CLOCK has made due at TIMESTAMP; true if one ran.
Test whether one compatible scalar is at most another.
Multiplication and scalar scaling.
Subtraction or unary negation.
Addition over compatible quantities.
Protocol class for objects receiving canvas events.
(canvas)(canvas)(canvas)(canvas timestamp function)(canvas)Predict when a frame acquired now will become visible on CANVAS.
(context surface-texture)Return the stable presentation slot key for SURFACE-TEXTURE in CONTEXT. Applications use this to retain per-frame resources without assuming that a backend returns the same Lisp wrapper every time it revisits a native drawable.
A MuPDF context: its allocator, its store, and its error stack.
A scroll, carrying where the pointer was and how far the wheel turned. The amounts are in wheel notches rather than pixels, positive up and right, already corrected for a natural-scrolling platform -- what the window system says the user asked for, not what the hardware reported.
A portable physical-key event with logical modifiers and layout text.
True on a canvas loop while its frames are held or parked by a failure: the window is still pumped, but no event reaches the application.
(canvas event)The small portable portion of a canvas presentation configuration.
(&optional (stream *standard-output*))(canvas)Return true when the caller is CANVAS's native event/frame thread.
(canvas)Return a plist describing whether CANVAS's native loop is still alive. The keys are :STATE, :PHASE, :PHASE-SECONDS, :TICKS, and :STALLED-P. A caller reads this to answer the question a beachballing window raises -- is anything servicing that window at all -- without attaching a debugger.
(canvas)Return how long CANVAS's loop has been in one phase past its deadline. NIL means the loop is healthy: either it is cycling, or it is parked in a bounded wait that the window system is pumping for it.
(canvas)The text on the system clipboard, or NIL when there is none or the window system has no clipboard to ask.
(canvas enabled)Give CANVAS its whole display, or hand it back to the window manager.
(canvas enabled)Capture or release relative pointer motion for CANVAS.
(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.
(canvas gpu-provider &optional configuration)Create a GPU presentation relationship between CANVAS and GPU-PROVIDER. When CONFIGURATION is omitted, return the context unconfigured.
Instances of GPU-PROVIDER subclasses are platform-specific factories for requesting GPU-DEVICE instances.
(context)Return the GPU device used by CONTEXT, or NIL before first configuration.
(context)Return CONTEXT's configured drawable extent as (WIDTH HEIGHT), or NIL.
(context configuration)Configure or reconfigure CONTEXT for presentation.
(context)Return the borrowed GPU texture current during a canvas frame.
(context function)Acquire a frame texture, call FUNCTION with texture, encoder, and predicted presentation time, then complete presentation. FUNCTION runs on the canvas's native frame thread, with CANVAS-TIME overridden to that same prediction.
(context function)(context red green blue &optional (alpha 1.0))
Portable canvas and presentation protocols.
A
canvasis a native place with a lifetime, size, event source, and frame clock. Acanvas-contextis a configured relationship between that place and a GPU implementation. Platform hosts implement the former protocol; presentation backends implement the latter.