grafting 0.5.1

Native texture interop helpers for importing offscreen producer frames into host-owned wgpu textures
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

# grafting


Import native GPU textures (GL framebuffers, Vulkan images, Metal IOSurfaces) into host-owned `wgpu` textures. This is the core library of the [servo-wgpu-interop](../) workspace.

This crate is **framework-agnostic** — it has no Servo dependency and can be used by any application that needs to import externally-produced GPU content into wgpu.

## What it does


A "producer" (Servo, a GL renderer, a video decoder, etc.) renders into a native GPU resource. This crate imports that resource into a `wgpu::Texture` owned by the host application, enabling zero-copy compositing across API boundaries.

## Platform support


| Platform | Import path | Status |
| --- | --- | --- |
| Linux / Android | GL FBO → Vulkan external memory → wgpu | Implemented |
| macOS / iOS | IOSurface → Metal texture → wgpu | Implemented |
| Windows (Vulkan) | GL FBO → Vulkan image (NT handle) → wgpu | Implemented |
| Windows (DX12) | GL FBO → DX12 shared texture → wgpu | Hardware-verified through the Servo demos |

## Key types


- `HostWgpuContext` — wraps the host's `wgpu::Device` and `wgpu::Queue`
- `NativeFrame` — platform-specific frame produced by the offscreen renderer
- `ImportedTexture` — the result of importing a `NativeFrame` into wgpu
- `ImportOptions` — controls import behavior (format, usage flags)
- `CapabilityMatrix` — runtime query of what the current platform/driver supports
- `InteropBackend` — detected backend (Vulkan, Metal, DX12)
- `FrameProducer` / `TextureImporter` — traits for the produce/import pipeline
- `WgpuTextureImporter` — default `TextureImporter` implementation
- `InteropSynchronizer` — trait for cross-API synchronization policies

## Modules


- `raw_gl` — surfman-independent GL import functions. Use `RawGlFrameProducer` for any GL application without bringing surfman as a dependency (set `default-features = false`).
- `surfman_gl` — surfman-backed frame producer (enabled by default via the `surfman` feature).

## Usage


For Servo embedding, pair this crate with [`servo-wgpu-interop-adapter`](../servo-wgpu-interop-adapter/) which handles Servo-specific setup. For standalone GL import, see [`demo-raw-gl`](../demo-raw-gl/) which uses the `raw_gl` module directly.

Pick exactly one `wgpu-*` feature; it must match the wgpu your host already
uses, or the imported texture will not share a device.

```toml
[dependencies]
# Default: wgpu 29, plus the surfman GL producer path.

grafting = "0.5.1"

# Same, against wgpu 28.

grafting = { version = "0.5.1", default-features = false, features = ["wgpu-28", "surfman"] }

# Shared-texture import only (DX12 / Metal / Vulkan DMABUF). No GL, no
# surfman, no glow. This is what wgpu-weld takes.
grafting = { version = "0.5.1", default-features = false, features = ["wgpu-29"] }

# Same shared-texture surface against wgpu 30.
grafting = { version = "0.5.1", default-features = false, features = ["wgpu-30"] }
```

## License


[MPL-2.0](../LICENSE)