bevy_symbios_texture

Procedural, tileable texture generation for Bevy.

Generates albedo, normal, roughness (ORM), and optional emissive maps entirely on the CPU — no asset files required. Generation is multi-core (rows are produced in parallel) and seamlessly tileable for all surface textures via toroidal 4-D noise mapping. Alpha-masked card textures (leaf, twig, window, stained glass, iron grille, chain-link, log-end) produce per-pixel transparency and do not tile. Sprite-atlas generators (soft disc, spark, snowflake, puff, ring, petal, shard, leaf sprite, flame, flower) bake alpha-silhouette particle-billboard sheets where every atlas cell is a per-cell-seeded variant of the same config.

Bevy compatibility

bevy_symbios_texture	Bevy
0.4 – 0.6	0.18

Installation

[dependencies]
bevy_symbios_texture = "0.6"

The optional egui feature adds editor widgets for every config type (required for the texture_viewer example):

[dependencies]
bevy_symbios_texture = { version = "0.6", features = ["egui"] }

Migrating from 0.5 to 0.6

0.6 adds ten new generators (fabric, sand, snow, ice, lava, leaf_sprite, flame, flower, chain_link, log_end) plus hammered and diamond-plate metal styles, and parallelises generation across cores. The breaking changes:

• TextureMap gained fields. It now carries emissive: Option<Vec<u8>> and mip_level_count: u32 in addition to the three pixel buffers. Code that constructs TextureMap literals must add these (emissive: None, mip_level_count: 1 for a freshly generated base level). GeneratedHandles likewise gained emissive: Option<Handle<Image>>.
• Mipmaps are computed on the worker thread. Async generation now returns a TextureMap with the full chain already appended; map_to_images computes it on demand only when absent, so most callers need no change.
• generate_atlas and sample_grid/sample_grid_into gained Sync bounds to enable row-parallel generation. Custom SpriteCell types and 4-D noise functions must be Sync (they already are in practice).
• Cache identity changed. Fingerprints are now a structural hash of the config (stable across Rust versions and platforms) rather than a hash of the Debug string, and FileStore blobs use on-disk format v3 with manifest_version mixed into the key. Existing FileStore caches are invalidated once and rebuild automatically.
• Accepted visual drift. Bark and marble warp layers now use a separate warp_octaves field (default 3) instead of the base octaves, so default output shifts slightly. Configs serialised before 0.6 still deserialise (the field defaults to 3).

Quick start

Synchronous (blocking)

Suitable for startup systems or contexts where a small generation time is acceptable.

use bevy::prelude::*;
use bevy_symbios_texture::{
    bark::{BarkConfig, BarkGenerator},
    generator::{TextureGenerator, map_to_images},
};

fn setup(mut commands: Commands, mut images: ResMut<Assets<Image>>) {
    let map = BarkGenerator::new(BarkConfig::default())
        .generate(512, 512)
        .expect("valid dimensions");

    let handles = map_to_images(map, &mut images);

    commands.spawn(Sprite {
        image: handles.albedo,
        ..default()
    });
}

Asynchronous (non-blocking, recommended)

Offloads pixel math to a private, bounded rayon thread pool (default 4 concurrent tasks; configurable via AsyncTextureConfig::pool_threads) so the main thread is never stalled. On WASM, falls back to Bevy's AsyncComputeTaskPool.

Within each texture, rows are generated in parallel: async tasks work-steal across the private pool (so pool_threads remains the CPU cap), while direct synchronous generate() calls parallelise on the caller's rayon pool — usually the global one, using every core. Output is byte-identical to serial generation.

If rayon::ThreadPoolBuilder::build() fails at first init (out-of-memory, OS thread limit, sandboxed environments) the library logs a warning and falls back to running each generator inline on the calling thread. Texture generation still works — slower and blocking the spawning thread — instead of panicking.

use bevy::prelude::*;
use bevy_symbios_texture::{
    AsyncTextureConfig, SymbiosTexturePlugin,
    async_gen::{PendingTexture, TextureReady},
    bark::BarkConfig,
};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        // Default pool: 4 concurrent tasks.
        .add_plugins(SymbiosTexturePlugin::default())
        // Or explicitly: 0 = auto (available_parallelism() / 2),
        // any positive value = exact thread count.
        // .add_plugins(SymbiosTexturePlugin {
        //     config: AsyncTextureConfig { pool_threads: 0 },
        // })
        .add_systems(Startup, spawn_task)
        .add_systems(Update, on_ready)
        .run();
}

fn spawn_task(mut commands: Commands) {
    commands.spawn(PendingTexture::bark(BarkConfig::default(), 1024, 1024));
}

fn on_ready(
    mut commands: Commands,
    ready: Query<(Entity, &TextureReady)>,
) {
    for (entity, tex) in &ready {
        commands.entity(entity).despawn();
        // tex.0.albedo / tex.0.normal / tex.0.roughness are Handle<Image>
    }
}

Dropping a PendingTexture entity before generation completes sets a cancellation flag; tasks that have not yet started exit without doing any work.

One-shot procedural materials

build_procedural_material_async collapses the StandardMaterial-allocate + PendingTexture-spawn + post-completion-patch dance into a single call. Define a MaterialSettings (PBR fields + a TextureConfig enum that selects the generator), call the helper, and use the returned handle immediately:

use bevy_symbios_texture::{
    MaterialSettings, TextureConfig, build_procedural_material_async,
    brick::BrickConfig,
};

fn spawn_brick_wall(
    mut commands: Commands,
    mut materials: ResMut<Assets<StandardMaterial>>,
    mut images: ResMut<Assets<Image>>,
    mut meshes: ResMut<Assets<Mesh>>,
) {
    let settings = MaterialSettings {
        base_color: [0.65, 0.30, 0.20],
        roughness: 0.85,
        texture: TextureConfig::Brick(BrickConfig::default()),
        ..MaterialSettings::default()
    };
    let material = build_procedural_material_async(
        &mut commands, &mut materials, &mut images, /*cache=*/ None,
        &settings, 512, 512,
    );
    commands.spawn((Mesh3d(meshes.add(Cuboid::default())), MeshMaterial3d(material)));
}

Texture cache

To avoid regenerating the same (generator, config, size) tuple across spawns, insert a TextureCache resource:

use bevy_symbios_texture::{DEFAULT_MEMORY_CACHE_ENTRIES, TextureCache};

app.insert_resource(TextureCache::memory(DEFAULT_MEMORY_CACHE_ENTRIES));
// or, for cross-process persistence:
// app.insert_resource(TextureCache::file("./.texture-cache", manifest_version)?);

Cache hits return previously-uploaded Handle<Image> clones synchronously and skip the rayon dispatch entirely. Cache keys derive from a fingerprint of the config struct, so any field change automatically invalidates the prior entry. manifest_version is mixed into every FileStore on-disk key, so bumping it rotates the persisted cache without deleting the directory — use it when generator internals change without a config-field change.

