mcclim/gpu.lisp
A direct-GPU frame whose authored shape has transparent margins must not ask McCLIM to repaint those margins. McCLIM's ordinary background mixin composes every pane background over black, which turns transparency into an opaque rectangle before the backend sees it.
Suppress McCLIM background records at both levels of direct-GPU frame.
A lattice command's vertices live in the ANALYTIC vertex stream: the record is the same twelve floats with the lanes reinterpreted (cell coordinates, grid dimensions, the inked cells' color), so the lattice family borrows the analytic buffer and both analytic vertex stages, and differs only in its fragment shader and its summed-area texture.
Name the direct-compositor pipeline family required by command.
There is deliberately no default method: a new prepared semantic command must declare both how it encodes and which pipeline cohort must exist before an application render pass opens.
One immutable CPU snapshot published by a retained GPU mirror.
Return commands' direct pipeline families in first-use order.
Borrow mirror's current immutable CPU revision atomically.
Return the commands belonging to mirror's current atomic revision.
Copy and number one immutable CPU revision without publishing it yet.
Prepare dependents, then atomically publish immutable revision if newest.
Pipeline work is intentionally before publication and outside the small revision lock. If it fails, the previous command/buffer cohort remains the complete last-known-good presentation.
Prepare mirror's compositor for its current immutable GPU revision.
Applications call this at their pre-pass refresh boundary even when McCLIM's
semantic command stream is unchanged. It deliberately accepts only a direct
GPU mirror: raster mirrors have no retained semantic revision and are not a
fallback for application panels. target-format and depth-stencil identify an
application-owned attachment which differs from the mirror canvas. The
compositor protocol retains its own last-known-good pipeline cohort when
preparation of a newer shader revision fails.
Base vertex indices for the dense streams joined into one mirror frame.
Mutable frame-local data shared while semantic commands are prepared.
Copy command with its dense-stream range rebased by offsets.
Commands without dense-stream ranges may return themselves. There is no default method: every semantic command family must state its compose rule.
Prepare semantic command for mirror within frame-build.
Return the command to encode, or NIL when it produces no draw. There is no default method so adding a semantic command requires an explicit preparation decision.
Return command's logical-device clip rectangle, or NIL.
Encode one prepared command into pass using destination frame-state.
Dispatch is at command grain. Vertex and texture payloads remain in the
dense buffers owned by frame-state.
Whether compositor wants prepared command in the mirror texture.
A compositor which replays a command directly into its final render pass can return false, avoiding a lower-resolution copy underneath the direct draw.
Forget McCLIM fallback activity previously observed by medium.
Describe which BASIC-MEDIUM fallbacks fed medium's GPU polygon leaf.
Each entry reports semantic calls, polygon points produced by McCLIM, and GPU triangles emitted by luv. Direct polygon calls are named :DIRECT-POLYGON.
gpu-medium-push-vertex and append-gpu-text-vertex premultiply authored rgb
on the CPU. Solid and Slug vertex stages therefore forward rgb unchanged;
multiplying by their alpha lane here would premultiply a second time.
Append one analytical shape painted by design, or return NIL.
Return medium's rectangular clip in logical device coordinates, or NIL.
The mathematical shader vocabulary uses Vulkan's downward viewport. Metal lowering flips clip Y at the target boundary.
Both native backends currently expose float32x3 vertex attributes.
Carry opacity in position.z and store premultiplied rgb separately.
Return enough local expansion for two device pixels around an affine quad.
A construction-time pane may briefly have a singular device transform. Consume the relief primitive in that state instead of decomposing it into polygons that cannot preserve its height channel.
Return the immutable pixel-bearing design shared by transformed paints.
Map a point in drawing coordinates back into design's source image.
Append one convex polygon using design's native paint path, or NIL.
BASIC-MEDIUM deliberately implements these primitives in terms of its polygon leaf. The around methods retain that useful behavior while making the otherwise invisible decomposition measurable by the gallery.
Draw the uniform-radius roundrect primitive when medium supports it.
McCLIM's basic medium clears by composing the background over black, which is right for a raster that has no alpha and wrong for a medium whose destination is a live scene: a pane whose background has opacity zero should paint nothing, so a HUD title or a world bubble can float.
McCLIM's own DRAW-ROUNDED-RECTANGLE* is a convenience function whose decomposition loses the semantic primitive. Give this extension a real displayed output record so ordinary application panes retain and replay it as one command. DEF-GRECORDING supplies the standard ink/transformation capture and replay behavior used by McCLIM's built-in drawing operations.
DEF-GRECORDING normally reaches a built-in medium operation through McCLIM's stream-forwarding methods. This is a new generic, so provide the equivalent drawing leg explicitly while retaining the generated recording leg and output-record class.
Draw a roundrect as one backend primitive, with portable decomposition fallback.
The lattice primitive: a grid of unit cells as one analytic shape.
Drawn as many rectangles, every shared module edge is a compositing boundary: two half-covered fragments of the same ink OVER-composite to three quarters, a hairline that shimmers as the surface moves. As one primitive there is no interior boundary at all -- the fragment shader integrates the grid exactly over its own footprint (see hal/shader/lattice.lisp), so the drawing is seam-proof by construction rather than by alignment.
Append modules as one exactly box-filtered lattice quad, or return NIL.
Draw modules -- a bit array of unit cells, 1 where inked -- filling the
rectangle as one exactly filtered primitive when medium supports it. The
medium's ink paints the inked cells, the zero cells are white paper, and
the paper's edge is the primitive's own filtered boundary.
Portable decomposition: white paper, then one rectangle per inked cell. Hairlines between adjacent cells are this decomposition's nature; a backend with the primitive has none.
Draw a unit-cell bit grid as one exactly filtered backend primitive. INK paints the inked cells on white paper; the whole grid, paper edge included, is a single coverage computation, so nothing in it can seam.
Pane-local buffering is not a frame boundary. McCLIM gives every pane a
distinct medium, so only repaint-gpu-mirror may clear, join, and publish
their retained streams in painter order.
Return sheet and descendants in McCLIM's repaint painter order.
Return sheet's actual drawing medium, outside any recording context.
Publish sheet's retained semantic stream through embedded GPU mirror.
Replace sheet's retained streams with one redraw, then publish mirror.
Each pane owns a semantic medium, but one mirror owns the ordered GPU frame. The top-level stream is its compact presentation buffer.
Which TrueType file a CLIM text style means. DejaVu ships with the system and is always there; a nicer face takes over the :SANS-SERIF family -- the default face of every McCLIM pane here -- when it can be found. The checkout bundles Iosevka Aile (OFL, subset to the Latin, Greek, Cyrillic, punctuation, arrow, and symbol ranges a game UI needs) beside Monaspace in FONTS/; a face may also be dropped into the user's own fonts, and DejaVu stands in otherwise.
The font file name from the bundled fonts, else the user's own fonts,
else NIL.
Families to try for :SANS-SERIF, best first: a name and the regular, bold, italic, and bold-italic files looked for in the bundled and then the user's fonts. Italics are optional; the upright stands in.
The regular and bold files behind the :SANS-SERIF family on the GPU
text path; adopt-user-sans-serif-fonts retargets them.
DejaVu Sans
Point both text paths' :SANS-SERIF at the best installed preference.
The GPU medium reads *GPU-SANS-SERIF-FONTS*; the raster medium goes through
MCCLIM-RENDER's *FAMILIES/FACES* table, so that is retargeted too, and any
raster port already open forgets the faces it had cached. Returns the
family name adopted.
The basic port keeps its own memo of style to font on top of the TrueType caches; without clearing it the old faces keep being served.
The lattice family reuses the analytic vertex stage and vertex layout wholesale -- its vertices live in the analytic buffer -- and differs only in the fragment stage and the summed-area texture it reads.
Keep live mirrors honest when a new pipeline family is introduced after their solid pipeline already exists.
Create only what a textureless mirror needs to prepare its commands.
Metal presents each drawable through a fresh borrowed texture wrapper. Keep the stable slot's buffer, but refresh the cheap view so it never retains the destroyed wrapper from the prior frame.
Also repairs states retained across a live class redefinition which introduced the owner slot.
ARGB32 integers occupy BGRA bytes on the little-endian native targets, matching the portable texture format.
modules (a ROWS x COLUMNS bit array, 1 where a cell is inked) as its
summed-area table on the (ROWS+1) x (COLUMNS+1) node lattice, packed for an
RG16-UINT texture with the count in the low word.
Node (row, column) counts the inked cells strictly below and left of it. The table of a unit-cell-constant function is exactly bilinear within each cell, which is what lets the fragment shader recover continuous box integrals from four taps. Sixteen bits hold any grid up to 256 x 256 of solid ink.
The summed-area texture for modules, cached by the grid's identity.
The screen quad is dilated here rather than per vertex: its pixel scale is SIZE, and a HiDPI canvas only makes that an underestimate, which is the safe side. Two logical pixels was the old constant.
Bind one prepared command's resources and draw its dense vertex range.
Encode clip in physical drawable pixels and return whether it is nonempty.
Logically empty state and return every resource it formerly owned.
Exhaustively release state after first detaching all logical ownership.
Logical detachment precedes native destruction, so a condition cannot leave a half-owned table that will double-release on a later close.
Drawing may continue on the McCLIM side while canvas presentation crosses onto its native frame thread. Upload one immutable frame snapshot so the allocation size and the bytes written cannot drift.
Destination-frame ownership is unknown until the application
borrows its drawable. Publication therefore remains CPU-only;
encode-direct-gpu-mirror uploads this exact revision into that
drawable's bounded source state before replaying its commands.
No drawable is acquired and no pass is encoded. Publish the retained snapshot synchronously with the repaint that authored it, so command ranges and all six dense buffers are one revision.
Render direct-GPU mirror into its hidden drawable and save a PNG.
An explicitly owned AVFrame.
(command)Name the direct-compositor pipeline family required by COMMAND. There is deliberately no default method: a new prepared semantic command must declare both how it encodes and which pipeline cohort must exist before an application render pass opens.
(commands)(mirror commands vertices analytic-vertices relief-vertices
gradient-vertices image-vertices text-data &key (copy-p t))(mirror revision)(compositor mirror revision)Prepare COMPOSITOR for immutable MIRROR REVISION outside a render pass.
Logical disjunction of tests and raw truth values.
Test whether one compatible scalar is less than another.
(mirror &key
(target-format nil target-format-p)
(depth-stencil nil depth-stencil-p))Prepare MIRROR's compositor for its current immutable GPU revision. Applications call this at their pre-pass refresh boundary even when McCLIM's semantic command stream is unchanged. It deliberately accepts only a direct GPU mirror: raster mirrors have no retained semantic revision and are not a fallback for…
A direct GPU target for an ordered LUV-GPU-MEDIUM drawing stream. An embedded mirror retains an immutable prepared CPU revision for the game's final pass; a standalone mirror renders into its native canvas drawable.
(compositor mirror revision &key target-format depth-stencil)Prepare COMPOSITOR for REVISION and an application-owned attachment. This target-aware protocol is used when the application renders a retained mirror somewhere other than its canvas format. The default preserves the ordinary revision protocol for compositors without target-specific state.
Base vertex indices for the dense streams joined into one mirror frame.
Mutable frame-local data shared while semantic commands are prepared.
(command offsets)Copy COMMAND with its dense-stream range rebased by OFFSETS. Commands without dense-stream ranges may return themselves. There is no default method: every semantic command family must state its compose rule.
(command mirror frame-build)Prepare semantic COMMAND for MIRROR within FRAME-BUILD. Return the command to encode, or NIL when it produces no draw. There is no default method so adding a semantic command requires an explicit preparation decision.
(command pass frame-state)Encode one prepared COMMAND into PASS using destination FRAME-STATE. Dispatch is at command grain. Vertex and texture payloads remain in the dense buffers owned by FRAME-STATE.
(compositor command)Whether COMPOSITOR wants prepared COMMAND in the mirror texture. A compositor which replays a command directly into its final render pass can return false, avoiding a lower-resolution copy underneath the direct draw.
The semantic primitive currently being decomposed by BASIC-MEDIUM.
When true, frame realization and repaint remain drawable-only and hidden.
(medium primitive field &optional (amount 1))An ordered McCLIM drawing stream containing no software pixel surface.
(medium)Describe which BASIC-MEDIUM fallbacks fed MEDIUM's GPU polygon leaf. Each entry reports semantic calls, polygon points produced by McCLIM, and GPU triangles emitted by luv. Direct polygon calls are named :DIRECT-POLYGON.
((medium primitive) &body body)(medium x y color)(data width height screen-x screen-y alpha outline-x outline-y
horizontal-count band-offset curve-offset vertical-count
min-x min-y max-x max-y color)(generic-function name specialized-lambda-list options &body body)Define a shader-producing method with ordinary DEFMETHOD identity. Calling the method reparses its small source form so changes to source-level abstractions participate in live rebuilding. Method replacement remains the role/stage identity watched by the MOP; abstraction revisions are tracked separately by live…
(role stage)Return the current durable shader specification for ROLE and STAGE.
Select and reorder vector components by a designator such as :XYZ or :RGB.
(medium)(design medium center x-axis y-axis half-width half-height radius)Append one analytical shape painted by DESIGN, or return NIL.
(medium)The maximum of compatible quantities.
(medium)(transformation (design relief-design))The minimum of compatible quantities.
Subtraction or unary negation.
Multiplication and scalar scaling.
Division of two represented quantities.
(medium a b c color)(medium x-axis y-axis)The componentwise absolute value of a raw value.
The componentwise square root of a raw value.
Addition over compatible quantities.
(medium center x-axis y-axis local-x local-y
half-width half-height radius color)(medium center x-axis y-axis half-width half-height radius color)(medium center x-axis y-axis local-x local-y
half-width half-height radius color height)(medium center x-axis y-axis half-width half-height radius color height)A paint carrying signed height above its presentation surface. Positive heights are raised and negative heights are recessed. Ordinary McCLIM backends see ALBEDO; relief-aware backends may render the height.
((design relief-design) x y)(medium gradient center x-axis y-axis local-x local-y
half-width half-height radius)(gradient x y)Return two interpolable shader coordinates and the gradient kind lane.
(medium gradient center x-axis y-axis half-width half-height radius)A two-stop analytical paint. Geometry and paint remain independent.
(design)(design)Logical conjunction of tests and raw truth values.
Logical negation of one test or raw truth value.
(design x y)(medium design center x-axis y-axis local-x local-y
half-width half-height radius)(medium design center x-axis y-axis half-width half-height radius)(coordinates)(medium points color)Test whether one compatible scalar is at least another.
(design medium points)Append one convex polygon using DESIGN's native paint path, or NIL.
(medium gradient points)(medium design points)(medium start end thickness color)((medium luv-gpu-medium) x y)((medium luv-gpu-medium) x1 y1 x2 y2)((medium luv-gpu-medium) x1 y1 x2 y2 filled)(eta1 eta2)((medium luv-gpu-medium)
cx cy rdx1 rdy1 rdx2 rdy2 eta1 eta2 filled)((medium luv-gpu-medium) cx cy radius eta1 eta2 filled)(medium x1 y1 x2 y2 radius filled)Draw the uniform-radius roundrect primitive when MEDIUM supports it.
((medium luv-gpu-medium) left top right bottom)A CPU raster medium whose image and semantic reliefs feed a luv target.
(sheet x1 y1 x2 y2 &rest options
&key (radius 7) (filled t) &allow-other-keys)(medium modules x1 y1 x2 y2 color)(medium modules x1 y1 x2 y2)Draw MODULES -- a bit array of unit cells, 1 where inked -- filling the rectangle as one exactly filtered primitive when MEDIUM supports it. The medium's ink paints the inked cells, the zero cells are white paper, and the paper's edge is the primitive's own filtered boundary.
Test whether two compatible scalars are equal.
(sheet modules x1 y1 x2 y2 &rest options)Draw a unit-cell bit grid as one exactly filtered backend primitive. INK paints the inked cells on white paper; the whole grid, paper edge included, is a single coverage computation, so nothing in it can seam.
((medium luv-gpu-medium) coordinates closed filled)((medium luv-gpu-medium) pattern x y)((medium luv-gpu-medium) coordinates closed filled)Test whether one compatible scalar is greater than another.
((medium luv-gpu-medium) continuation &optional buffered-p)(sheet)(name-and-options lambda-list &body body)Define a function whose complete dynamic extent is an ambient trace zone. The inferred name is PACKAGE/FUNCTION. Use (NAME :ZONE ZONE-NAME) to provide a more semantic name and :VALUE FORM to attach a Tracy work count.
(mirror sheet)(mirror sheet function)(mirror)Drain callback-only input and publish any resulting visual state.
(sheet)Handle events for a callback-only frame while dispatching native input. Conventional RUN-FRAME-TOP-LEVEL frames consume their own queues instead.
((port luv-gpu-port) (sheet mirrored-sheet-mixin))A luv port whose media record McCLIM drawing directly as GPU geometry.
(name)The font file NAME from the bundled fonts, else the user's own fonts, else NIL.
Families to try for :SANS-SERIF, best first: a name and the regular, bold, italic, and bold-italic files looked for in the bundled and then the user's fonts. Italics are optional; the upright stands in.
The regular and bold files behind the :SANS-SERIF family on the GPU text path; ADOPT-USER-SANS-SERIF-FONTS retargets them.
()Point both text paths' :SANS-SERIF at the best installed preference. The GPU medium reads *GPU-SANS-SERIF-FONTS*; the raster medium goes through MCCLIM-RENDER's *FAMILIES/FACES* table, so that is retargeted too, and any raster port already open forgets the faces it had cached. Returns the family name adopted.
DejaVu Sans
(text-style)(text-style)(text-style reader)(font-pathname)(text-style (medium luv-gpu-medium))(text-style (medium luv-gpu-medium))(text-style (medium luv-gpu-medium) character)((medium luv-gpu-medium) string &key text-style (start 0) end)(font-pathname string &key direction)((medium luv-gpu-medium) string &key text-style (start 0) end)((medium luv-gpu-medium) string x y start end align-x align-y
toward-x toward-y transform-glyphs)A named group of rules, compiled in definition order under its documentation as a comment.
(mirror &key readback-p)(&optional (stream *standard-output*))(provider &optional descriptor)If you're lucky, someone has bound this to a working GPU-PROVIDER.
A MuPDF context: its allocator, its store, and its error stack.
(canvas gpu-provider &optional configuration)Create a GPU presentation relationship between CANVAS and GPU-PROVIDER. When CONFIGURATION is omitted, return the context unconfigured.
(context)Return CONTEXT's configured drawable extent as (WIDTH HEIGHT), or NIL.
(context configuration)Configure or reconfigure CONTEXT for presentation.
(handle)Logically invalidate HANDLE immediately. Native teardown may be deferred until submitted work which captured HANDLE has completed.
(mirror device format)(device descriptor)Asks the DEVICE for a handle to newly created instance of some object fulfilling the DESCRIPTOR.
(mirror device format)(mirror device format)How the children of a list are arranged.
(mirror device format)(mirror device format)(mirror device format)(device)(mirror context)(context)Return the GPU device used by CONTEXT, or NIL before first configuration.
(mirror device)(mirror context surface)(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.
(state device byte-count)(state device byte-count)(state device byte-count)(state device byte-count)(state device byte-count)(state device byte-count)(mirror design)(queue destination data data-layout size)(modules)MODULES (a ROWS x COLUMNS bit array, 1 where a cell is inked) as its summed-area table on the (ROWS+1) x (COLUMNS+1) node lattice, packed for an RG16-UINT texture with the count in the low word. Node (row, column) counts the inked cells strictly below and left of it. The table of a unit-cell-constant function is…
A simple Org table without formulas.
(mirror modules)(mirror atlas)(command min-x min-y max-x max-y)(cache font-pathname string &key direction)(shaped font-loader cache font-pathname)(draws shaped font-loader)(cache glyphs)(pixels-per-em)The em distance a glyph quad laid out at PIXELS-PER-EM should grow on each side: the live dilation in filter widths, plus the static padding. For a stage that cannot dilate per vertex (a flat screen quad, whose pixel scale is known when it is laid out).
(mirror)(pass pipeline bind-group buffer first-vertex vertex-count)(pass-encoder pipeline)(pass-encoder index bind-group)(pass-encoder slot buffer &key (offset 0))(pass-encoder vertex-count
&optional (instance-count 1) (first-vertex 0) (first-instance 0))(pass mirror surface clip)(pass-encoder x y width height)(mirror context function)(context function)Replay COMPOSITOR's textureless McCLIM mirror into PASS under affine STATE. DESTINATION-TEXTURE describes the open pass for format and clipping. FRAME-TEXTURE names the bounded in-flight presentation slot whose host-visible buffers are safe to update; normally both arguments are the same texture.
(encoder descriptor)(pass-encoder)(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.
(mirror pathname)(buffer &key offset size)Wait for BUFFER's device queue and copy mapped bytes back to the host.
(pathname pixels width height format)(mirror)Release renderer-specific resources retained by MIRROR.
(compositor)Exhaustively release resources retained by a mirror COMPOSITOR.
Direct GPU McCLIM output.
The medium records painter-ordered triangles. It never allocates a pixel image and the mirror presents those vertices directly into its luv canvas.