/**
 * \file hvif-cairo.h
 * \author Hans-Jörg Schurr
 *
 * \brief An experimental renderer for \a hvif images based on cairo.
 *
 * This library provides functions for rendering \a hvif images with cairo.
 * The rendere is incomplete and serves only as a vehicle to understand the
 * semantic of \a hvif images. In general it only attempts to render
 * features exposed by Icon-o-Matic. Furthermore multiple stroke transforms
 * and contour transforms are not supported. Furthermore the colour space
 * is not equivalent to the colour space used on Haiku. The renderer is only
 * lightly tested and most likely contains horrible bugs.
 */

#ifndef HVIF_CAIRO_H
#define HVIF_CAIRO_H

#include "hvif-light.h"

#include <cairo.h>

/** \typedef The result of rendering an image. */
typedef enum hvif_cairo_status
{
	HVIF_CAIRO_SUCCESS = 0, /**< Rendering succeed completely. */
	HVIF_CAIRO_UNSUPPORTED, /**< Success, but some features are unsupported. */
	HVIF_CAIRO_ERROR_NOMEM, /**< Not enough memory could be allocated. */
	HVIF_CAIRO_ERROR /**< Rendering failed. */
} hvif_cairo_status;

/**
 * \brief Renders a \a hvif image into a PNG file.
 *
 * Renders an \a hvif image into a PNG file using the toy PNF output of cairo.
 * The result is always a square picture. The image is scaled to fill the the
 * square.
 *
 * \param[in] filename The filename of the resulting image.
 * \param[in] image A parsed \a hvif image.
 * \param[in] pixel_size The size of generated picture in pixels.
 * \return A `hvif_cairo_status`.
 * \note A status of `HVIF_CAIRO_UNSUPPORTED` does not indicate a rendering
 * 	error, but informs the user that some unsupported features were
 * 	encoutnered.
 */
hvif_cairo_status hvif_cairo_png_render(
	const char* filename, hvif_image* image, unsigned pixel_size);

/**
 * \brief Renders a \a hvif image into a cairo surface.
 *
 * Renders an \a hvif image into a cairo surface. The image is a 64 by 64 units
 * square scaled by `scale`. Hence a `scala` of 2.0 indicates that the image
 * should be 128 by 128.
 *
 * \param[in] surface A cairo surface.
 * \param[in] image A parsed \a hvif image.
 * \param[in] scale The amount the image should be scaled.
 * \return A `hvif_cairo_status`.
 * \note A status of `HVIF_CAIRO_UNSUPPORTED` does not indicate a rendering
 * 	error, but informs the user that some unsupported features were
 * 	encoutnered.
 */
hvif_cairo_status hvif_cairo_surface_render(
	cairo_surface_t* surface, hvif_image* image, double scale);

/**
 * \brief Renders a \a hvif image into a cairo context.
 *
 * Renders an \a hvif image into a cairo context. The image is a 64 by 64 units
 * square. No scaling is performed. The scale parameter is used to for the
 * LOD feauture. Hence, a scale of 0.5 hides shapes that have a minimum or
 * maximum scale of 0.5. Usually, a scale of 0.5 indicates that the result has
 * a size of 32 by 32 pixel.
 *
 * \param[in] context A cairo context.
 * \param[in] image A parsed \a hvif image.
 * \param[in] scale The the context was scaled.
 * \return A `hvif_cairo_status`.
 * \note A status of `HVIF_CAIRO_UNSUPPORTED` does not indicate a rendering
 * 	error, but informs the user that some unsupported features were
 * 	encoutnered.
 */
hvif_cairo_status hvif_cairo_render(
	cairo_t* context, hvif_image* image, double scale);

#endif /* HVIF_CAIRO_H */