The library ships two built-in stores — MemoryStore (bounded, FIFO eviction, default) and FileStore (binary blobs on disk) — and exposes the TextureCacheStore trait for custom backends. FileStore persists the raw pixel blobs as generation completes and re-uploads them (regenerating mipmaps) on the first hit after a restart, so warm caches survive across processes.

Animated parameter curves

Time-varying weathering, age, and seasonal change are first-class via the AnimatedProceduralMaterial component plus a small set of ParameterCurve impls (Linear, EaseInOut, Stepped, ScriptedFn). Attach the component to a material entity and the tick_animated_procedural_materials system regenerates the texture whenever the curve's output changes:

use bevy_symbios_texture::{
    AnimatedProceduralMaterial, Linear, ParameterCurve, TextureConfig,
    metal::MetalConfig,
};

let rust = Linear { from: 0.0_f64, to: 1.0, duration: 10.0 };
let base = MetalConfig::default();
let animator = AnimatedProceduralMaterial::new(material, 512, 512, move |t| {
    TextureConfig::Metal(MetalConfig {
        rust_level: rust.eval(t),
        ..base.clone()
    })
})
.with_min_regen_interval(0.25); // throttle regeneration to 4 Hz

Two thresholds gate regeneration: a wall-clock cooldown (min_regen_interval, default 0.25 s) and fingerprint equality. Stepped or plateaued curves cost essentially nothing once the value stops changing.

For sub-second smoothness across the steady-state pixels, drive a fragment-shader uniform on the material — generator output is RGBA8 and is the wrong knob for sub-frame interpolation.

Compute-shader fast path

A wgpu compute-shader port of the hottest generators (FBM-based bark, brick, marble) is on the roadmap but not implemented. The remaining work — porting toroidal noise to WGSL with bit-equivalent CPU/GPU output, dispatch + readback plumbing, a feature flag that swaps in the GPU path when available, and a benchmark suite — is multi-week and was deliberately deferred so this release could ship the asynchronous + cached + animated path on a known-good CPU baseline.

If you need realtime texture editing at 60 FPS today, the alternatives are:

• Rely on the row-parallel CPU path: on a modern many-core desktop the heaviest generator (bark) renders a 512² map in ~20 ms, so interactive editing at moderate resolutions is already feasible without the GPU port.
• Bake the texture once via the regular CPU path and animate a material uniform (rust mask weight, colour blend, etc.) in the fragment shader.
• Use AnimatedProceduralMaterial with a coarse min_regen_interval and accept the staircase update cadence.

Generators

Surface textures (tileable)

All tileable generators produce three seamlessly-repeating maps:

Map	Format	Contents
albedo	Rgba8UnormSrgb	Base colour
normal	Rgba8Unorm	Tangent-space normal (R=X, G=Y, B=Z)
roughness	Rgba8Unorm	ORM: R=Occlusion, G=Roughness, B=Metallic
emissive	Rgba8UnormSrgb	Optional emissive / glow map

Upload with map_to_images to get repeat-wrapping samplers. When a generator produces an emissive map the polling systems assign it to StandardMaterial::emissive_texture; Bevy multiplies it by the material's emissive colour factor, which the material flow auto-defaults to white when MaterialSettings::emission_color / emission_strength are left unset, so the glow shows out of the box. Set them only to tint or brighten beyond the map's encoded values.

Bark

Domain-warped FBM noise with an anisotropic Worley plate layer for rhytidome furrows, producing fibrous, streaked bark grain.

use bevy_symbios_texture::bark::BarkConfig;

let config = BarkConfig {
    seed: 42,
    scale: 2.0,             // spatial frequency of the pattern
    octaves: 6,             // FBM detail levels (base layer)
    warp_octaves: 3,        // FBM detail for the warp layers (3 is plenty)
    warp_u: 0.15,           // lateral warp strength
    warp_v: 0.55,           // vertical (fibre) warp strength
    color_light: [0.45, 0.28, 0.14],  // ridge colour, linear RGB
    color_dark:  [0.09, 0.05, 0.03],  // groove colour, linear RGB
    normal_strength: 3.0,
    furrow_multiplier: 0.78, // blend weight of the Worley plate layer [0, 1]
    furrow_scale_u: 2.0,     // horizontal cell frequency (higher = narrower plates)
    furrow_scale_v: 0.48,    // vertical cell frequency (lower = longer plates)
    furrow_shape: 2.0,       // plate height power (<1 widens plateau, sharpens cracks)
};

Rock

Ridged multifractal noise for cracked, faceted stone.

use bevy_symbios_texture::rock::RockConfig;

let config = RockConfig {
    seed: 7,
    scale: 3.0,
    octaves: 8,
    attenuation: 2.0,    // ridge sharpness (higher = sharper)
    color_light: [0.37, 0.42, 0.36],
    color_dark:  [0.22, 0.20, 0.18],
    normal_strength: 4.0,
};

Ground

Blended dual-scale FBM for organic soil / dirt surfaces.

use bevy_symbios_texture::ground::GroundConfig;

let config = GroundConfig {
    seed: 13,
    macro_scale: 2.0,    // large soil-patch scale
    macro_octaves: 5,
    micro_scale: 8.0,    // fine grain scale
    micro_octaves: 4,
    micro_weight: 0.35,  // 0.0 = all macro, 1.0 = all micro
    color_dry:   [0.52, 0.40, 0.26],
    color_moist: [0.28, 0.20, 0.12],
    normal_strength: 2.0,
};

Brick

Grid-based SDF with per-cell colour hashing and configurable mortar/bonding pattern.

use bevy_symbios_texture::brick::BrickConfig;

let config = BrickConfig {
    seed: 42,
    scale: 4.0,          // number of brick rows across the tile
    row_offset: 0.5,     // 0.0 = stack bond, 0.5 = running bond, 0.333 = third bond
    aspect_ratio: 2.0,   // brick width-to-height ratio
    mortar_size: 0.05,   // mortar gap as a fraction of cell height [0, 0.4]
    bevel: 0.5,          // corner bevel radius as a fraction of mortar_size [0, 1]
    cell_variance: 0.15, // per-brick colour jitter [0, 1]
    roughness: 0.5,      // surface pitting noise intensity [0, 1]
    color_brick:  [0.56, 0.28, 0.18],
    color_mortar: [0.76, 0.73, 0.67],
    normal_strength: 4.0,
};

Plank

Anisotropic grain FBM with domain warp, Worley knots, and horizontal joint gaps. Each plank row has an independent de-correlated grain phase.

use bevy_symbios_texture::plank::PlankConfig;

