Struct AsepriteFile 

pub struct AsepriteFile { /* private fields */ }

An Aseprite .ase/.aseprite file.

Creating a file from scratch

use aseprite::*;

let mut file = AsepriteFile::new(32, 32, ColorMode::Rgba);
let layer = file.add_layer("Background");
let frame = file.add_frame(100);
let pixels = Pixels::new(vec![0u8; 32 * 32 * 4], 32, 32, ColorMode::Rgba).unwrap();
file.set_cel(layer, frame, pixels, 0, 0).unwrap();

Reading and writing

use aseprite::AsepriteFile;

let data = std::fs::read("sprite.aseprite").unwrap();
let file = AsepriteFile::from_reader(&data[..]).unwrap();
let mut output = Vec::new();
file.write_to(&mut output).unwrap();

Implementations

impl AsepriteFile

pub fn new(width: u16, height: u16, color_mode: ColorMode) -> Self

Creates an empty file with the given canvas dimensions and color mode.

pub fn width(&self) -> u16

Returns the canvas width in pixels.

pub fn height(&self) -> u16

Returns the canvas height in pixels.

pub fn color_mode(&self) -> ColorMode

Returns the color mode.

pub fn flags(&self) -> u32

Returns the raw header flags.

pub fn pixel_ratio(&self) -> (u8, u8)

Returns the pixel aspect ratio as (width, height).

pub fn grid(&self) -> &GridInfo

Returns the grid overlay settings.

pub fn color_profile(&self) -> &Option<ColorProfile>

Returns the color profile, if set.

pub fn palette(&self) -> &[Color]

Returns the color palette (empty if no palette chunk was present).

pub fn layers(&self) -> &[Layer]

Returns all layers in document order.

pub fn frames(&self) -> &[Frame]

Returns all frames.

pub fn tags(&self) -> &[Tag]

Returns all animation tags.

pub fn slices(&self) -> &[Slice]

Returns all slices.

pub fn sprite_user_data(&self) -> &Option<UserData>

Returns the sprite-level user data, if set.

pub fn transparent_index(&self) -> u8

Returns the transparent palette index (only meaningful for indexed color mode).

pub fn legacy_masks(&self) -> &[LegacyMask]

Returns legacy mask chunks (deprecated in modern Aseprite, preserved for round-trip fidelity).

pub fn tilesets(&self) -> &[Tileset]

Returns all tilesets.

pub fn external_files(&self) -> &[ExternalFile]

Returns all external file references.

pub fn cel(&self, layer: LayerRef, frame: usize) -> Option<&Cel>

Returns the raw cel at the given layer and frame, or None. May return CelKind::Linked; use resolve_cel to follow links.

pub fn resolve_cel(&self, layer: LayerRef, frame: usize) -> Option<&Cel>

Returns the cel at the given layer and frame, following linked cels.

Unlike cel(), this never returns CelKind::Linked. Returns None if the cel doesn’t exist or the link target is missing.

pub fn layer_ref(&self, index: usize) -> Option<LayerRef>

Returns a LayerRef handle for the given index, or None if the index is out of bounds or points to a group.

pub fn group_ref(&self, index: usize) -> Option<GroupRef>

Returns a GroupRef handle for the given index, or None if the index is out of bounds or is not a group.

pub fn add_layer(&mut self, name: &str) -> LayerRef

Adds a normal layer at the top level.

pub fn add_layer_with(&mut self, name: &str, opts: LayerOptions) -> LayerRef

Adds a normal layer at the top level with custom options.

pub fn add_group(&mut self, name: &str) -> GroupRef

Adds a group layer at the top level.

pub fn add_group_with(&mut self, name: &str, opts: LayerOptions) -> GroupRef

Adds a group layer at the top level with custom options.

pub fn add_layer_in(&mut self, name: &str, parent: GroupRef) -> LayerRef

Adds a normal layer inside a group.

pub fn add_layer_in_with( &mut self, name: &str, parent: GroupRef, opts: LayerOptions, ) -> LayerRef

