gpui: draw externally owned native GPU surfaces on Windows, and keep Core Video resources alive until command-buffer completion

[Haoxincode]

Context

This follows longbridge/gpui-kit#3168. GPUI Kit consumes unmodified gpui-pre snapshots of this repository and does not carry renderer patches, so that report was redirected here. Once the behavior is in Zed, their snapshot job can pick it up.

I embed camera frames that a platform decoder has already produced as GPU resources. Copying each frame through the CPU sprite atlas is the wrong path: it adds a readback, inserts frames into an atlas that will never reuse them, and cannot keep up with a live preview. surface() / PaintSurface is already the primitive for this. On current main it is not usable for the case below.

This is narrower than #60572. That proposal is a backend-neutral compositor for externally rendered wgpu textures. These frames are not wgpu textures. They are a CVPixelBuffer, or a D3D11 BGRA shader-resource view that already belongs to the window device. I would like to extend the existing surface primitive rather than add a second one.

What main does today

macOS. gpui::surface() / Window::paint_surface takes a CVPixelBuffer, and gpui_apple samples it in draw_surfaces. Two gaps:

1. The pixel format is hard-asserted to kCVPixelFormatType_420YpCbCr8BiPlanarFullRange. Any other format aborts the process, including release builds, because the check is assert_eq!. Single-plane BGRA is already proposed separately in #61291. This discussion does not need to absorb that change.
2. The CVMetalTexture values returned by CVMetalTextureCacheCreateTextureFromImage are locals in the encode loop. They drop when the iteration ends, before the command buffer completes. Core Video requires both the source CVPixelBuffer and each CVMetalTexture to stay alive until the GPU is done reading. Keeping only the MTLTexture is not sufficient: the cache may recycle the underlying IOSurface while the command buffer is still in flight. A caller with a small CVPixelBufferPool then either stalls or samples a recycled allocation.

Windows. PaintSurface::image_buffer exists only under cfg(target_os = "macos"), surface() is macOS-only, and DirectXRenderer::draw_surfaces returns without drawing:

fn draw_surfaces(&mut self, surfaces: &[PaintSurface]) -> Result<()> {
    if surfaces.is_empty() {
        return Ok(());
    }
    Ok(())
}

There is no way to submit an externally owned D3D11 texture. The other image path uploads CPU BGRA into the atlas.

wgpu. Surfaces are skipped. That belongs in #60572, not here.

Contract

Same surface() element and PaintSurface primitive on each platform. No CPU pixels cross the boundary. The renderer only enqueues a read.

• macOS. Continue to accept a CVPixelBuffer. While encoding, retain that buffer and every CVMetalTexture derived from it with the command buffer, and release them from the buffer's completed handler. After commit, the Scene may drop its clone. The underlying pool allocation must remain unique until that handler runs. A regression test is a pool with kCVPixelBufferPoolAllocationThresholdKey = 1: create one buffer, paint it, drop the scene, flush the texture cache, and assert that a second create_pixel_buffer still returns kCVReturnWouldExceedAllocationThreshold while the command buffer is blocked. Unblocking the queue must then allow the allocation. The same lease has to cover whatever formats draw_surfaces accepts, so it still holds if gpui: Support single-plane BGRA CVPixelBuffers in surface rendering #61291 adds a single BGRA plane.
• Windows. Accept an immutable BGRA8 ID3D11ShaderResourceView that already belongs to the renderer's ID3D11Device (one mip, TEXTURE2D, opaque full-range). Draw it with the existing sprite geometry, bounds, and content mask, and do not allocate an atlas tile. Unbind the SRV before returning so a later primitive cannot sample it. The caller imports across devices and holds the resource until its own GPU reads complete. GPUI should not grow a second completion scheduler. If the view is busy, on the wrong device, or in the wrong format, skip that surface and continue the frame. One unavailable video frame must not stop unrelated UI from painting.
• Lifetime, written down. Document which object the caller keeps, and until when. On macOS the framework can hold the Core Video lease, which is what makes a bounded pool safe. On Windows the caller already owns the keyed mutex and completion fence.

