CoreVideo surfaces (macOS)
Show CoreVideo frames as a retained, styled view, fitted like an image.
native_surface(label, Rc<NativeSurface>) and native_surface_signal(label, || frame) provide a retained component with padding, dimensions, decoration, clipping, opacity and ObjectFit. The default is centered Contain. The view owns its pixels; use ordinary sibling/parent components for controls.
unsafe NativeSurface::from_pixel_buffer(CFRetained<CVPixelBuffer>) adopts an initialized, Metal-compatible immutable frame. The producer must finish writing before adoption and must not mutate its pixels or attachments while the scene or renderer retains it. Pixel-buffer pools cannot reclaim the retained source. Supported formats are premultiplied BGRA and full-range bi-planar NV12 (420f). NV12 uses full-range BT.601 conversion, matching GPUI 0.2.2; video-range, other color matrices and HDR are not claimed.
CoreVideo planes become textures on the renderer’s own Metal device via wgpu’s HAL import. BGRA is sampled directly; NV12 is converted to an RGBA texture by a compute shader. There is no CPU pixel readback or upload in this rendering path. Repainting the same frame reuses the import/conversion; a new immutable frame identity invalidates paint. Source dimensions, plane geometry, device texture limits and a combined 64 MiB active/in-flight texel-payload budget and 1,024-frame metadata limit are checked. The payload estimate excludes external IOSurface row padding and driver/CoreVideo bookkeeping; it is not a process-RSS bound. Backpressure waits for retired submitted reads only if a replacement would otherwise exceed that budget.
CVMetalTexture wrappers and their source frames remain alive until queue-completion callbacks permit retirement. Renderer teardown explicitly waits for outstanding device work before releasing them, including when no later frame/event arrives. Normal frames do not wait for GPU completion. Native surfaces are UI-thread resources; they deliberately do not assert arbitrary CoreVideo attachments are Send/Sync.
The reference CPU rasterizer omits native surfaces; it does not silently read them back. This API is exposed only on macOS and requires a Metal renderer.
The macOS continuation packet records execution on macOS 26.4 / Apple M5 Max: the complete Metal suite passed, including metal_imports_native_bgra_and_nv12_reuses_frames_and_releases_on_teardown and the retained component fitting/binding test. The native native_surfaces --smoke-test window also alternated four BGRA/NV12 frames successfully. These establish real imported pixels, frame reuse and ownership/teardown behavior; they are not inferred from the earlier ARM cross-check or Linux WGSL validation. They do not establish video playback throughput, presentation cadence or hardware performance rankings.
The Mac validation bundle runs the complete GPU rendering suite, including native surfaces, before native window probes. Its interactive checklist also covers layout/media painting, clipboard exchange, editing and three separate native IME scenarios. The IME fixture has a 20-second lifetime per launch. Each operator case keeps a separate log; FAIL exits unsuccessfully, while skipped or unrecognized answers remain pending. CI runs the automated subset and preserves the pending manual checklist.