270 lines
39 KiB
HTML
270 lines
39 KiB
HTML
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Converts a value to a `BindGroup` with a given `BindGroupLayout`, which can then be used in Bevy shaders. This trait can be derived (and generally should be). Read on for details and examples."><title>AsBindGroup in bevy_render::render_resource - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../../static.files/rustdoc-42caa33d.css"><meta name="rustdoc-vars" data-root-path="../../" data-static-root-path="../../static.files/" data-current-crate="bevy_render" data-themes="" data-resource-suffix="" data-rustdoc-version="1.84.0 (9fc6b4312 2025-01-07)" data-channel="1.84.0" data-search-js="search-92e6798f.js" data-settings-js="settings-0f613d39.js" ><script src="../../static.files/storage-59e33391.js"></script><script defer src="sidebar-items.js"></script><script defer src="../../static.files/main-5f194d8c.js"></script><noscript><link rel="stylesheet" href="../../static.files/noscript-893ab5e7.css"></noscript><link rel="icon" href="https://bevyengine.org/assets/icon.png"></head><body class="rustdoc trait"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button><a class="logo-container" href="../../bevy_render/index.html"><img src="https://bevyengine.org/assets/icon.png" alt=""></a></nav><nav class="sidebar"><div class="sidebar-crate"><a class="logo-container" href="../../bevy_render/index.html"><img src="https://bevyengine.org/assets/icon.png" alt="logo"></a><h2><a href="../../bevy_render/index.html">bevy_<wbr>render</a><span class="version">0.15.1</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">AsBind<wbr>Group</a></h2><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#deriving" title="Deriving">Deriving</a></li></ul><h3><a href="#required-associated-types">Required Associated Types</a></h3><ul class="block"><li><a href="#associatedtype.Data" title="Data">Data</a></li><li><a href="#associatedtype.Param" title="Param">Param</a></li></ul><h3><a href="#required-methods">Required Methods</a></h3><ul class="block"><li><a href="#tymethod.bind_group_layout_entries" title="bind_group_layout_entries">bind_group_layout_entries</a></li><li><a href="#tymethod.unprepared_bind_group" title="unprepared_bind_group">unprepared_bind_group</a></li></ul><h3><a href="#provided-methods">Provided Methods</a></h3><ul class="block"><li><a href="#method.as_bind_group" title="as_bind_group">as_bind_group</a></li><li><a href="#method.bind_group_layout" title="bind_group_layout">bind_group_layout</a></li><li><a href="#method.label" title="label">label</a></li></ul><h3><a href="#dyn-compatibility">Dyn Compatibility</a></h3><h3><a href="#implementors">Implementors</a></h3></section><div id="rustdoc-modnav"><h2><a href="index.html">In bevy_<wbr>render::<wbr>render_<wbr>resource</a></h2></div></div></nav><div class="sidebar-resizer"></div><main><div class="width-limiter"><rustdoc-search></rustdoc-search><section id="main-content" class="content"><div class="main-heading"><span class="rustdoc-breadcrumbs"><a href="../index.html">bevy_render</a>::<wbr><a href="index.html">render_resource</a></span><h1>Trait <span class="trait">AsBindGroup</span><button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../../src/bevy_render/render_resource/bind_group.rs.html#304-368">Source</a> </span></div><pre class="rust item-decl"><code>pub trait AsBindGroup {
|
||
type <a href="#associatedtype.Data" class="associatedtype">Data</a>: <a class="trait" href="https://doc.rust-lang.org/1.84.0/core/marker/trait.Send.html" title="trait core::marker::Send">Send</a> + <a class="trait" href="https://doc.rust-lang.org/1.84.0/core/marker/trait.Sync.html" title="trait core::marker::Sync">Sync</a>;
|
||
type <a href="#associatedtype.Param" class="associatedtype">Param</a>: <a class="trait" href="../../bevy_ecs/system/system_param/trait.SystemParam.html" title="trait bevy_ecs::system::system_param::SystemParam">SystemParam</a> + 'static;
|
||
|
||
// Required methods
|
||
fn <a href="#tymethod.unprepared_bind_group" class="fn">unprepared_bind_group</a>(
|
||
&self,
|
||
layout: &<a class="struct" href="struct.BindGroupLayout.html" title="struct bevy_render::render_resource::BindGroupLayout">BindGroupLayout</a>,
|
||
render_device: &<a class="struct" href="../renderer/struct.RenderDevice.html" title="struct bevy_render::renderer::RenderDevice">RenderDevice</a>,
|
||
param: &mut <a class="type" href="../../bevy_ecs/system/system_param/type.SystemParamItem.html" title="type bevy_ecs::system::system_param::SystemParamItem">SystemParamItem</a><'_, '_, Self::<a class="associatedtype" href="trait.AsBindGroup.html#associatedtype.Param" title="type bevy_render::render_resource::AsBindGroup::Param">Param</a>>,
|
||
) -> <a class="enum" href="https://doc.rust-lang.org/1.84.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a><<a class="struct" href="struct.UnpreparedBindGroup.html" title="struct bevy_render::render_resource::UnpreparedBindGroup">UnpreparedBindGroup</a><Self::<a class="associatedtype" href="trait.AsBindGroup.html#associatedtype.Data" title="type bevy_render::render_resource::AsBindGroup::Data">Data</a>>, <a class="enum" href="enum.AsBindGroupError.html" title="enum bevy_render::render_resource::AsBindGroupError">AsBindGroupError</a>>;
|
||
<span class="item-spacer"></span> fn <a href="#tymethod.bind_group_layout_entries" class="fn">bind_group_layout_entries</a>(
|
||
render_device: &<a class="struct" href="../renderer/struct.RenderDevice.html" title="struct bevy_render::renderer::RenderDevice">RenderDevice</a>,
|
||
) -> <a class="struct" href="https://doc.rust-lang.org/1.84.0/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a><<a class="struct" href="struct.BindGroupLayoutEntry.html" title="struct bevy_render::render_resource::BindGroupLayoutEntry">BindGroupLayoutEntry</a>>
|
||
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.84.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span>;
|
||
|
||
// Provided methods
|
||
fn <a href="#method.label" class="fn">label</a>() -> <a class="enum" href="https://doc.rust-lang.org/1.84.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a><&'static <a class="primitive" href="https://doc.rust-lang.org/1.84.0/std/primitive.str.html">str</a>> { ... }
|
||
<span class="item-spacer"></span> fn <a href="#method.as_bind_group" class="fn">as_bind_group</a>(
|
||
&self,
|
||
layout: &<a class="struct" href="struct.BindGroupLayout.html" title="struct bevy_render::render_resource::BindGroupLayout">BindGroupLayout</a>,
|
||
render_device: &<a class="struct" href="../renderer/struct.RenderDevice.html" title="struct bevy_render::renderer::RenderDevice">RenderDevice</a>,
|
||
param: &mut <a class="type" href="../../bevy_ecs/system/system_param/type.SystemParamItem.html" title="type bevy_ecs::system::system_param::SystemParamItem">SystemParamItem</a><'_, '_, Self::<a class="associatedtype" href="trait.AsBindGroup.html#associatedtype.Param" title="type bevy_render::render_resource::AsBindGroup::Param">Param</a>>,
|
||
) -> <a class="enum" href="https://doc.rust-lang.org/1.84.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a><<a class="struct" href="struct.PreparedBindGroup.html" title="struct bevy_render::render_resource::PreparedBindGroup">PreparedBindGroup</a><Self::<a class="associatedtype" href="trait.AsBindGroup.html#associatedtype.Data" title="type bevy_render::render_resource::AsBindGroup::Data">Data</a>>, <a class="enum" href="enum.AsBindGroupError.html" title="enum bevy_render::render_resource::AsBindGroupError">AsBindGroupError</a>> { ... }
|
||
<span class="item-spacer"></span> fn <a href="#method.bind_group_layout" class="fn">bind_group_layout</a>(render_device: &<a class="struct" href="../renderer/struct.RenderDevice.html" title="struct bevy_render::renderer::RenderDevice">RenderDevice</a>) -> <a class="struct" href="struct.BindGroupLayout.html" title="struct bevy_render::render_resource::BindGroupLayout">BindGroupLayout</a>
|
||
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.84.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
|
||
}</code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Converts a value to a <a href="struct.BindGroup.html" title="struct bevy_render::render_resource::BindGroup"><code>BindGroup</code></a> with a given <a href="struct.BindGroupLayout.html" title="struct bevy_render::render_resource::BindGroupLayout"><code>BindGroupLayout</code></a>, which can then be used in Bevy shaders.
|
||
This trait can be derived (and generally should be). Read on for details and examples.</p>
|
||
<p>This is an opinionated trait that is intended to make it easy to generically
|
||
convert a type into a <a href="struct.BindGroup.html" title="struct bevy_render::render_resource::BindGroup"><code>BindGroup</code></a>. It provides access to specific render resources,
|
||
such as <a href="../render_asset/struct.RenderAssets.html" title="struct bevy_render::render_asset::RenderAssets"><code>RenderAssets<GpuImage></code></a> and <a href="../texture/struct.FallbackImage.html" title="struct bevy_render::texture::FallbackImage"><code>crate::texture::FallbackImage</code></a>. If a type has a <a href="../../bevy_asset/handle/enum.Handle.html" title="enum bevy_asset::handle::Handle"><code>Handle<Image></code></a>,
|
||
these can be used to retrieve the corresponding <a href="struct.Texture.html" title="struct bevy_render::render_resource::Texture"><code>Texture</code></a> resource.</p>
|
||
<p><a href="trait.AsBindGroup.html#method.as_bind_group" title="method bevy_render::render_resource::AsBindGroup::as_bind_group"><code>AsBindGroup::as_bind_group</code></a> is intended to be called once, then the result cached somewhere. It is generally
|
||
ok to do “expensive” work here, such as creating a <a href="struct.Buffer.html" title="struct bevy_render::render_resource::Buffer"><code>Buffer</code></a> for a uniform.</p>
|
||
<p>If for some reason a <a href="struct.BindGroup.html" title="struct bevy_render::render_resource::BindGroup"><code>BindGroup</code></a> cannot be created yet (for example, the <a href="struct.Texture.html" title="struct bevy_render::render_resource::Texture"><code>Texture</code></a>
|
||
for an <a href="../../bevy_image/image/struct.Image.html" title="struct bevy_image::image::Image"><code>Image</code></a> hasn’t loaded yet), just return <a href="enum.AsBindGroupError.html#variant.RetryNextUpdate" title="variant bevy_render::render_resource::AsBindGroupError::RetryNextUpdate"><code>AsBindGroupError::RetryNextUpdate</code></a>, which signals that the caller
|
||
should retry again later.</p>
|
||
<h2 id="deriving"><a class="doc-anchor" href="#deriving">§</a>Deriving</h2>
|
||
<p>This trait can be derived. Field attributes like <code>uniform</code> and <code>texture</code> are used to define which fields should be bindings,
|
||
what their binding type is, and what index they should be bound at:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code>
|
||
<span class="attr">#[derive(AsBindGroup)]
|
||
</span><span class="kw">struct </span>CoolMaterial {
|
||
<span class="attr">#[uniform(<span class="number">0</span>)]
|
||
</span>color: LinearRgba,
|
||
<span class="attr">#[texture(<span class="number">1</span>)]
|
||
#[sampler(<span class="number">2</span>)]
|
||
</span>color_texture: Handle<Image>,
|
||
<span class="attr">#[storage(<span class="number">3</span>, read_only)]
|
||
</span>storage_buffer: Handle<ShaderStorageBuffer>,
|
||
<span class="attr">#[storage(<span class="number">4</span>, read_only, buffer)]
|
||
</span>raw_buffer: Buffer,
|
||
<span class="attr">#[storage_texture(<span class="number">5</span>)]
|
||
</span>storage_texture: Handle<Image>,
|
||
}</code></pre></div>
|
||
<p>In WGSL shaders, the binding would look like this:</p>
|
||
<div class="example-wrap"><pre class="language-wgsl"><code>@group(2) @binding(0) var<uniform> color: vec4<f32>;
|
||
@group(2) @binding(1) var color_texture: texture_2d<f32>;
|
||
@group(2) @binding(2) var color_sampler: sampler;
|
||
@group(2) @binding(3) var<storage> storage_buffer: array<f32>;
|
||
@group(2) @binding(4) var<storage> raw_buffer: array<f32>;
|
||
@group(2) @binding(5) var storage_texture: texture_storage_2d<rgba8unorm, read_write>;</code></pre></div>
|
||
<p>Note that the “group” index is determined by the usage context. It is not defined in <a href="trait.AsBindGroup.html" title="trait bevy_render::render_resource::AsBindGroup"><code>AsBindGroup</code></a>. For example, in Bevy material bind groups
|
||
are generally bound to group 2.</p>
|
||
<p>The following field-level attributes are supported:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>uniform(BINDING_INDEX)</code></p>
|
||
<ul>
|
||
<li>The field will be converted to a shader-compatible type using the <a href="trait.ShaderType.html" title="trait bevy_render::render_resource::ShaderType"><code>ShaderType</code></a> trait, written to a <a href="struct.Buffer.html" title="struct bevy_render::render_resource::Buffer"><code>Buffer</code></a>, and bound as a uniform.
|
||
<a href="trait.ShaderType.html" title="trait bevy_render::render_resource::ShaderType"><code>ShaderType</code></a> is implemented for most math types already, such as <a href="https://doc.rust-lang.org/1.84.0/std/primitive.f32.html" title="primitive f32"><code>f32</code></a>, <a href="../../glam/f32/sse2/vec4/struct.Vec4.html" title="struct glam::f32::sse2::vec4::Vec4"><code>Vec4</code></a>, and
|
||
<a href="../../bevy_color/linear_rgba/struct.LinearRgba.html" title="struct bevy_color::linear_rgba::LinearRgba"><code>LinearRgba</code></a>. It can also be derived for custom structs.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p><code>texture(BINDING_INDEX, arguments)</code></p>
|
||
<ul>
|
||
<li>This field’s <a href="../../bevy_asset/handle/enum.Handle.html" title="enum bevy_asset::handle::Handle"><code>Handle<Image></code></a> will be used to look up the matching <a href="struct.Texture.html" title="struct bevy_render::render_resource::Texture"><code>Texture</code></a>
|
||
GPU resource, which will be bound as a texture in shaders. The field will be assumed to implement <a href="https://doc.rust-lang.org/1.84.0/core/convert/trait.Into.html" title="trait core::convert::Into"><code>Into<Option<Handle<Image>>></code></a>. In practice,
|
||
most fields should be a <a href="../../bevy_asset/handle/enum.Handle.html" title="enum bevy_asset::handle::Handle"><code>Handle<Image></code></a> or <a href="https://doc.rust-lang.org/1.84.0/core/option/enum.Option.html" title="enum core::option::Option"><code>Option<Handle<Image>></code></a>. If the value of an <a href="https://doc.rust-lang.org/1.84.0/core/option/enum.Option.html" title="enum core::option::Option"><code>Option<Handle<Image>></code></a> is
|
||
<a href="https://doc.rust-lang.org/1.84.0/core/option/enum.Option.html#variant.None" title="variant core::option::Option::None"><code>None</code></a>, the <a href="../texture/struct.FallbackImage.html" title="struct bevy_render::texture::FallbackImage"><code>crate::texture::FallbackImage</code></a> resource will be used instead. This attribute can be used in conjunction with a <code>sampler</code> binding attribute
|
||
(with a different binding index) if a binding of the sampler for the <a href="../../bevy_image/image/struct.Image.html" title="struct bevy_image::image::Image"><code>Image</code></a> is also required.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<div><table><thead><tr><th>Arguments</th><th>Values</th><th>Default</th></tr></thead><tbody>
|
||
<tr><td><code>dimension</code> = “…”</td><td><code>"1d"</code>, <code>"2d"</code>, <code>"2d_array"</code>, <code>"3d"</code>, <code>"cube"</code>, <code>"cube_array"</code></td><td><code>"2d"</code></td></tr>
|
||
<tr><td><code>sample_type</code> = “…”</td><td><code>"float"</code>, <code>"depth"</code>, <code>"s_int"</code> or <code>"u_int"</code></td><td><code>"float"</code></td></tr>
|
||
<tr><td><code>filterable</code> = …</td><td><code>true</code>, <code>false</code></td><td><code>true</code></td></tr>
|
||
<tr><td><code>multisampled</code> = …</td><td><code>true</code>, <code>false</code></td><td><code>false</code></td></tr>
|
||
<tr><td><code>visibility(...)</code></td><td><code>all</code>, <code>none</code>, or a list-combination of <code>vertex</code>, <code>fragment</code>, <code>compute</code></td><td><code>vertex</code>, <code>fragment</code></td></tr>
|
||
</tbody></table>
|
||
</div>
|
||
<ul>
|
||
<li><code>storage_texture(BINDING_INDEX, arguments)</code>
|
||
<ul>
|
||
<li>This field’s <a href="../../bevy_asset/handle/enum.Handle.html" title="enum bevy_asset::handle::Handle"><code>Handle<Image></code></a> will be used to look up the matching <a href="struct.Texture.html" title="struct bevy_render::render_resource::Texture"><code>Texture</code></a>
|
||
GPU resource, which will be bound as a storage texture in shaders. The field will be assumed to implement <a href="https://doc.rust-lang.org/1.84.0/core/convert/trait.Into.html" title="trait core::convert::Into"><code>Into<Option<Handle<Image>>></code></a>. In practice,
|
||
most fields should be a <a href="../../bevy_asset/handle/enum.Handle.html" title="enum bevy_asset::handle::Handle"><code>Handle<Image></code></a> or <a href="https://doc.rust-lang.org/1.84.0/core/option/enum.Option.html" title="enum core::option::Option"><code>Option<Handle<Image>></code></a>. If the value of an <a href="https://doc.rust-lang.org/1.84.0/core/option/enum.Option.html" title="enum core::option::Option"><code>Option<Handle<Image>></code></a> is
|
||
<a href="https://doc.rust-lang.org/1.84.0/core/option/enum.Option.html#variant.None" title="variant core::option::Option::None"><code>None</code></a>, the <a href="../texture/struct.FallbackImage.html" title="struct bevy_render::texture::FallbackImage"><code>crate::texture::FallbackImage</code></a> resource will be used instead.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<div><table><thead><tr><th>Arguments</th><th>Values</th><th>Default</th></tr></thead><tbody>
|
||
<tr><td><code>dimension</code> = “…”</td><td><code>"1d"</code>, <code>"2d"</code>, <code>"2d_array"</code>, <code>"3d"</code>, <code>"cube"</code>, <code>"cube_array"</code></td><td><code>"2d"</code></td></tr>
|
||
<tr><td><code>image_format</code> = …</td><td>any member of <a href="enum.TextureFormat.html" title="enum bevy_render::render_resource::TextureFormat"><code>TextureFormat</code></a></td><td><code>Rgba8Unorm</code></td></tr>
|
||
<tr><td><code>access</code> = …</td><td>any member of <a href="enum.StorageTextureAccess.html" title="enum bevy_render::render_resource::StorageTextureAccess"><code>StorageTextureAccess</code></a></td><td><code>ReadWrite</code></td></tr>
|
||
<tr><td><code>visibility(...)</code></td><td><code>all</code>, <code>none</code>, or a list-combination of <code>vertex</code>, <code>fragment</code>, <code>compute</code></td><td><code>compute</code></td></tr>
|
||
</tbody></table>
|
||
</div>
|
||
<ul>
|
||
<li><code>sampler(BINDING_INDEX, arguments)</code>
|
||
<ul>
|
||
<li>This field’s <a href="../../bevy_asset/handle/enum.Handle.html" title="enum bevy_asset::handle::Handle"><code>Handle<Image></code></a> will be used to look up the matching <a href="struct.Sampler.html" title="struct bevy_render::render_resource::Sampler"><code>Sampler</code></a> GPU
|
||
resource, which will be bound as a sampler in shaders. The field will be assumed to implement <a href="https://doc.rust-lang.org/1.84.0/core/convert/trait.Into.html" title="trait core::convert::Into"><code>Into<Option<Handle<Image>>></code></a>. In practice,
|
||
most fields should be a <a href="../../bevy_asset/handle/enum.Handle.html" title="enum bevy_asset::handle::Handle"><code>Handle<Image></code></a> or <a href="https://doc.rust-lang.org/1.84.0/core/option/enum.Option.html" title="enum core::option::Option"><code>Option<Handle<Image>></code></a>. If the value of an <a href="https://doc.rust-lang.org/1.84.0/core/option/enum.Option.html" title="enum core::option::Option"><code>Option<Handle<Image>></code></a> is
|
||
<a href="https://doc.rust-lang.org/1.84.0/core/option/enum.Option.html#variant.None" title="variant core::option::Option::None"><code>None</code></a>, the <a href="../texture/struct.FallbackImage.html" title="struct bevy_render::texture::FallbackImage"><code>crate::texture::FallbackImage</code></a> resource will be used instead. This attribute can be used in conjunction with a <code>texture</code> binding attribute
|
||
(with a different binding index) if a binding of the texture for the <a href="../../bevy_image/image/struct.Image.html" title="struct bevy_image::image::Image"><code>Image</code></a> is also required.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<div><table><thead><tr><th>Arguments</th><th>Values</th><th>Default</th></tr></thead><tbody>
|
||
<tr><td><code>sampler_type</code> = “…”</td><td><code>"filtering"</code>, <code>"non_filtering"</code>, <code>"comparison"</code>.</td><td><code>"filtering"</code></td></tr>
|
||
<tr><td><code>visibility(...)</code></td><td><code>all</code>, <code>none</code>, or a list-combination of <code>vertex</code>, <code>fragment</code>, <code>compute</code></td><td><code>vertex</code>, <code>fragment</code></td></tr>
|
||
</tbody></table>
|
||
</div>
|
||
<ul>
|
||
<li><code>storage(BINDING_INDEX, arguments)</code>
|
||
<ul>
|
||
<li>The field’s <a href="../../bevy_asset/handle/enum.Handle.html" title="enum bevy_asset::handle::Handle"><code>Handle<Storage></code></a> will be used to look up the matching <a href="struct.Buffer.html" title="struct bevy_render::render_resource::Buffer"><code>Buffer</code></a> GPU resource, which
|
||
will be bound as a storage buffer in shaders. If the <code>storage</code> attribute is used, the field is expected a raw
|
||
buffer, and the buffer will be bound as a storage buffer in shaders.</li>
|
||
<li>It supports and optional <code>read_only</code> parameter. Defaults to false if not present.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<div><table><thead><tr><th>Arguments</th><th>Values</th><th>Default</th></tr></thead><tbody>
|
||
<tr><td><code>visibility(...)</code></td><td><code>all</code>, <code>none</code>, or a list-combination of <code>vertex</code>, <code>fragment</code>, <code>compute</code></td><td><code>vertex</code>, <code>fragment</code></td></tr>
|
||
<tr><td><code>read_only</code></td><td>if present then value is true, otherwise false</td><td><code>false</code></td></tr>
|
||
<tr><td><code>buffer</code></td><td>if present then the field will be assumed to be a raw wgpu buffer</td><td></td></tr>
|
||
</tbody></table>
|
||
</div>
|
||
<p>Note that fields without field-level binding attributes will be ignored.</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="attr">#[derive(AsBindGroup)]
|
||
</span><span class="kw">struct </span>CoolMaterial {
|
||
<span class="attr">#[uniform(<span class="number">0</span>)]
|
||
</span>color: LinearRgba,
|
||
this_field_is_ignored: String,
|
||
}</code></pre></div>
|
||
<p>As mentioned above, <a href="https://doc.rust-lang.org/1.84.0/core/option/enum.Option.html" title="enum core::option::Option"><code>Option<Handle<Image>></code></a> is also supported:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="attr">#[derive(AsBindGroup)]
|
||
</span><span class="kw">struct </span>CoolMaterial {
|
||
<span class="attr">#[uniform(<span class="number">0</span>)]
|
||
</span>color: LinearRgba,
|
||
<span class="attr">#[texture(<span class="number">1</span>)]
|
||
#[sampler(<span class="number">2</span>)]
|
||
</span>color_texture: <span class="prelude-ty">Option</span><Handle<Image>>,
|
||
}</code></pre></div>
|
||
<p>This is useful if you want a texture to be optional. When the value is <a href="https://doc.rust-lang.org/1.84.0/core/option/enum.Option.html#variant.None" title="variant core::option::Option::None"><code>None</code></a>, the <a href="../texture/struct.FallbackImage.html" title="struct bevy_render::texture::FallbackImage"><code>crate::texture::FallbackImage</code></a> will be used for the binding instead, which defaults
|
||
to “pure white”.</p>
|
||
<p>Field uniforms with the same index will be combined into a single binding:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="attr">#[derive(AsBindGroup)]
|
||
</span><span class="kw">struct </span>CoolMaterial {
|
||
<span class="attr">#[uniform(<span class="number">0</span>)]
|
||
</span>color: LinearRgba,
|
||
<span class="attr">#[uniform(<span class="number">0</span>)]
|
||
</span>roughness: f32,
|
||
}</code></pre></div>
|
||
<p>In WGSL shaders, the binding would look like this:</p>
|
||
<div class="example-wrap"><pre class="language-wgsl"><code>struct CoolMaterial {
|
||
color: vec4<f32>,
|
||
roughness: f32,
|
||
};
|
||
|
||
@group(2) @binding(0) var<uniform> material: CoolMaterial;</code></pre></div>
|
||
<p>Some less common scenarios will require “struct-level” attributes. These are the currently supported struct-level attributes:</p>
|
||
<ul>
|
||
<li><code>uniform(BINDING_INDEX, ConvertedShaderType)</code>
|
||
<ul>
|
||
<li>This also creates a <a href="struct.Buffer.html" title="struct bevy_render::render_resource::Buffer"><code>Buffer</code></a> using <a href="trait.ShaderType.html" title="trait bevy_render::render_resource::ShaderType"><code>ShaderType</code></a> and binds it as a uniform, much
|
||
like the field-level <code>uniform</code> attribute. The difference is that the entire <a href="trait.AsBindGroup.html" title="trait bevy_render::render_resource::AsBindGroup"><code>AsBindGroup</code></a> value is converted to <code>ConvertedShaderType</code>,
|
||
which must implement <a href="trait.ShaderType.html" title="trait bevy_render::render_resource::ShaderType"><code>ShaderType</code></a>, instead of a specific field implementing <a href="trait.ShaderType.html" title="trait bevy_render::render_resource::ShaderType"><code>ShaderType</code></a>. This is useful if more complicated conversion
|
||
logic is required. The conversion is done using the <a href="trait.AsBindGroupShaderType.html" title="trait bevy_render::render_resource::AsBindGroupShaderType"><code>AsBindGroupShaderType<ConvertedShaderType></code></a> trait, which is automatically implemented
|
||
if <code>&Self</code> implements <a href="https://doc.rust-lang.org/1.84.0/core/convert/trait.Into.html" title="trait core::convert::Into"><code>Into<ConvertedShaderType></code></a>. Only use <a href="trait.AsBindGroupShaderType.html" title="trait bevy_render::render_resource::AsBindGroupShaderType"><code>AsBindGroupShaderType</code></a> if access to resources like <a href="../render_asset/struct.RenderAssets.html" title="struct bevy_render::render_asset::RenderAssets"><code>RenderAssets<GpuImage></code></a> is
|
||
required.</li>
|
||
</ul>
|
||
</li>
|
||
<li><code>bind_group_data(DataType)</code>
|
||
<ul>
|
||
<li>The <a href="trait.AsBindGroup.html" title="trait bevy_render::render_resource::AsBindGroup"><code>AsBindGroup</code></a> type will be converted to some <code>DataType</code> using <a href="https://doc.rust-lang.org/1.84.0/core/convert/trait.Into.html" title="trait core::convert::Into"><code>Into<DataType></code></a> and stored
|
||
as <a href="trait.AsBindGroup.html#associatedtype.Data" title="associated type bevy_render::render_resource::AsBindGroup::Data"><code>AsBindGroup::Data</code></a> as part of the <a href="trait.AsBindGroup.html#method.as_bind_group" title="method bevy_render::render_resource::AsBindGroup::as_bind_group"><code>AsBindGroup::as_bind_group</code></a> call. This is useful if data needs to be stored alongside
|
||
the generated bind group, such as a unique identifier for a material’s bind group. The most common use case for this attribute
|
||
is “shader pipeline specialization”. See <a href="trait.SpecializedRenderPipeline.html" title="trait bevy_render::render_resource::SpecializedRenderPipeline"><code>SpecializedRenderPipeline</code></a>.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>The previous <code>CoolMaterial</code> example illustrating “combining multiple field-level uniform attributes with the same binding index” can
|
||
also be equivalently represented with a single struct-level uniform attribute:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="attr">#[derive(AsBindGroup)]
|
||
#[uniform(<span class="number">0</span>, CoolMaterialUniform)]
|
||
</span><span class="kw">struct </span>CoolMaterial {
|
||
color: LinearRgba,
|
||
roughness: f32,
|
||
}
|
||
|
||
<span class="attr">#[derive(ShaderType)]
|
||
</span><span class="kw">struct </span>CoolMaterialUniform {
|
||
color: LinearRgba,
|
||
roughness: f32,
|
||
}
|
||
|
||
<span class="kw">impl </span>From<<span class="kw-2">&</span>CoolMaterial> <span class="kw">for </span>CoolMaterialUniform {
|
||
<span class="kw">fn </span>from(material: <span class="kw-2">&</span>CoolMaterial) -> CoolMaterialUniform {
|
||
CoolMaterialUniform {
|
||
color: material.color,
|
||
roughness: material.roughness,
|
||
}
|
||
}
|
||
}</code></pre></div>
|
||
<p>Setting <code>bind_group_data</code> looks like this:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="attr">#[derive(AsBindGroup)]
|
||
#[bind_group_data(CoolMaterialKey)]
|
||
</span><span class="kw">struct </span>CoolMaterial {
|
||
<span class="attr">#[uniform(<span class="number">0</span>)]
|
||
</span>color: LinearRgba,
|
||
is_shaded: bool,
|
||
}
|
||
|
||
<span class="attr">#[derive(Copy, Clone, Hash, Eq, PartialEq)]
|
||
</span><span class="kw">struct </span>CoolMaterialKey {
|
||
is_shaded: bool,
|
||
}
|
||
|
||
<span class="kw">impl </span>From<<span class="kw-2">&</span>CoolMaterial> <span class="kw">for </span>CoolMaterialKey {
|
||
<span class="kw">fn </span>from(material: <span class="kw-2">&</span>CoolMaterial) -> CoolMaterialKey {
|
||
CoolMaterialKey {
|
||
is_shaded: material.is_shaded,
|
||
}
|
||
}
|
||
}</code></pre></div>
|
||
</div></details><h2 id="required-associated-types" class="section-header">Required Associated Types<a href="#required-associated-types" class="anchor">§</a></h2><div class="methods"><details class="toggle" open><summary><section id="associatedtype.Data" class="method"><a class="src rightside" href="../../src/bevy_render/render_resource/bind_group.rs.html#306">Source</a><h4 class="code-header">type <a href="#associatedtype.Data" class="associatedtype">Data</a>: <a class="trait" href="https://doc.rust-lang.org/1.84.0/core/marker/trait.Send.html" title="trait core::marker::Send">Send</a> + <a class="trait" href="https://doc.rust-lang.org/1.84.0/core/marker/trait.Sync.html" title="trait core::marker::Sync">Sync</a></h4></section></summary><div class="docblock"><p>Data that will be stored alongside the “prepared” bind group.</p>
|
||
</div></details><section id="associatedtype.Param" class="method"><a class="src rightside" href="../../src/bevy_render/render_resource/bind_group.rs.html#308">Source</a><h4 class="code-header">type <a href="#associatedtype.Param" class="associatedtype">Param</a>: <a class="trait" href="../../bevy_ecs/system/system_param/trait.SystemParam.html" title="trait bevy_ecs::system::system_param::SystemParam">SystemParam</a> + 'static</h4></section></div><h2 id="required-methods" class="section-header">Required Methods<a href="#required-methods" class="anchor">§</a></h2><div class="methods"><details class="toggle method-toggle" open><summary><section id="tymethod.unprepared_bind_group" class="method"><a class="src rightside" href="../../src/bevy_render/render_resource/bind_group.rs.html#346-351">Source</a><h4 class="code-header">fn <a href="#tymethod.unprepared_bind_group" class="fn">unprepared_bind_group</a>(
|
||
&self,
|
||
layout: &<a class="struct" href="struct.BindGroupLayout.html" title="struct bevy_render::render_resource::BindGroupLayout">BindGroupLayout</a>,
|
||
render_device: &<a class="struct" href="../renderer/struct.RenderDevice.html" title="struct bevy_render::renderer::RenderDevice">RenderDevice</a>,
|
||
param: &mut <a class="type" href="../../bevy_ecs/system/system_param/type.SystemParamItem.html" title="type bevy_ecs::system::system_param::SystemParamItem">SystemParamItem</a><'_, '_, Self::<a class="associatedtype" href="trait.AsBindGroup.html#associatedtype.Param" title="type bevy_render::render_resource::AsBindGroup::Param">Param</a>>,
|
||
) -> <a class="enum" href="https://doc.rust-lang.org/1.84.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a><<a class="struct" href="struct.UnpreparedBindGroup.html" title="struct bevy_render::render_resource::UnpreparedBindGroup">UnpreparedBindGroup</a><Self::<a class="associatedtype" href="trait.AsBindGroup.html#associatedtype.Data" title="type bevy_render::render_resource::AsBindGroup::Data">Data</a>>, <a class="enum" href="enum.AsBindGroupError.html" title="enum bevy_render::render_resource::AsBindGroupError">AsBindGroupError</a>></h4></section></summary><div class="docblock"><p>Returns a vec of (binding index, <code>OwnedBindingResource</code>).
|
||
In cases where <code>OwnedBindingResource</code> is not available (as for bindless texture arrays currently),
|
||
an implementor may define <code>as_bind_group</code> directly. This may prevent certain features
|
||
from working correctly.</p>
|
||
</div></details><details class="toggle method-toggle" open><summary><section id="tymethod.bind_group_layout_entries" class="method"><a class="src rightside" href="../../src/bevy_render/render_resource/bind_group.rs.html#365-367">Source</a><h4 class="code-header">fn <a href="#tymethod.bind_group_layout_entries" class="fn">bind_group_layout_entries</a>(
|
||
render_device: &<a class="struct" href="../renderer/struct.RenderDevice.html" title="struct bevy_render::renderer::RenderDevice">RenderDevice</a>,
|
||
) -> <a class="struct" href="https://doc.rust-lang.org/1.84.0/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a><<a class="struct" href="struct.BindGroupLayoutEntry.html" title="struct bevy_render::render_resource::BindGroupLayoutEntry">BindGroupLayoutEntry</a>><div class="where">where
|
||
Self: <a class="trait" href="https://doc.rust-lang.org/1.84.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Returns a vec of bind group layout entries</p>
|
||
</div></details></div><h2 id="provided-methods" class="section-header">Provided Methods<a href="#provided-methods" class="anchor">§</a></h2><div class="methods"><details class="toggle method-toggle" open><summary><section id="method.label" class="method"><a class="src rightside" href="../../src/bevy_render/render_resource/bind_group.rs.html#311-313">Source</a><h4 class="code-header">fn <a href="#method.label" class="fn">label</a>() -> <a class="enum" href="https://doc.rust-lang.org/1.84.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a><&'static <a class="primitive" href="https://doc.rust-lang.org/1.84.0/std/primitive.str.html">str</a>></h4></section></summary><div class="docblock"><p>label</p>
|
||
</div></details><details class="toggle method-toggle" open><summary><section id="method.as_bind_group" class="method"><a class="src rightside" href="../../src/bevy_render/render_resource/bind_group.rs.html#316-340">Source</a><h4 class="code-header">fn <a href="#method.as_bind_group" class="fn">as_bind_group</a>(
|
||
&self,
|
||
layout: &<a class="struct" href="struct.BindGroupLayout.html" title="struct bevy_render::render_resource::BindGroupLayout">BindGroupLayout</a>,
|
||
render_device: &<a class="struct" href="../renderer/struct.RenderDevice.html" title="struct bevy_render::renderer::RenderDevice">RenderDevice</a>,
|
||
param: &mut <a class="type" href="../../bevy_ecs/system/system_param/type.SystemParamItem.html" title="type bevy_ecs::system::system_param::SystemParamItem">SystemParamItem</a><'_, '_, Self::<a class="associatedtype" href="trait.AsBindGroup.html#associatedtype.Param" title="type bevy_render::render_resource::AsBindGroup::Param">Param</a>>,
|
||
) -> <a class="enum" href="https://doc.rust-lang.org/1.84.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a><<a class="struct" href="struct.PreparedBindGroup.html" title="struct bevy_render::render_resource::PreparedBindGroup">PreparedBindGroup</a><Self::<a class="associatedtype" href="trait.AsBindGroup.html#associatedtype.Data" title="type bevy_render::render_resource::AsBindGroup::Data">Data</a>>, <a class="enum" href="enum.AsBindGroupError.html" title="enum bevy_render::render_resource::AsBindGroupError">AsBindGroupError</a>></h4></section></summary><div class="docblock"><p>Creates a bind group for <code>self</code> matching the layout defined in <a href="trait.AsBindGroup.html#method.bind_group_layout" title="associated function bevy_render::render_resource::AsBindGroup::bind_group_layout"><code>AsBindGroup::bind_group_layout</code></a>.</p>
|
||
</div></details><details class="toggle method-toggle" open><summary><section id="method.bind_group_layout" class="method"><a class="src rightside" href="../../src/bevy_render/render_resource/bind_group.rs.html#354-362">Source</a><h4 class="code-header">fn <a href="#method.bind_group_layout" class="fn">bind_group_layout</a>(render_device: &<a class="struct" href="../renderer/struct.RenderDevice.html" title="struct bevy_render::renderer::RenderDevice">RenderDevice</a>) -> <a class="struct" href="struct.BindGroupLayout.html" title="struct bevy_render::render_resource::BindGroupLayout">BindGroupLayout</a><div class="where">where
|
||
Self: <a class="trait" href="https://doc.rust-lang.org/1.84.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Creates the bind group layout matching all bind groups returned by <a href="trait.AsBindGroup.html#method.as_bind_group" title="method bevy_render::render_resource::AsBindGroup::as_bind_group"><code>AsBindGroup::as_bind_group</code></a></p>
|
||
</div></details></div><h2 id="dyn-compatibility" class="section-header">Dyn Compatibility<a href="#dyn-compatibility" class="anchor">§</a></h2><div class="dyn-compatibility-info"><p>This trait is <b>not</b> <a href="https://doc.rust-lang.org/1.84.0/reference/items/traits.html#object-safety">dyn compatible</a>.</p><p><i>In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.</i></p></div><h2 id="implementors" class="section-header">Implementors<a href="#implementors" class="anchor">§</a></h2><div id="implementors-list"></div><script src="../../trait.impl/bevy_render/render_resource/bind_group/trait.AsBindGroup.js" async></script></section></div></main></body></html> |