I have this behavior working against the gpui-pre 0.3.6 snapshot (zed@bcf6582), with a WARP test that the Windows path samples BGRA, respects the clip, and unbinds the SRV, and with the Metal pool test above. I can open a PR against main once this shape is acceptable.

Non-goals

• A new external-compositor trait, or any wgpu types in gpui.
• NV12 video-processor conversion inside the renderer. The caller can hand over an already converted BGRA view.
• Any change in GPUI Kit itself. They pick this up when they bump the snapshot pin.

[Vanuan]

Here's my suggestion

[Vanuan]

Surface work released in bite-gpui v1.23 version. So far, vulkan/linux/dma-buf + va-api path is implemented.
Next up implementing windows path based on media foundation and aligning both paths with mac's corevideo. The consumer API would be published here: https://github.com/bite-gpui/gpui_video

After that, upstreaming work could start. The issue is that I don't have access to all the platforms, so I'd have to rely on virtual machines and/or CI.

[0xbeefd1ed]

macOS. Continue to accept a CVPixelBuffer

But why? Why not directly take a MTLTexture, since that's the texture that the macOS backend will be rendering?

[0xbeefd1ed]

As I understand, CVPixelBuffer describes the whole frame (CoreVideo), so it's the highest level.

CoreVideo is specifically for videos. Why do you want the primitives at the highest level? An application trying to show something that they generated in real time on the GPU wouldn't want to pull in CoreVideo.

This is not shareable by itself.

What do you mean by "sharable"? Shared by whom? And why not?

it must be created in the context of the same MTLDevice

On Apple Silicon Macs, MTLDevice are singleton. One process can have at most one MTLDevice. MTLCreateSystemDefaultDevice always returns the same MTLDevice.

From my limited understanding, there's a difference between Frame and Texture

Can you clarify what do you mean by a frame?

texture is just a handle and a pixel format, so you have to sample it and possibly convert it.

textures are a lot more than that. They can be laid out in multiple image layouts (see vkImageLayout), some of them may be sampled, some of them may be presented. In Vulkan, a texture in VK_IMAGE_LAYOUT_PRESENT_SRC_KHR can be presented. In Metal, a texture created from IOSurface can be presented.

so you have to sample it and possibly convert it.

Why is that bad? GPUI will always have to sample it and blit it into its own framebuffer.

In general, CoreVideo shouldn't show up anywhere on this stack. If the Windows counterpart is a D3D11 SRV, the macOS equivalence is MTLTexture, period. There should also be no requirement on the pixel format of that texture. GPUI should sample that texture inside its own shaders and that should work for any pixel format supported by the GPU.

[Vanuan]

CoreVideo is specifically for videos. Why do you want the primitives at the highest level? An application trying to show something that they generated in real time on the GPU wouldn't want to pull in CoreVideo.

I don't "want" anything. It's what exists now. surface() was specifically added to support external video streams in GPUI apps, as I understand it.

What do you mean by "sharable"? Shared by whom? And why not?

Shareable between gpui renderer and another renderer, whether it's in-process or out of process.
MTLTexture lives in a private memory space, tied to MTLDevice context. And it is hardware specific.

On Apple Silicon Macs, MTLDevice are singleton. One process can have at most one MTLDevice. MTLCreateSystemDefaultDevice always returns the same MTLDevice.

If you want to support only unified architecture, that's a fair argument. OTOH, GPUI is a cross-platform framework, and I'm not sure whether it supports only Apple Silicon. Also, we don't know the future, so the architecture must be flexible if Apple ever decides to support multiple GPUs again. So I imagine you could introduce enum for surface() or abstract away concrete implementation. The point is, you can't model cross-platform framework primitives after opaque high-level APIs. That would significantly increase implementation/maintenance burden for other platforms.

Can you clarify what do you mean by a frame?

While a texture is just content (static bunch of pixels, having width, height and pixel format), a frame represents a presentable abstraction. A frame knows where and when it's being presented. A texture must be sampled by something else at specific time and place.

textures are a lot more than that.

Ok. How is it related?

Why is that bad? GPUI will always have to sample it and blit it into its own framebuffer.

