Merge pull request 'Sierpinski Gasket' (#2) from sierpinski_gasket into main

Reviewed-on: #2

Cargo.toml

@@ -22,7 +22,9 @@ spirv-std = { git = "https://github.com/Rust-GPU/rust-gpu.git", rev = "67f1ff2"
 anyhow = "1.0.102"
 bytemuck = { version = "1.25.0", features = ["derive"] }
 glam = { version = "0.33.1", default-features = false, features = ["bytemuck", "scalar-math"] }
+image = { version = "0.25.10", default-features = false, features = ["default-formats"]}
 libm = "0.2.16"
 rand = { version = "0.10.1", default-features = false }
 rspirv = "0.13.0"
-
+rand_xoshiro = "0.8.1"
+tempfile = "3.27.0"

enkou-shaders/Cargo.toml

@@ -15,3 +15,9 @@ glam.workspace = true
 libm.workspace = true
 rand.workspace = true
 spirv-std.workspace = true
+
+[dev-dependencies]
+anyhow.workspace = true
+image.workspace = true
+rand_xoshiro.workspace = true
+tempfile.workspace = true

enkou-shaders/examples/gasket.rs

@@ -0,0 +1,75 @@
+use anyhow::{Context, Result};
+use enkou_shaders::Coefficients2;
+use enkou_shaders::camera::Camera;
+use enkou_shaders::chaos_game::ChaosGame;
+use enkou_shaders::transform::Transform;
+use glam::{Affine2, UVec2, Vec2, uvec2};
+use image::{GrayImage, Luma};
+use rand::SeedableRng;
+use rand_xoshiro::Xoshiro256StarStar;
+use std::mem;
+use std::process::Command;
+use tempfile::NamedTempFile;
+
+const ITERATIONS: u32 = 50_000;
+const ITERATIONS_DISCARD: u32 = 20;
+const IMAGE_DIMENSION: UVec2 = uvec2(600, 600);
+
+pub fn main() -> Result<()> {
+    let seed: u64 = 4; // chosen by fair dice roll
+    let mut rng = Xoshiro256StarStar::seed_from_u64(seed);
+
+    let transforms = [
+        // F_0: (x / 2, y / 2)
+        Transform::new(Affine2::from_coefficients(0.5, 0.0, 0.0, 0.0, 0.5, 0.0)),
+        // F_1: ((x + 1) / 2, y / 2)
+        Transform::new(Affine2::from_coefficients(0.5, 0.0, 0.5, 0.0, 0.5, 0.0)),
+        // F_2: (x / 2, (y + 1) / 2)
+        Transform::new(Affine2::from_coefficients(0.5, 0.0, 0.0, 0.0, 0.5, 0.5)),
+    ];
+
+    let weights = [1.0 / 3.0, 1.0 / 3.0, 1.0 / 3.0];
+
+    let mut image = GrayImage::new(IMAGE_DIMENSION.x, IMAGE_DIMENSION.y);
+
+    // The gasket is defined on the range [0, 1] for both X and Y
+    let camera = Camera::new(
+        IMAGE_DIMENSION,
+        Vec2::ONE * 0.5,
+        0.0,
+        Vec2::ZERO,
+        IMAGE_DIMENSION.as_vec2(),
+    );
+
+    let mut chaos_game = ChaosGame::new(&mut rng, &transforms, &weights);
+    for i in 0..ITERATIONS {
+        let next_point = chaos_game.next().unwrap();
+
+        if i < ITERATIONS_DISCARD {
+            continue;
+        }
+
+        if let Some(next_point) = camera.transform_point_to_image(next_point) {
+            image.put_pixel(next_point.x, next_point.y, Luma([255u8]))
+        }
+    }
+
+    let temp = NamedTempFile::with_suffix(".png").context("Unable to create file for image")?;
+    image.save(temp.path()).context("Unable to save image")?;
+
+    let open_program = cfg_select! {
+        unix => "xdg-open",
+        _ => panic!("Unknown system"),
+    };
+
+    Command::new(open_program)
+        .arg(temp.path())
+        .spawn()?
+        .wait()?;
+
+    // In case the image viewer forks and gives control back prior to reading the file,
+    // drop it and don't run the destructor
+    mem::forget(temp);
+
+    Ok(())
+}

enkou-shaders/src/camera.rs

@@ -1,18 +1,26 @@
+//! # Camera
+//!
+//! Map points from the IFS coordinate system to pixel coordinates. This is a lossy transformation.
 use bytemuck::{Pod, Zeroable};
 use glam::{Affine2, IVec2, UVec2, Vec2, vec2};
 use libm::powf;
 
+/// Settings used to map IFS coordinates to pixel coordinates.
+///
+/// The camera is itself an affine transformation, capable of zoom, rotation, and translation
+/// of the IFS coordinates before rendering to the final image.
 #[derive(Copy, Clone, Pod, Zeroable)]
 #[repr(C)]
 pub struct Camera {
+    dimensions: UVec2,
     transform: Affine2,
 }
 
 impl Camera {
-    /// Construct a new camera that maps IFS coordinates to pixel coordinates.
+    /// Construct a new camera for translating IFS coordinates to pixel coordinates.
     ///
-    /// The camera object is itself an affine transformation, but it's helpful to express
+    /// While the camera is implemented as a single affine transformation, it's helpful
-    /// the parameters in individual steps, and compose them internally.
+    /// to express the transform steps individually.
     ///
     /// # Arguments
     ///
@@ -23,7 +31,7 @@ impl Camera {
     ///     `center` translation, so it is about the new origin.
     /// * `zoom` - Zoom factor applied to IFS coordinates. IFS coordinates are scaled by
     ///     `pow(2, zoom)`, so a zoom factor of 0 is the identity.
-    /// * `scale` - Pixels per unit of IFS coordinates. By default, this parameter is chosen such
+    /// * `scale` - Pixels per unit of IFS coordinates. This parameter is usually chosen such
     ///     that the largest dimension will cover the range `[-2, 2]`, but values higher or lower
     ///     can be used as a secondary zoom.
     pub fn new(dimensions: UVec2, center: Vec2, rotate: f32, zoom: Vec2, scale: Vec2) -> Camera {
@@ -39,7 +47,10 @@ impl Camera {
             * zoom_transform
             * ifs_center_transform;
 
-        Camera { transform }
+        Camera {
+            dimensions,
+            transform,
+        }
     }
 
     /// Map a point from IFS coordinates to pixel coordinates.
@@ -62,6 +73,21 @@ impl Camera {
     pub fn transform_point(&self, point: Vec2) -> IVec2 {
         self.transform.transform_point2(point).as_ivec2()
     }
+
+    /// Map a point from IFS coordinates to pixel coordinates (like [`transform_point`](Camera::transform_point)),
+    /// and check that the result is within the provided image dimensions.
+    pub fn transform_point_to_image(&self, point: Vec2) -> Option<UVec2> {
+        let pixel_coordinates = self.transform_point(point);
+        if pixel_coordinates.x < 0
+            || pixel_coordinates.y < 0
+            || (pixel_coordinates.x as u32) >= self.dimensions.x
+            || (pixel_coordinates.y as u32) >= self.dimensions.y
+        {
+            None
+        } else {
+            Some(pixel_coordinates.as_uvec2())
+        }
+    }
 }
 
 #[cfg(test)]

enkou-shaders/src/chaos_game.rs

@@ -0,0 +1,93 @@
+//! # Chaos Game
+//!
+//! Fractal flames are a class of
+//! [iterated function systems](https://en.wikipedia.org/wiki/Iterated_function_system)
+//! that generate images following a simple algorithm:
+//!
+//! - Pick a starting point `(x, y)`
+//! - Iterate:
+//!     - Pick a [`Transform`] from the set of available transforms
+//!     - Apply the current point to the chosen transform, generating a new point `(x, y)`
+//!     - Plot the new point `(x, y)`
+//!
+//! This algorithm is also known as the ["chaos game"](https://en.wikipedia.org/wiki/Chaos_game),
+//! and it forms the basic system for producing images.
+use crate::transform::Transform;
+use glam::{Vec2, vec2};
+use rand::distr::{Distribution, StandardUniform};
+use rand::{Rng, RngExt};
+
+struct BiUnit;
+impl Distribution<f32> for BiUnit {
+    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> f32 {
+        rng.sample::<f32, _>(StandardUniform) * 2.0 - 1.0
+    }
+}
+
+/// Iterate one step in the chaos game; choose the next transform, apply it,
+/// and return the resulting point. Also returns the transform index so that
+/// path-dependent weights (the "Xaos" table in Apophysis) can be chosen
+/// for the next iteration step.
+///
+/// # Arguments
+///
+/// * `weights` - Weights are assumed to be normalized; adding all elements together should return the value 1
+pub fn step_chaos_game<R: Rng>(
+    point: Vec2,
+    rng: &mut R,
+    transforms: &[Transform],
+    weights: &[f32],
+) -> (Vec2, u32) {
+    let mut choice_weight = rng.sample::<f32, _>(StandardUniform);
+    let mut transform_index: u32 = 0;
+
+    for weight in weights {
+        choice_weight -= weight;
+        if choice_weight <= 0.0 {
+            break;
+        }
+
+        transform_index += 1;
+    }
+
+    (
+        transforms[transform_index as usize].transform_point(point),
+        transform_index,
+    )
+}
+
+/// Iterator for chaos game state. Holds the current point and references to all other data
+/// necessary to generate fractal flame images.
+///
+/// New points in the chaos game are produced by iterating on the chaos game.
+pub struct ChaosGame<'a, R: Rng> {
+    current_point: Vec2,
+    rng: &'a mut R,
+    transforms: &'a [Transform],
+    weights: &'a [f32],
+}
+
+impl<'a, R: Rng> ChaosGame<'a, R> {
+    /// Create a new chaos game iterator
+    pub fn new(rng: &'a mut R, transforms: &'a [Transform], weights: &'a [f32]) -> Self {
+        let current_point = vec2(rng.sample(BiUnit), rng.sample(BiUnit));
+        ChaosGame {
+            current_point,
+            rng,
+            transforms,
+            weights,
+        }
+    }
+}
+
+impl<'a, R: Rng> Iterator for ChaosGame<'a, R> {
+    type Item = Vec2;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        let (next_point, _) =
+            step_chaos_game(self.current_point, self.rng, self.transforms, self.weights);
+        self.current_point = next_point;
+
+        Some(next_point)
+    }
+}

enkou-shaders/src/lib.rs

@@ -3,19 +3,20 @@
 #![warn(missing_docs)]
 
 pub mod camera;
+pub mod chaos_game;
+pub mod transform;
 
 use bytemuck::{Pod, Zeroable};
 use core::f32::consts::PI;
-use glam::{Affine2, Vec2, Vec3, Vec4, vec2, vec3};
+use glam::{Affine2, Vec3, Vec4, vec2, vec3};
-use rand::distr::StandardUniform;
-use rand::{Rng, RngExt};
 #[cfg(target_arch = "spirv")]
 use spirv_std::num_traits::Float;
 use spirv_std::spirv;
 
-/// Utility trait for [`Affine2`] to convert between `flam3` notation and [`glam`].
+/// Utility trait to convert between `flam3` notation and [`glam`].
+#[allow(missing_docs)]
 pub trait Coefficients2 {
-    /// Convert affine transformation coefficients to the [`Affine2`] representation.
+    /// Convert affine transformation coefficients to the [`glam`] representation.
     /// Parameters use the following form:
     ///
     /// ```text
@@ -77,54 +78,7 @@ impl Coefficients2 for Affine2 {
 
 #[derive(Copy, Clone, Pod, Zeroable)]
 #[repr(C)]
-pub struct Transform {
+#[allow(missing_docs)]
-    pub coefficients: Affine2,
-}
-
-impl Transform {
-    pub fn new(coefficients: Affine2) -> Self {
-        Transform { coefficients }
-    }
-
-    pub fn transform_point(&self, point: Vec2) -> Vec2 {
-        self.coefficients.transform_point2(point)
-    }
-}
-
-/// Iterate one step in the chaos game; choose the next transform, apply it,
-/// and return the resulting point. Also returns the transform index so that
-/// path-dependent weights (the "Xaos" table in Apophysis) can be chosen
-/// for the next iteration step.
-///
-/// # Arguments
-///
-/// * `weights` - Weights are assumed to be normalized; adding all elements together should return the value 1
-pub fn step_chaos_game<R: Rng>(
-    rng: &mut R,
-    point: Vec2,
-    weights: &[f32],
-    transforms: &[Transform],
-) -> (Vec2, u32) {
-    let mut choice_weight = rng.sample::<f32, _>(StandardUniform);
-    let mut transform_index: u32 = 0;
-
-    for weight in weights {
-        choice_weight -= weight;
-        if choice_weight <= 0.0 {
-            break;
-        }
-
-        transform_index += 1;
-    }
-
-    (
-        transforms[transform_index as usize].transform_point(point),
-        transform_index,
-    )
-}
-
-#[derive(Copy, Clone, Pod, Zeroable)]
-#[repr(C)]
 pub struct ShaderConstants {
     pub width: u32,
     pub height: u32,
@@ -132,11 +86,13 @@ pub struct ShaderConstants {
 }
 
 #[spirv(fragment)]
+#[allow(missing_docs)]
 pub fn main_fs(vtx_color: Vec3, output: &mut Vec4) {
     *output = Vec4::from((vtx_color, 1.));
 }
 
 #[spirv(vertex)]
+#[allow(missing_docs)]
 pub fn main_vs(
     #[spirv(vertex_index)] vert_id: i32,
     #[spirv(descriptor_set = 0, binding = 0, storage_buffer)] constants: &ShaderConstants,

enkou-shaders/src/transform.rs

@@ -0,0 +1,26 @@
+//! # Transform
+//!
+//! Transforms are the "functions" in an iterated function system. They take in a point,
+//! and generate a new point. For fractal flames, transforms are always affine,
+//! but produce more interesting images once we add variations.
+use bytemuck::{Pod, Zeroable};
+use glam::{Affine2, Vec2};
+
+/// Affine transform for use in the [`chaos_game`](crate::chaos_game).
+#[derive(Copy, Clone, Pod, Zeroable)]
+#[repr(C)]
+pub struct Transform {
+    coefficients: Affine2,
+}
+
+impl Transform {
+    /// Create a new transform from an affine transformation matrix
+    pub fn new(coefficients: Affine2) -> Self {
+        Transform { coefficients }
+    }
+
+    /// Apply this transform to a point in IFS coordinates, producing a new point
+    pub fn transform_point(&self, point: Vec2) -> Vec2 {
+        self.coefficients.transform_point2(point)
+    }
+}