prgpu 0.1.16

GPU-accelerated rendering utilities for Adobe Premiere Pro and After Effects plugins
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
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

# `InvocationBase` + `ConfigBuilder`

Adobe hands every render path a different bag of host objects. The
adapters extract those into a single `InvocationBase` before the graph
executor or any per-pass code runs. `ConfigBuilder` then turns the base
+ a few per-pass slot bindings into a `Configuration` (the low-level ABI
struct kernel dispatchers consume).

## `Configuration` (low-level ABI)

Stays as the sole struct passed to generated `kernel::gpu(cfg, params)` /
`kernel::cpu(...)` calls. Don't mutate it field-by-field in effect code —
that's what `ConfigBuilder` is for.

## `InvocationBase` (per-render normalised state)

```rust
pub struct InvocationBase {
    pub host: Host,                    // AfterEffects | Premiere
    pub backend: Backend,              // Cpu | Cuda | Metal | OpenCL
    pub render_kind: RenderKind,
    pub device_handle: *mut c_void,
    pub context_handle: Option<*mut c_void>,
    pub command_queue_handle: *mut c_void,
    pub bytes_per_pixel: u32,
    pub pixel_layout: PixelLayout,     // Rgba | Bgra | Vuya601 | Vuya709
    pub time: f32,
    pub progress: f32,
    pub render_generation: u64,
    pub main_source: FrameBinding,
    pub incoming_source: Option<FrameBinding>,
    pub outgoing_source: Option<FrameBinding>,
    pub output: FrameBinding,
}
```

`InvocationBase` is built ONCE per render call. The adapter:

- AE PF CPU path: `EffectAdapter::build_invocation_cpu`
- AE PF GPU path: `EffectAdapter::build_invocation_gpu`
- Premiere GPU path: `GpuFilterAdapter::build_invocation`

Effect code never constructs one directly outside of tests.

## `FrameBinding` (typed pixel-buffer view)

```rust
pub struct FrameBinding {
    pub data: *mut c_void,
    pub pitch_px: i32,
    pub width: u32,
    pub height: u32,
    pub mip_levels: u32,
    pub bytes_per_pixel: u32,
    pub pixel_layout: PixelLayout,
}
```

`unsafe impl Send + Sync` — the raw pointer is a host-owned token that
survives the dispatch. Same contract as `Configuration`.

## `ConfigBuilder` (per-pass `Configuration` assembly)

```rust
let cfg = ConfigBuilder::new(&base)
    .source(PassBinding::MainSource)         // slot 0 (outgoing)
    .input(PassBinding::Inline(bloom_l0))    // slot 1 (incoming) — optional
    .target(PassBinding::Output)             // slot 2 (dest)
    .dispatch_size(out_w, out_h)             // dispatch grid
    .mip_levels(5)                           // optional
    .build()?;
```

| Slot method   | Maps to                  |
|---------------|--------------------------|
| `source(b)`   | `outgoing` (slot 0)      |
| `outgoing(b)` | same (alias)             |
| `input(b)`    | `incoming` (slot 1)      |
| `incoming(b)` | same (alias)             |
| `target(b)`   | `dest` (slot 2)          |
| `dest(b)`     | same (alias)             |

`PassBinding` variants:

- `MainSource` / `Output` / `OutgoingSource` / `IncomingSource` — resolve
  through `InvocationBase`.
- `Inline(FrameBinding)` — pre-built binding (snapshots, mip slices).
- `Null` — explicit no-op.

When `incoming` is unset, it mirrors `outgoing` — matches kernels that
ignore slot 1 and avoids a separate `dispatch_size` argument for it.

`build()` validates: missing target → `MissingDest`, zero dispatch size →
`ZeroDispatchSize`.

## When to use it directly

The graph executor does this for you. Reach for `ConfigBuilder` directly
only when:

- writing a unit test that needs a synthetic `Configuration`,
- writing custom code that bypasses the graph (e.g. a one-off
  `prepare_source_copy` step).

For everything else, declare passes through
[`render_graph.md`](render_graph.md).