[![Crate](https://img.shields.io/crates/v/icodec)](https://crates.io/crates/icodec)
[![API](https://docs.rs/icodec/badge.svg)](https://docs.rs/icodec/)
![Minimum rustc version](https://img.shields.io/badge/rustc-1.37+-lightgray.svg)
![Downloads](https://img.shields.io/crates/d/icodec)
[![License](https://img.shields.io/crates/l/icodec)](http://spdx.org/licenses/MIT.html)

A pure Rust library for encoding and decoding
[ICO image files](https://en.wikipedia.org/wiki/ICO_%28file_format%29). This is 
a fork of _[rust-ico](https://crates.io/crates/ico)_.

# Overview

An ICO file (.ico) stores a collection of small images of different sizes and
color depths (up to 256x256 pixels each). Individial images within the file
can be encoded in either BMP or PNG format. ICO files are typically used for
website favicons and for Windows application icons.

## Usage

Joining multiple images into an ICO file can be accomplished with the
`encode::IcoEncoder` struct:

```rust
#![allow(overflowing_literals)]

use std::io;
use icodec::{resample, encode::{IcoEncoder, Encode, Save}, Image, Icon};

fn example() -> io::Result<()> {
    // Initialize the icon
    let mut ico = IcoEncoder::new();
 
    // Add a single icon
    let image = Image::open("example.png")?;
    ico.add_icon(resample::linear, &image, Icon(32, 32))?;
 
    // Add multiple icons
    ico.add_icons(
        resample::linear,
        &image,
        vec![Icon(64, 64), Icon(256, 256)]
    )?;
 
    // Save the icon to disk
    ico.save(&"~/example.ico")?;
    Ok(())
}
```

Likewise, decoding ICO files can be done via the `decode::IcoDecoder`
struct:

Traits and types to assist in decoding ICO files.

# Example

```rust
#![allow(overflowing_literals)]

use std::{io, fs::File};
use icodec::{decode::{IcoDecoder, Decode}, Image, Icon};

fn example() -> io::Result<()> {
    // Open the source file
    let file = File::open("~/example.ico")?;

    // Attempt to parse the file
    let ico = IcoDecoder::read(file)?;
 
    // Loop trought the icons of the icon
    // in an arbitraty order
    for (icon, image) in &ico {
        // Do something . . .
    }
    
    // Querying the icon for a particularly
    // sized image
    if let Some(image) = ico.get(&Icon(256, 256)) {
        // Do something . . .
    }
 
    Ok(())
}
```

# Supported Image Formats

| Format | Supported?                                                             | 
|--------|------------------------------------------------------------------------| 
| `png`  | All supported color types                                              | 
| `jpeg` | Baseline and progressive                                               | 
| `gif`  | Yes                                                                    | 
| `bmp`  | Yes                                                                    | 
| `webp` | Lossy(Luma channel only)                                               | 
| `svg`  | [Static SVG Full 1.1](https://github.com/RazrFalcon/resvg#svg-support) |

# Build Requirements

**Icodec** relies on [`harfbuzz_rs`](https://crates.io/crates/harfbuzz_rs), wich means
[CMake](https://cmake.org/) is required to be installed for it build.

# License

**Icodec** is made available under the
[MIT License](http://spdx.org/licenses/MIT.html).

This is a fork of _[rust-ico](https://crates.io/crates/ico)_. As such, it conforms 
to it's
[original licensing terms](https://github.com/mdsteele/rust-ico/blob/master/LICENSE).

# Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the 
work by you shall be licensed as above, without any additional terms or conditions.

Feel free to help out! Contributions are welcomed 😃