Byte Engine Docs
View on docs.rs

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

ItemKindDescription
SetLayoutstructThe 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.
SetBinderstructThe SetBinder struct builds the descriptor writes of one set by BESL resource name.
PipelineSetsstructThe PipelineSets struct holds the descriptor sets [create_sets] made for one pipeline, to bind when the pipeline is recorded.
PublishedSetsstructThe 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.
ResourceenumThe Resource enum names one concrete resource for a BESL binding, for [create_sets] to bind by name.
create_setsfnCreates the descriptor sets a published pipeline reads, one per layout its shaders use, and binds resources to them by BESL name.
MAX_PIPELINE_SETSconstThe most descriptor sets [create_sets] makes for one pipeline: the shader's own and the layout layers it lists.
MAX_IMAGE_ARRAY_ELEMENTSconstThe 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) -> Self

    Builds the layout a baked shader declares.

  • fn from_layers(layers: &[(&str, &str)]) -> Self

    Builds the layout the last of layers declares. 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: SetLayout

    Returns each distinct layout of sets once, in first-seen order, with the bindings any of its copies uses

    marked as used.

    A pipeline's stages each declare the layouts they list; this is the pipeline's view of them.

  • fn layout(&self) -> &ghi::DescriptorSetLayout

    Returns the GHI layout, which descriptor sets are created from and shaders declare.

  • fn interface(&self) -> &SetInterface

    Returns the layout's bindings, with the names BESL gives them.

  • fn slot(&self, name: &str) -> ghi::ResourceSlot

    Returns 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::DescriptorSetHandle

    Creates an empty descriptor set for this layout. Next, write its resources through Self::binder.

  • fn binder(&self, set: ghi::DescriptorSetHandle) -> SetBinder<'_>

    Related: SetBinder

    Returns 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) -> SetLayout

    Related: 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::DescriptorSetHandle

    Returns the set the writes target.

  • fn slot(&self, name: &str) -> ghi::ResourceSlot

    Returns 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::DescriptorWrite

    Binds a buffer.

  • fn image(&self, name: &str, image: impl Into<ghi::BaseImageHandle>) -> ghi::DescriptorWrite

    Binds a storage image a shader loads or stores.

  • fn image_element(&self, name: &str, image: impl Into<ghi::BaseImageHandle>, index: u32) -> ghi::DescriptorWrite

    Binds 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::DescriptorWrite

    Binds a texture a shader samples through sampler.

  • fn sampled_with_frame(&self, name: &str, image: ghi::DynamicImageHandle, sampler: ghi::SamplerHandle, frame_offset: i32) -> ghi::DescriptorWrite

    Binds the copy of a per-frame texture that belongs to a relative frame, such as -1 for the previous frame.

  • fn sampled_element(&self, name: &str, image: impl Into<ghi::BaseImageHandle>, sampler: ghi::SamplerHandle, index: u32) -> ghi::DescriptorWrite

    Binds 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
impl Copy for PipelineSets
impl Default for 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, PipelineSets

    Returns the pipeline's sets, creating them with create_sets the first time the pipeline is available and

    after each rebuild. Returns None while the pipeline is unavailable, or when resources do not match its

    layouts, 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
impl Copy for PublishedSets
impl Default for 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

  • ImageArray

    The first count images 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>) -> Self

    Keeps a buffer ready for a BESL binding that is intentionally not reachable yet.

  • fn image(name: &'static str, image: impl Into<ghi::ImageOrSwapchain>) -> Self

    Binds a storage-image destination without exposing whether it is an image or swapchain.

  • fn image_array(name: &'static str, images: &[ghi::BaseImageHandle]) -> Self

    Binds images to the first elements of an arrayed storage-image binding, such as the debug target pool a

    shader 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_ELEMENTS images.

  • 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) -> Resource

    Related: 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.

On this page

Module set_layoutContentsQuick ReferenceStructsSetLayoutImplementationsPanicsPanicsTrait Implementationsimpl ArchivePointee for SetLayoutimpl<ST> CastableFrom for SetLayoutimpl Clone for SetLayoutimpl Downcast for SetLayoutimpl DowncastSync for SetLayoutimpl Instrument for SetLayoutimpl LayoutRaw for SetLayoutimpl<T, N1> Niching for SetLayoutimpl Pointee for SetLayoutimpl Read for SetLayoutimpl WithSubscriber for SetLayoutSetBinder<'a>ImplementationsTrait Implementationsimpl ArchivePointee for SetBinder<'a>impl<ST> CastableFrom for SetBinder<'a>impl Clone for SetBinder<'a>impl Copy for SetBinder<'a>impl Downcast for SetBinder<'a>impl DowncastSync for SetBinder<'a>impl Instrument for SetBinder<'a>impl LayoutRaw for SetBinder<'a>impl<T, N1> Niching for SetBinder<'a>impl Pointee for SetBinder<'a>impl Read for SetBinder<'a>impl WithSubscriber for SetBinder<'a>PipelineSetsImplementationsTrait Implementationsimpl ArchivePointee for PipelineSetsimpl<ST> CastableFrom for PipelineSetsimpl Clone for PipelineSetsimpl Copy for PipelineSetsimpl Default for PipelineSetsimpl Downcast for PipelineSetsimpl DowncastSync for PipelineSetsimpl Instrument for PipelineSetsimpl LayoutRaw for PipelineSetsimpl<T, N1> Niching for PipelineSetsimpl Pointee for PipelineSetsimpl Read for PipelineSetsimpl<R> ReadPrimitive for PipelineSetsimpl WithSubscriber for PipelineSetsPublishedSetsImplementationsTrait Implementationsimpl ArchivePointee for PublishedSetsimpl<ST> CastableFrom for PublishedSetsimpl Clone for PublishedSetsimpl Copy for PublishedSetsimpl Default for PublishedSetsimpl Downcast for PublishedSetsimpl DowncastSync for PublishedSetsimpl Instrument for PublishedSetsimpl LayoutRaw for PublishedSetsimpl<T, N1> Niching for PublishedSetsimpl Pointee for PublishedSetsimpl Read for PublishedSetsimpl<R> ReadPrimitive for PublishedSetsimpl WithSubscriber for PublishedSetsEnumsResourceVariantsImplementationsPanicsTrait Implementationsimpl ArchivePointee for Resourceimpl<ST> CastableFrom for Resourceimpl Clone for Resourceimpl Copy for Resourceimpl Downcast for Resourceimpl DowncastSync for Resourceimpl Instrument for Resourceimpl LayoutRaw for Resourceimpl<T, N1> Niching for Resourceimpl Pointee for Resourceimpl Read for Resourceimpl WithSubscriber for ResourceFunctionscreate_setsConstantsMAX_PIPELINE_SETSMAX_IMAGE_ARRAY_ELEMENTS