let config = PlankConfig {
    seed: 42,
    plank_count: 5.0,     // number of planks visible vertically
    grain_scale: 12.0,    // controls how fine the grain lines are
    joint_width: 0.06,    // gap between planks as a fraction of plank height [0, 0.3]
    stagger: 0.5,         // horizontal stagger of end-joints [0, 1]
    knot_density: 0.25,   // fraction of cells that contain a Worley knot [0, 1]
    grain_warp: 0.35,     // domain-warp strength that bends grain lines [0, 1]
    color_wood_light: [0.72, 0.52, 0.30],
    color_wood_dark:  [0.42, 0.26, 0.12],
    normal_strength: 2.5,
};

Concrete

Smooth FBM surface relief with optional horizontal formwork-panel seams and scattered air-pocket pits.

use bevy_symbios_texture::concrete::ConcreteConfig;

let config = ConcreteConfig {
    seed: 17,
    scale: 5.0,
    octaves: 5,
    roughness: 0.45,          // overall bump amplitude [0, 1]
    formwork_lines: 4.0,      // number of horizontal panel seams [0 = none]
    formwork_depth: 0.12,     // groove depth of seams [0, 1]
    pit_density: 0.08,        // air-pocket density [0, 0.5]
    color_base: [0.55, 0.54, 0.52],
    color_pit:  [0.35, 0.34, 0.33],
    normal_strength: 2.5,
};

Metal

Brushed metal (anisotropic FBM scratches), standing-seam roof panels, hand-hammered dimples, or diamond tread plate — all with optional rust-patch weathering. For Hammered and DiamondPlate, scale sets the dimple / stud count across the tile.

use bevy_symbios_texture::metal::{MetalConfig, MetalStyle};

let config = MetalConfig {
    seed: 31,
    style: MetalStyle::Brushed, // or StandingSeam, Hammered, DiamondPlate
    scale: 6.0,
    seam_count: 6.0,      // StandingSeam: number of ridges across the tile
    seam_sharpness: 2.5,  // StandingSeam: 0.5 = sinusoidal, 4.0 = sharp
    brush_stretch: 8.0,   // Brushed: anisotropy (higher = longer horizontal scratches)
    roughness: 0.25,      // micro-roughness amplitude [0, 1]
    metallic: 0.85,       // metallic value for clean areas [0, 1]
    rust_level: 0.15,     // rust-patch coverage [0 = none, 1 = heavy]
    color_metal: [0.42, 0.44, 0.47],
    color_rust:  [0.42, 0.24, 0.12],
    normal_strength: 3.0,
};

Shingle

Overlapping roof shingles or tiles with configurable profile shape, moss growth, and staggered bonding.

use bevy_symbios_texture::shingle::ShingleConfig;

let config = ShingleConfig {
    seed: 42,
    scale: 5.0,           // number of shingle rows across the tile
    shape_profile: 0.5,   // 0.0 = square/flat, 1.0 = scalloped (half-circle cut)
    overlap: 0.45,        // fraction of each shingle hidden under the row above [0, 0.8]
    stagger: 0.5,         // horizontal stagger of alternate rows [0, 1]
    moss_level: 0.18,     // moss/algae growth on the lower exposed edge [0, 1]
    color_tile:  [0.40, 0.25, 0.18],
    color_grout: [0.18, 0.14, 0.12],
    normal_strength: 5.0,
};

Pavers

Square or flat-top hexagonal paving stones with grout joints, per-stone colour variance, and a rounded-box SDF bevel.

use bevy_symbios_texture::pavers::{PaversConfig, PaversLayout};

let config = PaversConfig {
    seed: 23,
    scale: 5.0,           // roughly the number of pavers across the tile
    aspect_ratio: 1.0,    // width-to-height ratio for Square layout (ignored for Hexagonal)
    grout_width: 0.08,    // grout gap as a fraction of stone size [0, 0.4]
    bevel: 0.5,           // corner bevel radius as a fraction of grout half-width [0, 1]
    cell_variance: 0.10,  // per-paver colour jitter [0, 1]
    roughness: 0.30,      // surface FBM micro-detail amplitude [0, 1]
    color_stone: [0.48, 0.44, 0.40],
    color_grout: [0.28, 0.27, 0.26],
    layout: PaversLayout::Square, // or PaversLayout::Hexagonal
    normal_strength: 3.5,
};

Stucco

High-frequency FBM bumps over a flat matte base — typical of sand-float or pebble-dash exterior render. Entirely matte with zero metallic response.

use bevy_symbios_texture::stucco::StuccoConfig;

let config = StuccoConfig {
    seed: 13,
    scale: 8.0,       // bump density (higher = finer texture)
    octaves: 6,
    roughness: 0.35,  // bump amplitude / surface relief depth [0, 1]
    color_base:   [0.92, 0.89, 0.84],
    color_shadow: [0.72, 0.70, 0.66],
    normal_strength: 2.0,
};

Ashlar

Irregular cut-stone masonry with per-block colour variance, chisel-edge darkening, and configurable mortar joints.

use bevy_symbios_texture::ashlar::AshlarConfig;

let config = AshlarConfig {
    seed: 13,
    rows: 4,              // number of stone courses (rows) [2, 8]
    cols: 4,              // base blocks per course [2, 6]; each row may vary ±1
    mortar_size: 0.04,    // mortar gap as a fraction of average cell size [0, 0.15]
    bevel: 0.4,           // corner bevel as fraction of mortar_size [0, 1]
    cell_variance: 0.18,  // per-block colour jitter [0, 1]
    chisel_depth: 0.4,    // darkening near each block border [0, 1]
    roughness: 0.45,      // FBM face micro-detail amplitude [0, 1]
    color_stone: [0.52, 0.50, 0.47],
    color_mortar: [0.72, 0.70, 0.65],
    normal_strength: 4.5,
};

Cobblestone

Voronoi cell decomposition producing domed, irregularly shaped stones separated by mud/dirt gaps.

use bevy_symbios_texture::cobblestone::CobblestoneConfig;

let config = CobblestoneConfig {
    seed: 7,
    scale: 6.0,           // approximate number of stones across the tile [3, 12]
    gap_width: 0.12,      // mud gap threshold as fraction of stone spacing [0.02, 0.25]
    cell_variance: 0.20,  // per-stone colour jitter [0, 1]
    roundness: 1.2,       // dome profile power [0.5, 2.0]; higher = flatter tops
    color_stone: [0.46, 0.43, 0.40],
    color_mud: [0.22, 0.18, 0.14],
    normal_strength: 5.0,
};

Marble

Domain-warped FBM noise passed through a sinusoidal vein function for polished marble or granite with thin dark veins on a light background.

use bevy_symbios_texture::marble::MarbleConfig;

let config = MarbleConfig {
    seed: 55,
    scale: 3.0,            // overall pattern scale [1, 8]
    octaves: 5,            // FBM octaves for the base layer [3, 8]
    warp_octaves: 3,       // FBM octaves for the warp layers [1, 6]
    warp_strength: 0.6,    // how much the veins meander [0, 1.5]
    vein_frequency: 3.0,   // period of sin() on warped FBM [1, 8]
    vein_sharpness: 2.0,   // exponent narrowing the veins [0.5, 6]
    roughness: 0.08,       // surface roughness [0, 0.3]; low for polished marble
    color_base: [0.92, 0.90, 0.87],
    color_vein: [0.42, 0.38, 0.34],
    normal_strength: 1.5,
};

