Struct Image 

pub struct Image { /* private fields */ }

An RGBA8 image: sRGB-encoded, not premultiplied, tightly packed rows, top row first.

That is the layout that GPU texture uploads and most engines take, such as Diamon’s TextureStore::register.

Implementations

impl Image

pub fn new(width: u32, height: u32) -> Result<Self>

A transparent image. Both sides must be at least 1 and within the default Limits.

Examples found in repository

examples/night_shift.rs (line 767)

fn scale(image: &Image, n: u32) -> spritebox::Result<Image> {
    let mut out = Image::new(image.width() * n, image.height() * n)?;
    for y in 0..out.height() {
        for x in 0..out.width() {
            out.set_pixel(x, y, image.pixel(x / n, y / n).unwrap());
        }
    }
    Ok(out)
}
fn effects(frame: i32) -> Canvas {
    let mut c = Canvas::new(W, H, '.');
    // Periodic rain; its entire state returns after exactly 96 frames.
    for i in 0..225u32 {
        let y = (pick(i * 29 + 2, 384) + frame * 4) % 384 - 42;
        let x = (pick(i * 29 + 1, W) - y / 3).rem_euclid(W);
        let len = 3 + pick(i * 29 + 3, 6);
        c.line(
            x,
            y,
            x - len / 3,
            y + len,
            if i % 7 == 0 { 't' } else { 's' },
        );
    }
    // Broken puddle rings rather than a full, distracting reflection mirror.
    for i in 0..27u32 {
        let phase = (frame + pick(i + 401, 32)) % 32;
        let x = 96 + pick(i + 500, 326);
        let y = 225 + pick(i + 600, 56);
        if phase < 16 {
            let r = phase / 4 + 1;
            c.line(x - r, y, x + r, y, if phase < 8 { 'g' } else { 'f' });
            c.put(x - r - 1, y - 1, 'f');
            c.put(x + r + 1, y - 1, 'f');
        }
    }
    // Slow wisps escaping the restaurant pot; offsets wrap out of sight.
    for i in 0..5 {
        let t = (frame + i * 19) % FRAMES;
        let y = 234 - t / 5;
        let x = 389 + ((t as f64 * 0.15).sin() * 3.) as i32;
        c.ellipse(x, y, 1 + t / 32, 2, 'u');
    }
    // Lantern light and a subtle heartbeat in the cyan sign.
    c.ellipse(321, 219, 10, 13, 'v');
    if frame % 48 < 43 {
        c.rect(76, 91, 1, 75, 'w');
        c.rect(98, 91, 2, 75, 'w');
    }
    c.rect(12, 284, 112, 1, 'g');
    c.text(13, 289, "NIGHT SHIFT", 'p', 1);
    c.text(407, 289, "02:17", 'h', 1);
    c
}

fn reflection(frame: i32) -> Canvas {
    let mut c = Canvas::new(W, H, '.');
    let x = (frame * 8 + 396) % 768 - 280;
    for row in 0..7 {
        let yy = 197 + row * 7;
        for xx in (x.max(98)..(x + 260).min(417)).step_by(11) {
            c.rect(
                xx,
                yy,
                3 + row,
                1,
                if row < 2 {
                    'x'
                } else if row < 4 {
                    'y'
                } else {
                    'z'
                },
            );
        }
    }
    c
}

