More cleanup.

Author: tychedelia

crates/processing_pyo3/examples/particles_basic.py

@@ -13,8 +13,6 @@ def setup():
 
     directional_light((0.95, 0.9, 0.85), 600.0)
 
-    # Source mesh whose vertices become particle positions; uvs come along for
-    # free and we use them to color each particle.
     source = Geometry.sphere(5.0, 32, 24)
     p = Particles(
         geometry=source,

crates/processing_pyo3/examples/particles_emit.py

@@ -21,8 +21,7 @@ def setup():
         attributes=[Attribute.position(), Attribute.color()],
     )
 
-    # Push unemitted slots far off-screen so they don't all render at the
-    # origin while the ring buffer is still filling.
+    # Park unemitted slots far off-screen until the ring buffer fills.
     pos_buf = p.buffer(Attribute.position())
     pos_buf.write([1.0e6] * (capacity * 3))
 
@@ -39,9 +38,7 @@ def draw():
     use_material(mat)
     particles(p, sphere)
 
-    # Emit 4 particles per frame in an outward-spiraling ring; once the ring
-    # buffer fills (~500 frames at 4/frame for capacity 2000), oldest get
-    # overwritten and the swirl continues without bound.
+    # Emit 4 particles per frame in an outward-spiraling ring.
     burst = 4
     positions = []
     colors = []

crates/processing_pyo3/examples/particles_emit_gpu.py

@@ -148,7 +148,7 @@ def setup():
         ],
     )
 
-    # Mark all unemitted slots dead so they don't render at origin.
+    # Park unemitted slots until the spawn kernel fills them.
     dead_buf = p.buffer(Attribute.dead())
     dead_buf.write([1.0] * CAPACITY)
 
@@ -167,7 +167,6 @@ def draw():
     use_material(mat)
     particles(p, particle)
 
-    # Animate spawn point in a small circle so the fountain meanders.
     t = elapsed_time
     sx = math.cos(t) * 0.4
     sz = math.sin(t) * 0.4

crates/processing_pyo3/examples/particles_from_mesh.py

@@ -13,8 +13,6 @@ def setup():
 
     directional_light((0.95, 0.9, 0.85), 200.0)
 
-    # Source mesh whose vertices become the particle positions. UVs come along
-    # for free and we'll use them to paint each particle a unique color.
     source = Geometry.sphere(5.0, 32, 24)
     p = Particles(
         geometry=source,

crates/processing_pyo3/examples/particles_lifecycle.py

@@ -74,7 +74,7 @@ def setup():
         attributes=[position_attr, color_attr, scale_attr, dead_attr, age_attr],
     )
 
-    # Mark all slots dead initially so unemitted ring slots don't render.
+    # Park unemitted slots until the spawn loop fills them.
     dead_buf = p.buffer(dead_attr)
     dead_buf.write([1.0] * capacity)
 
@@ -92,12 +92,10 @@ def draw():
     use_material(mat)
     particles(p, sphere)
 
-    # Spawn `BURST` new particles per frame in a small fountain.
     positions = []
     colors = []
     for k in range(BURST):
         i = frame * BURST + k
-        # Cheap pseudo-random offset.
         u = (((i * 2654435761) >> 8) & 0xFFFF) / 65535.0
         v = (((i * 40503) >> 8) & 0xFFFF) / 65535.0
         theta = u * math.tau

crates/processing_pyo3/examples/particles_noise.py

@@ -14,8 +14,6 @@ def setup():
 
     directional_light((0.95, 0.9, 0.85), 200.0)
 
