Trait RenderCommand

Source

pub trait RenderCommand<P: PhaseItem> {
    type Param: SystemParam + 'static;
    type ViewQuery: ReadOnlyQueryData;
    type ItemQuery: ReadOnlyQueryData;

    // Required method
    fn render<'w>(
        item: &P,
        view: ROQueryItem<'w, Self::ViewQuery>,
        entity: Option<ROQueryItem<'w, Self::ItemQuery>>,
        param: SystemParamItem<'w, '_, Self::Param>,
        pass: &mut TrackedRenderPass<'w>,
    ) -> RenderCommandResult;
}

Expand description

RenderCommands are modular standardized pieces of render logic that can be composed into Draw functions.

To turn a stateless render command into a usable draw function it has to be wrapped by a RenderCommandState. This is done automatically when registering a render command as a Draw function via the AddRenderCommand::add_render_command method.

Compared to the draw function the required ECS data is fetched automatically (by the RenderCommandState) from the render world. Therefore the three types Param, ViewQuery and ItemQuery are used. They specify which information is required to execute the render command.

Multiple render commands can be combined together by wrapping them in a tuple.

§Example

The DrawMaterial draw function is created from the following render command tuple. Const generics are used to set specific bind group locations:

pub type DrawMaterial<M> = (
    SetItemPipeline,
    SetMeshViewBindGroup<0>,
    SetMeshBindGroup<1>,
    SetMaterialBindGroup<M, 2>,
    DrawMesh,
);

Required Associated Types§

Source

type Param: SystemParam + 'static

Specifies the general ECS data (e.g. resources) required by RenderCommand::render.

When fetching resources, note that, due to lifetime limitations of the Deref trait, SRes::into_inner must be called on each SRes reference in the RenderCommand::render method, instead of being automatically dereferenced as is the case in normal systems.

All parameters have to be read only.

Source

type ViewQuery: ReadOnlyQueryData

Specifies the ECS data of the view entity required by RenderCommand::render.

The view entity refers to the camera, or shadow-casting light, etc. from which the phase item will be rendered from. All components have to be accessed read only.

Source

type ItemQuery: ReadOnlyQueryData

Specifies the ECS data of the item entity required by RenderCommand::render.

The item is the entity that will be rendered for the corresponding view. All components have to be accessed read only.

For efficiency reasons, Bevy doesn’t always extract entities to the render world; for instance, entities that simply consist of meshes are often not extracted. If the entity doesn’t exist in the render world, the supplied query data will be None.