1
0
Fork 0
Browse Source

Add documentation on the cairo interface and final newline

master
Hans-Joerg Schurr 2 years ago
parent
commit
d4208de6f9
  1. 23
      src/hvif-cairo.c
  2. 57
      src/hvif-cairo.h
  3. 1
      src/hvif-light.c
  4. 17
      src/hvif-light.h

23
src/hvif-cairo.c

@ -35,6 +35,9 @@ cairo_matrix_init_from_matrix(
#ifdef DEBUG
void
/**
* \brief Prints the transformation definet by a hvif matrix.
*/
print_matrix(const hvif_matrix* matrix)
{
printf("x_new = %f * x + %f * y + %f\n", matrix->xx, matrix->xy, matrix->x0);
@ -47,6 +50,9 @@ print_matrix(const hvif_matrix* matrix)
#define B(c) (COLOR_GET_BLUE(c) / 255.0)
#define A(c) (COLOR_GET_ALPHA(c) / 255.0)
/**
* \brief Create a patch for a diamond gradient.
*/
void
create_diamond_patch(
cairo_pattern_t* pat, double s1, double s2, hvif_color c1, hvif_color c2)
@ -93,6 +99,9 @@ create_diamond_patch(
cairo_mesh_pattern_end_patch(pat);
}
/**
* \brief Create a patch for a conic gradient.
*/
void
create_conic_patch(
cairo_pattern_t* pat, double r, double angle1, double angle2, hvif_color c1,
@ -117,6 +126,11 @@ create_conic_patch(
cairo_mesh_pattern_end_patch(pat);
}
/**
* \brief Create a cairo pattern from a \a hvif style.
*
* XY and sqrt XY gradients are unsupported and replaced by radial gradients.
*/
hvif_cairo_status
create_pattern_style(cairo_pattern_t** pat, hvif_style* style)
{
@ -235,6 +249,9 @@ create_pattern_style(cairo_pattern_t** pat, hvif_style* style)
return unsupported ? HVIF_CAIRO_UNSUPPORTED : HVIF_CAIRO_SUCCESS;
}
/**
* \brief Create a cairo path from a \a hvif path.
*/
void
create_path(cairo_t* cr, cairo_path_t** path, hvif_path* hvif_path)
{
@ -357,6 +374,7 @@ hvif_cairo_status
hvif_cairo_png_render(
const char* filename, hvif_image* image, unsigned pixel_size)
{
assert(image != NULL);
cairo_surface_t* surface =
cairo_image_surface_create(CAIRO_FORMAT_ARGB32, pixel_size, pixel_size);
double scale = pixel_size / 64.0;
@ -377,6 +395,8 @@ hvif_cairo_status
hvif_cairo_surface_render(
cairo_surface_t* surface, hvif_image* image, double scale)
{
assert(surface != NULL);
assert(image != NULL);
cairo_t* cr = cairo_create(surface);
cairo_scale(cr, scale, scale);
hvif_cairo_status result = hvif_cairo_render(cr, image, scale);
@ -387,6 +407,8 @@ hvif_cairo_surface_render(
hvif_cairo_status
hvif_cairo_render(cairo_t* context, hvif_image* image, double scale)
{
assert(context != NULL);
assert(image != NULL);
cairo_save(context);
cairo_pattern_t** patterns =
@ -440,3 +462,4 @@ hvif_cairo_render(cairo_t* context, hvif_image* image, double scale)
cairo_restore(context);
return result;
}

57
src/hvif-cairo.h

@ -20,21 +20,70 @@
#include <cairo.h>
/** \typedef The result of rendering an image. */
typedef enum hvif_cairo_status
{
HVIF_CAIRO_SUCCESS = 0,
HVIF_CAIRO_UNSUPPORTED,
HVIF_CAIRO_ERROR_NOMEM,
HVIF_CAIRO_ERROR
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 */

1
src/hvif-light.c

@ -807,3 +807,4 @@ hvif_free(hvif_image* image)
}
#endif /* INTERNAL_DATASTRUCTURES */

17
src/hvif-light.h

@ -48,19 +48,20 @@ struct hvif_result
};
/**
* \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.
* \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.
* \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);
#endif /* HVIF_LIGHT_H */

Loading…
Cancel
Save