Presentation state of one surface: the Core Animation layer it presents to, the configuration it presents under, and the drawable the current frame is holding. More...
#include "donner/gpu/metal/MetalSurface.h"
Public Member Functions | |
| ~MetalSurface () | |
| Destructor; hands back an outstanding drawable and releases this surface's retain on the layer, which the embedder still owns and which outlives the release. | |
| MetalSurface (const MetalSurface &)=delete | |
| MetalSurface & | operator= (const MetalSurface &)=delete |
| SurfaceCapabilities | capabilities () const |
| What this layer can present, for choosing a configuration. Every value reported here is accepted by configure, and every value absent from it is refused. | |
| Status | configure (const SurfaceConfiguration &configuration) |
Applies configuration to the layer, replacing any previous one. | |
| Result< SurfaceStatus > | acquire () |
| Takes the next frame's drawable from the layer. | |
| id< MTLTexture > | currentTexture () const |
| Texture of the frame currently held, or nil when none is. | |
| Result< SurfaceStatus > | present () |
| Hands the held frame to the layer and releases it. | |
| void | abandon () |
| Hands the held frame back to the layer without showing it. Does nothing when none is held. | |
Static Public Member Functions | |
| static Result< std::unique_ptr< MetalSurface > > | Create (id< MTLDevice > device, const SurfaceDescriptor &descriptor) |
Binds a surface to the Core Animation layer descriptor names. | |
Presentation state of one surface: the Core Animation layer it presents to, the configuration it presents under, and the drawable the current frame is holding.
A layer hands out a small, fixed number of drawables and takes one back only when it is presented or released. Exactly one frame is held at a time, which the runtime enforces before a second acquisition reaches the layer; the check in acquire is a backstop for a caller that reached this type directly. Holding the drawable rather than only its texture is what makes abandon possible: a frame the caller decided not to show is handed straight back to the layer instead of being presented to the screen.
Nothing here owns a window. The layer belongs to whoever created the surface, and outlives it; this type only configures the layer, takes drawables from it, and puts them back.
Threading: used from the one thread that owns the device, like the rest of the runtime. Core Animation layers are not thread safe, and a layer property set outside an explicit transaction is only published when the setting thread's run loop commits one, so configure wraps its writes in a transaction of its own rather than relying on the caller having a run loop.
| Result< SurfaceStatus > donner::gpu::metal::MetalSurface::acquire | ( | ) |
Takes the next frame's drawable from the layer.
The returned status distinguishes a frame that came back under a configuration the layer has outgrown (SurfaceStatus::Outdated, which still carries a usable texture) from one that did not come back at all. On success currentTexture names the frame until it is presented or abandoned.
| Status donner::gpu::metal::MetalSurface::configure | ( | const SurfaceConfiguration & | configuration | ) |
Applies configuration to the layer, replacing any previous one.
Values the layer cannot present are refused rather than substituted: Core Animation silently accepts a pixel format it will not draw, so a configuration outside capabilities fails closed here instead of producing a surface nobody asked for.
| configuration | Format, usage, extent, pacing and alpha compositing. |
|
static |
Binds a surface to the Core Animation layer descriptor names.
| device | Metal device the layer must render with. |
| descriptor | Label and platform object; the platform object must be a CAMetalLayer. |
| Result< SurfaceStatus > donner::gpu::metal::MetalSurface::present | ( | ) |
Hands the held frame to the layer and releases it.
Presents immediately, so the frame's own work must already have finished: a drawable handed over while the GPU is still writing it is shown half drawn. Ordering that is the caller's job - donner::gpu::metal::MetalDevice waits for the frame's submission before calling this - because the layer's own scheduling gives no such guarantee. Scheduling the present on a command buffer would not help: presentDrawable: fires when that buffer is scheduled, not when it completes, so a present-only buffer committed afterwards can still run first.
1.15.0 