hvif-light/src/hvif-light.h

/**
 * \file hvif-light.h
 * \author Hans-Jörg Schurr
 *
 * \brief Parse a \a hvif images.
 *
 * This library provides functions for parsing Haiku Vector Icon
 * files. The parser should be able to parse any files generated by Haiku
 * as of April 2020. It is, however, wholly untested and should not be
 * used. It most likely contains horrible bugs. During parsing some
 * basic checks for consistency of the image data are performed. But
 * not everything is checked. For example, paths might be invalid.
 */

#ifndef HVIF_LIGHT_H
#define HVIF_LIGHT_H

#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>

/** \typedef The general result type. */
typedef enum hvif_status
{
	SUCCESS = 0, /**< The image has been parsed into memory. */
	ERROR_EOF, /**< The file ended before parsing finished. */
	ERROR_NOMEM, /**< Not enough memory could be allocated. */
	ERROR_MAGIC, /**< The magic number of the file is wrong. */
	ERROR_STYLE, /**< A style related error occurred. */
	ERROR_PATH, /**< A path related error occurred. */
	ERROR_SHAPE /**< A shape related error occurred. */
} hvif_status;

/**
 * \typedef Opaque structure to reference a parsed image.
 * 	An API to inspect the image will be provided later.
 */
typedef struct hvif_image hvif_image;

/**
 * \typedef Captures the result of parsing: a status code together with the
 * 	image.
 */
typedef struct hvif_result hvif_result;
struct hvif_result
{
	hvif_status status; /**< Indicates success or an error in parsing. */
	hvif_image* image; /**< The image structure. NULL if parsing failed. */
};

/**
 * \brief Parses a \a hvif image from a file.
 * \param[in] file A valid file handler.
 * \return A `hvif_result` structure. A status other then SUCCESS indicates
 * 	an error. In this case the image is NULL. Otherwise the image needs
 *	to be freed. A success does not indicate that the image is renderable.
 */
hvif_result hvif_from_file(FILE* file);

/**
 * \brief Frees the memory of the image datastructures.
 * \param[in] image An image pointer returned by a previous call to
 * 	`hvif_from_file`. Can be NULL.
 */
void hvif_free(hvif_image* image);

/**
 * \defgroup Inspection API to inspect images
 * @{
 */

/**
 * \brief Returns the number of styles of a \a hvif image.
 * \param[in] file A valid image.
 * \return The number of styles in the image.
 */
uint8_t hvif_num_styles(hvif_image* image);

/**
 * \brief Returns the number of paths of a \a hvif image.
 * \param[in] file A valid image.
 * \return The number of paths in the image.
 */
uint8_t hvif_num_paths(hvif_image* image);

/**
 * \brief Returns the number of shapes of a \a hvif image.
 * \param[in] file A valid image.
 * \return The number of shapes in the image.
 */
uint8_t hvif_num_shapes(hvif_image* image);

/** \typedef Gradient types used by HVIF. */
typedef enum hvif_gradients_type
{
	HVIF_GRADIENT_LINEAR =
		0, /**< A linear gradient. A solid color is a linear gradient with only one stop */
	HVIF_GRADIENT_CIRCULAR, /**< A circular gradient. */
	HVIF_GRADIENT_DIAMOND, /**< A diamond gradient. */
	HVIF_GRADIENT_CONIC,
	HVIF_GRADIENT_XY,
	HVIF_GRADIENT_SQRT_XY,
	HVIF_GRADIENT_TYPE_MAX /**< The number of valid gradient types. */
} hvif_gradients_type;

/**
 * \brief Returns the gradient type of a style.
 * \param[in] file A valid image.
 * \param[in] style The index of the style.
 * \param[out] type The gradient type of the style.
 * \return ERROR_STYLE if this style does not exist.
 */
hvif_status hvif_style_gradient_type(
	hvif_image* image, uint8_t style, hvif_gradients_type* type);

/**
 * \brief Returns the number of gradient stops of a style.
 * \param[in] file A valid image.
 * \param[in] style The index of the style.
 * \param[out] num_stops The number of stops.
 * \return ERROR_STYLE if this style does not exist.
 */
hvif_status hvif_style_num_stops(
	hvif_image* image, uint8_t style, uint8_t* num_stops);

/** \typedef A color. */
typedef struct hvif_color hvif_color;
struct hvif_color
{
	uint8_t red;
	uint8_t green;
	uint8_t blue;
	uint8_t alpha;
};

/** \typedef A gradient stop: a color and an offset between 0.0 and 1.0. */
typedef struct hvif_gradient_stop hvif_gradient_stop;
struct hvif_gradient_stop
{
	hvif_color color; /**< The color of the gradient stop. */
	float offset; /**< The offset of the stop between 0.0 and 1.0. */
};

/**
 * \brief Returns a gradient stop.
 * \param[in] file A valid image.
 * \param[in] style The index of the style.
 * \param[in] stop The index of the stop.
 * \param[out] stop The gradient stop.
 * \return ERROR_STYLE if this style or stop index does not exist.
 */
hvif_status hvif_style_stop(
	hvif_image* image, uint8_t style, uint8_t stop,
	hvif_gradient_stop* gradient_stop);

/** \typedef An affine transformation matrix. */
typedef struct hvif_matrix hvif_matrix;
struct hvif_matrix
{
	double xx;
	double yx;
	double xy;
	double yy;
	double x0;
	double y0;
};

/**
 * \brief Returns the transformation applied to a style.
 * \param[in] file A valid image.
 * \param[in] style The index of the style.
 * \param[out] transformation The transformation matrix.
 * \return ERROR_STYLE if this style does not exist.
 */
hvif_status hvif_style_transformation(
	hvif_image* image, uint8_t style, hvif_matrix* transformation);

/**@}*/

#endif /* HVIF_LIGHT_H */