From: Michael Orlitzky Date: Wed, 9 Aug 2023 04:02:32 +0000 (-0400) Subject: io-svg.c: improve documentation; drop the unused size_func field. X-Git-Tag: 0.0.2~4 X-Git-Url: https://gitweb.michael.orlitzky.com/?a=commitdiff_plain;h=7d30815b11ee9fdce43c158b07fe43042b6b3e8d;p=libsvgtiny-pixbuf.git io-svg.c: improve documentation; drop the unused size_func field. --- diff --git a/io-svg.c b/io-svg.c index 95a0812..8ef9ff9 100644 --- a/io-svg.c +++ b/io-svg.c @@ -10,13 +10,20 @@ /* This "header" includes extra code that we've copy/pasted from GDK */ #include "gdk_pixbuf_get_from_surface.h" -/* - * The width and height of the viewport that we'll render the SVG +/* Declare the two functions that we export. Their names aren't + * mentioned in gdk-pixbuf-io.h, but they are required by the + * implementation, as you can confirm from the API docs or in + * gdk-pixbuf-io.c. The G_MODULE_EXPORT macro is defined in + * glib's gmodule.h */ +G_MODULE_EXPORT void fill_vtable(GdkPixbufModule* module); +G_MODULE_EXPORT void fill_info(GdkPixbufFormat *info); + + +/* The width and height of the viewport that we'll render the SVG * into. The final "picture" may not actually be this size; based on * the height, width, viewBox, and preserveAspectRatio attributes in * the SVG itself, libsvgtiny may scale, stretch, offset, etc. the - * paths to make them fit nicely into the viewport. - */ + * paths to make them fit nicely into the viewport. */ #define VIEWPORT_WIDTH 512 #define VIEWPORT_HEIGHT 512 @@ -25,10 +32,14 @@ typedef struct svgtiny_diagram diagram_t; typedef struct svgtiny_shape shape_t; +/* Our main data structure. One of these is created when we start + * loading an SVG, and it persists while the SVG is being read. It + * contains a few boilerplate members, and the svg_data/svg_data_size + * fields that we use to keep track of the buffer where the SVG file + * lives. */ typedef struct { GdkPixbufModuleUpdatedFunc updated_func; GdkPixbufModulePreparedFunc prepared_func; - GdkPixbufModuleSizeFunc size_func; gpointer user_data; /* The SVG "file" that we're building in memory. */ @@ -45,6 +56,9 @@ typedef struct { /** * @brief Render an svgtiny path using cairo. * + * This was lovingly borrowed from @c examples/svgtiny_display_x11.c + * in libsvgtiny itself, and modified to use a transparent background. + * * @param cr * A pointer to a valid cairo context. * @@ -349,6 +363,10 @@ static GdkPixbuf* gdk_pixbuf_from_svg_buffer(const gchar* buffer, } +/** + * @brief Our implementation of GdkPixbufModuleBeginLoadFunc, as + * defined in gdk-pixbuf-io.h. + */ static gpointer gdk_pixbuf_begin_load(GdkPixbufModuleSizeFunc size_func, GdkPixbufModulePreparedFunc prep_func, GdkPixbufModuleUpdatedFunc updated_func, @@ -357,7 +375,6 @@ static gpointer gdk_pixbuf_begin_load(GdkPixbufModuleSizeFunc size_func, SvgTinyContext* context = g_new(SvgTinyContext, 1); - context->size_func = size_func; context->prepared_func = prep_func; context->updated_func = updated_func; context->user_data = user_data; @@ -368,6 +385,11 @@ static gpointer gdk_pixbuf_begin_load(GdkPixbufModuleSizeFunc size_func, return context; } + +/** + * @brief Our implementation of GdkPixbufModuleIncrementLoadFunc, as + * defined in gdk-pixbuf-io.h. + */ static gboolean gdk_pixbuf_load_increment(gpointer data, const guchar* buf, guint buf_size, @@ -386,6 +408,10 @@ static gboolean gdk_pixbuf_load_increment(gpointer data, return TRUE; } +/** + * @brief Convenience function to execute the "updated" callback + * stored in our @c context. + */ static void emit_updated(SvgTinyContext* context, GdkPixbuf* pixbuf) { if (context->updated_func != NULL) { (*context->updated_func)(pixbuf, @@ -397,6 +423,10 @@ static void emit_updated(SvgTinyContext* context, GdkPixbuf* pixbuf) { } } +/** + * @brief Convenience function to execute the "prepared" callback + * stored in our @c context. + */ static void emit_prepared(SvgTinyContext* context, GdkPixbuf* pixbuf) { if (context->prepared_func != NULL) { (*context->prepared_func)(pixbuf, NULL, context->user_data); @@ -616,6 +646,10 @@ static gchar* process_gtk_symbolic_svg_xinclude(const gchar* buffer, } +/** + * @brief Our implementation of GdkPixbufModuleStopLoadFunc, as + * defined in gdk-pixbuf-io.h. + */ static gboolean gdk_pixbuf_stop_load(gpointer data, GError **error) { SvgTinyContext* context = (SvgTinyContext*)data; GdkPixbuf* pixbuf = NULL; @@ -662,14 +696,20 @@ static gboolean gdk_pixbuf_stop_load(gpointer data, GError **error) { } -G_MODULE_EXPORT void fill_vtable(GdkPixbufModule* module); +/** + * @brief Our implementation of GdkPixbufModuleFillVtableFunc, as + * defined in gdk-pixbuf-io.h. + */ void fill_vtable(GdkPixbufModule* module) { module->begin_load = gdk_pixbuf_begin_load; module->load_increment = gdk_pixbuf_load_increment; module->stop_load = gdk_pixbuf_stop_load; } -G_MODULE_EXPORT void fill_info(GdkPixbufFormat *info); +/** + * @brief Our implementation of GdkPixbufModuleFillInfoFunc, as + * defined in gdk-pixbuf-io.h. + */ void fill_info(GdkPixbufFormat* info) { /* Borrowed from librsvg-2.40.21 */ static const GdkPixbufModulePattern signature[] = {