Thatch

Dense fibrous roofing material with anisotropic straw fibres, lateral domain-warp wiggle, and layered bundle overlap shadows.

use bevy_symbios_texture::thatch::ThatchConfig;

let config = ThatchConfig {
    seed: 19,
    density: 12.0,         // fibre frequency along U [4, 24]
    anisotropy: 8.0,       // V frequency = density / anisotropy [4, 16]
    warp_strength: 0.15,   // lateral domain-warp wiggle [0, 0.5]
    layer_count: 8.0,      // straw-bundle overlap layers along V [4, 16]
    layer_shadow: 0.55,    // shadow depth at bundle bottom [0, 1]
    color_straw: [0.62, 0.54, 0.28],
    color_shadow: [0.22, 0.17, 0.09],
    normal_strength: 3.5,
};

Corrugated

Corrugated metal sheets with sine-wave ridges and valley-concentrated rust weathering.

use bevy_symbios_texture::corrugated::CorrugatedConfig;

let config = CorrugatedConfig {
    seed: 31,
    ridges: 8.0,           // number of corrugation ridges across U [3, 20]
    ridge_depth: 1.0,      // ridge profile amplitude [0.5, 2.0]
    roughness: 0.35,       // base surface roughness [0, 1]
    rust_level: 0.25,      // rust accumulation in valleys [0, 1]
    metallic: 0.85,        // metallic value [0, 1]
    color_metal: [0.72, 0.74, 0.76],
    color_rust: [0.55, 0.30, 0.12],
    normal_strength: 4.0,
};

Asphalt

Three-band toroidal FBM (macro staining, micro roughness, aggregate flecks) for tarmac / asphalt with exposed stone chips.

use bevy_symbios_texture::asphalt::AsphaltConfig;

let config = AsphaltConfig {
    seed: 88,
    scale: 4.0,              // base noise scale [2, 12]
    aggregate_density: 0.22, // exposed stone chip density [0.05, 0.4]
    aggregate_scale: 16.0,   // fleck noise frequency [8, 32]
    roughness: 0.90,         // overall surface roughness [0.7, 1.0]
    stain_level: 0.25,       // macro stain / oil variation [0, 1]
    color_base: [0.06, 0.06, 0.07],
    color_aggregate: [0.35, 0.33, 0.30],
    normal_strength: 2.5,
};

Sand

Wind-rippled sand: a directional sine ridge field phase-warped by FBM so crests meander and merge, plus grain micro-relief and thresholded bright flecks (exposed sparkling grains read as local smooth spots in the ORM).

use bevy_symbios_texture::sand::SandConfig;

let config = SandConfig {
    seed: 91,
    ripple_count: 10.0,    // crests across the tile [4, 24]
    ripple_warp: 0.6,      // crest meander strength [0, 1.5]
    grain_density: 0.12,   // bright-fleck density [0, 0.5]
    grain_scale: 24.0,     // grain noise frequency [8, 48]
    color_crest: [0.86, 0.74, 0.52],
    color_trough: [0.62, 0.50, 0.34],
    normal_strength: 2.5,
};

Snow

Wind-drifted snow: soft FBM relief with a cool shadow tint in the troughs and thresholded sparkle flecks — crystals that brighten the albedo and drop ORM roughness to near zero for specular glints.

use bevy_symbios_texture::snow::SnowConfig;

let config = SnowConfig {
    seed: 73,
    drift_scale: 2.5,      // drift relief scale [1, 6]
    drift_octaves: 4,      // FBM octaves [2, 6]
    sparkle_density: 0.08, // glinting-crystal density [0, 0.5]
    crust_roughness: 0.85, // base crust roughness [0.5, 1]
    color_snow: [0.93, 0.95, 0.99],
    color_shadow: [0.62, 0.70, 0.86],  // cool trough tint
    normal_strength: 1.8,
};

Ice

Polished lake ice: a near-mirror pale-blue base crossed by thin recessed crack veins (sinusoidal bands over FBM contours), with frost patches that whiten the colour and raise roughness toward matte.

use bevy_symbios_texture::ice::IceConfig;

let config = IceConfig {
    seed: 117,
    scale: 3.0,            // pattern scale [1, 8]
    crack_density: 4.0,    // vein frequency [1, 8]
    vein_sharpness: 7.0,   // crack narrowing exponent [2, 12]
    frost_level: 0.25,     // matte frost coverage [0, 1]
    color_ice: [0.72, 0.84, 0.94],
    color_crack: [0.30, 0.44, 0.62],
    normal_strength: 1.5,
};

Wainscoting

Wood-panel wainscoting with recessed panel faces, rail/stile framing, and anisotropic grain FBM with domain warp.

use bevy_symbios_texture::wainscoting::WainscotingConfig;

let config = WainscotingConfig {
    seed: 37,
    panels_x: 1,           // horizontal panel divisions [1, 4]
    panels_y: 2,           // vertical panel divisions [1, 4]
    frame_width: 0.20,     // rail/stile width as fraction of cell [0.05, 0.35]
    panel_inset: 0.06,     // panel recess depth [0, 0.15]
    grain_scale: 10.0,     // wood grain spatial frequency [4, 24]
    grain_warp: 0.30,      // grain domain-warp strength [0, 0.8]
    color_wood_light: [0.65, 0.44, 0.20],
    color_wood_dark: [0.28, 0.16, 0.07],
    normal_strength: 4.0,
};

Fabric

Plain-weave cloth: perpendicular warp/weft threads as half-cylinder profiles, over/under crossing relief, fibre fuzz, and yarn-mottle tinting. Match the two colours for solid cloth or contrast them for two-tone weaves.

use bevy_symbios_texture::fabric::FabricConfig;

let config = FabricConfig {
    seed: 29,
    thread_count: 24.0,    // threads per tile edge [8, 64]
    thread_width: 0.85,    // thread width as cell fraction [0.3, 0.98]
    weave_contrast: 0.6,   // over/under relief depth [0, 1]
    fuzz: 0.35,            // fibre fuzz strength [0, 1]
    color_warp: [0.55, 0.36, 0.24],  // vertical threads
    color_weft: [0.62, 0.44, 0.30],  // horizontal threads
    normal_strength: 3.0,
};

Encaustic

Decorative ceramic tiles with glazed surfaces in configurable geometric patterns (checkerboard, octagon, diamond).

use bevy_symbios_texture::encaustic::{EncausticConfig, EncausticPattern};