-    # Seed positions from a sphere mesh; noise will jitter them around their
-    # initial sphere shape over time.
     source = Geometry.sphere(5.0, 32, 24)
     p = Particles(
         geometry=source,

crates/processing_pyo3/src/compute.rs

@@ -16,18 +16,14 @@ pub struct Buffer {
     pub(crate) entity: Entity,
     element_type: Option<ShaderValue>,
     size: u64,
-    /// `false` for buffers we created and own — `Drop` destroys the entity.
-    /// `true` for buffers we wrap (e.g. a Field's attribute buffer) where the
-    /// underlying entity belongs to someone else; destroying it would yank the
-    /// buffer out from under the owner.
+    /// `true` for borrowed wrappers (e.g. `Particles.buffer()`) where the
+    /// underlying entity belongs elsewhere; `Drop` skips destroy in that case.
     borrowed: bool,
 }
 
 impl Buffer {
-    /// Wrap an existing buffer entity (e.g., one owned by a Field).
-    /// `size` is queried from the buffer; `element_type` is supplied so typed
-    /// reads / `__getitem__` work correctly. The wrapper does NOT destroy the
-    /// entity on drop — ownership stays with whoever produced it.
+    /// Wrap an existing buffer entity without taking ownership. `Drop` will
+    /// not destroy it.
     pub(crate) fn from_entity(entity: Entity, element_type: Option<ShaderValue>) -> Self {
         let size = buffer_size(entity).unwrap_or(0);
         Self {
@@ -144,10 +140,8 @@ impl Buffer {
     }
 
     pub fn write(&mut self, values: &Bound<'_, PyAny>) -> PyResult<()> {
-        // Fast path: raw bytes go through unchanged. This is essential for
-        // large buffers where iterating Python objects would be unworkably
-        // slow (e.g. 1M-element fields). Element type is preserved if already
-        // known; otherwise the buffer stays untyped (read() returns bytes).
+        // Bytes path skips per-element conversion — the only viable route for
+        // multi-million-element uploads.
         if let Ok(b) = values.cast::<PyBytes>() {
             return buffer_write(self.entity, b.as_bytes().to_vec())
                 .map_err(|e| PyRuntimeError::new_err(format!("{e}")));

crates/processing_pyo3/src/graphics.rs

@@ -500,8 +500,6 @@ impl Graphics {
 
     #[pyo3(signature = (*args))]
     pub fn fill(&self, args: &Bound<'_, PyTuple>) -> PyResult<()> {
-        // `fill(buffer)` — per-particle albedo for `Particles` draws. Bypasses the
-        // color-mode parser and feeds the buffer entity straight through.
         if args.len() == 1
             && let Ok(buf) = args.get_item(0)?.extract::<PyRef<crate::compute::Buffer>>()
         {

crates/processing_pyo3/src/lib.rs

@@ -1146,10 +1146,8 @@ mod mewnala {
             Ok(())
         });
 
-        // Tear the App down gracefully while the thread-local is still alive,
-        // matching what `processing::exit()` does in Rust sketches. Without
-        // this the App falls to its eager thread-local destructor at process
-        // exit and a Bevy resource panics inside its own Drop, aborting.
+        // Tear down the App while the thread-local is still alive — letting
+        // it run via the eager TLS destructor aborts inside a Bevy resource Drop.
         let _ = ::processing::exit(0);
 
         result

crates/processing_pyo3/src/material.rs

@@ -21,7 +21,6 @@ pub(crate) fn py_to_shader_value(value: &Bound<'_, PyAny>) -> PyResult<shader_va
         return Ok(shader_value::ShaderValue::Int(v));
     }
 
-    // Accept PyVec types
     if let Ok(v) = value.extract::<PyRef<PyVec4>>() {
         return Ok(shader_value::ShaderValue::Float4(v.0.to_array()));
     }
@@ -36,7 +35,6 @@ pub(crate) fn py_to_shader_value(value: &Bound<'_, PyAny>) -> PyResult<shader_va
         return Ok(shader_value::ShaderValue::Buffer(buf.entity));
     }
 
-    // Fall back to raw arrays
     if let Ok(v) = value.extract::<[f32; 4]>() {
         return Ok(shader_value::ShaderValue::Float4(v));
     }
@@ -53,9 +51,8 @@ pub(crate) fn py_to_shader_value(value: &Bound<'_, PyAny>) -> PyResult<shader_va
     )))
 }
 
-/// Apply an `albedo` value to a material, dispatching by Python type. The
-/// material's backing asset is swapped between plain-PBR and field-buffer
-/// variants as needed; all other `StandardMaterial` state survives the swap.
+/// Dispatch `albedo=` by Python type to the matching Rust setter. May swap
+/// the backing asset; all other StandardMaterial state survives.
 fn apply_albedo(entity: Entity, value: &Bound<'_, PyAny>) -> PyResult<()> {
     if let Ok(buf) = value.extract::<PyRef<Buffer>>() {
         return material_set_albedo_buffer(entity, buf.entity)
@@ -95,9 +92,8 @@ fn apply_kwargs(entity: Entity, kwargs: &Bound<'_, PyDict>) -> PyResult<()> {
 
 #[pymethods]
 impl Material {
-    /// Construct a material. With no args, returns a default PBR. With a
-    /// `shader` arg, returns a custom material. Any kwargs (`albedo=...`,
-    /// `roughness=...`, etc.) are applied after construction.
+    /// No args: default PBR. With `shader`: custom material. Kwargs are
+    /// applied via `set` after construction.
     #[new]
     #[pyo3(signature = (shader=None, **kwargs))]
     pub fn new(shader: Option<&Shader>, kwargs: Option<&Bound<'_, PyDict>>) -> PyResult<Self> {
@@ -114,8 +110,8 @@ impl Material {
         Ok(Self { entity })
     }
 
-    /// PBR-lit material. `albedo` accepts a `Color` (solid) or a `Buffer`
-    /// (per-particle, indexed by per-instance tag — used with `Field`s).
+    /// PBR-lit material. `albedo` accepts a `Color` or a `Buffer` (the latter
+    /// being per-particle, used with `Particles`).
     #[staticmethod]
     #[pyo3(signature = (**kwargs))]
     pub fn pbr(kwargs: Option<&Bound<'_, PyDict>>) -> PyResult<Self> {
@@ -126,8 +122,7 @@ impl Material {
         Ok(Self { entity })
     }
 
-    /// Unlit material — same shape as `pbr` but skips lighting calculations
-    /// (the per-particle / solid color is the final output).
+    /// Like `pbr` but skips lighting; albedo is the final output color.
     #[staticmethod]
     #[pyo3(signature = (**kwargs))]
     pub fn unlit(kwargs: Option<&Bound<'_, PyDict>>) -> PyResult<Self> {
@@ -140,10 +135,8 @@ impl Material {
         Ok(Self { entity })
     }
 
-    /// Patch one or more material properties. `albedo` is special-cased and
-    /// may swap the backing asset type between solid-color and buffer-color
-    /// variants — all other `StandardMaterial` state (roughness, metallic,
-    /// emissive, alpha_mode, unlit, etc.) is preserved across the swap.
+    /// Patch material properties. `albedo` may swap the backing asset between
+    /// color and buffer variants; other StandardMaterial fields are preserved.
     #[pyo3(signature = (**kwargs))]
     pub fn set(&self, kwargs: Option<&Bound<'_, PyDict>>) -> PyResult<()> {
         let Some(kwargs) = kwargs else {