From d4208de6f90f71fa85eb16b15e5841be1626108f Mon Sep 17 00:00:00 2001 From: Hans-Joerg Schurr Date: Tue, 5 May 2020 21:33:48 +0200 Subject: [PATCH] Add documentation on the cairo interface and final newline --- src/hvif-cairo.c | 23 +++++++++++++++++++ src/hvif-cairo.h | 57 ++++++++++++++++++++++++++++++++++++++++++++---- src/hvif-light.c | 1 + src/hvif-light.h | 17 ++++++++------- 4 files changed, 86 insertions(+), 12 deletions(-) diff --git a/src/hvif-cairo.c b/src/hvif-cairo.c index d8e6ba5..565397c 100644 --- a/src/hvif-cairo.c +++ b/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; } + diff --git a/src/hvif-cairo.h b/src/hvif-cairo.h index 21658e3..33d2183 100644 --- a/src/hvif-cairo.h +++ b/src/hvif-cairo.h @@ -20,21 +20,70 @@ #include +/** \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 */ + diff --git a/src/hvif-light.c b/src/hvif-light.c index 3251c0b..97c4e4a 100644 --- a/src/hvif-light.c +++ b/src/hvif-light.c @@ -807,3 +807,4 @@ hvif_free(hvif_image* image) } #endif /* INTERNAL_DATASTRUCTURES */ + diff --git a/src/hvif-light.h b/src/hvif-light.h index feda95f..483053d 100644 --- a/src/hvif-light.h +++ b/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 */ +