ico/
lib.rs

1//! A library for encoding/decoding [ICO image
2//! files](https://en.wikipedia.org/wiki/ICO_%28file_format%29).
3//!
4//! # Overview
5//!
6//! An ICO file (.ico) stores a collection of small images of different sizes
7//! and color depths.  Individial images within the file can be encoded in
8//! either BMP or PNG format.  ICO files are typically used for website
9//! favicons and for Windows application icons.
10//!
11//! CUR files (.cur), which store Windows cursor images, use the same file
12//! format as ICO files, except that each image also comes with (x, y)
13//! *hotspot* coordinates that determines where on the image the user is
14//! pointing.  This libary supports both file types.
15//!
16//! # Examples
17//!
18//! ## Reading an ICO file
19//!
20//! ```no_run
21//! // Read an ICO file from disk:
22//! let file = std::fs::File::open("path/to/file.ico").unwrap();
23//! let icon_dir = ico::IconDir::read(file).unwrap();
24//! // Print the size of each image in the ICO file:
25//! for entry in icon_dir.entries() {
26//!     println!("{}x{}", entry.width(), entry.height());
27//! }
28//! // Decode the first entry into an image:
29//! let image = icon_dir.entries()[0].decode().unwrap();
30//! // You can get raw RGBA pixel data to pass to another image library:
31//! let rgba = image.rgba_data();
32//! assert_eq!(rgba.len(), (4 * image.width() * image.height()) as usize);
33//! // Alternatively, you can save the image as a PNG file:
34//! let file = std::fs::File::create("icon.png").unwrap();
35//! image.write_png(file).unwrap();
36//! ```
37//!
38//! ## Creating an ICO file
39//!
40//! ```no_run
41//! // Create a new, empty icon collection:
42//! let mut icon_dir = ico::IconDir::new(ico::ResourceType::Icon);
43//! // Read a PNG file from disk and add it to the collection:
44//! let file = std::fs::File::open("path/to/image.png").unwrap();
45//! let image = ico::IconImage::read_png(file).unwrap();
46//! icon_dir.add_entry(ico::IconDirEntry::encode(&image).unwrap());
47//! // Alternatively, you can create an IconImage from raw RGBA pixel data
48//! // (e.g. from another image library):
49//! let rgba = vec![std::u8::MAX; 4 * 16 * 16];
50//! let image = ico::IconImage::from_rgba_data(16, 16, rgba);
51//! icon_dir.add_entry(ico::IconDirEntry::encode(&image).unwrap());
52//! // Finally, write the ICO file to disk:
53//! let file = std::fs::File::create("favicon.ico").unwrap();
54//! icon_dir.write(file).unwrap();
55//! ```
56
57#![warn(missing_docs)]
58
59#[macro_use]
60mod macros;
61
62mod bmpdepth;
63mod icondir;
64mod image;
65mod restype;
66
67pub use crate::icondir::{IconDir, IconDirEntry};
68pub use crate::image::IconImage;
69pub use crate::restype::ResourceType;
70
71//===========================================================================//
ico/lib.rs

ico/
lib.rs
