README.md 2.28 KB
Newer Older
Steven vanZyl's avatar
Steven vanZyl committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
# Steve's Simple Image Format

This is a simple graphical image format that I created as a challenge for
myself: To design and create an image format, with decoder, in a day.

I chose Rust simply because I like it and thought it was suitable for
this project. Additionally I intend to write a simple web decoder which
possibly will use WebAssembly so Rust is quite suited.

## Building

```
cargo build
```

## Specification

### Header

Every file begins with the header which is exactly 7 bytes long and
is composed of:

- 2 byte magic number. In hex it's `AE AE`.
- 1 byte sequential version number.
- 2 byte width of the image.
- 2 byte height of the image.

The magic number identifies this file as a SSIF file regardless of the file
extension or any other interference.

The version number is used for compatibility purposes with other versions of
the format.

The width and height are conviences for developers so that the format can
easily be read into a fixed sized buffer with the size known beforehand.
This does however limit the image to a total of `2^32` bytes.

### Format and Compression

Past the header is the actual file data, which can be broken up into 3-byte
segments. These 2 bytes contain:

- 2 bytes of color data.
- 1 byte length of the color run.

The length of the data section must be a mutiple of 3. Any additional bytes will
be ignored.

The color data itself is contained within two bytes representing RGBA in
4-bits each in exactly that order. The individual color values can be extracted
using standard bit-shifting or bit-masking methods.

Colors go up in intensity and alpha goes up in opacity. Therefore `FF FF` is
white while `00 00` is completely transparent and `00 0F` is black.
Steven vanZyl's avatar
Steven vanZyl committed
55
The colorspace is rather limited but for my purposes I wanted that.
Steven vanZyl's avatar
Steven vanZyl committed
56 57 58 59 60

The second byte is defines the "run" length of this color, or the horizontal
length along this row of pixels to use this color. This is a form of basic
compression. A length of 1 means this is only one pixel, a length of 100
means this is a line 100 pixels long.
Steven vanZyl's avatar
Steven vanZyl committed
61 62
Runs longer than or going off the end of a row are considered **valid** and will
wrap onto the next line.
Steven vanZyl's avatar
Steven vanZyl committed
63 64 65 66 67 68

## License

This project is licensed under the
[MIT License](https://opensource.org/licenses/MIT)
which you can read online at that link or in the [LICENSE file](./LICENSE)