Internal documentation: control flow between different layers

[kpreid]

The big picture architecture diagram has a useful set of arrows. However, when I have contributed to wgpu, I've sometimes gotten lost in a maze of similarly-named functions and types in multiple libraries; particularly, #3052 involved a lot of trial and error, simply changing stuff and seeing what compile errors appeared.

I'd like to request that someone familiar with the architecture create a narrower-focused diagram, which specifically lists the types (various Contexts?) and function calls involved in a Rust-user-facing operation (wgpu::Foo::bar()) passing through wgpu-core and wgpu-hal all the way to backend-specific code, so that if, for example, someone wants to pass additional information through those layers, they can understand what all the layers that need to be changed are, and thus discover the constraints in play before they start tinkering. This document might also discuss how backend dispatch works, to make it clear what code might be not being executed on the developer's platform and thus needing additional attention.

[Wumpf]

kinda related to

• wgpu_hal rules are not documented #4098