It's not bad, it just means you have to bring a lot more of Metal API into gpui.

If the Windows counterpart is a D3D11 SRV, the macOS equivalence is MTLTexture, period.

I'm not arguing. The proposal is not set in stone. If you have a better proposal you can lay it out. I'm just saying if you want to introduce lower level of abstraction, you have to bring it in through a different API, so that existing apps don't break.

That being said, pretty much every version of Zed introduced breaking changes in gpui, so changing semantics of existing API might be acceptable.

You could also look into gpui_interop and propose additions to bite-gpui, as I currently don't have Mac hardware to iterate on. I might have time next month to start upstreaming gpu_canvas()/surface() patches, so laying out the shape of corresponding Mac surface would be much appreciated.

[0xbeefd1ed]

surface() was specifically added to support external video streams in GPUI apps, as I understand it.

Right, and that's clearly a narrower use case compared to the one we're currently evaluating.

Shareable between gpui renderer and another renderer, whether it's in-process or out of process.

For in-process: MTLTexture is sharable by this definition, as long as they're created for a single device, which is always the case on all Macs that aren't deprecated by Apple. For out-of-process, you will always have to find some way to share memory between two processes, which will probably have to go through the CPU.

If you have a better proposal you can lay it out.

The better proposal would just be providing GPUI with the texture that it actually uses for rendering for the current platform, aka MTLTexture for Mac, D3D11 SRV for Windows, vkImage for Vulkan (if there's ever a Vulkan backend for Linux), wgpu::Texture for wgpu. It will be up to the user to get that texture uploaded to the GPU using the graphics API of that platform. Any special-purpose pixel buffers like CVPixelBuffer should be strictly out-of-scope for GPUI.

For Frame vs Texture: Under your definition, GPUI is a UI framework so it should only ever have to deal with textures. GPUI composes these textures into a "frame", which in graphics land we call a framebuffer, then it presents that framebuffer onto the swapchain. Framebuffer is a texture in a specific format and tied to a specific swapchain. If you happen to get any other presentable surfaces from any other sources that you want to present onto the screen directly, it should be up to you to present those surfaces using platform APIs. Otherwise, you convert those presentable surfaces into a regular texture, which GPUI can then sample and compose onto its own framebuffer.

[Vanuan]

I thought this is simple like that as well, before I tried to actually implement it for Windows and Linux. But there are serious issues with synchronization and zero-copy support. Along with a raw texture, you must provide API to grab and release sync locks. And if you force the user to convert CVPixelBuffer / IOSurface into MTLTexture, you'd introduce additional copy.

It is also requires for API to be platform agnostic and platform-specific at the same time. So that you can wrap it back with wgpu API.

Please, try forking bite-gpui and gpui_interop to see if what you're suggesting is compatible with windows and linux shapes and the metal counterpart actually works without screen tearing and black screens across video and 3D engine producers.

[0xbeefd1ed]

And if you force the user to convert CVPixelBuffer / IOSurface into MTLTexture, you'd introduce additional copy.

Not at all. You can use [MTLTexture newTextureWithDescriptor:iosurface:plane:] or CVMetalTextureCacheCreateTextureFromImage and that should be zero-copy.

screen tearing and black screens

That's not something CVPixelBuffer gives you for free. CVPixelBuffer isn't a "frame" and it doesn't give you "synchronization primitives". What you're likely seeing is Metal 3's automatic hazard tracking and that's there for MTLTexture too. So if you restrict the API to just Metal 3 you don't need to pass in additional "sync lock". I'm assuming that by "sync lock" you mean MTLSharedEvent / MTLFence / vkSemaphore / ID3D11Fence.

Obviously the producer of the MTLTexture will always have to synchronize with GPUI and we don't have a guarantee that the producer will also be using Metal 3 with automatic hazard tracking. That's why it's best if the macOS API offers some platform specific way to synchronize with the producer of the MTLTexture and signal once it's done using it. This applies to D3D11 with ID3D11Fence and Vulkan with vkSemaphore. wgpu does not have any type of explicit synchronization so passing in a wgpu::Texture should be enough.