set_layout
Generated Rust API reference for byte_engine.
byte_engine / rendering / set_layout
Module set_layout
Descriptor set layouts the renderer shares with its shaders, and name-based binding of resources to them.
A layout layer, a .besl file that declares descriptors, is the single declaration of one descriptor set: the
shaders that list the layer are baked against it, and the renderer builds its SetLayout from the same file
with SetLayout::from_layers. Resources are bound by the names the layer gives them, so no slot number is
repeated in Rust.
Contents
Quick Reference
| Item | Kind | Description |
|---|---|---|
SetLayout | struct | The SetLayout struct describes one descriptor set the renderer shares with its shaders: the GHI layout sets are created from, and the name each resource has in BESL. |
SetBinder | struct | The SetBinder struct builds the descriptor writes of one set by BESL resource name. |
PipelineSets | struct | The PipelineSets struct holds the descriptor sets [create_sets] made for one pipeline, to bind when the pipeline is recorded. |
PublishedSets | struct | The PublishedSets struct holds the descriptor sets of one pipeline whose layouts are only known once it is published, and makes them again when the pipeline is rebuilt. |
Resource | enum | The Resource enum names one concrete resource for a BESL binding, for [create_sets] to bind by name. |
create_sets | fn | Creates the descriptor sets a published pipeline reads, one per layout its shaders use, and binds resources to them by BESL name. |
MAX_PIPELINE_SETS | const | The most descriptor sets [create_sets] makes for one pipeline: the shader's own and the layout layers it lists. |
MAX_IMAGE_ARRAY_ELEMENTS | const | The most elements [Resource::image_array] binds, which is the most debug targets a sink's pool holds. |
Structs
SetLayout
struct SetLayout {
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/rendering/set_layout.rs:35-38
The SetLayout struct describes one descriptor set the renderer shares with its shaders: the GHI layout sets are
created from, and the name each resource has in BESL.
Build it from a layout layer with Self::from_layers, or from a published pipeline's interface with
Self::new. Next, create a set with Self::create_set and bind resources to it by name through
Self::binder. Cloning is cheap; clones are the same layout.
Implementations
-
fn new(interface: &SetInterface) -> SelfBuilds the layout a baked shader declares.
-
fn from_layers(layers: &[(&str, &str)]) -> SelfBuilds the layout the last of
layersdeclares. The layers before it are the ones it builds on, lowest first,as a shader's sidecar lists them. Give each layer as its name, which diagnostics show, and its source, such as
the layer's asset path and
include_str!of the file.Panics
Panics when the layers do not link, or when the last layer declares no descriptor. Both are errors in the
engine's own assets.
-
fn merged<'a>(sets: impl IntoIterator<Item = &'a SetLayout>) -> Arc<[SetLayout]>Related:
SetLayoutReturns each distinct layout of
setsonce, in first-seen order, with the bindings any of its copies usesmarked as used.
A pipeline's stages each declare the layouts they list; this is the pipeline's view of them.
-
fn layout(&self) -> &ghi::DescriptorSetLayoutReturns the GHI layout, which descriptor sets are created from and shaders declare.
-
fn interface(&self) -> &SetInterfaceReturns the layout's bindings, with the names BESL gives them.
-
fn slot(&self, name: &str) -> ghi::ResourceSlotReturns the slot of the resource BESL names
name.Panics
Panics when the layout declares no such resource.
-
fn create_set(&self, context: &mut impl ContextCreate, name: &str) -> ghi::DescriptorSetHandleCreates an empty descriptor set for this layout. Next, write its resources through
Self::binder. -
fn binder(&self, set: ghi::DescriptorSetHandle) -> SetBinder<'_>Related:
SetBinderReturns a binder that builds the writes of
set, which must have been created from this layout.
Trait Implementations
impl ArchivePointee for SetLayout
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for SetLayout
impl Clone for SetLayout
-
fn clone(&self) -> SetLayoutRelated:
SetLayout
impl Downcast for SetLayout
-
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 SetLayout
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for SetLayout
impl LayoutRaw for SetLayout
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for SetLayout
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for SetLayout
-
type Metadata = ()
impl Read for SetLayout
impl WithSubscriber for SetLayout
SetBinder<'a>
struct SetBinder<'a> {
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/rendering/set_layout.rs:143-146
The SetBinder struct builds the descriptor writes of one set by BESL resource name.
Get one from SetLayout::binder, then pass its writes to ghi::context::Context::write or
ghi::frame::Frame::write. Every method panics when the layout declares no resource of that name.
Implementations
-
fn set(&self) -> ghi::DescriptorSetHandleReturns the set the writes target.
-
fn slot(&self, name: &str) -> ghi::ResourceSlotReturns the slot of the resource named
name, for the writes this binder has no method for. -
fn buffer(&self, name: &str, buffer: impl Into<ghi::BaseBufferHandle>) -> ghi::DescriptorWriteBinds a buffer.
-
fn image(&self, name: &str, image: impl Into<ghi::BaseImageHandle>) -> ghi::DescriptorWriteBinds a storage image a shader loads or stores.
-
fn image_element(&self, name: &str, image: impl Into<ghi::BaseImageHandle>, index: u32) -> ghi::DescriptorWriteBinds one mip of a storage image.
Binds one element of an arrayed storage image, such as a debug target pool slot.
-
fn image_mip(&self, name: &str, image: impl Into<ghi::BaseImageHandle>, mip_level: u32) -> ghi::DescriptorWrite -
fn sampled(&self, name: &str, image: impl Into<ghi::BaseImageHandle>, sampler: ghi::SamplerHandle) -> ghi::DescriptorWriteBinds a texture a shader samples through
sampler. -
fn sampled_with_frame(&self, name: &str, image: ghi::DynamicImageHandle, sampler: ghi::SamplerHandle, frame_offset: i32) -> ghi::DescriptorWriteBinds the copy of a per-frame texture that belongs to a relative frame, such as
-1for the previous frame. -
fn sampled_element(&self, name: &str, image: impl Into<ghi::BaseImageHandle>, sampler: ghi::SamplerHandle, index: u32) -> ghi::DescriptorWriteBinds one element of a texture array.
Trait Implementations
impl ArchivePointee for SetBinder<'a>
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for SetBinder<'a>
impl Clone for SetBinder<'a>
-
fn clone(&self) -> SetBinder<'a>Related:
SetBinder
impl Copy for SetBinder<'a>
impl Downcast for SetBinder<'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 DowncastSync for SetBinder<'a>
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for SetBinder<'a>
impl LayoutRaw for SetBinder<'a>
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for SetBinder<'a>
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for SetBinder<'a>
-
type Metadata = ()
impl Read for SetBinder<'a>
impl WithSubscriber for SetBinder<'a>
PipelineSets
struct PipelineSets {
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/rendering/set_layout.rs:251-254
The PipelineSets struct holds the descriptor sets create_sets made for one pipeline, to bind when the
pipeline is recorded. A fixed capacity keeps it copyable into render commands.
Implementations
-
fn handles(&self) -> SmallVec<[ghi::DescriptorSetHandle; 4]>Returns the sets to pass to
bind_descriptor_sets.
Trait Implementations
impl ArchivePointee for PipelineSets
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for PipelineSets
impl Clone for PipelineSets
-
fn clone(&self) -> PipelineSetsRelated:
PipelineSets
impl Copy for PipelineSets
impl Default for PipelineSets
-
fn default() -> PipelineSetsRelated:
PipelineSets
impl Downcast for PipelineSets
-
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 PipelineSets
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for PipelineSets
impl LayoutRaw for PipelineSets
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for PipelineSets
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for PipelineSets
-
type Metadata = ()
impl Read for PipelineSets
impl<R> ReadPrimitive for PipelineSets
impl WithSubscriber for PipelineSets
PublishedSets
struct PublishedSets {
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/rendering/set_layout.rs:269-274
The PublishedSets struct holds the descriptor sets of one pipeline whose layouts are only known once it is
published, and makes them again when the pipeline is rebuilt.
Keep one next to the pipeline's PipelineRef and call Self::get each
frame before recording.
Implementations
-
fn get(&mut self, frame: &mut ghi::implementation::Frame<'_>, pipeline_manager: &crate::rendering::PipelineManagerClient, pipeline: crate::rendering::PipelineRef, name: &str, resources: &[Resource]) -> Option<PipelineSets>Related:
PipelineManagerClient,PipelineRef,Resource,PipelineSetsReturns the pipeline's sets, creating them with
create_setsthe first time the pipeline is available andafter each rebuild. Returns
Nonewhile the pipeline is unavailable, or whenresourcesdo not match itslayouts, which is logged once per revision.
Trait Implementations
impl ArchivePointee for PublishedSets
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for PublishedSets
impl Clone for PublishedSets
-
fn clone(&self) -> PublishedSetsRelated:
PublishedSets
impl Copy for PublishedSets
impl Default for PublishedSets
-
fn default() -> PublishedSetsRelated:
PublishedSets
impl Downcast for PublishedSets
-
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 PublishedSets
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for PublishedSets
impl LayoutRaw for PublishedSets
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for PublishedSets
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for PublishedSets
-
type Metadata = ()
impl Read for PublishedSets
impl<R> ReadPrimitive for PublishedSets
impl WithSubscriber for PublishedSets
Enums
Resource
enum Resource {
Buffer(&'static str, ghi::BaseBufferHandle),
PlannedBuffer(&'static str, ghi::BaseBufferHandle),
Image(&'static str, ghi::ImageOrSwapchain),
ImageArray(&'static str, [Option<ghi::BaseImageHandle>; 15]),
CombinedImageSampler(&'static str, ghi::BaseImageHandle, ghi::SamplerHandle, ghi::Layouts),
}Defined in crates/byte-engine/src/rendering/set_layout.rs:356-363
The Resource enum names one concrete resource for a BESL binding, for create_sets to bind by name.
Variants
-
ImageArrayThe first
countimages of an arrayed storage-image binding, element by element.
Implementations
-
fn buffer(name: &'static str, buffer: impl Into<ghi::BaseBufferHandle>) -> Self -
fn planned_buffer(name: &'static str, buffer: impl Into<ghi::BaseBufferHandle>) -> SelfKeeps a buffer ready for a BESL binding that is intentionally not reachable yet.
-
fn image(name: &'static str, image: impl Into<ghi::ImageOrSwapchain>) -> SelfBinds a storage-image destination without exposing whether it is an image or swapchain.
-
fn image_array(name: &'static str, images: &[ghi::BaseImageHandle]) -> SelfBinds
imagesto the first elements of an arrayed storage-image binding, such as the debug target pool ashader declares as
debug_view_targets. Elements past them stay unbound, so the shader must not index them.Panics
Panics with more than
MAX_IMAGE_ARRAY_ELEMENTSimages. -
fn combined_image_sampler(name: &'static str, image: impl Into<ghi::BaseImageHandle>, sampler: ghi::SamplerHandle, layout: ghi::Layouts) -> Self
Trait Implementations
impl ArchivePointee for Resource
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for Resource
impl Clone for Resource
-
fn clone(&self) -> ResourceRelated:
Resource
impl Copy for Resource
impl Downcast for Resource
-
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 Resource
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for Resource
impl LayoutRaw for Resource
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for Resource
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for Resource
-
type Metadata = ()
impl Read for Resource
impl WithSubscriber for Resource
Functions
create_sets
fn create_sets(frame: &mut ghi::implementation::Frame<'_>, name: &str, sets: &[SetLayout], resources: &[Resource]) -> Result<PipelineSets, String>Defined in crates/byte-engine/src/rendering/set_layout.rs:318-349
Creates the descriptor sets a published pipeline reads, one per layout its shaders use, and binds resources to
them by BESL name.
Use it for sets whose layout is only known once the pipeline is published, such as a shader's own descriptors.
sets are the pipeline's layouts and name labels the created sets. Every binding the pipeline reaches must take
exactly one resource of its kind; a binding it does not reach may be left out. Next, bind
PipelineSets::handles after the pipeline.
Constants
MAX_PIPELINE_SETS
const MAX_PIPELINE_SETS: usize = 4usize;Defined in crates/byte-engine/src/rendering/set_layout.rs:246
The most descriptor sets create_sets makes for one pipeline: the shader's own and the layout layers it lists.
MAX_IMAGE_ARRAY_ELEMENTS
const MAX_IMAGE_ARRAY_ELEMENTS: usize = 15usize;Defined in crates/byte-engine/src/rendering/set_layout.rs:352
The most elements Resource::image_array binds, which is the most debug targets a sink's pool holds.