let config = EncausticConfig {
    seed: 47,
    scale: 5.0,            // tile cells across the texture [2, 10]
    pattern: EncausticPattern::Octagon, // or Checkerboard, Diamond
    grout_width: 0.06,     // grout line width as fraction of cell [0.02, 0.15]
    glaze_roughness: 0.04, // glaze surface waviness [0, 0.1]
    color_a: [0.72, 0.38, 0.22],  // primary tile colour
    color_b: [0.22, 0.35, 0.65],  // secondary tile colour
    color_grout: [0.82, 0.80, 0.75],
    normal_strength: 3.0,
};

Alpha-masked cards

Card generators produce an RGBA8 texture where albedo.alpha encodes the silhouette (0 = fully transparent, 255 = fully opaque). Upload with map_to_images_card so the sampler does not tile and the alpha silhouette does not bleed at edges.

Leaf

A discrete leaf silhouette with procedural venation: midrib, secondary veins, a Perlin venule (tertiary vein) network, Worley capillaries, and optional lobed margins.

use bevy_symbios_texture::leaf::LeafConfig;

let config = LeafConfig {
    seed: 0,
    color_base: [0.12, 0.19, 0.11],  // interior colour, linear RGB
    color_edge: [0.35, 0.28, 0.05],  // edge / autumn tinge
    serration_strength: 0.12,         // tooth depth [0, ~0.35]
    vein_angle: 2.5,                  // secondary vein acuteness
    micro_detail: 0.3,                // Worley capillary blend weight
    normal_strength: 1.0,
    lobe_count: 4.0,                  // 0 = smooth; >0 = lobed margins
    lobe_depth: 0.23,
    lobe_sharpness: 1.0,
    petiole_length: 0.12,             // fraction of V reserved for the stalk
    petiole_width: 0.022,
    midrib_width: 0.12,
    vein_count: 6.0,
    venule_strength: 0.50,
};

LeafSampler can also be used directly for per-pixel evaluation without going through the full generator (e.g., inside a twig compositor):

use bevy_symbios_texture::leaf::{LeafConfig, LeafSampler};

let sampler = LeafSampler::new(LeafConfig::default());
if let Some(sample) = sampler.sample(0.5, 0.4) {
    // sample.height, sample.color, sample.roughness
}

Twig

A composite foliage card: a tapered, organically curved stem carrying multiple leaf cards. Supports two phyllotaxis modes:

• Monopodial (sympodial: false) — opposite leaf pairs on a straight axis with a terminal leaf at the apex.
• Sympodial (sympodial: true) — alternate leaves on a zigzag axis, with a terminal leaf at the apex.

use std::f64::consts::FRAC_PI_2;
use bevy_symbios_texture::twig::TwigConfig;
use bevy_symbios_texture::leaf::LeafConfig;

let config = TwigConfig {
    leaf: LeafConfig::default(),
    stem_color: [0.18, 0.08, 0.06],
    stem_half_width: 0.021,
    leaf_pairs: 4,
    leaf_angle: FRAC_PI_2 - 0.35,  // ~70° from stem axis
    leaf_scale: 0.38,
    stem_curve: 0.015,
    sympodial: true,
};

Window

An SDF-based window card with configurable frame, mullions/muntins, and per-pane glass. The alpha channel is transparent outside the frame and semi-transparent over glass panes.

use bevy_symbios_texture::window::WindowConfig;

let config = WindowConfig {
    seed: 42,
    frame_width: 0.08,       // frame width as a fraction of the card [0, 0.4]
    panes_x: 2,              // number of panes horizontally
    panes_y: 3,              // number of panes vertically
    mullion_thickness: 0.025, // mullion/muntin thickness as a fraction of the glass area
    corner_radius: 0.02,     // inner glass-opening corner rounding [0, 0.4]
    glass_opacity: 0.30,     // glass alpha [0 = clear, 1 = frosted/opaque]
    grime_level: 0.15,       // grime/dirt noise on glass [0, 1]
    color_frame: [0.85, 0.82, 0.78],
    normal_strength: 3.0,
};

Stained Glass

Voronoi-based stained-glass panel with lead came borders and semi-transparent coloured glass panes. Glass alpha is 180 (semi-transparent); lead is 255 (fully opaque).

use bevy_symbios_texture::stained_glass::StainedGlassConfig;

let config = StainedGlassConfig {
    seed: 63,
    cell_count: 12,        // approximate number of glass cells [5, 25]
    lead_width: 0.05,      // lead came width as fraction of cell spacing [0.02, 0.12]
    saturation: 0.85,      // glass colour saturation [0.5, 1.0]
    glass_roughness: 0.06, // glass surface waviness [0, 0.15]
    grime_level: 0.12,     // grime/dirt accumulation on glass [0, 0.5]
    normal_strength: 2.5,
};

Iron Grille

Rectangular or round-bar iron grille / portcullis with configurable bar count and joint-concentrated rust weathering.

use bevy_symbios_texture::iron_grille::IronGrilleConfig;

let config = IronGrilleConfig {
    seed: 71,
    bars_x: 4,             // vertical bars [2, 10]
    bars_y: 6,             // horizontal bars [2, 10]
    bar_width: 0.04,       // bar half-width as fraction of card [0.02, 0.20]
    round_bars: true,      // true = cylindrical cross-section, false = rectangular
    rust_level: 0.30,      // rust at joints [0, 1]
    color_iron: [0.14, 0.13, 0.13],
    color_rust: [0.42, 0.22, 0.08],
    normal_strength: 3.5,
};

Chain-Link

A woven diamond wire mesh: two cylindrical wire families at ±45° with over/under crossing relief and rust pooling at the joints. Transparent between the wires.

use bevy_symbios_texture::chain_link::ChainLinkConfig;

let config = ChainLinkConfig {
    seed: 83,
    cell_count: 8.0,       // diamond cells across the card [4, 16]
    wire_radius: 0.07,     // wire radius in lattice units [0.02, 0.2]
    weave_depth: 0.6,      // over/under relief [0, 1]
    rust_level: 0.2,       // crossing rust [0, 1]
    color_wire: [0.62, 0.64, 0.66],
    color_rust: [0.45, 0.24, 0.10],
    normal_strength: 3.0,
};

Log End

The sawn end of a log: irregular round silhouette, FBM-wobbled concentric growth rings, optional radial drying cracks, and a streaked bark rim. Completes the wood set alongside bark and plank.

use bevy_symbios_texture::log_end::LogEndConfig;

let config = LogEndConfig {
    seed: 7,
    ring_count: 14.0,      // growth rings [4, 30]
    ring_warp: 0.35,       // ring wobble [0, 1]
    ring_contrast: 1.8,    // latewood band sharpness [0.5, 4]
    crack_count: 5.0,      // radial drying cracks [0, 12]; 0 = none
    bark_width: 0.07,      // bark rim thickness [0.02, 0.2]
    color_early: [0.78, 0.62, 0.42],
    color_late: [0.48, 0.33, 0.18],
    color_bark: [0.30, 0.20, 0.12],
    normal_strength: 2.5,
};

Lava

