sar_core/
lib.rs

1//! # SAR Parser
2//!
3//! A Rust library for parsing and rendering SymbolArt (SAR) files from Phantasy Star Online 2.
4//!
5//! ## Overview
6//!
7//! This library provides functionality to:
8//! - Parse SAR files into a structured format
9//! - Render SymbolArt compositions into images
10//! - Manipulate and inspect SymbolArt properties
11//!
12//! ## Basic Usage
13//!
14//! ```no_run
15//! use sar_core::{parse, SymbolArtDrawer, SymbolArt};
16//! use sar_core::renderer::draw::Drawer;
17//!
18//! // Parse a SAR file
19//! let bytes = std::fs::read("example.sar").unwrap();
20//! let symbol_art = parse(bytes).unwrap();
21//!
22//! // Create a drawer and render the SymbolArt
23//! let drawer = SymbolArtDrawer::new();
24//! let image = drawer.draw(&symbol_art).unwrap();
25//!
26//! // Save the rendered image
27//! image.save("output.png").unwrap();
28//! ```
29//!
30//! ## Core Concepts
31//!
32//! ### SymbolArt
33//!
34//! A SymbolArt is a user-created artwork composed of multiple layers of symbols. Each layer contains:
35//! - A symbol (from a predefined set)
36//! - Position information (four corner points)
37//! - Color and transparency settings
38//! - Visibility state
39//!
40//! ### Layers
41//!
42//! Each layer in a SymbolArt has the following properties:
43//! - Position: Defined by four corner points (top-left, bottom-left, top-right, bottom-right)
44//! - Symbol: A unique identifier for the symbol used in the layer
45//! - Color: RGBA color values
46//! - Visibility: Whether the layer is hidden or visible
47//!
48//! ## Advanced Usage
49//!
50//! ### Customizing the Renderer
51//!
52//! ```no_run
53//! use sar_core::{parse, SymbolArtDrawer, SymbolArt};
54//! use sar_core::renderer::draw::Drawer;
55//!
56//! let bytes = std::fs::read("example.sar").unwrap();
57//! let symbol_art = parse(bytes).unwrap();
58//!
59//! // Create a customized drawer
60//! let drawer = SymbolArtDrawer::new()
61//!     .with_raise_error(true)  // Make errors fatal
62//!     .with_chunk_size(5);     // Adjust parallel processing
63//!
64//! // Render with custom scale
65//! let image = drawer.draw_with_scale(&symbol_art, 2.0).unwrap();
66//! ```
67//!
68//! ### Inspecting SymbolArt Properties
69//!
70//! ```no_run
71//! use sar_core::{parse, SymbolArt, SymbolArtLayer};
72//!
73//! let bytes = std::fs::read("example.sar").unwrap();
74//! let symbol_art = parse(bytes).unwrap();
75//!
76//! // Get basic information
77//! println!("Name: {}", symbol_art.name());
78//! println!("Author ID: {}", symbol_art.author_id());
79//! println!("Dimensions: {}x{}", symbol_art.width(), symbol_art.height());
80//!
81//! // Inspect layers
82//! for (i, layer) in symbol_art.layers().iter().enumerate() {
83//!     println!("Layer {}:", i);
84//!     println!("  Symbol ID: {}", layer.symbol().id());
85//!     println!("  Color: {:?}", layer.color());
86//!     println!("  Hidden: {}", layer.is_hidden());
87//! }
88//! ```
89//!
90//! ## File Format
91//!
92//! SAR files have the following structure:
93//! - Header (8 bytes)
94//!   - Author ID (4 bytes, big-endian)
95//!   - Number of layers (1 byte)
96//!   - Height (1 byte)
97//!   - Width (1 byte)
98//!   - Sound effect (1 byte)
99//! - Layer data (variable length)
100//!   - Position data (8 bytes per layer)
101//!   - Layer properties (4 bytes per layer)
102//! - Name data (UTF-16LE, up to 13 characters)
103//!
104//! ## Error Handling
105//!
106//! The library uses a custom `Result` type for error handling. Common errors include:
107//! - Invalid file format
108//! - I/O errors
109//! - Symbol not found
110//! - Projection errors during rendering
111//!
112//! ```
113//! use sar_core::{parse, Result};
114//!
115//! fn process_sar_file(bytes: &[u8]) -> Result<()> {
116//!     let symbol_art = parse(Vec::from(bytes))?;
117//!     // Process the SymbolArt...
118//!     Ok(())
119//! }
120//! ```
121//!
122//! ## Performance Considerations
123//!
124//! - The renderer uses parallel processing for layer rendering
125//! - Symbol resources are cached for better performance
126//! - The chunk size can be adjusted to balance parallelization overhead
127//!
128//! ## Dependencies
129//!
130//! - `image`: For image processing and rendering
131//! - `imageproc`: For geometric transformations
132//! - `rayon`: For parallel processing
133//! - `blowfish`: For file decryption
134//! - `ages_prs`: For file decompression
135//!
136//! ## License
137//!
138//! This project is licensed under the MIT License - see the LICENSE file for details.
139
140mod core;
141mod parser;
142pub mod renderer;
143pub use core::result::Result;
144pub use core::sa::{Color, SymbolArt, SymbolArtLayer};
145pub use parser::payload::parse;
146pub use renderer::SymbolArtDrawer;
147pub use renderer::default::draw;
148
149#[cfg(test)]
150mod test;
sar_core/lib.rs

sar_core/
lib.rs
