diff --git a/source/plutosvg.h b/source/plutosvg.h index d416fc7..7bb5f3f 100644 --- a/source/plutosvg.h +++ b/source/plutosvg.h @@ -54,14 +54,16 @@ extern "C" { #endif /** - * @brief plutosvg_version - * @return + * @brief Returns the version number of PlutoSVG. + * + * @return The version number as an integer. */ PLUTOSVG_API int plutosvg_version(void); /** - * @brief plutosvg_version_string - * @return + * @brief Returns the version string of PlutoSVG. + * + * @return Pointer to a string containing the version information. */ PLUTOSVG_API const char* plutosvg_version_string(void); @@ -71,107 +73,112 @@ PLUTOSVG_API const char* plutosvg_version_string(void); typedef struct plutosvg_document plutosvg_document_t; /** - * @brief Callback function type for resolving CSS color variables in SVG documents. - * @param closure A pointer to user-defined data passed to the callback function. - * @param name A pointer to the string representing the name of the color variable. - * @param length The length of the color variable name string. - * @param color A pointer to a `plutovg_color_t` structure where the resolved color will be stored. - * @return `true` if the color variable was successfully resolved and stored in the `color` structure; `false` otherwise. + * @brief Callback type for resolving CSS color variables in SVG documents. + * + * @param closure User-defined data for the callback. + * @param name Name of the color variable. + * @param length Length of the color variable name. + * @param color Pointer to `plutovg_color_t` where the resolved color will be stored. + * @return `true` if the color variable was successfully resolved; `false` otherwise. */ typedef bool(*plutosvg_palette_func_t)(void* closure, const char* name, int length, plutovg_color_t* color); /** * @brief Loads an SVG document from a data buffer. - * @param data A pointer to a buffer containing the SVG data. - * @param length The length of the data buffer. - * @param width The container width for the SVG document. This is used to resolve the initial viewport when the root SVG width is specified in relative units. - * @param height The container height for the SVG document. This is used to resolve the initial viewport when the root SVG height is specified in relative units. - * @param destroy_func A function pointer to a custom destroy function that will be called when the document is destroyed. - * @param closure A pointer to user-defined data that will be passed to the destroy function. - * @return A pointer to a `plutosvg_document_t` structure representing the loaded SVG document, or NULL if the loading fails. + * + * @note The buffer pointed to by `data` must remain valid until the `plutosvg_document_t` object is destroyed. + * + * @param data Pointer to the SVG data buffer. + * @param length Length of the data buffer. + * @param width Container width for resolving the initial viewport. + * @param height Container height for resolving the initial viewport. + * @param destroy_func Custom function to call when the document is destroyed. + * @param closure User-defined data for the `destroy_func` callback. + * @return Pointer to the loaded `plutosvg_document_t` structure, or NULL if loading fails. */ PLUTOSVG_API plutosvg_document_t* plutosvg_document_load_from_data(const char* data, int length, float width, float height, plutovg_destroy_func_t destroy_func, void* closure); /** * @brief Loads an SVG document from a file. - * @param A pointer to a null-terminated string representing the path to the file containing the SVG data. - * @param width The container width for the SVG document. This is used to resolve the initial viewport when the root SVG width is specified in relative units. - * @param height The container height for the SVG document. This is used to resolve the initial viewport when the root SVG height is specified in relative units. - * @return A pointer to a `plutosvg_document_t` structure representing the loaded SVG document, or NULL if the loading fails. + * + * @param filename Path to the SVG file. + * @param width Container width for resolving the initial viewport. + * @param height Container height for resolving the initial viewport. + * @return Pointer to the loaded `plutosvg_document_t` structure, or NULL if loading fails. */ PLUTOSVG_API plutosvg_document_t* plutosvg_document_load_from_file(const char* filename, float width, float height); /** * @brief Renders an SVG document or a specific element onto a canvas. * - * This function renders either a specific element identified by `id` or the entire SVG document if `id` is `NULL`. - * The rendering process takes into account the optional color and palette function for variable resolution. - * - * @param document A pointer to a `plutosvg_document_t` structure representing the SVG document.. - * @param id A pointer to a null-terminated string specifying the ID of the SVG element to render. If `NULL`, the entire SVG document is rendered. - * @param canvas A pointer to the `plutovg_canvas_t` structure representing the canvas onto which the SVG element or document will be rendered. - * @param current_color A pointer to a `plutovg_color_t` structure used to resolve CSS current color values. - * @param palette_func A callback function of type `plutosvg_palette_func_t` used to resolve CSS color variables (custom properties) defined in the SVG. - * @param closure A pointer to user-defined data that will be passed to the `palette_func` callback. - * @return `true` if the rendering operation was successful; `false` otherwise. + * @param document Pointer to the SVG document. + * @param id ID of the SVG element to render, or `NULL` to render the entire document. + * @param canvas Canvas onto which the SVG element or document will be rendered. + * @param current_color Color used to resolve CSS 'currentColor' values. + * @param palette_func Callback for resolving CSS color variables. + * @param closure User-defined data for the `palette_func` callback. + * @return `true` if rendering was successful; `false` otherwise. */ PLUTOSVG_API bool plutosvg_document_render(const plutosvg_document_t* document, const char* id, plutovg_canvas_t* canvas, const plutovg_color_t* current_color, plutosvg_palette_func_t palette_func, void* closure); /** - * @brief plutosvg_document_render_to_surface - * @param document - * @param id - * @param width - * @param height - * @param current_color - * @param palette_func - * @param closure - * @return + * @brief Renders an SVG document or a specific element onto a surface. + * + * @param document Pointer to the SVG document. + * @param id ID of the SVG element to render, or `NULL` to render the entire document. + * @param width Width of the surface, or `-1` if unspecified. + * @param height Height of the surface, or `-1` if unspecified. + * @param current_color Color for resolving CSS `currentColor` values. + * @param palette_func Callback for resolving CSS color variables. + * @param closure User-defined data for the `palette_func` callback. + * @return Pointer to the rendered `plutovg_surface_t` structure, or `NULL` if rendering fails. */ PLUTOSVG_API plutovg_surface_t* plutosvg_document_render_to_surface(const plutosvg_document_t* document, const char* id, int width, int height, const plutovg_color_t* current_color, plutosvg_palette_func_t palette_func, void* closure); /** * @brief Returns the intrinsic width of the SVG document. - * @param document A pointer to a `plutosvg_document_t` structure representing the SVG document.. + * + * @param document Pointer to the SVG document. * @return The intrinsic width of the SVG document. */ PLUTOSVG_API float plutosvg_document_get_width(const plutosvg_document_t* document); /** * @brief Returns the intrinsic height of the SVG document. - * @param document A pointer to a `plutosvg_document_t` structure representing the SVG document.. + * + * @param document Pointer to the SVG document. * @return The intrinsic height of the SVG document. */ PLUTOSVG_API float plutosvg_document_get_height(const plutosvg_document_t* document); /** - * @brief Retrieves the extents of a specific element within the SVG document or the whole document if the ID is NULL. + * @brief Retrieves the bounding box of a specific element or the entire SVG document. * - * This function calculates and retrieves the bounding box (extents) of an element identified by its ID within the given SVG document. - * If the ID is NULL, the extents of the entire SVG document are retrieved. The extents are returned as a `plutovg_rect_t` structure. + * Calculates and retrieves the extents of an element identified by `id` or the whole document if `id` is `NULL`. * - * @param document A pointer to a `plutosvg_document_t` structure representing the SVG document.. - * @param id A string representing the ID of the element whose extents are to be retrieved, or NULL to retrieve the extents of the entire document. - * @param extents A pointer to a `plutovg_rect_t` structure where the extents will be stored. - * @return `true` if the extents were successfully retrieved, `false` otherwise. + * @param document Pointer to the SVG document. + * @param id ID of the element whose extents to retrieve, or `NULL` to retrieve the extents of the entire document. + * @param extents Pointer to a `plutovg_rect_t` structure where the extents will be stored. + * @return `true` if extents were successfully retrieved; `false` otherwise. */ PLUTOSVG_API bool plutosvg_document_extents(const plutosvg_document_t* document, const char* id, plutovg_rect_t* extents); /** - * @brief Destroys an SVG document and frees associated resources. - * @param document A pointer to a `plutosvg_document_t` structure representing the SVG document to be destroyed. If the pointer is NULL, the function does nothing. + * @brief Destroys an SVG document and frees its resources. + * + * @param document Pointer to a `plutosvg_document_t` structure to be destroyed. If `NULL`, the function does nothing. */ PLUTOSVG_API void plutosvg_document_destroy(plutosvg_document_t* document); /** - * @brief Returns a pointer to a structure containing PlutoSVG hooks for integration with FreeType's SVG module. + * @brief Retrieves PlutoSVG hooks for integrating with FreeType's SVG module. * - * These hooks enable FreeType to use PlutoSVG for rendering SVG graphics embedded in fonts. + * Provides hooks that allow FreeType to use PlutoSVG for rendering SVG graphics in fonts. * - * @return a pointer to a structure containing PlutoSVG hooks for integration with FreeType's SVG module. + * @return Pointer to the structure containing PlutoSVG hooks for FreeType's SVG module, or `NULL` if FreeType integration is not enabled. */ PLUTOSVG_API const void* plutosvg_ft_svg_hooks(void);