Cooling lava: dark basalt plates from a toroidal Voronoi decomposition, separated by molten cracks that drive the emissive map — the glow colour ramps with crack depth and is written to StandardMaterial::emissive_texture. The material flow auto-enables a white emissive factor when a glow map is present, so lava glows out of the box; set emission_color / emission_strength only to tint or brighten it.

use bevy_symbios_texture::lava::LavaConfig;

let config = LavaConfig {
    seed: 666,
    plate_scale: 6.0,        // crust plates across the tile [3, 12]
    crack_width: 0.14,       // molten-crack width [0.02, 0.3]
    glow_falloff: 1.6,       // glow concentration exponent [0.5, 4]
    color_crust: [0.08, 0.07, 0.07],
    color_glow: [1.0, 0.45, 0.06],
    emissive_intensity: 1.0, // glow multiplier [0, 4]
    normal_strength: 4.0,
};

Sprite atlases

The sprite family produces small alpha-silhouette cards aimed at particle billboards. Unlike the foliage cards, each sprite generator can bake a variant_rows × variant_cols atlas in a single image: every cell renders the same config with a per-cell derived seed, so a particle system using random atlas frames gets per-particle shape variety from one texture bake. Atlas dimensions are clamped to 1..=16 per axis; 1 × 1 bakes a single sprite. Soft fractional alpha is encouraged — glows and mist fade out smoothly rather than cutting like foliage cards.

Shared scaffolding (the SpriteCell trait, the generate_atlas driver, and the deterministic CellRng parameter stream) lives in the sprite module. Upload with map_to_images_card; sprites never tile.

use bevy_symbios_texture::{
    generator::{TextureGenerator, map_to_images_card},
    spark::{SparkConfig, SparkGenerator},
};

let map = SparkGenerator::new(SparkConfig {
    variant_rows: 4,       // 4 × 4 atlas = 16 spark variants in one bake
    variant_cols: 4,
    ..SparkConfig::default()
})
.generate(512, 512)
.expect("valid dimensions");

let handles = map_to_images_card(map, &mut images);

Soft Disc

Radial-falloff disc with a solid core and tunable halo — the workhorse particle sprite: fireflies, embers, mist motes, bokeh glints, additive glows.

use bevy_symbios_texture::soft_disc::SoftDiscConfig;

let config = SoftDiscConfig {
    seed: 0,
    variant_rows: 1,       // atlas rows [1, 16]
    variant_cols: 1,       // atlas columns [1, 16]
    color_core: [1.0, 0.98, 0.9],   // centre colour, linear RGB
    color_halo: [1.0, 0.72, 0.25],  // outer halo colour
    core_radius: 0.15,     // fully-opaque core radius [0, 0.9]
    falloff: 2.5,          // halo falloff exponent [0.3, 8]; higher = tighter glow
    ellipticity: 0.0,      // max per-variant elongation [0, 0.6]; 0 = always round
    scale_jitter: 0.15,    // per-variant shrink fraction [0, 0.5]
    normal_strength: 1.0,
};

Spark

N-pointed streak burst: a bright core with radial arms fading toward their tips. Embers, glints, impact sparks, magic sparkles.

use bevy_symbios_texture::spark::SparkConfig;

let config = SparkConfig {
    seed: 0,
    variant_rows: 2,
    variant_cols: 2,
    points: 4,             // number of streak arms [2, 12]
    color_core: [1.0, 0.95, 0.8],
    color_tip: [1.0, 0.45, 0.1],
    core_radius: 0.12,     // solid central glow radius [0.02, 0.5]
    arm_sharpness: 3.0,    // angular tightness [0.5, 10]; higher = needle-thin
    falloff: 1.8,          // radial fade exponent along each arm [0.5, 6]
    length_jitter: 0.3,    // per-arm length jitter [0, 0.8]
    normal_strength: 1.0,
};

Snowflake

Dendritic flake with N-fold symmetry: a central plate, one main arm per sector, and paired side branches. Per-variant jitter is where the "no two snowflakes alike" character comes from.

use bevy_symbios_texture::snowflake::SnowflakeConfig;

let config = SnowflakeConfig {
    seed: 0,
    variant_rows: 2,
    variant_cols: 2,
    arms: 6,               // symmetry order [3, 8]; real snow is hexagonal
    color: [0.92, 0.96, 1.0],
    core_radius: 0.12,     // central plate radius [0, 0.4]
    arm_width: 0.045,      // main-arm half-width at the centre [0.01, 0.12]
    branch_pairs: 3,       // side-branch pairs per arm [0, 5]
    branch_angle: 1.05,    // branch angle, radians [0.3, 1.4]; ~60° is realistic
    branch_scale: 0.45,    // branch length vs remaining arm length [0.1, 1]
    softness: 0.02,        // anti-aliasing edge width [0.005, 0.08]
    normal_strength: 1.5,
};

Puff

Billowy blob of domain-warped fractal noise masked by a soft radial falloff. Dust motes, smoke, fog banks, sea mist.

use bevy_symbios_texture::puff::PuffConfig;

let config = PuffConfig {
    seed: 0,
    variant_rows: 2,
    variant_cols: 2,
    color_base: [0.86, 0.86, 0.9],    // lit colour
    color_shadow: [0.52, 0.52, 0.58], // noise-trough colour
    noise_scale: 3.0,      // noise frequency across a cell [1, 8]
    octaves: 4,            // fractal octave count [1, 8]
    warp: 0.45,            // domain-warp strength [0, 1.5]; billows the silhouette
    density: 0.9,          // overall alpha multiplier [0, 1]
    edge_falloff: 2.0,     // radial mask exponent [0.5, 6]; higher = rounder puff
    contrast: 1.3,         // noise remap exponent [0.5, 4]; higher = wispier
    normal_strength: 1.0,
};

Ring

Soft annulus with optional angular waviness: shockwaves, water-drop ripples, magic circles, halos.

use bevy_symbios_texture::ring::RingConfig;

let config = RingConfig {
    seed: 0,
    variant_rows: 1,
    variant_cols: 1,
    color: [0.85, 0.93, 1.0],
    radius: 0.6,           // centreline radius [0.1, 0.9]
    thickness: 0.12,       // annulus half-thickness [0.01, 0.5]
    falloff: 2.0,          // cross-section falloff exponent [0.5, 6]
    waviness: 0.0,         // angular radius modulation [0, 0.3]; 0 = perfect circle
    wave_count: 6,         // waviness lobes around the ring [2, 16]
    radius_jitter: 0.1,    // per-variant radius jitter [0, 0.4]
    normal_strength: 1.0,
};

Petal

A single flower petal: an obovate blade with a soft throat-to-edge gradient and an optional notched tip. Petal-fall particles, blossom decals, or — at 1 × 1 — a building block for procedural flowers.

use bevy_symbios_texture::petal::PetalConfig;

