Deploying to master from @ gfx-rs/wgpu@2f50426 🚀

Author: cwfitzgerald

doc/search-index.js

@@ -197,56 +197,107 @@
 <a href="#196" id="196">196</a>
 <a href="#197" id="197">197</a>
 <a href="#198" id="198">198</a>
-<a href="#199" id="199">199</a></pre></div><pre class="rust"><code><span class="kw">use crate</span>::{
+<a href="#199" id="199">199</a>
+<a href="#200" id="200">200</a>
+<a href="#201" id="201">201</a>
+<a href="#202" id="202">202</a>
+<a href="#203" id="203">203</a>
+<a href="#204" id="204">204</a>
+<a href="#205" id="205">205</a>
+<a href="#206" id="206">206</a>
+<a href="#207" id="207">207</a>
+<a href="#208" id="208">208</a>
+<a href="#209" id="209">209</a>
+<a href="#210" id="210">210</a>
+<a href="#211" id="211">211</a>
+<a href="#212" id="212">212</a>
+<a href="#213" id="213">213</a>
+<a href="#214" id="214">214</a>
+<a href="#215" id="215">215</a>
+<a href="#216" id="216">216</a>
+<a href="#217" id="217">217</a>
+<a href="#218" id="218">218</a>
+<a href="#219" id="219">219</a>
+<a href="#220" id="220">220</a>
+<a href="#221" id="221">221</a>
+<a href="#222" id="222">222</a>
+<a href="#223" id="223">223</a>
+<a href="#224" id="224">224</a>
+<a href="#225" id="225">225</a>
+<a href="#226" id="226">226</a>
+<a href="#227" id="227">227</a>
+<a href="#228" id="228">228</a>
+<a href="#229" id="229">229</a>
+<a href="#230" id="230">230</a>
+<a href="#231" id="231">231</a>
+<a href="#232" id="232">232</a>
+<a href="#233" id="233">233</a>
+<a href="#234" id="234">234</a>
+<a href="#235" id="235">235</a>
+<a href="#236" id="236">236</a>
+<a href="#237" id="237">237</a>
+<a href="#238" id="238">238</a>
+<a href="#239" id="239">239</a>
+<a href="#240" id="240">240</a>
+<a href="#241" id="241">241</a>
+<a href="#242" id="242">242</a>
+<a href="#243" id="243">243</a>
+<a href="#244" id="244">244</a>
+<a href="#245" id="245">245</a>
+<a href="#246" id="246">246</a>
+<a href="#247" id="247">247</a>
+<a href="#248" id="248">248</a>
+<a href="#249" id="249">249</a>
+<a href="#250" id="250">250</a>
+<a href="#251" id="251">251</a>
+<a href="#252" id="252">252</a>
+<a href="#253" id="253">253</a>
+<a href="#254" id="254">254</a>
+<a href="#255" id="255">255</a>
+<a href="#256" id="256">256</a>
+<a href="#257" id="257">257</a>
+<a href="#258" id="258">258</a>
+<a href="#259" id="259">259</a>
+<a href="#260" id="260">260</a>
+<a href="#261" id="261">261</a>
+<a href="#262" id="262">262</a>
+<a href="#263" id="263">263</a>
+<a href="#264" id="264">264</a>
+<a href="#265" id="265">265</a>
+<a href="#266" id="266">266</a>
+<a href="#267" id="267">267</a>
+<a href="#268" id="268">268</a>
+<a href="#269" id="269">269</a>
+<a href="#270" id="270">270</a>
+<a href="#271" id="271">271</a>
+<a href="#272" id="272">272</a></pre></div><pre class="rust"><code><span class="kw">use crate</span>::{
     util::align_to, Buffer, BufferAddress, BufferDescriptor, BufferSize, BufferUsages,
     BufferViewMut, CommandEncoder, Device, MapMode,
 };
 <span class="kw">use </span>std::fmt;
-<span class="kw">use </span>std::sync::{mpsc, Arc};
-
-<span class="kw">struct </span>Chunk {
-    buffer: Arc&lt;Buffer&gt;,
-    size: BufferAddress,
-    offset: BufferAddress,
-}
-
-<span class="doccomment">/// `Sync` wrapper that works by providing only exclusive access.
-///
-/// See https://doc.rust-lang.org/nightly/std/sync/struct.Exclusive.html
-</span><span class="kw">struct </span>Exclusive&lt;T&gt;(T);
-
-<span class="kw">unsafe impl</span>&lt;T&gt; Sync <span class="kw">for </span>Exclusive&lt;T&gt; {}
-
-<span class="kw">impl</span>&lt;T&gt; Exclusive&lt;T&gt; {
-    <span class="kw">fn </span>new(value: T) -&gt; <span class="self">Self </span>{
-        <span class="self">Self</span>(value)
-    }
-
-    <span class="kw">fn </span>get_mut(<span class="kw-2">&amp;mut </span><span class="self">self</span>) -&gt; <span class="kw-2">&amp;mut </span>T {
-        <span class="kw-2">&amp;mut </span><span class="self">self</span>.<span class="number">0
-    </span>}
-}
+<span class="kw">use </span>std::sync::mpsc;
 
 <span class="doccomment">/// Efficiently performs many buffer writes by sharing and reusing temporary buffers.
 ///
 /// Internally it uses a ring-buffer of staging buffers that are sub-allocated.
-/// It has an advantage over [`Queue::write_buffer()`] in a way that it returns a mutable slice,
-/// which you can fill to avoid an extra data copy.
+/// Its advantage over [`Queue::write_buffer_with()`] is that the individual allocations
+/// are cheaper; `StagingBelt` is most useful when you are writing very many small pieces
+/// of data. It can be understood as a sort of arena allocator.
 ///
 /// Using a staging belt is slightly complicated, and generally goes as follows:
-/// 1. Write to buffers that need writing to using [`StagingBelt::write_buffer()`].
+/// 1. Use [`StagingBelt::write_buffer()`] or [`StagingBelt::allocate()`] to allocate
+///    buffer slices, then write your data to them.
 /// 2. Call [`StagingBelt::finish()`].
 /// 3. Submit all command encoders that were used in step 1.
 /// 4. Call [`StagingBelt::recall()`].
 ///
-/// [`Queue::write_buffer()`]: crate::Queue::write_buffer
+/// [`Queue::write_buffer_with()`]: crate::Queue::write_buffer_with
 </span><span class="kw">pub struct </span>StagingBelt {
     chunk_size: BufferAddress,
     <span class="doccomment">/// Chunks into which we are accumulating data to be transferred.
     </span>active_chunks: Vec&lt;Chunk&gt;,
     <span class="doccomment">/// Chunks that have scheduled transfers already; they are unmapped and some
-    /// command encoder has one or more `copy_buffer_to_buffer` commands with them
-    /// as source.
+    /// command encoder has one or more commands with them as source.
     </span>closed_chunks: Vec&lt;Chunk&gt;,
     <span class="doccomment">/// Chunks that are back from the GPU and ready to be mapped for write and put
     /// into `active_chunks`.
@@ -269,7 +320,7 @@
     ///   (per [`StagingBelt::finish()`]); and
     /// * bigger is better, within these bounds.
     </span><span class="kw">pub fn </span>new(chunk_size: BufferAddress) -&gt; <span class="self">Self </span>{
-        <span class="kw">let </span>(sender, receiver) = std::sync::mpsc::channel();
+        <span class="kw">let </span>(sender, receiver) = mpsc::channel();
         StagingBelt {
             chunk_size,
             active_chunks: Vec::new(),
@@ -280,7 +331,7 @@
         }
     }
 
-    <span class="doccomment">/// Allocate the staging belt slice of `size` to be uploaded into the `target` buffer
+    <span class="doccomment">/// Allocate a staging belt slice of `size` to be copied into the `target` buffer
     /// at the specified offset.
     ///
     /// The upload will be placed into the provided command encoder. This encoder
@@ -298,10 +349,61 @@
         size: BufferSize,
         device: <span class="kw-2">&amp;</span>Device,
     ) -&gt; BufferViewMut&lt;<span class="lifetime">'_</span>&gt; {
+        <span class="kw">let </span>(mapped, belt_buffer, offset_in_belt_buffer) = <span class="self">self</span>.allocate(
+            size,
+            <span class="kw">const </span>{ BufferSize::new(<span class="kw">crate</span>::COPY_BUFFER_ALIGNMENT).unwrap() },
+            device,
+        );
+        encoder.copy_buffer_to_buffer(
+            belt_buffer,
+            offset_in_belt_buffer,
+            target,
+            offset,
+            size.get(),
+        );
+        mapped
+    }
+
+    <span class="doccomment">/// Allocate a staging belt slice with the given `size` and `alignment` and return it.
+    ///
+    /// This allows you to do whatever you want with the slice after, such as
+    /// copying it to a texture or executing a compute shader that reads it, whereas
+    /// [`StagingBelt::write_buffer()`] can only write to other buffers.
+    ///
+    /// If the `size` is greater than the space available in any free internal buffer, a new buffer
+    /// will be allocated for it. Therefore, the `chunk_size` passed to [`StagingBelt::new()`]
+    /// should ideally be larger than every such size.
+    ///
+    /// The chosen slice will be positioned within the buffer at a multiple of `alignment`,
+    /// which may be used to meet alignment requirements for the operation you wish to perform
+    /// with the slice. This does not necessarily affect the alignment of the mapping.
+    ///
+    /// Three values are returned:
+    ///
+    /// * The mapped buffer view which you should write into from the CPU side (Rust code).
+    /// * The buffer containing the slice, for you to use in GPU commands.
+    ///   All commands involving this slice must be submitted after
+    ///   [`StagingBelt::finish()`] is called and before [`StagingBelt::recall()`] is called.
+    /// * The offset within the buffer at which the slice starts.
+    ///   This offset should be used for all GPU commands, and should not be used with
+    ///   the mapped buffer view.
+    </span><span class="kw">pub fn </span>allocate(
+        <span class="kw-2">&amp;mut </span><span class="self">self</span>,
+        size: BufferSize,
+        alignment: BufferSize,
+        device: <span class="kw-2">&amp;</span>Device,
+    ) -&gt; (BufferViewMut&lt;<span class="lifetime">'_</span>&gt;, <span class="kw-2">&amp;</span>Buffer, BufferAddress) {
+        <span class="macro">assert!</span>(
+            alignment.get().is_power_of_two(),
+            <span class="string">"alignment must be a power of two, not {alignment}"
+        </span>);
+        <span class="comment">// At minimum, we must have alignment sufficient to map the buffer.
+        </span><span class="kw">let </span>alignment = alignment.get().max(<span class="kw">crate</span>::MAP_ALIGNMENT);
+
         <span class="kw">let </span><span class="kw-2">mut </span>chunk = <span class="kw">if let </span><span class="prelude-val">Some</span>(index) = <span class="self">self
             </span>.active_chunks
             .iter()
-            .position(|chunk| chunk.offset + size.get() &lt;= chunk.size)
+            .position(|chunk| chunk.can_allocate(size, alignment))
         {
             <span class="self">self</span>.active_chunks.swap_remove(index)
         } <span class="kw">else </span>{
@@ -310,35 +412,35 @@
             </span><span class="kw">if let </span><span class="prelude-val">Some</span>(index) = <span class="self">self
                 </span>.free_chunks
                 .iter()
-                .position(|chunk| size.get() &lt;= chunk.size)
+                .position(|chunk| chunk.can_allocate(size, alignment))
             {
                 <span class="self">self</span>.free_chunks.swap_remove(index)
             } <span class="kw">else </span>{
-                <span class="kw">let </span>size = <span class="self">self</span>.chunk_size.max(size.get());
                 Chunk {
-                    buffer: Arc::new(device.create_buffer(<span class="kw-2">&amp;</span>BufferDescriptor {
+                    buffer: device.create_buffer(<span class="kw-2">&amp;</span>BufferDescriptor {
                         label: <span class="prelude-val">Some</span>(<span class="string">"(wgpu internal) StagingBelt staging buffer"</span>),
-                        size,
+                        size: <span class="self">self</span>.chunk_size.max(size.get()),
                         usage: BufferUsages::MAP_WRITE | BufferUsages::COPY_SRC,
                         mapped_at_creation: <span class="bool-val">true</span>,
-                    })),
-                    size,
+                    }),
                     offset: <span class="number">0</span>,
                 }
             }
         };
 
-        encoder.copy_buffer_to_buffer(<span class="kw-2">&amp;</span>chunk.buffer, chunk.offset, target, offset, size.get());
-        <span class="kw">let </span>old_offset = chunk.offset;
-        chunk.offset = align_to(chunk.offset + size.get(), <span class="kw">crate</span>::MAP_ALIGNMENT);
+        <span class="kw">let </span>allocation_offset = chunk.allocate(size, alignment);
 
         <span class="self">self</span>.active_chunks.push(chunk);
-        <span class="self">self</span>.active_chunks
-            .last()
-            .unwrap()
-            .buffer
-            .slice(old_offset..old_offset + size.get())
-            .get_mapped_range_mut()
+        <span class="kw">let </span>chunk = <span class="self">self</span>.active_chunks.last().unwrap();
+
+        (
+            chunk
+                .buffer
+                .slice(allocation_offset..allocation_offset + size.get())
+                .get_mapped_range_mut(),
+            <span class="kw-2">&amp;</span>chunk.buffer,
+            allocation_offset,
+        )
     }
 
     <span class="doccomment">/// Prepare currently mapped buffers for use in a submission.
