Add documentation on the cairo interface and final newline

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;
 }
+

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 */
+

src/hvif-light.c

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

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 */
+