let config = PetalConfig {
    seed: 0,
    variant_rows: 2,
    variant_cols: 2,
    color_base: [0.98, 0.72, 0.82],   // main blade colour
    color_edge: [0.93, 0.5, 0.66],    // silhouette-edge colour
    color_throat: [0.99, 0.88, 0.55], // attachment-point (nectar guide) tint
    length: 0.92,          // petal length as fraction of the cell [0.4, 1]
    width: 0.6,            // max blade width [0.15, 0.95]
    peak: 0.65,            // position of max width from the throat [0.3, 0.9]
    tip_notch: 0.08,       // tip notch radius [0, 0.25]; 0 = smooth tip
    curl: 0.4,             // lateral shading strength [0, 1]; fakes curl
    asymmetry: 0.15,       // max per-variant axis skew [0, 0.4]
    normal_strength: 1.5,
};

Shard

Irregular rock-chip / debris-flake silhouette: a jittered polygon with a darkened rim and noise-grained interior. Impact debris, crumbling masonry, shattered ice, kicked-up gravel.

use bevy_symbios_texture::shard::ShardConfig;

let config = ShardConfig {
    seed: 0,
    variant_rows: 2,
    variant_cols: 2,
    color_base: [0.46, 0.43, 0.4],  // interior colour
    color_edge: [0.24, 0.22, 0.21], // fractured-rim colour
    sides: 5,              // polygon vertex count [3, 9]
    irregularity: 0.45,    // vertex jitter [0, 0.9]; 0 = regular polygon
    edge_band: 0.18,       // darkened-rim width as fraction of radius [0.02, 0.5]
    grain: 0.35,           // interior fractal-grain strength [0, 1]
    normal_strength: 2.5,
};

Flame

A single tongue of fire: a teardrop envelope displaced by fractal turbulence that grows toward the tip, with a core→mid→tip colour ramp. Per-variant cells jitter lean, elongation, and turbulence phase, so random atlas frames read as flicker. Pairs well with additive blending.

use bevy_symbios_texture::flame::FlameConfig;

let config = FlameConfig {
    seed: 0,
    variant_rows: 2,       // atlas rows [1, 16]
    variant_cols: 2,       // atlas columns [1, 16]
    elongation: 1.6,       // vertical stretch [1, 3]; taller = lazier wisp
    turbulence: 0.55,      // tip displacement strength [0, 1.5]
    lean_jitter: 0.25,     // max per-variant sideways lean [0, 0.5]
    falloff: 1.6,          // envelope fade exponent [0.5, 4]
    color_core: [1.0, 0.97, 0.78],  // hot base
    color_mid: [1.0, 0.55, 0.10],
    color_tip: [0.85, 0.16, 0.02],  // cool fringe
    normal_strength: 1.0,
};

Flower

A radially composed blossom: petal blades (the petal sampler re-aimed outward) under a domed, stamen-dotted centre disc — the sprite counterpart of how twig composites leaves. Every petal in every variant draws its own jitter stream.

use bevy_symbios_texture::flower::FlowerConfig;
use bevy_symbios_texture::petal::PetalConfig;

let config = FlowerConfig {
    seed: 0,
    variant_rows: 2,       // atlas rows [1, 16]
    variant_cols: 2,       // atlas columns [1, 16]
    petal: PetalConfig::default(), // shared blade appearance
    petal_count: 6,        // blades [4, 12]
    center_radius: 0.14,   // centre disc radius [0.05, 0.3]
    center_color: [0.96, 0.78, 0.25],
    dot_density: 0.5,      // stamen dots [0, 1]
    normal_strength: 1.5,
};

Leaf Sprite

The atlas counterpart of the single-leaf foliage card: every cell bakes a per-cell-seeded leaf variant with bounded jitter on serration, lobes, vein count, and a green-preserving colour tint. Falling-foliage particle systems get per-particle leaf variety from one bake.

use bevy_symbios_texture::leaf::LeafConfig;
use bevy_symbios_texture::leaf_sprite::LeafSpriteConfig;

let config = LeafSpriteConfig {
    seed: 0,
    variant_rows: 2,       // atlas rows [1, 16]
    variant_cols: 2,       // atlas columns [1, 16]
    leaf: LeafConfig::default(), // base leaf appearance for every cell
    shape_jitter: 0.5,     // silhouette jitter [0, 1]
    tint_jitter: 0.25,     // colour tint jitter [0, 1]
};

Evolutionary parameter search (genetics)

All config types implement symbios_genetics::Genotype, making them compatible with the evolutionary algorithms in the symbios-genetics crate (SimpleGA, Nsga2, MapElites).

Each field is independently perturbed during mutation and drawn uniformly from one of two parents during crossover:

use symbios_genetics::Genotype;
use bevy_symbios_texture::bark::BarkConfig;
use rand::SeedableRng;

let mut config = BarkConfig::default();
let mut rng = rand::rngs::StdRng::seed_from_u64(42);
config.mutate(&mut rng, 0.3);  // perturb each field with 30 % probability

let parent_b = BarkConfig { seed: 99, ..BarkConfig::default() };
let child = config.crossover(&parent_b, &mut rng);

The texture_viewer example uses this to mutate any displayed material when you click Mutate.

The Genotype implementations and the egui editor widgets are generated by declarative macros (impl_genotype! / impl_config_editor!) rather than hand-written per-config boilerplate. Each macro invocation declares the config struct, field kinds (seed, f64, colour, enum, etc.), and optional post-hooks for tiling-invariant fixups, keeping the per-config call site small while covering all 40 config types.

TextureConfig itself also implements Genotype (mutation delegates to the wrapped config; crossover recombines like variants field-wise) and exposes registry-derived helpers — all_defaults() for dropdowns and benches, module_name() for stable identifiers, generate_sync() for synchronous dispatch, and (behind the egui feature) ui::texture_config_editor for variant-generic parameter editing. The texture_viewer example and the criterion bench suite are built entirely on these, so they extend automatically when a generator is added to the registry.

Architecture