fn render_frame(
    frame: i32,
    city: &Image,
    train: &Image,
    street: &Image,
    palette: &str,
) -> Result<Image, Box<dyn std::error::Error>> {
    let mut image = city.clone();
    overlay(
        &mut image,
        &render_canvas(&reflection(frame), palette)?,
        0,
        0,
    );
    overlay(&mut image, train, (frame * 8 + 396) % 768 - 280, 145);
    overlay(&mut image, street, 0, 0);
    overlay(&mut image, &render_canvas(&effects(frame), palette)?, 0, 0);
    Ok(image)
}
fn source_header() -> String {
    let mut s = String::from(
        "; NIGHT SHIFT / an original spritebox scene.\n; All shapes are authored procedurally, without a reference bitmap.\npalette night\n",
    );
    for (key, value) in PALETTE {
        writeln!(s, "  {key} {value}").unwrap();
    }
    s
}
fn render_canvas(canvas: &Canvas, palette: &str) -> Result<Image, Box<dyn std::error::Error>> {
    let mut s = palette.to_string();
    canvas.source("effect", &mut s);
    let d = Document::parse(&s)?;
    Ok(d.sprite("effect").unwrap().render())
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
    let out = root.join("out/night-shift");
    let frames = out.join("frames");
    std::fs::create_dir_all(&frames)?;
    std::fs::create_dir_all(root.join("examples/night_shift"))?;
    let palette = source_header();
    let mut source = palette.clone();
    background().source("city", &mut source);
    train().source("last_train", &mut source);
    frontage().source("street", &mut source);
    // A clean, editable hero frame uses spritebox's native layer composition.
    let hero_x = 116;
    let mut train_hero = Canvas::new(W, H, '.');
    let train_pixels = train();
    for y in 0..train_pixels.h {
        for x in 0..train_pixels.w {
            train_hero.put(x + hero_x, y + 145, train_pixels.get(x, y));
        }
    }
    train_hero.source("train_at_station", &mut source);
    reflection(0).source("reflections", &mut source);
    effects(0).source("rain", &mut source);
    source.push_str("\nsprite night_shift 480x300 palette=night\n  layer city = city\n  layer reflections = reflections\n  layer train = train_at_station\n  layer street = street\n  layer atmosphere = rain\n");
    let art_path = root.join("examples/night_shift/night_shift.spritebox");
    std::fs::write(&art_path, &source)?;
    let doc = Document::parse(&source)?;
    let city = doc.sprite("city").unwrap().render();
    let train = doc.sprite("last_train").unwrap().render();
    let street = doc.sprite("street").unwrap().render();
    let hero = doc.sprite("night_shift").unwrap().render();
    let first = render_frame(0, &city, &train, &street, &palette)?;
    if hero != first {
        return Err("The editable layered sprite differs from animation frame zero".into());
    }
    if first != render_frame(FRAMES, &city, &train, &street, &palette)? {
        return Err("The animation does not close seamlessly".into());
    }
    png::write_file(out.join("night-shift-native.png"), &hero)?;
    png::write_file(out.join("night-shift.png"), &scale(&hero, 3)?)?;
    let mut sheet = Image::new(W as u32 * 2, H as u32 * 2)?;
    for f in 0..FRAMES {
        let image = render_frame(f, &city, &train, &street, &palette)?;
        png::write_file(frames.join(format!("{f:03}.png")), &scale(&image, 3)?)?;
        if f == 0 {
            png::write_file(out.join("night-shift.png"), &scale(&image, 3)?)?;
            png::write_file(out.join("night-shift-native.png"), &image)?;
        }
        if f % 24 == 0 {
            sheet.copy_from(&image, i64::from((f / 24) % 2 * W), i64::from((f / 48) * H));
            println!("Rendered {f}/{FRAMES} frames");
        }
    }
    png::write_file(out.join("contact-sheet.png"), &sheet)?;
    if png::read_file(out.join("night-shift-native.png"))? != hero {
        return Err("PNG round-trip mismatch".into());
    }
    // Keep a transparent sheet of useful original assets as well as the scene.
    png::write_file(out.join("train.png"), &scale(&train, 4)?)?;
    println!("Art: {}\nFrames: {}", art_path.display(), frames.display());
    Ok(())
}

pub fn new_with(width: u32, height: u32, limits: &Limits) -> Result<Self>

A transparent image within limits.

pub fn from_pixels(width: u32, height: u32, pixels: Vec<u8>) -> Result<Self>

An image of pixels, which must hold width * height * 4 bytes.

pub fn width(&self) -> u32

Examples found in repository

examples/night_shift.rs (line 753)

