bevyengine/bevy

bevy_render

The render SubApp, the render graph, and the GPU resource layer. The center of Bevy's rendering architecture: every other rendering crate (bevy_pbr, bevy_sprite_render, bevy_ui_render, etc.) builds on the abstractions defined here.

Purpose

bevy_render runs Bevy's GPU work in a separate SubApp (RenderSubApp) so the main world can compute frame N+1 while the GPU is still on frame N. It owns:

The RenderApp SubApp and the ExtractSchedule that copies data from the main world into it each frame.
The RenderGraph — a DAG of nodes (clears, passes, compute dispatches) that gets walked once per frame.
The wgpu device, queue, and pipeline cache.
Asset extraction for meshes, images, and materials.
Cameras, views, and visibility infrastructure (the bevy_camera crate hosts the data types; this crate hosts the systems).
Phase items and render phases (sorted draw lists per pass).

Directory layout

crates/bevy_render/src/
├── lib.rs                   # RenderPlugin, RenderApp setup
├── extract_*               # Helper traits to extract data into the render world
├── extract_resource.rs     # Auto-extract simple resources
├── extract_component.rs    # Auto-extract components
├── render_graph/           # Render graph + node trait
├── render_resource/        # wgpu wrappers (Buffer, Texture, BindGroup, Pipeline)
├── render_phase/           # PhaseItem, RenderPhase, sorting
├── pipelined_rendering.rs  # The pipelined-rendering wiring
├── camera/                 # CameraPlugin (bridges bevy_camera)
├── view/                   # Per-view extraction & uniforms
├── globals/                # Global uniform buffer (time, viewport)
├── batching/               # GPU instance buffers
├── settings.rs             # WgpuSettings (limits, features)
└── …

Key abstractions

Type	File	Description
`RenderPlugin`	`crates/bevy_render/src/lib.rs`	The plugin that adds the render SubApp.
`RenderApp` (label)	`crates/bevy_render/src/lib.rs`	`AppLabel` for the render SubApp.
`ExtractSchedule`	`crates/bevy_render/src/lib.rs`	Schedule that runs in the render SubApp with read access to the main world.
`RenderSet`	`crates/bevy_render/src/lib.rs`	System sets: `ExtractCommands`, `Prepare`, `Queue`, `Render`, etc.
`RenderGraph`	`crates/bevy_render/src/render_graph/graph.rs`	DAG of `Node`s.
`Node` (trait)	`crates/bevy_render/src/render_graph/node.rs`	A render-graph node with an `update` and `run` method.
`RenderPhase<I>`	`crates/bevy_render/src/render_phase/mod.rs`	A sorted list of phase items for one camera pass.
`PhaseItem` (trait)	`crates/bevy_render/src/render_phase/mod.rs`	Anything draw-able in a phase (`Opaque3d`, `Transparent2d`, etc).
`WgpuSettings`	`crates/bevy_render/src/settings.rs`	Limits, features, backend selection.
`RenderDevice` / `RenderQueue` / `RenderAdapter`	`crates/bevy_render/src/renderer/mod.rs`	wgpu wrappers as ECS resources.
`PipelineCache`	`crates/bevy_render/src/render_resource/pipeline_cache.rs`	Async-compiled `wgpu::RenderPipeline` cache.
`ExtractComponentPlugin<C>`	`crates/bevy_render/src/extract_component.rs`	Boilerplate for "extract this component each frame."
`ExtractResourcePlugin<R>`	`crates/bevy_render/src/extract_resource.rs`	Same for resources.

How it works

sequenceDiagram
    participant Main as Main World
    participant Render as Render World
    participant GPU as wgpu

    Main->>Main: Update / PostUpdate
    Main->>Render: ExtractSchedule (with main world access)
    Render->>Render: PrepareSet (allocate buffers, bind groups)
    Render->>Render: QueueSet (sort phase items)
    Render->>Render: RenderSet (walk render graph)
    Render->>GPU: encode CommandBuffer
    Render->>GPU: queue.submit
    GPU-->>Render: present

The pipelined-rendering wrinkle: while the renderer is running in the render SubApp, the main SubApp is allowed to compute the next frame. The two SubApps synchronize at ExtractSchedule (renderer reads main world; main paused) and at frame submission. This is what pipelined_rendering.rs orchestrates.

The render graph

A RenderGraph is a DAG of nodes. Each node has labeled input and output slots (textures, buffers, view IDs). On run, the graph walks dependencies and asks each node to record commands into a RenderContext. The built-in graph contains nodes from bevy_core_pipeline (clear, prepass, main pass, tonemapping), bevy_pbr (shadow pass, deferred), bevy_ui_render (UI pass), and so on.

User code can insert nodes with app.add_node / app.add_node_edge to build custom pipelines.

Render phases and sorting

A render phase is a typed list of PhaseItems. Each item carries a sort key (distance, material, mesh ID) plus an entity ID. Phases are produced in the Queue step, sorted in Sort, and drained in Render. Standard phases include Opaque3d, AlphaMask3d, Transparent3d, Shadow, Opaque2d, Transparent2d, etc.

Pipeline cache

PipelineCache compiles wgpu::RenderPipelines asynchronously on a background task pool. Materials and meshes request a pipeline by specialization key (mesh layout + material variant + shader defs) and get back a handle to either a ready or in-progress pipeline. Pipeline objects are cached and reused across frames.

Integration points

Depends on: wgpu, bevy_app, bevy_ecs, bevy_asset, bevy_image, bevy_mesh, bevy_shader, bevy_camera, bevy_color, bevy_math, bevy_window.
Depended on by: bevy_pbr, bevy_sprite_render, bevy_ui_render, bevy_post_process, bevy_anti_alias, bevy_gizmos_render, bevy_solari, bevy_core_pipeline, anything that issues GPU work.
Environment variables: WGPU_DEBUG, WGPU_VALIDATION, WGPU_FORCE_FALLBACK_ADAPTER, WGPU_ADAPTER_NAME, WGPU_SETTINGS_PRIO, VERBOSE_SHADER_ERROR. See the crate-level rustdoc.

Entry points for modification

Adding a render-graph node: implement Node, register with RenderGraph::add_node, wire edges with add_node_edge. See crates/bevy_core_pipeline/src/core_3d/main_pass_3d_node.rs for a worked example.
Adding a phase item type: implement PhaseItem and CachedRenderPipelinePhaseItem. Look at Opaque3d in bevy_core_pipeline.
Customizing wgpu setup: insert WgpuSettings before adding RenderPlugin.
Per-frame uniforms: look at view/ and globals/ for the patterns. Each "view" gets a uniform buffer with camera matrices.
Adding a render resource type: implement the trait in render_resource/ or just use wgpu types directly via the RenderDevice resource.