TextureGenerator (trait)
    │
    │  Tileable surface textures
    ├── BarkGenerator       ─── ToroidalNoise (domain-warped FBM + Worley plates)
    ├── RockGenerator       ─── ToroidalNoise (RidgedMulti)
    ├── GroundGenerator     ─── ToroidalNoise × 2 (dual-scale FBM)
    ├── BrickGenerator      ─── ToroidalNoise FBM + rounded-box SDF grid
    ├── PlankGenerator      ─── ToroidalNoise FBM + Worley knots (anisotropic)
    ├── ConcreteGenerator   ─── ToroidalNoise FBM + cosine formwork + pit FBM
    ├── MetalGenerator      ─── ToroidalNoise FBM (brushed/standing-seam) + rust FBM
    ├── ShingleGenerator    ─── ToroidalNoise FBM + sawtooth overlap ramp
    ├── PaversGenerator     ─── ToroidalNoise FBM + square/hex SDF grid
    ├── StuccoGenerator     ─── ToroidalNoise FBM (high-frequency, matte)
    ├── AshlarGenerator     ─── ToroidalNoise FBM + irregular SDF grid + chisel edge
    ├── CobblestoneGenerator─── toroidal Voronoi (domed F1, mud gap at F2−F1)
    ├── MarbleGenerator     ─── ToroidalNoise FBM (domain-warped sinusoidal veins)
    ├── ThatchGenerator     ─── ToroidalNoise FBM (anisotropic fibre + sawtooth layers)
    ├── CorrugatedGenerator ─── sine-wave ridge profile + rust FBM
    ├── AsphaltGenerator    ─── ToroidalNoise FBM × 3 (macro/micro/aggregate)
    ├── WainscotingGenerator─── ToroidalNoise grain FBM + panel margin SDF
    ├── EncausticGenerator  ─── ToroidalNoise glaze FBM + geometric pattern SDF
    ├── FabricGenerator     ─── perpendicular thread lattice + over/under weave
    ├── SandGenerator       ─── warped sine ripples + grain flecks
    ├── SnowGenerator       ─── FBM drift relief + sparkle flecks
    ├── IceGenerator        ─── sinusoidal crack veins + frost patches
    ├── LavaGenerator       ─── toroidal Voronoi plates + emissive crack glow
    │
    │  Alpha-masked cards
    ├── LeafGenerator       ─── LeafSampler (silhouette + venation)
    ├── TwigGenerator       ─── LeafSampler × N (composite stem + leaves)
    ├── WindowGenerator     ─── rounded-box SDF frame/mullions + FBM grime
    ├── StainedGlassGenerator── toroidal Voronoi + lead came SDF + grime FBM
    ├── IronGrilleGenerator ─── bar SDF grid + joint rust FBM
    ├── ChainLinkGenerator  ─── diagonal wire lattice + over/under weave
    ├── LogEndGenerator     ─── warped concentric rings + bark rim
    │
    │  Sprite atlases (alpha-masked cards, via sprite::generate_atlas)
    ├── SoftDiscGenerator   ─── radial-falloff disc (core + halo)
    ├── SparkGenerator      ─── N-armed streak burst
    ├── SnowflakeGenerator  ─── dendritic N-fold flake
    ├── PuffGenerator       ─── domain-warped FBM blob + radial mask
    ├── RingGenerator       ─── soft annulus + angular waviness
    ├── PetalGenerator      ─── obovate blade + throat/edge gradient
    ├── ShardGenerator      ─── jittered polygon chip + grain FBM
    ├── LeafSpriteGenerator ─── LeafSampler atlas (per-cell leaf variants)
    ├── FlameGenerator      ─── teardrop envelope + FBM turbulence
    └── FlowerGenerator     ─── PetalCell × N (radial composite blossom)
                                │
                        height_to_normal() → normal map
                        linear_to_srgb()   → albedo encoding
                                │
                 TextureMap { albedo, normal, roughness, emissive? }
                                │
                map_to_images()      → GeneratedHandles (repeat sampler)
                map_to_images_card() → GeneratedHandles (clamp sampler)
                                │
                        full mipmap chain (type-correct averaging)

Noise-in-constructor — the surface generators and the SDF-based cards (window, stained glass, iron grille) build their noise objects (Fbm<Perlin>, RidgedMulti<Perlin>, ToroidalNoise<…>) once in new() and store them as struct fields. Calling generate() multiple times (e.g. to produce size variants of the same material) skips the initialisation cost. Worley is the exception: it contains an Rc and is therefore !Send / !Sync, so the generators that use it (BarkGenerator, PlankGenerator) construct it locally — and, since generation is row-parallel, once per row inside the parallel loop (the construction cost is microseconds against the per-row pixel work). The foliage cards (LeafGenerator, TwigGenerator — leaf sampling also uses Worley) and the sprite generators hold only their config and build their samplers per generate() call. The cell-decomposition surfaces (CobblestoneGenerator, LavaGenerator) instead use a dependency-free, Sync hash-based toroidal Voronoi (noise::toroidal_voronoi).

Workspace buffer pooling — generators that allocate large intermediate grids (e.g. BarkGenerator, ThatchGenerator) accept an optional Workspace via generate_with_workspace(). The workspace maintains a pool of Vec<f64> buffers that are borrowed and returned across calls, eliminating repeated 128 MB+ allocations at 4096×4096 resolution.

Seamless tiling is provided by ToroidalNoise, which maps 2-D UV coordinates onto a 4-D torus so that noise wraps perfectly at every edge:

nx = cos(2π·u) · frequency
ny = sin(2π·u) · frequency
nz = cos(2π·v) · frequency
nw = sin(2π·v) · frequency

Because cos(0) = cos(2π) and sin(0) = sin(2π), u=0 and u=1 always resolve to the same 4-D point, guaranteeing zero-seam tiling.

Normal maps are derived from the height field via central-difference gradients. For the tileable surface textures the neighbours wrap toroidally, so the normals are also seamless. For card textures (leaf, twig, window, stained glass, iron grille, and all sprites) the boundary uses clamp-to-edge so normals do not bleed across the transparent silhouette border. Sprite atlases additionally dilate heights into fully-transparent texels before derivation so the normals do not crease at silhouette edges.

Colour encoding uses a 4096-entry sRGB lookup table (built once via OnceLock) to avoid repeated f32::powf calls during rasterisation. A 256-entry table would be insufficient because the sRGB curve is steep near zero; 4096 bins keep the maximum quantisation error well below one count in u8.

Mipmap generation uses a 2×2 box filter with type-correct averaging: sRGB values are decoded to linear light before averaging and re-encoded afterward (avoiding dark mipmaps), normal-map XYZ vectors are averaged and renormalized (avoiding zero-length normals in PBR shaders), and ORM values are averaged directly in linear space. Async generation tasks precompute the full chain on the worker thread (TextureMap::with_mips), so the main-thread upload in the polling systems is a pure buffer move; map_to_images / map_to_images_card compute the chain on demand for maps without one (synchronous callers, cache loads). 16× anisotropic filtering is enabled on all samplers.

Examples

texture_viewer

cargo run --release --example texture_viewer --features egui

Displays an interactive material viewer with three columns: albedo (left), normal map (centre), and a 3-D PBR preview (right) with the generated material applied. Tileable surface textures are shown on a spinning cube; alpha-masked cards and sprite atlases get a gently swaying alpha-blended quad in front of a checkerboard backdrop instead, so per-pixel alpha is visible. An egui panel on the left lets you select any of the 40 generators from a dropdown, trigger a random Mutate (rate = 0.3), and edit every parameter live.

procedural_material

cargo run --release --example procedural_material

Side-by-side comparison of build_procedural_material_async (left cube) against the manual PendingTexture + material-patching flow it replaces (right cube).

animated_rust

cargo run --release --example animated_rust

Animates rust coverage on a metal panel from 0 % to 100 % over ten seconds via AnimatedProceduralMaterial driving a Linear curve, throttled to roughly four regenerations per second.

License

MIT — see LICENSE.