hvif-light/README.md

# A simple library to render Haiku Vector Icons

:warning: **Do not use this library. It is not ready yet.**

The [Haiku](https://www.haiku-os.org) operating system uses a custom
format to represent vector icons. The Haiku Vector Icon Format
(hvif) is optimized to create tiny files that can be saved with
the file metadata.  For a good technical overview of the format see
[this](http://blog.leahhanson.us/post/recursecenter2016/haiku_icons.html)
blog post by Leah Hanson.  The goal of this library is to allow the
usage of this format independent of the Haiku ecosystem.
The best way to create new icons is to use the
[Icon-O-Matic](https://www.haiku-os.org/docs/userguide/en/applications/icon-o-matic.html)
tool that ships with Haiku.

The library is written in modern standard C and MIT licensed. When
finished it will feature a parser and and serializer for hvif files
without any dependencies beyond *libc* and multiple simple backends.
Furthermore, a toy tool to convert *hvif* files into *png* files is
included.

The author is not associated with the Haiku project.

## Current Status

The library is currently under active development. The current parser
should be able to parse *hvif* files created with current Haiku builds,
but is mostly untested. There is an experimental rasterizer based on
[cairo](https://www.cairographics.org/) is included. The purpose of this
rasterizer is testing. It is not feature complete, but renders most real
world icons reasonably well.

### Example

The `File_GoogleFS` icon from the Haiku distribution as rendered by Haiku:

![](docs/examples/File_GoogleFS_orig.png)

and as rendered with the current cairo based rasterizer:

![](docs/examples/File_GoogleFS_hviflight.png)

While not perfect, the result is quite decent.

## Building

### Release Distribution

The build system is standard auto tools. When downloading a release distribution
the usual
```bash
$ ./configure
$ make -j
```
and `make install` as root should work. Beside a recent C compiler and
`pkg-config` the *cairo* library is required for now.  Since no sensible
functionality independent of *cairo* is implemented as of now, cairo is
a hard dependency.

### Development

To compile a freshly cloned repository run:

```bash
$ autoreconf -i
$ ./configure
$ make -j
```

On NixOS the included `shell.nix` script can be used to bring the
dependencies and a couple of development tools into scope.

### Documentation

HTML documentation can be generated with `make html` if Doxygen is
installed.

## Contribution

Contributions are very welcome. Please send patches or bugreports to
`commits at schurr dot at`. If you are unfamiliar with the Email based git
workflow, see [this](https://git-send-email.io/) excellent tutorial.