Module core 

The renderer module is responsible for rendering the scene.

It extracts the main world into the render world and runs the render schedule. It provides the Render and the Extract schedule, of the RenderApp (see RenderSet for the sets of the render schedule). It also provides multiple resources, such as the RenderInstance and the SwapchainFrame, which are used by the render graph and the render pipelines. Lastly, it also handles window events, such as resizing, and sends the corresponding events to the render app.

Render resources

• The render instance is stored in the RenderInstance resource (available in the render app), which is an Arc<RwLock<>> to allow parallelism in the render app.
• The current swap chain frame is stored in the SwapchainFrame resource (available in the render app).
• The device limits are stored in the DeviceLimits resource (available in both the main app and the render app).

Simple render system

To add a simple render system, you can add a system to the render schedule. For example, to update the camera buffer before rendering, you can add a system to the RenderSet::Prepare set of the render schedule:

app.get_sub_app_mut(RenderApp).unwrap()
    .add_systems(Render, update_camera_buffer.in_set(RenderSet::Prepare));

Extract phase

Extracting data from the main world

As the render app runs in a separate thread from the main app, it cannot access the main world directly. To extract data from the main world, you can use the extract schedule and the ExtractWorld system parameter. For example, to extract the camera data from the main world, you can add a system to the extract schedule:

app.get_sub_app_mut(RenderApp).unwrap()
    .add_systems(Extract, extract_camera_data);

fn extract_camera_data(mut commands: Commands, camera_query: ExtractWorld<Query<&Camera>>) {
    let camera = camera_query.single();
    commands.insert_resource(ExtractedCameraData {
        // ...
    });
}

Extracting while mutating the main world

If you need to extract data from the main world while also mutating it, you can use the MainWorld resource:

pub fn extract_messages(
  mut render_test_resource: ResMut<TestResource>,
  mut main_world: ResMut<MainWorld>
) {
   /* (...) */
}

Extracting resources and entities

To extract resources and entities from the main world, see the sync module, which provides utilities to automatically extract resources, query and entities from the main to the render world.

Window events

The renderer also handles window events, such as resizing. If the window is resized, an event of type SurfaceResized is sent to the main and render app, which contains the new width and height of the window in physical pixels. To listen to these events, you can do:

app.get_sub_app_mut(RenderApp).unwrap()
    .add_systems(Render, handle_resize_events);

fn handle_resize_events(mut window_resized_events: MessageReader<SurfaceResized>) {
    for event in window_resized_events.read() {
        // Handle the resize event
    }
}

Structs

DeviceLimits

Resource storing the device limits. This is useful for pipelines to know the limits of the device and adjust their behavior accordingly. It is available in both the main app and the render app, as some pipelines may need to know the limits during extraction.

Extract

The schedule that is used to extract the main world into the render world. Configure it such that it skips applying commands during the extract schedule. The extract schedule will be executed when sync is called between the main app and the sub app.

ExtractWorld

A helper for accessing MainWorld content using a system parameter. ExtractWorld is used to get data from the main world during crate::core::Extract. Note that the system parameter P must implement ReadOnlySystemParam, as the main world is only accessible for reading in this context.

MainWorld

Stores the main world for rendering as a resource. This resource is only available during the extract schedule and is used to move data from the main world to the render world. It is wrapped in a resource to avoid borrowing issues when extracting data from the main world.

Render

The renderer schedule. This schedule is responsible for rendering the scene.

RenderApp

The render app. This is the app that is responsible for rendering the scene. It runs in a separate thread from the main app and has its own schedule and resources. It is used to extract the main world into the render world and run the render schedule. It is also used to manage the swap chain and present the rendered frame to the window.

RenderInstance

The wgpu render instance resource. It is wrapped in an Arc<RwLock<>> to allow it to be shared between the main app and the render app, and to allow it to be mutated from both apps without borrowing issues. It is also wrapped in a resource to avoid borrowing issues when accessing it from different systems.

SurfaceResized

An event that is sent when the surface is resized. This event is sent with the new width and height of the surface. It is used to update the surface configuration and resize the swap chain.

SwapchainFrame

Resource storing the current swap chain frame. This is used to store the current frame that is being rendered to, so that it can be accessed by the render graph and the present system. It is wrapped in an Option because there may not be a frame available at all times (e.g. when the window is minimized). It is also wrapped in a resource to avoid borrowing issues when accessing it from different systems.

Enums

RenderSet

The renderer schedule set. The render schedule will be executed by the renderer app.