fn overlay(image: &mut Image, source: &Image, x: i32, y: i32) {
    for sy in 0..source.height() as i32 {
        let yy = sy + y;
        if yy < 0 || yy >= image.height() as i32 {
            continue;
        }
        for sx in 0..source.width() as i32 {
            let xx = sx + x;
            if xx < 0 || xx >= image.width() as i32 {
                continue;
            }
            let col = source.pixel(sx as u32, sy as u32).unwrap();
            if col.a > 0 {
                let under = image.pixel(xx as u32, yy as u32).unwrap();
                image.set_pixel(xx as u32, yy as u32, col.over(under));
            }
        }
    }
}
fn scale(image: &Image, n: u32) -> spritebox::Result<Image> {
    let mut out = Image::new(image.width() * n, image.height() * n)?;
    for y in 0..out.height() {
        for x in 0..out.width() {
            out.set_pixel(x, y, image.pixel(x / n, y / n).unwrap());
        }
    }
    Ok(out)
}

pub fn height(&self) -> u32

Examples found in repository

examples/night_shift.rs (line 748)

fn overlay(image: &mut Image, source: &Image, x: i32, y: i32) {
    for sy in 0..source.height() as i32 {
        let yy = sy + y;
        if yy < 0 || yy >= image.height() as i32 {
            continue;
        }
        for sx in 0..source.width() as i32 {
            let xx = sx + x;
            if xx < 0 || xx >= image.width() as i32 {
                continue;
            }
            let col = source.pixel(sx as u32, sy as u32).unwrap();
            if col.a > 0 {
                let under = image.pixel(xx as u32, yy as u32).unwrap();
                image.set_pixel(xx as u32, yy as u32, col.over(under));
            }
        }
    }
}
fn scale(image: &Image, n: u32) -> spritebox::Result<Image> {
    let mut out = Image::new(image.width() * n, image.height() * n)?;
    for y in 0..out.height() {
        for x in 0..out.width() {
            out.set_pixel(x, y, image.pixel(x / n, y / n).unwrap());
        }
    }
    Ok(out)
}

pub fn pixels(&self) -> &[u8]

The RGBA8 bytes, width * height * 4 of them.

pub fn into_pixels(self) -> Vec<u8>

pub fn pixel(&self, x: u32, y: u32) -> Option<Color>

The color at (x, y), or None outside the image.

Examples found in repository

examples/night_shift.rs (line 758)

fn overlay(image: &mut Image, source: &Image, x: i32, y: i32) {
    for sy in 0..source.height() as i32 {
        let yy = sy + y;
        if yy < 0 || yy >= image.height() as i32 {
            continue;
        }
        for sx in 0..source.width() as i32 {
            let xx = sx + x;
            if xx < 0 || xx >= image.width() as i32 {
                continue;
            }
            let col = source.pixel(sx as u32, sy as u32).unwrap();
            if col.a > 0 {
                let under = image.pixel(xx as u32, yy as u32).unwrap();
                image.set_pixel(xx as u32, yy as u32, col.over(under));
            }
        }
    }
}
fn scale(image: &Image, n: u32) -> spritebox::Result<Image> {
    let mut out = Image::new(image.width() * n, image.height() * n)?;
    for y in 0..out.height() {
        for x in 0..out.width() {
            out.set_pixel(x, y, image.pixel(x / n, y / n).unwrap());
        }
    }
    Ok(out)
}

pub fn set_pixel(&mut self, x: u32, y: u32, color: Color)

Sets the color at (x, y). Outside the image, does nothing.

Examples found in repository

examples/night_shift.rs (line 761)

fn overlay(image: &mut Image, source: &Image, x: i32, y: i32) {
    for sy in 0..source.height() as i32 {
        let yy = sy + y;
        if yy < 0 || yy >= image.height() as i32 {
            continue;
        }
        for sx in 0..source.width() as i32 {
            let xx = sx + x;
            if xx < 0 || xx >= image.width() as i32 {
                continue;
            }
            let col = source.pixel(sx as u32, sy as u32).unwrap();
            if col.a > 0 {
                let under = image.pixel(xx as u32, yy as u32).unwrap();
                image.set_pixel(xx as u32, yy as u32, col.over(under));
            }
        }
    }
}
fn scale(image: &Image, n: u32) -> spritebox::Result<Image> {
    let mut out = Image::new(image.width() * n, image.height() * n)?;
    for y in 0..out.height() {
        for x in 0..out.width() {
            out.set_pixel(x, y, image.pixel(x / n, y / n).unwrap());
        }
    }
    Ok(out)
}

