ProtoPie renderer — renderer-gpu
개발 문서 원문 텍스트 추출본 / 2026-09-14

# renderer-gpu

wgpu context + RHI (Rendering Hardware Interface) trait abstraction layer. All rendering backends consume this crate.

## Module layout

```
src/
├── lib.rs                              # module declarations + pub use (RHI types/traits)
├── context.rs                          # GpuContext, GpuBackend, GpuContextError, browser backend mask
├── config.rs                           # SurfaceConfig
├── binding/
│   ├── bind_group_cache.rs             # WgpuBindGroupCache — LRU bind group cache
│   └── texture_binding_system.rs       # WgpuTextureBindingSystem — texture bind group management
└── rhi/
    ├── mod.rs                          # RHI re-exports
    ├── error.rs                        # RhiError, RhiResult
    ├── traits.rs                       # RHI trait definitions
    ├── types.rs                        # RHI descriptor types
    └── wgpu.rs                         # wgpu trait implementations
```

## RHI traits

| Trait                | Role                                                            |
|----------------------|-----------------------------------------------------------------|
| `RhiObject`          | base — `MaybeSendSync` + `as_any()` for downcast                |
| `RhiDevice`          | create buffers / textures / bind groups / pipelines / passes    |
| `RhiQueue`           | submit + `write_buffer()` + `write_texture()` (raw + rgba8)     |
| `RhiBuffer`          | GPU buffer (`size()`)                                           |
| `RhiTexture`         | GPU texture (`desc()`)                                          |
| `RhiTextureView`     | marker                                                          |
| `RhiSampler`         | marker                                                          |
| `RhiBindGroupLayout` | marker                                                          |
| `RhiBindGroup`       | marker                                                          |
| `RhiShaderModule`    | marker                                                          |
| `RhiPipelineLayout`  | marker                                                          |
| `RhiRenderPipeline`  | marker                                                          |
| `RhiRenderPass`      | `set_pipeline / set_bind_group / draw_indexed / …`              |
| `RhiCommandEncoder`  | `begin_render_pass / finish`                                    |
| `RhiCommandBuffer`   | finished command buffer                                         |

## Descriptor types

| Type                  | 역할                                                   |
|-----------------------|--------------------------------------------------------|
| `BufferDesc`          | size, usage, mapped_at_creation                        |
| `BufferUsage`         | UNIFORM / VERTEX / INDEX / COPY_DST / COPY_SRC         |
| `TextureDesc`         | width, height, format, usage, sample_count             |
| `TextureUsage`        | TEXTURE_BINDING / COPY_DST / RENDER_ATTACHMENT / COPY_SRC |
| `SamplerDesc`         | filter modes, address modes                            |
| `BindGroupLayoutEntry` / `BindGroupEntry` | binding metadata                  |
| `BindingType`         | UniformBuffer / Texture (filterable/unfilterable/uint) / Sampler |
| `BindingResource`     | Buffer / EntireBuffer / TextureView / Sampler          |
| `RenderPipelineDesc`  | layout, shader, vertex layout, format, blend_mode      |
| `RenderPassDesc`      | label, color attachments                               |
| `ColorAttachment`     | view, load_op                                          |
| `VertexFormat`        | Float32x2 / Float32x4                                  |
| `IndexFormat`         | Uint16 / Uint32                                        |
| `LoadOp`              | Clear(RhiColor) / Load                                 |

## wgpu wrappers

`Wgpu*` (`WgpuRhiDevice`, `WgpuRhiQueue`, `WgpuRhiBuffer`, …) — production wgpu 26 백엔드 구현. Trait object 는 모두 `Arc<dyn ...>` 로 공유 소유.

## Platform markers

`MaybeSend` / `MaybeSendSync` — 조건부 Send / Sync.
- Native: `Send` / `Send + Sync` 요구.
- WASM: no-op (browser wgpu 객체는 single-thread 라 `!Send`).

## Hard rules

- wgpu 26.x render pass 패턴 준수.
- Compute shader 는 WebGPU only (WebGL 미지원).
- 텍스처 포맷: surface capability 에 따라 Bgra8Unorm 또는 Rgba8Unorm. 텍스처 경로 따라 Rgba16Float / Rgba16Uint.
- 모든 RHI trait object 는 `Arc<dyn Trait>`. `as_any()` 로 downcast 지원.
- Stencil format: Depth24PlusStencil8.
- Texture cache / provider 는 renderer-resource 가 소유. 이 crate 에 두지 않음.
- WASM 빌드는 `Arc<dyn Rhi*>` 를 `!Send/!Sync` 객체로 유지. `clippy::arc_with_non_send_sync` 는 wasm wrapper / module 경계에서만 suppress.

## Dependencies

- renderer-core (BlendMode)
- wgpu 26