@@ -396,4 +498,48 @@
             .finish_non_exhaustive()
     }
 }
+
+<span class="kw">struct </span>Chunk {
+    buffer: Buffer,
+    offset: BufferAddress,
+}
+
+<span class="kw">impl </span>Chunk {
+    <span class="kw">fn </span>can_allocate(<span class="kw-2">&amp;</span><span class="self">self</span>, size: BufferSize, alignment: BufferAddress) -&gt; bool {
+        <span class="kw">let </span>alloc_start = align_to(<span class="self">self</span>.offset, alignment);
+        <span class="kw">let </span>alloc_end = alloc_start + size.get();
+
+        alloc_end &lt;= <span class="self">self</span>.buffer.size()
+    }
+
+    <span class="kw">fn </span>allocate(<span class="kw-2">&amp;mut </span><span class="self">self</span>, size: BufferSize, alignment: BufferAddress) -&gt; BufferAddress {
+        <span class="kw">let </span>alloc_start = align_to(<span class="self">self</span>.offset, alignment);
+        <span class="kw">let </span>alloc_end = alloc_start + size.get();
+
+        <span class="macro">assert!</span>(alloc_end &lt;= <span class="self">self</span>.buffer.size());
+        <span class="self">self</span>.offset = alloc_end;
+        alloc_start
+    }
+}
+
+<span class="kw">use </span>exclusive::Exclusive;
+<span class="kw">mod </span>exclusive {
+    <span class="doccomment">/// `Sync` wrapper that works by providing only exclusive access.
+    ///
+    /// See &lt;https://doc.rust-lang.org/nightly/std/sync/struct.Exclusive.html&gt;
+    </span><span class="kw">pub</span>(<span class="kw">super</span>) <span class="kw">struct </span>Exclusive&lt;T&gt;(T);
+
+    <span class="doccomment">/// Safety: `&amp;Exclusive` has no operations.
+    </span><span class="kw">unsafe impl</span>&lt;T&gt; Sync <span class="kw">for </span>Exclusive&lt;T&gt; {}
+
+    <span class="kw">impl</span>&lt;T&gt; Exclusive&lt;T&gt; {
+        <span class="kw">pub fn </span>new(value: T) -&gt; <span class="self">Self </span>{
+            <span class="self">Self</span>(value)
+        }
+
+        <span class="kw">pub fn </span>get_mut(<span class="kw-2">&amp;mut </span><span class="self">self</span>) -&gt; <span class="kw-2">&amp;mut </span>T {
+            <span class="kw-2">&amp;mut </span><span class="self">self</span>.<span class="number">0
+        </span>}
+    }
+}
 </code></pre></div></section></main></body></html>