pub fn copy_from(&mut self, source: &Image, x: i64, y: i64)

Copies source with its top-left corner at (x, y), replacing pixels and clipping to this image.

Examples found in repository

examples/night_shift.rs (line 929)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
    let out = root.join("out/night-shift");
    let frames = out.join("frames");
    std::fs::create_dir_all(&frames)?;
    std::fs::create_dir_all(root.join("examples/night_shift"))?;
    let palette = source_header();
    let mut source = palette.clone();
    background().source("city", &mut source);
    train().source("last_train", &mut source);
    frontage().source("street", &mut source);
    // A clean, editable hero frame uses spritebox's native layer composition.
    let hero_x = 116;
    let mut train_hero = Canvas::new(W, H, '.');
    let train_pixels = train();
    for y in 0..train_pixels.h {
        for x in 0..train_pixels.w {
            train_hero.put(x + hero_x, y + 145, train_pixels.get(x, y));
        }
    }
    train_hero.source("train_at_station", &mut source);
    reflection(0).source("reflections", &mut source);
    effects(0).source("rain", &mut source);
    source.push_str("\nsprite night_shift 480x300 palette=night\n  layer city = city\n  layer reflections = reflections\n  layer train = train_at_station\n  layer street = street\n  layer atmosphere = rain\n");
    let art_path = root.join("examples/night_shift/night_shift.spritebox");
    std::fs::write(&art_path, &source)?;
    let doc = Document::parse(&source)?;
    let city = doc.sprite("city").unwrap().render();
    let train = doc.sprite("last_train").unwrap().render();
    let street = doc.sprite("street").unwrap().render();
    let hero = doc.sprite("night_shift").unwrap().render();
    let first = render_frame(0, &city, &train, &street, &palette)?;
    if hero != first {
        return Err("The editable layered sprite differs from animation frame zero".into());
    }
    if first != render_frame(FRAMES, &city, &train, &street, &palette)? {
        return Err("The animation does not close seamlessly".into());
    }
    png::write_file(out.join("night-shift-native.png"), &hero)?;
    png::write_file(out.join("night-shift.png"), &scale(&hero, 3)?)?;
    let mut sheet = Image::new(W as u32 * 2, H as u32 * 2)?;
    for f in 0..FRAMES {
        let image = render_frame(f, &city, &train, &street, &palette)?;
        png::write_file(frames.join(format!("{f:03}.png")), &scale(&image, 3)?)?;
        if f == 0 {
            png::write_file(out.join("night-shift.png"), &scale(&image, 3)?)?;
            png::write_file(out.join("night-shift-native.png"), &image)?;
        }
        if f % 24 == 0 {
            sheet.copy_from(&image, i64::from((f / 24) % 2 * W), i64::from((f / 48) * H));
            println!("Rendered {f}/{FRAMES} frames");
        }
    }
    png::write_file(out.join("contact-sheet.png"), &sheet)?;
    if png::read_file(out.join("night-shift-native.png"))? != hero {
        return Err("PNG round-trip mismatch".into());
    }
    // Keep a transparent sheet of useful original assets as well as the scene.
    png::write_file(out.join("train.png"), &scale(&train, 4)?)?;
    println!("Art: {}\nFrames: {}", art_path.display(), frames.display());
    Ok(())
}

pub fn to_png(&self) -> Vec<u8>

Encodes the image as a PNG file. See png::encode.

impl Image

pub fn over_from(&mut self, source: &Image, x: i64, y: i64)

Draw source-over at signed coordinates, clipping to this image.

pub fn scaled_with(&self, scale: u32, limits: &Limits) -> Result<Image>

Nearest-neighbour integer scaling within explicit image limits.

Trait Implementations

impl Clone for Image

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Image

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Image

impl PartialEq for Image

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Image