render_pass
Generated Rust API reference for byte_engine.
byte_engine / rendering / render_pass
Module render_pass
Composable sink-local rendering stages.
Implement RenderPass for post-processing or overlays that run after scene
pipelines. Construct resources through RenderPassBuilder so the renderer
can track access policies and named render targets. Existing implementations
live in crate::rendering::render_passes.
Replace the color flowing through the graph with
RenderPassBuilder::create_main_render_target. The builder supplies an
intermediate image or the swapchain without exposing graph position to the pass.
Contents
Quick Reference
| Item | Kind | Description |
|---|---|---|
simple_compute | mod | Reusable construction for BESL compute render passes that bind their resources by name. |
SceneBackgroundTargets | struct | The SceneBackgroundTargets struct hands a scene background the scene pipeline's own targets. |
SceneBackground | struct | The SceneBackground struct shares one sink's background pass between the scene pipeline that records it and the renderer that asks it for frames. |
RenderPassBuilder | struct | The [RenderPassBuilder] struct provides sink resources and records the dependencies of a render pass. |
ReadFromResult | struct | |
RenderToResult | struct | |
MainRenderTarget | struct | The MainRenderTarget struct hides whether a replacement main output is an image or the sink swapchain. |
RenderPassState | enum | The RenderPassState enum identifies which preparation path a render pass uses: [RenderPass::prepare] or [RenderPass::bypass]. |
RenderPass | trait | The RenderPass trait defines a composable rendering step for a prepared sink. |
allocate_render_command | fn | Allocates a prepared render command in the application frame allocator. |
RenderPassReturn | type | A frame-allocated command that records one render pass. |
SceneBackgroundFactory | type | Builds the pass that fills a scene's background for one sink; see [RenderPassBuilder::create_scene_background]. |
Modules
simple_compute— Reusable construction for BESL compute render passes that bind their resources by name.
Structs
SceneBackgroundTargets
struct SceneBackgroundTargets {
pub color: ghi::BaseImageHandle,
pub depth: ghi::BaseImageHandle,
}Defined in crates/byte-engine/src/rendering/render_pass.rs:166-171
The SceneBackgroundTargets struct hands a scene background the scene pipeline's own targets.
They belong to the scene pipeline's render node, so the background uses them directly instead of declaring them
through RenderPassBuilder::read_from or RenderPassBuilder::render_to.
Fields
-
color:ghi::BaseImageHandleThe scene color, written in place wherever
depthis at infinity. -
depth:ghi::BaseImageHandleThe scene's reverse-Z depth, where
0means no surface.
Trait Implementations
impl ArchivePointee for SceneBackgroundTargets
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for SceneBackgroundTargets
impl Clone for SceneBackgroundTargets
-
fn clone(&self) -> SceneBackgroundTargetsRelated:
SceneBackgroundTargets
impl Copy for SceneBackgroundTargets
impl Downcast for SceneBackgroundTargets
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for SceneBackgroundTargets
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for SceneBackgroundTargets
impl LayoutRaw for SceneBackgroundTargets
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for SceneBackgroundTargets
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for SceneBackgroundTargets
-
type Metadata = ()
impl Read for SceneBackgroundTargets
impl WithSubscriber for SceneBackgroundTargets
SceneBackground
struct SceneBackground();Defined in crates/byte-engine/src/rendering/render_pass.rs:180
The SceneBackground struct shares one sink's background pass between the scene pipeline that records it and
the renderer that asks it for frames.
A scene pipeline records it after opaque surfaces and before transparent ones, so transparent surfaces composite
over the background inside the scene color and the scene color needs no coverage channel. Its
RenderPassState is shared by name like any other pass.
Implementations
-
fn prepare<'a>(&self, frame: &mut ghi::implementation::Frame<'_>, sink: &Sink, frame_allocator: &'a bumpalo::Bump) -> Option<RenderPassReturn<'a>>Related:
Sink,RenderPassReturnPrepares the active or bypass path selected by the background's state.
Trait Implementations
impl ArchivePointee for SceneBackground
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for SceneBackground
impl Clone for SceneBackground
-
fn clone(&self) -> SceneBackgroundRelated:
SceneBackground
impl Downcast for SceneBackground
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl Instrument for SceneBackground
impl LayoutRaw for SceneBackground
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for SceneBackground
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for SceneBackground
-
type Metadata = ()
impl Read for SceneBackground
impl WithSubscriber for SceneBackground
RenderPassBuilder<'a>
struct RenderPassBuilder<'a> {
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/rendering/render_pass.rs:207-231
The RenderPassBuilder struct provides sink resources and records the
dependencies of a render pass.
Declare auxiliary outputs with Self::create_render_target or
Self::render_to and inputs with Self::read_from. Use
Self::create_main_render_target for a replacement color result so the
renderer can select the final destination. Then construct the RenderPass
that records commands for those resources.
Implementations
-
fn debug_views(&mut self, views: &'static [&'static str]) -> DebugViewsRelated:
DebugViewsDeclares the debug views this pass can show, at most
MAX_VIEWS_PER_PASS, in the order the shader numbersthem from
0, and returns the pool they write into.Each view is selectable as
render.debug.view.<pass name>.<view name>, where the pass name isRenderPass::nameor the scene pipeline manager's name. The renderer records this pass as a writer of everypool slot. When the project leaves debug views out, the result reports no view shown and holds no targets.
Call it once per pass.
Panics
Panics on a second call, on more than
MAX_VIEWS_PER_PASSviews, or on a view name with a dot. -
fn create_gpu_counter(&mut self, name: &str) -> ghi::CounterHandleCreates a GPU timing counter for one stage of this node's commands, which the inspector reports as
stage.<name>next to the node's ownscene.<manager>orpass.<name>time.Wrap the stage's commands with
ghi::command_buffer::CommonCommandBufferMode::counterinside the node'srecording, once per frame, and only on frames the stage records: a counter around no commands reports a
meaningless near-zero time. Stage counters nest inside the node's counter, so a node's stages add up to its
time plus whatever it records outside them.
-
fn create_scene_background(&mut self, targets: SceneBackgroundTargets) -> Option<SceneBackground>Related:
SceneBackgroundTargets,SceneBackgroundCreates this sink's scene background, or returns
Nonewhen the application registered none.Scene pipelines call this with their color and depth
targets. Record the result after opaque surfaces andbefore transparent ones.
-
fn alias(&mut self, orig: &'a str, alias: &'a str) -
fn format_of(&self, name: &str) -> ghi::Formats -
fn render_to(&mut self, name: &'a str) -> RenderToResultRelated:
RenderToResultReturns an existing image for writing by this render pass.
-
fn create_render_target(&mut self, builder: ghi::image::Builder<'a>) -> RenderToResultRelated:
RenderToResultCreates a transferable render-target image and returns it for writing by this render pass.
-
fn create_scaled_render_target(&mut self, builder: ghi::image::Builder<'a>, resolution_divisor: u32) -> RenderToResultRelated:
RenderToResultCreates a transferable render-target image at a fraction of the sink resolution.
The renderer sizes the image to the sink extent divided by
resolution_divisor, so2gives ahalf-resolution target. Like every render target, it can be captured by name for debugging.
The target holds valid contents only between the first and the last pass of a frame that uses it, since
targets whose uses do not overlap share memory. Its contents are undefined when its first pass starts, so that
pass must write every pixel it later reads. Use
Self::create_persistent_render_targetfor contents thatmust survive into the next frame.
-
fn create_persistent_render_target(&mut self, builder: ghi::image::Builder<'a>) -> RenderToResultRelated:
RenderToResultCreates a full-resolution render target whose contents stay valid across frames.
Use it for images a pass updates incrementally, such as a layer that only redraws damaged regions. Unlike
Self::create_render_target, the target never shares memory with other targets. -
fn create_history_target(&mut self, builder: ghi::image::Builder<'a>, resolution_divisor: u32) -> ghi::DynamicImageHandleCreates a sink-sized image that keeps one copy per frame in flight, so later frames can read it as history.
The renderer sizes the image to the sink extent divided by
resolution_divisor, but never binds it as anattachment, so no pass clears it.
The creating pass writes this frame's copy. Any pass reads the previous frame's copy by binding the handle
with
ghi::DescriptorWrite::combined_image_sampler_with_frameand an offset of-1.A previous-frame copy holds no usable data on a sink's first frame or right after a resize, so the reading pass
must track whether it recorded the sink at the same extent in the previous frame.
-
fn create_main_render_target(&mut self, builder: ghi::image::Builder<'a>) -> MainRenderTargetRelated:
MainRenderTargetCreates a replacement for the color image named
main.The renderer supplies the sink swapchain when this pass is terminal. In
every other position, this creates and aliases the requested image. Bind
the returned target as a writable image without inspecting its variant.
Compute shaders must use a formatless storage-image output because the
swapchain format can differ from the intermediate format. Raster passes
should derive their attachment descriptor from the returned target. Next,
bind a compute output with
simple_compute::Resource::image.While the pass is bypassed, the renderer copies the incoming
maininto the replacement, so later passes readthe image this pass would have transformed.
-
fn read_from(&mut self, name: &'a str) -> ReadFromResultRelated:
ReadFromResult -
fn context(&mut self) -> &mut ghi::implementation::Context -
fn pipeline_manager(&self) -> &crate::rendering::PipelineManagerClientRelated:
PipelineManagerClientReturns a client for requesting pipelines shared by renderer dependants.
Trait Implementations
impl ArchivePointee for RenderPassBuilder<'a>
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for RenderPassBuilder<'a>
impl Downcast for RenderPassBuilder<'a>
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl Instrument for RenderPassBuilder<'a>
impl LayoutRaw for RenderPassBuilder<'a>
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for RenderPassBuilder<'a>
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for RenderPassBuilder<'a>
-
type Metadata = ()
impl Read for RenderPassBuilder<'a>
impl WithSubscriber for RenderPassBuilder<'a>
ReadFromResult
struct ReadFromResult {
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/rendering/render_pass.rs:574-576
Trait Implementations
impl ArchivePointee for ReadFromResult
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for ReadFromResult
impl Clone for ReadFromResult
-
fn clone(&self) -> ReadFromResultRelated:
ReadFromResult
impl Copy for ReadFromResult
impl Downcast for ReadFromResult
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for ReadFromResult
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for ReadFromResult
impl LayoutRaw for ReadFromResult
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for ReadFromResult
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for ReadFromResult
-
type Metadata = ()
impl Read for ReadFromResult
impl WithSubscriber for ReadFromResult
RenderToResult
struct RenderToResult {
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/rendering/render_pass.rs:591-594
Trait Implementations
impl ArchivePointee for RenderToResult
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for RenderToResult
impl Clone for RenderToResult
-
fn clone(&self) -> RenderToResultRelated:
RenderToResult
impl Copy for RenderToResult
impl Downcast for RenderToResult
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for RenderToResult
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for RenderToResult
impl LayoutRaw for RenderToResult
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for RenderToResult
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for RenderToResult
-
type Metadata = ()
impl Read for RenderToResult
impl WithSubscriber for RenderToResult
MainRenderTarget
struct MainRenderTarget {
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/rendering/render_pass.rs:619-622
The MainRenderTarget struct hides whether a replacement main output is an image or the sink swapchain.
Pass it directly to simple_compute::Resource::image or convert it into a
raster attachment descriptor.
Trait Implementations
impl ArchivePointee for MainRenderTarget
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for MainRenderTarget
impl Clone for MainRenderTarget
-
fn clone(&self) -> MainRenderTargetRelated:
MainRenderTarget
impl Copy for MainRenderTarget
impl Downcast for MainRenderTarget
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for MainRenderTarget
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for MainRenderTarget
impl LayoutRaw for MainRenderTarget
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for MainRenderTarget
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for MainRenderTarget
-
type Metadata = ()
impl Read for MainRenderTarget
impl WithSubscriber for MainRenderTarget
Enums
RenderPassState
enum RenderPassState {
Enabled,
Bypassed,
}Defined in crates/byte-engine/src/rendering/render_pass.rs:88-92
The RenderPassState enum identifies which preparation path a render pass uses: RenderPass::prepare or
RenderPass::bypass.
Trait Implementations
impl ArchivePointee for RenderPassState
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for RenderPassState
impl Clone for RenderPassState
-
fn clone(&self) -> RenderPassStateRelated:
RenderPassState
impl Copy for RenderPassState
impl Debug for RenderPassState
-
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Default for RenderPassState
-
fn default() -> RenderPassStateRelated:
RenderPassState
impl Downcast for RenderPassState
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for RenderPassState
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Eq for RenderPassState
impl<K> Equivalent for RenderPassState
-
fn equivalent(&self, key: &K) -> bool
impl Instrument for RenderPassState
impl LayoutRaw for RenderPassState
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for RenderPassState
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for RenderPassState
-
fn eq(&self, other: &RenderPassState) -> boolRelated:
RenderPassState
impl Pointee for RenderPassState
-
type Metadata = ()
impl Read for RenderPassState
impl<R> ReadPrimitive for RenderPassState
impl StructuralPartialEq for RenderPassState
impl WithSubscriber for RenderPassState
Traits
RenderPass
trait RenderPass { ... }Defined in crates/byte-engine/src/rendering/render_pass.rs:48-83
The RenderPass trait defines a composable rendering step for a prepared sink.
Build persistent images and shader state through RenderPassBuilder, then
return frame-local recording work from Self::prepare. Register the
implementation with crate::rendering::renderer::Renderer.
Required Methods
-
fn name(&self) -> &'static strReturns the stable name used to control every sink-local instance of this pass.
-
fn prepare<'a>(&mut self, frame: &mut ghi::implementation::Frame<'_>, sink: &Sink, frame_allocator: &'a bumpalo::Bump) -> Option<RenderPassReturn<'a>>Prepares the render pass when its rendering condition is active.
Provided Methods
-
fn bypass<'a>(&mut self, _frame: &mut ghi::implementation::Frame<'_>, _sink: &Sink, _frame_allocator: &'a bumpalo::Bump) -> Option<RenderPassReturn<'a>>Prepares the maintenance work this pass still needs while it is bypassed.
-
fn needs_frame(&mut self) -> boolReports whether this pass has output that the last presented frame does not show yet.
Implementors
Functions
allocate_render_command
fn allocate_render_command<'a>(frame_allocator: &'a bumpalo::Bump, command: impl RenderPassFunction + Send + Sync + 'a) -> RenderPassReturn<'a>Defined in crates/byte-engine/src/rendering/render_pass.rs:36-41
Allocates a prepared render command in the application frame allocator.
Type Aliases
RenderPassReturn<'a>
type RenderPassReturn<'a> = &'a dyn RenderPassFunction + Send + Sync;Defined in crates/byte-engine/src/rendering/render_pass.rs:33
A frame-allocated command that records one render pass.
SceneBackgroundFactory
type SceneBackgroundFactory = dyn Fn(&'builder mut RenderPassBuilder<'resources>, SceneBackgroundTargets) -> utils::Box<dyn RenderPass>;Defined in crates/byte-engine/src/rendering/render_pass.rs:156-159
Builds the pass that fills a scene's background for one sink; see RenderPassBuilder::create_scene_background.