hal/metal/gpu.lisp
A provider for the system's preferred Metal device.
Metal is the native default on Apple hosts. Preserve an explicit provider installed by an embedding application before luv finishes loading.
A Metal4FX temporal scaler, its fence, and neutral exposure texture.
A device-compiled MSL library retaining its source document.
A linked Metal 4 render pipeline and its draw-time depth state.
A linked Metal 4 object/mesh pipeline with its dispatch geometry.
A general Metal 4 command encoder which owns recording memory until finish.
One finished, one-shot Metal 4 command buffer and its recorded dependencies.
A Metal 4 render encoder whose resources arrive through argument tables.
The first vertex-stage realization is the executable mechanism described by #348B7B; it deliberately has no legacy individual-resource setter path.
Serialize admitted device-native work against device destruction.
Retain resource as a dependency of encoder's eventual command buffer.
Allocate and begin one general Metal 4 command buffer.
End recording and transfer native memory and dependencies to one-shot work.
Retain explicit encoder ownership until wrapper publication.
Publish encoder's ended native ownership as one command-buffer wrapper.
Return object's persistent, progress-tracked native teardown closure.
Enqueue queue's newest ready shared-event signal, retaining it on failure.
Re-enqueuing the same monotonic value is safe if the Objective-C wrapper returned nonlocally after the native message took effect.
Whether queue owns no signal, submitted, or native-retirement obligation.
Unroot queue only after backend quiescence was proved under its lock.
Retire completed submissions and every now-eligible native ownership.
Service queue from the process custodian registry without caller access.
Never message a retiring/released MTLDevice or its event. Device teardown has already enforced this queue's complete barrier.
Transfer one native owner after revalidating its queue under the lock.
Transfer resource's native ownership before logically invalidating it.
Wait for the Metal 4 shared-event frontier most recently submitted.
Commit finished Metal work and retain its dependencies to queue's frontier.
after-commit performs the drawable signal and presentation handshake before
the completion event is enqueued. Presentation is the only caller of that
backend-local extension; ordinary callers use submit. #T9K4RC
Device teardown closes admission under this lock. Recheck after any wait to make this the authoritative gate before maintenance and FFI.
Register queue ownership before presentation can fail.
Presentation must be ordered before completion, but failure to enqueue that completion is now a rooted retryable queue obligation.
Return a persistent completion-and-ledger barrier for device destruction.
Return device's persistent one-native-call-at-a-time teardown.
Create one shared Metal buffer and add its allocation to device residency.
Copy a one-dimensional numeric array into shared Metal memory.
data holds single-floats or unsigned 8-, 16-, 32-, or 64-bit integers; offset is
aligned to the element size.
Numeric storage vectors are unboxed. Pin and copy their bytes once; crossing CFFI once per element turns large streamed populations into a multi-million-call owner-thread stall.
Create one resident two-dimensional Metal texture.
Translate a MetalFX texture usage mask into the portable usage vocabulary.
Create one synchronous Metal4FX temporal scaler for a fixed extent.
The scaler publishes the exact native texture contract that Luft uses to construct its temporal surface cohort. #NL5J0J
Metal 4 does not make an externally created MTLTexture resident merely because an argument table points at it. CVMetalTexture planes therefore need the same explicit residency membership as textures allocated by this device.
The first Metal vocabulary exposes only complete single-mip views, so the view is a semantic wrapper over the same native texture.
Upload one tightly represented byte image into a shared Metal texture.
A tightly packed simple array is already exactly the image Metal wants, so pin it and hand over its own storage. Staging it word by word costs tens of milliseconds on an image the size of a video frame, which is a whole frame's budget spent copying memory that did not need copying.
True when data's own storage is already the exact upload image.
Sharing needs a simple array -- displaced or adjustable storage is not one contiguous block -- starting at the beginning, with no padding between rows.
Upload data's own pinned storage into texture without staging a copy.
New importers can couple native-plane release to their own retained lifetime with a callback. Raw CF owners remain source-compatible.
Lower a mathematical shader directly to MSL and compile it on device.
The complete MSL document remains attached to the returned module so native diagnostics and graph provenance stay inspectable. This is the device-owned compiler boundary of #58IDSR.
Link device-owned vertex and fragment modules into a Metal 4 pipeline.
Link task, mesh, and fragment modules into a Metal 4 mesh pipeline.
Compile specification through a fresh Metal device and return bounded evidence.
Link two mathematical shaders on a fresh Metal device and return evidence.
Begin a Metal 4 color, depth, or color-and-depth pass.
Metal 4 queues do not perform ordinary MTLResource hazard tracking. Coalesce every texture produced by the preceding pass into the one producer-to-fragment barrier installed on the following encoder. The command encoder retains each concrete resource independently below.
Make earlier render and blit texture writes visible to a blit read.
MTL4CommandQueue ignores ordinary resource hazard tracking. A copy can consume either a render target or the destination of an earlier copy in this portable encoder, so both producer stages belong in the dependency.
Base condition for errors exposed by the luv GPU API.
A provider for the system's preferred Metal device.
Instances of GPU-PROVIDER subclasses are platform-specific factories for requesting GPU-DEVICE instances.
If you're lucky, someone has bound this to a working GPU-PROVIDER.
A Metal4FX temporal scaler, its fence, and neutral exposure texture.
A retained temporal reconstruction owner and its exact texture contract.
How the children of a list are arranged.
A device-compiled MSL library retaining its source document.
An open document and the context it was opened in.
A linked Metal 4 render pipeline and its draw-time depth state.
A linked Metal 4 object/mesh pipeline with its dispatch geometry.
A general Metal 4 command encoder which owns recording memory until FINISH.
One finished, one-shot Metal 4 command buffer and its recorded dependencies.
Finished one-shot work accepted by a GPU queue's SUBMIT operation.
A Metal 4 render encoder whose resources arrive through argument tables. The first vertex-stage realization is the executable mechanism described by #348B7B; it deliberately has no legacy individual-resource setter path.
(object operation)Logical disjunction of tests and raw truth values.
(device operation thunk)((device operation) &body body)(descriptor)(provider &optional descriptor)(device &key label)Create one synchronous Metal 4 compiler owned by DEVICE. Return the owned compiler and NIL on success, or NIL and a copied NSError description on native rejection.
(device &key label (initial-capacity 64))(object)(encoder operation)(encoder operation)(encoder resource)(encoder)(device descriptor)Asks the DEVICE for a handle to newly created instance of some object fulfilling the DESCRIPTOR.
Logical conjunction of tests and raw truth values.
(command-buffer &key flags)(encoder device command-buffer allocator)(command-buffer)(object)Return OBJECT's persistent, progress-tracked native teardown closure.
Test whether one compatible scalar is greater than another.
Test whether one compatible scalar is at most another.
(ledger custodian)(queue)(ledger completed-frontier &key (operation :maintain-queue))Attempt the eligible FIFO prefix in LEDGER at COMPLETED-FRONTIER. Only a successful eligible prefix leaves the ledger. The first ineligible or failed entry is a FIFO barrier: it and the entire unattempted suffix remain ahead of ownership transferred recursively by teardown callbacks.
(custodian)Perform one safe eventual-retirement service pass for CUSTODIAN. Backend methods revalidate native liveness while holding their queue lock and return true when the pass made progress. They must never acquire a queue lock while the process-wide custodian registry lock is held.
Addition over compatible quantities.
Test whether one compatible scalar is less than another.
(queue device)Logical negation of one test or raw truth value.
(resource device ready-after teardown invalidate operation)(resource teardown invalidate &key (operation :destroy))Perform TEARDOWN without a live queue, then invalidate RESOURCE. An error leaves the wrapper and its leak finalizer live and is re-signaled as a structured GPU-NATIVE-RETIREMENT-ERROR retaining the original cause.
(ledger resource ready-after teardown invalidate &optional custodian)Durably enqueue native ownership, then logically invalidate RESOURCE. INVALIDATE is called only after LEDGER owns the complete teardown. Queue implementations call this while holding the lock which also guards LEDGER.
(device owner teardown invalidate)Transfer OWNER's native teardown to DEVICE, then invalidate OWNER. Backend methods may transfer ownership to a durable device queue before INVALIDATE and attempt it immediately. The default has no such queue: native TEARDOWN must return successfully before INVALIDATE is called.
(resource device &optional extra-invalidation)(queue command-buffer)(command-buffers)(queue)Block until all work submitted to QUEUE so far has completed on the GPU.
(queue command-buffers &key after-commit)Commit finished Metal work and retain its dependencies to QUEUE's frontier. AFTER-COMMIT performs the drawable signal and presentation handshake before the completion event is enqueued. Presentation is the only caller of that backend-local extension; ordinary callers use SUBMIT. #T9K4RC
(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.
(queue command-buffers)(ledger custodian)The maximum of compatible quantities.
(handle)Logically invalidate HANDLE immediately. Native teardown may be deferred until submitted work which captured HANDLE has completed.
(pass-encoder)(&rest steps)Return a retryable closure over ordered, individually idempotent STEPS. Each zero-argument step is removed only after it returns normally. A retry therefore resumes at the failing native call without repeating any earlier destructive call which already succeeded.
(device queue)(ledger &key (operation :destroy-device))(device queue)(&optional (stream *standard-output*))(data)Return the CFFI element type and byte size for a one-dimensional DATA array of single-floats or unsigned 8-, 16-, 32-, or 64-bit integers.
(descriptor reason &optional details)The non-negative remainder of integer division.
Multiplication and scalar scaling.
Subtraction or unary negation.
(buffer &key offset size)Wait for BUFFER's device queue and copy mapped bytes back to the host.
(buffer &key offset size)Copy mapped BUFFER bytes only when its own newest submission is complete. Return the byte vector and true when ready, or NIL and NIL without waiting. Unlike READ-BUFFER this does not wait for unrelated newer queue work.
(format descriptor)(device width height pixel-format usage &key (storage-mode +storage-mode-private+)
label)(native descriptor role)(size descriptor &optional (operation :create))Test whether two compatible scalars are equal.
(category control &rest arguments)Write one timestamped line about CATEGORY, formatted from CONTROL. CATEGORY is a keyword naming the subsystem -- :canvas, :watchdog, :vulkan -- so a reader can tell at a glance which machine is talking.
(device compiler color-format depth-format motion-format output-format
input-width input-height output-width output-height)(queue destination data data-layout size)(device native-object owner descriptor)Wrap a platform texture and its retained OWNER in the HAL.
One native Objective-C pointer and exactly one owned or borrowed claim.
(object actual-device expected-device operation)(filter descriptor)(filter descriptor)(mode descriptor)(device min-filter mag-filter mip-filter address-mode-s address-mode-t
address-mode-r compare-function &key label)(function)(descriptor)(device descriptor layout)Test whether one compatible scalar is at least another.
(data offset bytes-per-row bytes-per-texel
size)True when DATA's own storage is already the exact upload image. Sharing needs a simple array -- displaced or adjustable storage is not one contiguous block -- starting at the beginning, with no padding between rows.
(texture width height bytes bytes-per-row)(descriptor)(specification &optional (target *metal-4-target*))The library band: eyebrow, site name, and the three doors.
(compiler source &key name)Synchronously compile SOURCE as Metal 4 and return an owned MTLLibrary. The second value is NIL on success or a copied NSError description on native rejection. Source and names cross only as in-memory NSString objects.
(() &body body)(string)Return an autoreleased NSString containing STRING. The result is borrowed and must remain inside its surrounding autorelease pool. Native APIs which copy an NSString argument may retain it beyond that scope in the ordinary Objective-C way.
(descriptor buffers)(format descriptor)(compiler vertex-library vertex-name fragment-library fragment-name
vertex-buffers color-formats topology &key depth-format blends label)(device compare-function depth-write-enabled &key label)(compiler object-library object-name object-workgroup-size
mesh-library mesh-name mesh-workgroup-size
fragment-library fragment-name color-format max-mesh-workgroups
&key blend label)(specification)(object)(vertex-specification fragment-specification vertex-buffers
&key (target-format :bgra8-unorm)
(primitive '(:topology :triangle-list))
(depth-stencil '(:format :depth32-float
:depth-write-enabled t
:depth-compare :less)))(pass operation)(device descriptor attachment)(device descriptor attachment)(encoder descriptor)(command-buffer &key color-attachments color-texture
(color #(0.0 0.0 0.0 1.0))
(color-clear-p t) (color-store-p t)
depth-texture (clear-depth 1.0)
(depth-clear-p t) (depth-store-p nil))(scaler device operation)(scaler color depth motion exposure output width height jitter-x jitter-y
reset-p)A simple Org table without formulas.
(layout type)Headings, paragraphs, figures and their IDs, mentions, marks.
(pass bind-group)(device max-buffer-count
&key (max-texture-count 0) (max-sampler-count 0) label
(attribute-strides-p nil))(pipeline slot)(pipeline)(format)(size)(command-buffer texture color)(native-encoder)(encoder source width height destination bytes-per-row)Both live backends now represent completed work as a monotonically valued queue frontier, but the records attached to that frontier are different. submit-vulkan-command-buffers signals the queue timeline, installs a vulkan-gpu-submission record, and returns its index. Queue maintenance reads the semaphore counter and…
Intent. Make Darwin's default Luft renderer accumulate the same jittered colour and motion contract as Vulkan while letting MetalFX own reconstruction, history, and its required synchronization. Evidence. The Metal renderer test creates a real RGBA16F + D32 + RG16F Metal4FX scaler, renders repeated frames, observes…
Intent: compile the existing block fragment shader-specification through a sibling target context, without translating its spir-v-module and without inventing a new shared IR. Evidence: – The graph already carries types, source forms, resources, semantic operations, and provenance. The current block fragment…
The Metal 4 implementation of luv's portable GPU protocol.