Adds a normal layer inside a group with custom options.

pub fn add_group_in(&mut self, name: &str, parent: GroupRef) -> GroupRef

Adds a nested group inside a parent group.

pub fn add_group_in_with( &mut self, name: &str, parent: GroupRef, opts: LayerOptions, ) -> GroupRef

Adds a nested group inside a parent group with custom options.

pub fn add_tilemap_layer(&mut self, name: &str, tileset_index: u32) -> LayerRef

Adds a tilemap layer referencing the given tileset index.

pub fn set_tilemap_cel( &mut self, layer: LayerRef, frame: usize, tiles: Vec<u32>, width: u16, height: u16, x: i16, y: i16, ) -> Result<(), AsepriteError>

Sets tilemap data for a tilemap layer/frame.

pub fn add_frame(&mut self, duration_ms: u16) -> usize

Adds a frame with the given duration in milliseconds. Returns the frame index.

pub fn set_cel( &mut self, layer: LayerRef, frame: usize, pixels: Pixels, x: i16, y: i16, ) -> Result<(), AsepriteError>

Sets compressed pixel data for a layer/frame. Returns an error if the frame index is out of bounds.

pub fn set_cel_with( &mut self, layer: LayerRef, frame: usize, opts: CelOptions, ) -> Result<(), AsepriteError>

Sets pixel data for a layer/frame with custom opacity, position, and z-index.

pub fn set_raw_cel( &mut self, layer: LayerRef, frame: usize, pixels: Pixels, x: i16, y: i16, ) -> Result<(), AsepriteError>

Sets uncompressed pixel data for a layer/frame.

pub fn set_linked_cel( &mut self, layer: LayerRef, frame: usize, source_frame: usize, ) -> Result<(), AsepriteError>

Sets a linked cel pointing to another frame’s cel. Returns an error if either frame index is out of bounds.

pub fn add_tag( &mut self, name: &str, frames: RangeInclusive<usize>, direction: LoopDirection, ) -> Result<usize, AsepriteError>

Adds an animation tag spanning the given frame range.

pub fn add_tag_with( &mut self, name: &str, frames: RangeInclusive<usize>, direction: LoopDirection, repeat: u16, ) -> Result<usize, AsepriteError>

Adds an animation tag with a custom repeat count.

pub fn set_palette(&mut self, colors: &[Color]) -> Result<(), AsepriteError>

Sets the color palette. Returns an error if more than 256 entries.

pub fn set_transparent_index(&mut self, index: u8)

Sets the transparent palette index.

pub fn set_color_profile(&mut self, profile: ColorProfile)

Sets the color profile.

pub fn add_slice(&mut self, slice: Slice)

Adds a slice.

pub fn set_sprite_user_data(&mut self, ud: UserData)

Sets the sprite-level user data.

pub fn add_tileset(&mut self, tileset: Tileset)

Adds a tileset definition.

pub fn add_external_file(&mut self, ef: ExternalFile)

Adds an external file reference.

pub fn set_layer_user_data(&mut self, layer: LayerRef, ud: UserData)

Sets user data on a layer.

pub fn set_group_user_data(&mut self, group: GroupRef, ud: UserData)

Sets user data on a group layer.

pub fn set_cel_user_data(&mut self, layer: LayerRef, frame: usize, ud: UserData)

Sets user data on a cel.

pub fn set_cel_extra(&mut self, layer: LayerRef, frame: usize, extra: CelExtra)

Sets extra precision bounds on a cel.

pub fn set_tag_user_data(&mut self, tag_index: usize, ud: UserData)

Sets user data on a tag.

impl AsepriteFile

pub fn from_reader<R: Read>(r: R) -> Result<Self, AsepriteError>

Parses an Aseprite file from any reader.

pub fn write_to<W: Write>(&self, w: W) -> Result<(), AsepriteError>

Writes the file in Aseprite binary format to any writer.

Trait Implementations

impl Clone for AsepriteFile

fn clone(&self) -> AsepriteFile

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AsepriteFile

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

Formats the value using the given formatter.