From 482c809d084bc2b1c1f782beb658e2e5d7296cc4 Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Fri, 30 Oct 2020 13:02:23 -0600 Subject: Start fixing autotools Rename librsvg/ to include/ since now it only has header files. --- include/.dirstamp | 0 include/rsvg-cairo.h | 390 ++++++++++++ include/rsvg-css.h | 63 ++ include/rsvg-features.h | 187 ++++++ include/rsvg-version.h.in | 13 + include/rsvg.h | 1462 +++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 2115 insertions(+) create mode 100644 include/.dirstamp create mode 100644 include/rsvg-cairo.h create mode 100644 include/rsvg-css.h create mode 100644 include/rsvg-features.h create mode 100644 include/rsvg-version.h.in create mode 100644 include/rsvg.h (limited to 'include') diff --git a/include/.dirstamp b/include/.dirstamp new file mode 100644 index 00000000..e69de29b diff --git a/include/rsvg-cairo.h b/include/rsvg-cairo.h new file mode 100644 index 00000000..87821057 --- /dev/null +++ b/include/rsvg-cairo.h @@ -0,0 +1,390 @@ +/* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* vim: set sw=4 sts=4 expandtab: */ +/* + rsvg-cairo.h: SAX-based renderer for SVG files using cairo + + Copyright (C) 2005 Red Hat, Inc. + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + + Author: Carl Worth +*/ + +#if !defined (__RSVG_RSVG_H_INSIDE__) && !defined (RSVG_COMPILATION) +#warning "Including directly is deprecated." +#endif + +#ifndef RSVG_CAIRO_H +#define RSVG_CAIRO_H + +#include + +G_BEGIN_DECLS + +/** + * rsvg_handle_render_cairo: + * @handle: A #RsvgHandle + * @cr: A Cairo context + * + * Draws a loaded SVG handle to a Cairo context. Please try to use + * rsvg_handle_render_document() instead, which allows you to pick the size + * at which the document will be rendered. + * + * Historically this function has picked a size by itself, based on the following rules: + * + * + * + * If the SVG document has both width and height + * attributes with physical units (px, in, cm, mm, pt, pc) or font-based units (em, + * ex), the function computes the size directly based on the dots-per-inch (DPI) you + * have configured with rsvg_handle_set_dpi(). This is the same approach as + * rsvg_handle_get_intrinsic_size_in_pixels(). + * + * + * Otherwise, if there is a viewBox attribute and both + * width and height are set to + * 100% (or if they don't exist at all and thus default to 100%), + * the function uses the width and height of the viewBox as a pixel size. This + * produces a rendered document with the correct aspect ratio. + * + * + * Otherwise, this function computes the extents of every graphical object in the SVG + * document to find the total extents. This is moderately expensive, but no more expensive + * than rendering the whole document, for example. + * + * + * This function cannot deal with percentage-based units for width + * and height because there is no viewport against which they could + * be resolved; that is why it will compute the extents of objects in that case. This + * is why we recommend that you use rsvg_handle_render_document() instead, which takes + * in a viewport and follows the sizing policy from the web platform. + * + * + * + * Drawing will occur with respect to the @cr's current transformation: for example, if + * the @cr has a rotated current transformation matrix, the whole SVG will be rotated in + * the rendered version. + * + * This function depends on the #RsvgHandle's DPI to compute dimensions in + * pixels, so you should call rsvg_handle_set_dpi() beforehand. + * + * Note that @cr must be a Cairo context that is not in an error state, that is, + * cairo_status() must return #CAIRO_STATUS_SUCCESS for it. Cairo can set a + * context to be in an error state in various situations, for example, if it was + * passed an invalid matrix or if it was created for an invalid surface. + * + * Returns: %TRUE if drawing succeeded; %FALSE otherwise. + * Since: 2.14 + * + * Deprecated: 2.52. Please use rsvg_handle_render_document() instead; that function lets + * you pass a viewport and obtain a good error message. + */ +RSVG_DEPRECATED_FOR(rsvg_handle_render_document) +gboolean rsvg_handle_render_cairo (RsvgHandle *handle, cairo_t *cr); + +/** + * rsvg_handle_render_cairo_sub: + * @handle: A #RsvgHandle + * @cr: A Cairo context + * @id: (nullable): An element's id within the SVG, starting with "##" (a single + * hash character), for example, "##layer1". This notation corresponds to a + * URL's fragment ID. Alternatively, pass %NULL to render the whole SVG. + * + * Renders a single SVG element in the same place as for a whole SVG document (a "subset" + * of the document). Please try to use rsvg_handle_render_layer() instead, which allows + * you to pick the size at which the document with the layer will be rendered. + * + * This is equivalent to rsvg_handle_render_cairo(), but it renders only a single + * element and its children, as if they composed an individual layer in the SVG. + * + * Historically this function has picked a size for the whole document by itself, based + * on the following rules: + * + * + * + * If the SVG document has both width and height + * attributes with physical units (px, in, cm, mm, pt, pc) or font-based units (em, + * ex), the function computes the size directly based on the dots-per-inch (DPI) you + * have configured with rsvg_handle_set_dpi(). This is the same approach as + * rsvg_handle_get_intrinsic_size_in_pixels(). + * + * + * Otherwise, if there is a viewBox attribute and both + * width and height are set to + * 100% (or if they don't exist at all and thus default to 100%), + * the function uses the width and height of the viewBox as a pixel size. This + * produces a rendered document with the correct aspect ratio. + * + * + * Otherwise, this function computes the extents of every graphical object in the SVG + * document to find the total extents. This is moderately expensive, but no more expensive + * than rendering the whole document, for example. + * + * + * This function cannot deal with percentage-based units for width + * and height because there is no viewport against which they could + * be resolved; that is why it will compute the extents of objects in that case. This + * is why we recommend that you use rsvg_handle_render_layer() instead, which takes + * in a viewport and follows the sizing policy from the web platform. + * + * + * + * Drawing will occur with respect to the @cr's current transformation: for example, if + * the @cr has a rotated current transformation matrix, the whole SVG will be rotated in + * the rendered version. + * + * This function depends on the #RsvgHandle's DPI to compute dimensions in + * pixels, so you should call rsvg_handle_set_dpi() beforehand. + * + * Note that @cr must be a Cairo context that is not in an error state, that is, + * cairo_status() must return #CAIRO_STATUS_SUCCESS for it. Cairo can set a + * context to be in an error state in various situations, for example, if it was + * passed an invalid matrix or if it was created for an invalid surface. + * + * Element IDs should look like an URL fragment identifier; for example, pass + * "##foo" (hash foo) to get the geometry of the element that + * has an id="foo" attribute. + * + * Returns: %TRUE if drawing succeeded; %FALSE otherwise. + * Since: 2.14 + * + * Deprecated: 2.52. Please use rsvg_handle_render_layer() instead; that function lets + * you pass a viewport and obtain a good error message. + */ +RSVG_DEPRECATED_FOR(rsvg_handle_render_layer) +gboolean rsvg_handle_render_cairo_sub (RsvgHandle *handle, cairo_t *cr, const char *id); + +/** + * rsvg_handle_render_document: + * @handle: An #RsvgHandle + * @cr: A Cairo context + * @viewport: Viewport size at which the whole SVG would be fitted. + * @error: (optional): a location to store a #GError, or %NULL + * + * Renders the whole SVG document fitted to a viewport. + * + * The @viewport gives the position and size at which the whole SVG document will be + * rendered. The document is scaled proportionally to fit into this viewport. + * + * The @cr must be in a #CAIRO_STATUS_SUCCESS state, or this function will not + * render anything, and instead will return an error. + * + * API ordering: This function must be called on a fully-loaded @handle. See + * the section API ordering for details. + * + * Panics: this function will panic if the @handle is not fully-loaded. + * + * Since: 2.46 + */ +RSVG_API +gboolean rsvg_handle_render_document (RsvgHandle *handle, + cairo_t *cr, + const RsvgRectangle *viewport, + GError **error); + +/** + * rsvg_handle_get_geometry_for_layer: + * @handle: An #RsvgHandle + * @id: (nullable): An element's id within the SVG, starting with "##" (a single + * hash character), for example, "##layer1". This notation corresponds to a + * URL's fragment ID. Alternatively, pass %NULL to compute the geometry for the + * whole SVG. + * @viewport: Viewport size at which the whole SVG would be fitted. + * @out_ink_rect: (out)(optional): Place to store the ink rectangle of the element. + * @out_logical_rect: (out)(optional): Place to store the logical rectangle of the element. + * @error: (optional): a location to store a #GError, or %NULL + * + * Computes the ink rectangle and logical rectangle of an SVG element, or the + * whole SVG, as if the whole SVG were rendered to a specific viewport. + * + * Element IDs should look like an URL fragment identifier; for example, pass + * "##foo" (hash foo) to get the geometry of the element that + * has an id="foo" attribute. + * + * The "ink rectangle" is the bounding box that would be painted + * for fully- stroked and filled elements. + * + * The "logical rectangle" just takes into account the unstroked + * paths and text outlines. + * + * Note that these bounds are not minimum bounds; for example, + * clipping paths are not taken into account. + * + * You can pass #NULL for the @id if you want to measure all + * the elements in the SVG, i.e. to measure everything from the + * root element. + * + * This operation is not constant-time, as it involves going through all + * the child elements. + * + * API ordering: This function must be called on a fully-loaded @handle. See + * the section API ordering for details. + * + * Panics: this function will panic if the @handle is not fully-loaded. + * + * Since: 2.46 + */ +RSVG_API +gboolean rsvg_handle_get_geometry_for_layer (RsvgHandle *handle, + const char *id, + const RsvgRectangle *viewport, + RsvgRectangle *out_ink_rect, + RsvgRectangle *out_logical_rect, + GError **error); + +/** + * rsvg_handle_render_layer: + * @handle: An #RsvgHandle + * @cr: A Cairo context + * @id: (nullable): An element's id within the SVG, starting with "##" (a single + * hash character), for example, "##layer1". This notation corresponds to a + * URL's fragment ID. Alternatively, pass %NULL to render the whole SVG document tree. + * @viewport: Viewport size at which the whole SVG would be fitted. + * @error: (optional): a location to store a #GError, or %NULL + * + * Renders a single SVG element in the same place as for a whole SVG document. + * + * The @viewport gives the position and size at which the whole SVG document would be + * rendered. The document is scaled proportionally to fit into this viewport; hence the + * individual layer may be smaller than this. + * + * This is equivalent to rsvg_handle_render_document(), but it renders only a + * single element and its children, as if they composed an individual layer in + * the SVG. The element is rendered with the same transformation matrix as it + * has within the whole SVG document. Applications can use this to re-render a + * single element and repaint it on top of a previously-rendered document, for + * example. + * + * Element IDs should look like an URL fragment identifier; for example, pass + * "##foo" (hash foo) to get the geometry of the element that + * has an id="foo" attribute. + * + * You can pass #NULL for the @id if you want to render all + * the elements in the SVG, i.e. to render everything from the + * root element. + * + * API ordering: This function must be called on a fully-loaded @handle. See + * the section API ordering for details. + * + * Panics: this function will panic if the @handle is not fully-loaded. + * + * Since: 2.46 + */ +RSVG_API +gboolean rsvg_handle_render_layer (RsvgHandle *handle, + cairo_t *cr, + const char *id, + const RsvgRectangle *viewport, + GError **error); + +/** + * rsvg_handle_get_geometry_for_element: + * @handle: An #RsvgHandle + * @id: (nullable): An element's id within the SVG, starting with "##" (a single + * hash character), for example, "##layer1". This notation corresponds to a + * URL's fragment ID. Alternatively, pass %NULL to compute the geometry for the + * whole SVG. + * @out_ink_rect: (out)(optional): Place to store the ink rectangle of the element. + * @out_logical_rect: (out)(optional): Place to store the logical rectangle of the element. + * @error: (optional): a location to store a #GError, or %NULL + * + * Computes the ink rectangle and logical rectangle of a single SVG element. + * + * While `rsvg_handle_get_geometry_for_layer` computes the geometry of an SVG element subtree with + * its transformation matrix, this other function will compute the element's geometry + * as if it were being rendered under an identity transformation by itself. That is, + * the resulting geometry is as if the element got extracted by itself from the SVG. + * + * This function is the counterpart to `rsvg_handle_render_element`. + * + * Element IDs should look like an URL fragment identifier; for example, pass + * "##foo" (hash foo) to get the geometry of the element that + * has an id="foo" attribute. + * + * The "ink rectangle" is the bounding box that would be painted + * for fully- stroked and filled elements. + * + * The "logical rectangle" just takes into account the unstroked + * paths and text outlines. + * + * Note that these bounds are not minimum bounds; for example, + * clipping paths are not taken into account. + * + * You can pass #NULL for the @id if you want to measure all + * the elements in the SVG, i.e. to measure everything from the + * root element. + * + * This operation is not constant-time, as it involves going through all + * the child elements. + * + * API ordering: This function must be called on a fully-loaded @handle. See + * the section API ordering for details. + * + * Panics: this function will panic if the @handle is not fully-loaded. + * + * Since: 2.46 + */ +RSVG_API +gboolean rsvg_handle_get_geometry_for_element (RsvgHandle *handle, + const char *id, + RsvgRectangle *out_ink_rect, + RsvgRectangle *out_logical_rect, + GError **error); + +/** + * rsvg_handle_render_element: + * @handle: An #RsvgHandle + * @cr: A Cairo context + * @id: (nullable): An element's id within the SVG, starting with "##" (a single + * hash character), for example, "##layer1". This notation corresponds to a + * URL's fragment ID. Alternatively, pass %NULL to render the whole SVG document tree. + * @element_viewport: Viewport size in which to fit the element + * @error: (optional): a location to store a #GError, or %NULL + * + * Renders a single SVG element to a given viewport + * + * This function can be used to extract individual element subtrees and render them, + * scaled to a given @element_viewport. This is useful for applications which have + * reusable objects in an SVG and want to render them individually; for example, an + * SVG full of icons that are meant to be be rendered independently of each other. + * + * Element IDs should look like an URL fragment identifier; for example, pass + * "##foo" (hash foo) to get the geometry of the element that + * has an id="foo" attribute. + * + * You can pass #NULL for the @id if you want to render all + * the elements in the SVG, i.e. to render everything from the + * root element. + * + * The `element_viewport` gives the position and size at which the named element will + * be rendered. FIXME: mention proportional scaling. + * + * API ordering: This function must be called on a fully-loaded @handle. See + * the section API ordering for details. + * + * Panics: this function will panic if the @handle is not fully-loaded. + * + * Since: 2.46 + */ +RSVG_API +gboolean rsvg_handle_render_element (RsvgHandle *handle, + cairo_t *cr, + const char *id, + const RsvgRectangle *element_viewport, + GError **error); + +G_END_DECLS + +#endif diff --git a/include/rsvg-css.h b/include/rsvg-css.h new file mode 100644 index 00000000..dfca15b0 --- /dev/null +++ b/include/rsvg-css.h @@ -0,0 +1,63 @@ +/* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* vim: set sw=4 sts=4 expandtab: */ +/* + rsvg-css.h : CSS utility functions + + Copyright (C) 2000 Eazel, Inc. + Copyright (C) 2002 Dom Lachowicz + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + + Author: Raph Levien +*/ +#ifndef RSVG_CSS_H +#define RSVG_CSS_H + +#include + +/* Override to export public/semi-public APIs */ +#ifndef RSVG_API +# define RSVG_API +#endif + +G_BEGIN_DECLS + +/* Keep this in sync with rust/src/color.rs:ColorKind */ +typedef enum { + RSVG_CSS_COLOR_SPEC_ARGB, + RSVG_CSS_COLOR_PARSE_ERROR +} RsvgCssColorKind; + +/* Keep this in sync with rust/src/color.rs:RsvgCssColor */ +typedef struct { + RsvgCssColorKind kind; + guint32 argb; /* only valid if kind == RSVG_CSS_COLOR_SPEC_ARGB */ +} RsvgCssColorSpec; + +/* This one is semi-public for mis-use in rsvg-convert */ +RSVG_API +RsvgCssColorSpec rsvg_css_parse_color (const char *str); + +#ifdef RSVG_COMPILATION + +/* Implemented in rust/src/color.rs */ +G_GNUC_INTERNAL +RsvgCssColorSpec rsvg_css_parse_color (const char *str); + +#endif /* RSVG_COMPILATION */ + +G_END_DECLS + +#endif diff --git a/include/rsvg-features.h b/include/rsvg-features.h new file mode 100644 index 00000000..906c3a0e --- /dev/null +++ b/include/rsvg-features.h @@ -0,0 +1,187 @@ +#if !defined (__RSVG_RSVG_H_INSIDE__) && !defined (RSVG_COMPILATION) +#warning "Including directly is deprecated." +#endif + +#ifndef RSVG_FEATURES_H +#define RSVG_FEATURES_H + +/** + * SECTION: rsvg-features + * @short_description: Check for the version of librsvg being used. + * + * Librsvg provides a few C macros that C and C++ programs can use to + * check the version being used at compile-time, that is, the API that + * the program expects to have. This is useful for programs that need + * to conditionally compile code with #ifdef blocks + * depending on the version of librsvg that may be available during + * compilation. + * + * Librsvg also provides a few global constants that can be used to + * check the version of librsvg being used at run-time. This is + * useful to know which version of librsvg is actually being used on + * the system where the program is running. + */ + +/** + * LIBRSVG_MAJOR_VERSION: + * + * This is a C macro that expands to a number with the major version + * of librsvg against which your program is compiled. + * + * For example, for librsvg-2.3.4, the major version is 2. + * + * C programs can use this as a compile-time check for the required + * version, but note that generally it is a better idea to do + * compile-time checks by calling pkg-config + * in your build scripts. + * + * Note: for a run-time check on the version of librsvg that your + * program is running with (e.g. the version which the linker used for + * your program), or for programs not written in C, use + * @rsvg_major_version instead. + */ + +/** + * LIBRSVG_MINOR_VERSION: + * + * This is a C macro that expands to a number with the minor version + * of librsvg against which your program is compiled. + * + * For example, for librsvg-2.3.4, the minor version is 3. + * + * C programs can use this as a compile-time check for the required + * version, but note that generally it is a better idea to do + * compile-time checks by calling pkg-config + * in your build scripts. + * + * Note: for a run-time check on the version of librsvg that your + * program is running with (e.g. the version which the linker used for + * your program), or for programs not written in C, use + * @rsvg_minor_version instead. + */ + +/** + * LIBRSVG_MICRO_VERSION: + * + * This is a C macro that expands to a number with the micro version + * of librsvg against which your program is compiled. + * + * For example, for librsvg-2.3.4, the micro version is 4. + * + * C programs can use this as a compile-time check for the required + * version, but note that generally it is a better idea to do + * compile-time checks by calling pkg-config + * in your build scripts. + * + * Note: for a run-time check on the version of librsvg that your + * program is running with (e.g. the version which the linker used for + * your program), or for programs not written in C, use + * @rsvg_micro_version instead. + */ + +/** + * LIBRSVG_VERSION: + * + * This is a C macro that expands to a string with the version of + * librsvg against which your program is compiled. + * + * For example, for librsvg-2.3.4, this macro expands to + * "2.3.4". + * + * C programs can use this as a compile-time check for the required + * version, but note that generally it is a better idea to do + * compile-time checks by calling pkg-config + * in your build scripts. + * + * Note: for a run-time check on the version of librsvg that your + * program is running with (e.g. the version which the linker used for + * your program), or for programs not written in C, use + * @rsvg_version instead. + */ + +/** + * LIBRSVG_CHECK_VERSION: + * @major: component for the major version to check + * @minor: component for the minor version to check + * @micro: component for the micro version to check + * + * This C macro returns #TRUE if the the version of librsvg being + * compiled against is the same or newer than the specified version. + * + * Note that this a compile-time check for C programs. If you want a + * run-time check for the version of librsvg being used, or if you are + * using another programming language, see the variables + * @rsvg_major_version, @rsvg_minor_version, @rsvg_micro_version + * instead. + */ +#define LIBRSVG_CHECK_VERSION(major,minor,micro) \ + (LIBRSVG_MAJOR_VERSION > (major) || \ + (LIBRSVG_MAJOR_VERSION == (major) && LIBRSVG_MINOR_VERSION > (minor)) || \ + (LIBRSVG_MAJOR_VERSION == (major) && LIBRSVG_MINOR_VERSION == (minor) && LIBRSVG_MICRO_VERSION >= (micro))) + +#ifndef __GI_SCANNER__ +#define LIBRSVG_HAVE_SVGZ (TRUE) +#define LIBRSVG_HAVE_CSS (TRUE) + +#define LIBRSVG_CHECK_FEATURE(FEATURE) (defined(LIBRSVG_HAVE_##FEATURE) && LIBRSVG_HAVE_##FEATURE) +#endif + +#ifndef __GTK_DOC_IGNORE__ + +/* + * On Windows builds, we need to decorate variables that are exposed in the public API + * so that they can be properly exported and linked to, for DLL builds + */ +#ifndef RSVG_VAR +# ifdef G_PLATFORM_WIN32 +# ifndef RSVG_STATIC +# ifdef RSVG_COMPILATION +# define RSVG_VAR extern __declspec (dllexport) +# else /* RSVG_COMPILATION */ +# define RSVG_VAR extern __declspec (dllimport) +# endif /* !RSVG_COMPILATION */ +# else /* !RSVG_STATIC */ +# define RSVG_VAR extern +# endif /* RSVG_STATIC */ +# else /* G_PLATFORM_WIN32 */ +# define RSVG_VAR extern +# endif /* !G_PLATFORM_WIN32 */ +#endif + +#endif /* __GTK_DOC_IGNORE__ */ + +/** + * rsvg_major_version: + * + * Major version of the library. For example, for version 2.3.4, the major + * version will be 2. + * + * Since: 2.52 + */ +RSVG_VAR const guint rsvg_major_version; + +/** + * rsvg_minor_version: + * + * Minor version of the library. For example, for version 2.3.4, the minor + * version will be 3. + * + * Since: 2.52 + */ +RSVG_VAR const guint rsvg_minor_version; + +/** + * rsvg_micro_version: + * + * Micro version of the library. For example, for version 2.3.4, the micro + * version will be 4. + * + * Since: 2.52 + */ +RSVG_VAR const guint rsvg_micro_version; + +#endif diff --git a/include/rsvg-version.h.in b/include/rsvg-version.h.in new file mode 100644 index 00000000..5fe431a9 --- /dev/null +++ b/include/rsvg-version.h.in @@ -0,0 +1,13 @@ +#if !defined (__RSVG_RSVG_H_INSIDE__) && !defined (RSVG_COMPILATION) +#warning "Including directly is deprecated." +#endif + +#ifndef RSVG_VERSION_H +#define RSVG_VERSION_H + +#define LIBRSVG_MAJOR_VERSION (@LIBRSVG_MAJOR_VERSION@) +#define LIBRSVG_MINOR_VERSION (@LIBRSVG_MINOR_VERSION@) +#define LIBRSVG_MICRO_VERSION (@LIBRSVG_MICRO_VERSION@) +#define LIBRSVG_VERSION "@PACKAGE_VERSION@" + +#endif diff --git a/include/rsvg.h b/include/rsvg.h new file mode 100644 index 00000000..11b02931 --- /dev/null +++ b/include/rsvg.h @@ -0,0 +1,1462 @@ +/* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* vim: set sw=4 sts=4 expandtab: */ +/* + rsvg.h: SAX-based renderer for SVG files into a GdkPixbuf. + + Copyright (C) 2000 Eazel, Inc. + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + + Author: Raph Levien +*/ + +#ifndef RSVG_H +#define RSVG_H + +#define __RSVG_RSVG_H_INSIDE__ + +#include +#include + +#include +#include + +G_BEGIN_DECLS + +#ifndef __GTK_DOC_IGNORE__ + +/* Override to export public/semi-public APIs */ +#ifndef RSVG_API +# define RSVG_API +#endif + +#if defined(RSVG_DISABLE_DEPRECATION_WARNINGS) || !GLIB_CHECK_VERSION (2, 31, 0) +#define RSVG_DEPRECATED RSVG_API +#define RSVG_DEPRECATED_FOR(f) RSVG_API +#else +#define RSVG_DEPRECATED G_DEPRECATED RSVG_API +#define RSVG_DEPRECATED_FOR(f) G_DEPRECATED_FOR(f) RSVG_API +#endif + +#endif /* __GTK_DOC_IGNORE__ */ + +/** + * RsvgError: + * @RSVG_ERROR_FAILED: the request failed + * + * An enumeration representing possible errors + */ +typedef enum { + RSVG_ERROR_FAILED +} RsvgError; + +#define RSVG_ERROR (rsvg_error_quark ()) + +/** + * rsvg_error_quark: + * + * The error domain for RSVG + * + * Returns: The error domain + */ +RSVG_API +GQuark rsvg_error_quark (void) G_GNUC_CONST; + +RSVG_API +GType rsvg_error_get_type (void); +#define RSVG_TYPE_ERROR (rsvg_error_get_type()) + +/** + * SECTION: rsvg-handle + * @short_description: Loads SVG data into memory. + * + * This is the main entry point into the librsvg library. An RsvgHandle is an + * object that represents SVG data in memory. Your program creates an + * RsvgHandle from an SVG file, or from a memory buffer that contains SVG data, + * or in the most general form, from a #GInputStream that will provide SVG data. + * + * Librsvg can load SVG images and render them to Cairo surfaces, + * using a mixture of SVG's [static mode] and [secure static mode]. + * Librsvg does not do animation nor scripting, and can load + * references to external data only in some situations; see below. + * + * Librsvg supports reading SVG 1.1 data, and is + * gradually adding support for features in SVG 2. Librsvg also supports + * SVGZ files, which are just an SVG stream compressed with the GZIP algorithm. + * + * # The "base file" and resolving references to external files + * + * When you load an SVG, librsvg needs to know the location of the "base file" + * for it. This is so that librsvg can determine the location of referenced + * entities. For example, say you have an SVG in /foo/bar/foo.svg + * and that it has an image element like this: + * + * |[ + * + * ]| + * + * In this case, librsvg needs to know the location of the toplevel + * /foo/bar/foo.svg so that it can generate the appropriate + * reference to /foo/bar/resources/foo.png. + * + * ## Security and locations of referenced files + * + * When processing an SVG, librsvg will only load referenced files if they are + * in the same directory as the base file, or in a subdirectory of it. That is, + * if the base file is /foo/bar/baz.svg, then librsvg will + * only try to load referenced files (from SVG's + * <image> element, for example, or from content + * included through XML entities) if those files are in /foo/bar/* or in /foo/bar/*/.../*. This is so that malicious SVG files cannot include files + * that are in a directory above. + * + * The full set of rules for deciding which URLs may be loaded is as follows; + * they are applied in order. A referenced URL will not be loaded as soon as + * one of these rules fails: + * + * + * + * All data: URLs may be loaded. These are sometimes used + * to include raster image data, encoded as base-64, directly in an SVG file. + * + * + * + * All other URL schemes in references require a base URL. For + * example, this means that if you load an SVG with + * rsvg_handle_new_from_data() without calling rsvg_handle_set_base_uri(), + * then any referenced files will not be allowed (e.g. raster images to be + * loaded from other files will not work). + * + * + * + * If referenced URLs are absolute, rather than relative, then they must + * have the same scheme as the base URL. For example, if the base URL has a + * "file" scheme, then all URL references inside the SVG must + * also have the "file" scheme, or be relative references which + * will be resolved against the base URL. + * + * + * + * If referenced URLs have a "resource" scheme, that is, + * if they are included into your binary program with GLib's resource + * mechanism, they are allowed to be loaded (provided that the base URL is + * also a "resource", per the previous rule). + * + * + * + * Otherwise, non-file schemes are not allowed. For + * example, librsvg will not load http resources, to keep + * malicious SVG data from "phoning home". + * + * + * + * A relative URL must resolve to the same directory as the base URL, or to + * one of its subdirectories. Librsvg will canonicalize filenames, by + * removing ".." path components and resolving symbolic links, to decide whether + * files meet these conditions. + * + * + * + * # Loading an SVG with GIO + * + * This is the easiest and most resource-efficient way of loading SVG data into + * an #RsvgHandle. + * + * If you have a #GFile that stands for an SVG file, you can simply call + * rsvg_handle_new_from_gfile_sync() to load an RsvgHandle from it. + * + * Alternatively, if you have a #GInputStream, you can use + * rsvg_handle_new_from_stream_sync(). + * + * Both of those methods allow specifying a #GCancellable, so the loading + * process can be cancelled from another thread. + * + * ## Loading an SVG from memory + * + * If you already have SVG data in a byte buffer in memory, you can create a + * memory input stream with g_memory_input_stream_new_from_data() and feed that + * to rsvg_handle_new_from_stream_sync(). + * + * Note that in this case, it is important that you specify the base_file for + * the in-memory SVG data. Librsvg uses the base_file to resolve links to + * external content, like raster images. + * + * # Loading an SVG without GIO + * + * You can load an RsvgHandle from a simple filename or URI with + * rsvg_handle_new_from_file(). Note that this is a blocking operation; there + * is no way to cancel it if loading a remote URI takes a long time. Also, note that + * this method does not let you specify #RsvgHandleFlags. + * + * Otherwise, loading an SVG without GIO is not recommended, since librsvg will + * need to buffer your entire data internally before actually being able to + * parse it. The deprecated way of doing this is by creating a handle with + * rsvg_handle_new() or rsvg_handle_new_with_flags(), and then using + * rsvg_handle_write() and rsvg_handle_close() to feed the handle with SVG data. + * Still, please try to use the GIO stream functions instead. + * + * # Resolution of the rendered image (dots per inch, or DPI) + * + * SVG images can contain dimensions like "5 cm" or + * "2 pt" that must be converted from physical units into + * device units. To do this, librsvg needs to know the actual dots per inch + * (DPI) of your target device. You can call rsvg_handle_set_dpi() or + * rsvg_handle_set_dpi_x_y() on an RsvgHandle to set the DPI before rendering + * it. + * + * # Rendering + * + * The preferred way to render a whole SVG document is to use + * rsvg_handle_render_document(). Please see its documentation for + * details. + * + * # API ordering + * + * Due to the way the librsvg API evolved over time, an #RsvgHandle object is available + * for use as soon as it is constructed. However, not all of its methods can be + * called at any time. For example, an #RsvgHandle just constructed with rsvg_handle_new() + * is not loaded yet, and it does not make sense to call rsvg_handle_get_dimensions() on it + * just at that point. + * + * The documentation for the available methods in #RsvgHandle may mention that a particular + * method is only callable on a "fully loaded handle". This means either: + * + * + * + * The handle was loaded with rsvg_handle_write() and rsvg_handle_close(), and + * those functions returned no errors. + * + * + * The handle was loaded with rsvg_handle_read_stream_sync() and that function + * returned no errors. + * + * + * + * Before librsvg 2.46, the library did not fully verify that a handle was in a + * fully loaded state for the methods that require it. To preserve + * compatibility with old code which inadvertently called the API without + * checking for errors, or which called some methods outside of the expected + * order, librsvg will just emit a g_critical() message in those cases. + * + * New methods introduced in librsvg 2.46 and later will check for the correct + * ordering, and panic if they are called out of order. This will abort + * the program as if it had a failed assertion. + */ + +/***** Begin documentation for RsvgHandle properties *****/ + +/** + * RsvgHandle:flags: + * + * Flags from #RsvgHandleFlags. + * + * Since: 2.36 + */ + +/** + * RsvgHandle::dpi-x: + * + * Horizontal resolution in dots per inch. + */ + +/** + * RsvgHandle::dpi-y: + * + * Horizontal resolution in dots per inch. + */ + +/** + * RsvgHandle::base-uri: + * + * Base URI, to be used to resolve relative references for resources. See the section + */ + +/** + * RsvgHandle:width: + * + * Width, in pixels, of the rendered SVG after calling the size callback + * as specified by rsvg_handle_set_size_callback(). + * + * Deprecated: 2.46. For historical reasons, this property is of integer type, + * which cannot give the exact size of SVG images that are not pixel-aligned. + * Moreover, reading each of the size properties causes the size of the SVG to + * be recomputed, so reading both the width and + * height properties will cause two such computations. + * Please use rsvg_handle_get_intrinsic_dimensions() instead. + */ + +/** + * RsvgHandle:height: + * + * Height, in pixels, of the rendered SVG after calling the size callback + * as specified by rsvg_handle_set_size_callback(). + * + * Deprecated: 2.46. For historical reasons, this property is of integer type, + * which cannot give the exact size of SVG images that are not pixel-aligned. + * Moreover, reading each of the size properties causes the size of the SVG to + * be recomputed, so reading both the width and + * height properties will cause two such computations. + * Please use rsvg_handle_get_intrinsic_dimensions() instead. + */ + +/** + * RsvgHandle:em: + * + * Exact width, in pixels, of the rendered SVG before calling the size callback + * as specified by rsvg_handle_set_size_callback(). + * + * Deprecated: 2.46. Reading each of the size properties causes the size of the + * SVG to be recomputed, so reading both the em and + * ex properties will cause two such computations. Please + * use rsvg_handle_get_intrinsic_dimensions() instead. + */ + +/** + * RsvgHandle:ex: + * + * Exact height, in pixels, of the rendered SVG before calling the size callback + * as specified by rsvg_handle_set_size_callback(). + * + * Deprecated: 2.46. Reading each of the size properties causes the size of the + * SVG to be recomputed, so reading both the em and + * ex properties will cause two such computations. Please + * use rsvg_handle_get_intrinsic_dimensions() instead. + */ + +/** + * RsvgHandle:title: + * + * SVG's title. + * + * Deprecated: 2.36. Reading this property always returns #NULL. + */ + +/** + * RsvgHandle:desc: + * + * SVG's description. + * + * Deprecated: 2.36. Reading this property always returns #NULL. + */ + +/** + * RsvgHandle:metadata: + * + * SVG's metadata + * + * Deprecated: 2.36. Reading this property always returns #NULL. + */ + +/***** End documentation for RsvgHandle properties *****/ + +#define RSVG_TYPE_HANDLE (rsvg_handle_get_type ()) +#define RSVG_HANDLE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), RSVG_TYPE_HANDLE, RsvgHandle)) +#define RSVG_HANDLE_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), RSVG_TYPE_HANDLE, RsvgHandleClass)) +#define RSVG_IS_HANDLE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), RSVG_TYPE_HANDLE)) +#define RSVG_IS_HANDLE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), RSVG_TYPE_HANDLE)) +#define RSVG_HANDLE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), RSVG_TYPE_HANDLE, RsvgHandleClass)) + +RSVG_API +GType rsvg_handle_get_type (void); + +typedef struct _RsvgHandle RsvgHandle; +typedef struct _RsvgHandleClass RsvgHandleClass; +typedef struct _RsvgDimensionData RsvgDimensionData; +typedef struct _RsvgPositionData RsvgPositionData; +typedef struct _RsvgRectangle RsvgRectangle; + +/** + * RsvgHandleClass: + * @parent: parent class + * + * Class structure for #RsvgHandle. + */ +struct _RsvgHandleClass { + GObjectClass parent; + + /*< private >*/ + gpointer _abi_padding[15]; +}; + +/** + * RsvgHandle: + * + * Lets you load SVG data and render it. + */ +struct _RsvgHandle { + GObject parent; + + /*< private >*/ + + gpointer _abi_padding[16]; +}; + +/** + * RsvgDimensionData: + * @width: SVG's width, in pixels + * @height: SVG's height, in pixels + * @em: SVG's original width, unmodified by #RsvgSizeFunc + * @ex: SVG's original height, unmodified by #RsvgSizeFunc + * + * Dimensions of an SVG image from rsvg_handle_get_dimensions(), or an + * individual element from rsvg_handle_get_dimensions_sub(). Please see + * the deprecation documentation for those functions. + * + * Deprecated: 2.46. FIXME: point to deprecation documentation. + */ +struct _RsvgDimensionData { + int width; + int height; + gdouble em; + gdouble ex; +}; + +/** + * RsvgPositionData: + * @x: position on the x axis + * @y: position on the y axis + * + * Position of an SVG fragment from rsvg_handle_get_position_sub(). Please + * the deprecation documentation for that function. + * + * Deprecated: 2.46. FIXME: point to deprecation documentation. + */ +struct _RsvgPositionData { + int x; + int y; +}; + +/** + * RsvgRectangle: + * @x: X coordinate of the left side of the rectangle + * @y: Y coordinate of the the top side of the rectangle + * @width: width of the rectangle + * @height: height of the rectangle + * + * A data structure for holding a rectangle. + * + * Since: 2.46 + */ +struct _RsvgRectangle { + double x; + double y; + double width; + double height; +}; + +/** + * rsvg_cleanup: + * + * Since: 2.36 + * Deprecated: 2.46: No-op. This function should not be called from normal programs. + */ +RSVG_DEPRECATED +void rsvg_cleanup (void); + +/** + * rsvg_set_default_dpi: + * @dpi: Dots Per Inch (aka Pixels Per Inch) + * + * Do not use this function. Create an #RsvgHandle and call + * rsvg_handle_set_dpi() on it instead. + * + * Since: 2.8 + * + * Deprecated: 2.42.3: This function used to set a global default DPI. However, + * it only worked if it was called before any #RsvgHandle objects had been + * created; it would not work after that. To avoid global mutable state, please + * use rsvg_handle_set_dpi() instead. + */ +RSVG_DEPRECATED +void rsvg_set_default_dpi (double dpi); + +/** + * rsvg_set_default_dpi_x_y: + * @dpi_x: Dots Per Inch (aka Pixels Per Inch) + * @dpi_y: Dots Per Inch (aka Pixels Per Inch) + * + * Do not use this function. Create an #RsvgHandle and call + * rsvg_handle_set_dpi_x_y() on it instead. + * + * Since: 2.8 + * + * Deprecated: 2.42.3: This function used to set a global default DPI. However, + * it only worked if it was called before any #RsvgHandle objects had been + * created; it would not work after that. To avoid global mutable state, please + * use rsvg_handle_set_dpi() instead. + */ +RSVG_DEPRECATED +void rsvg_set_default_dpi_x_y (double dpi_x, double dpi_y); + +/** + * rsvg_handle_set_dpi: + * @handle: An #RsvgHandle + * @dpi: Dots Per Inch (i.e. as Pixels Per Inch) + * + * Sets the DPI at which the @handle will be rendered. Common values are + * 75, 90, and 300 DPI. + * + * Passing a number <= 0 to @dpi will reset the DPI to whatever the default + * value happens to be, but since rsvg_set_default_dpi() is deprecated, please + * do not pass values <= 0 to this function. + * + * Since: 2.8 + */ +RSVG_API +void rsvg_handle_set_dpi (RsvgHandle *handle, double dpi); + +/** + * rsvg_handle_set_dpi_x_y: + * @handle: An #RsvgHandle + * @dpi_x: Dots Per Inch (i.e. Pixels Per Inch) + * @dpi_y: Dots Per Inch (i.e. Pixels Per Inch) + * + * Sets the DPI at which the @handle will be rendered. Common values are + * 75, 90, and 300 DPI. + * + * Passing a number <= 0 to @dpi will reset the DPI to whatever the default + * value happens to be, but since rsvg_set_default_dpi_x_y() is deprecated, + * please do not pass values <= 0 to this function. + * + * Since: 2.8 + */ +RSVG_API +void rsvg_handle_set_dpi_x_y (RsvgHandle *handle, double dpi_x, double dpi_y); + +/** + * rsvg_handle_new: + * + * Returns a new rsvg handle. Must be freed with @g_object_unref. This + * handle can be used to load an image. + * + * The preferred way of loading SVG data into the returned #RsvgHandle is with + * rsvg_handle_read_stream_sync(). + * + * The deprecated way of loading SVG data is with rsvg_handle_write() and + * rsvg_handle_close(); note that these require buffering the entire file + * internally, and for this reason it is better to use the stream functions: + * rsvg_handle_new_from_stream_sync(), rsvg_handle_read_stream_sync(), or + * rsvg_handle_new_from_gfile_sync(). + * + * After loading the #RsvgHandle with data, you can render it using Cairo or get + * a GdkPixbuf from it. When finished, free the handle with g_object_unref(). No + * more than one image can be loaded with one handle. + * + * Note that this function creates an #RsvgHandle with no flags set. If you + * require any of #RsvgHandleFlags to be set, use any of + * rsvg_handle_new_with_flags(), rsvg_handle_new_from_stream_sync(), or + * rsvg_handle_new_from_gfile_sync(). + * + * Returns: A new #RsvgHandle with no flags set. + **/ +RSVG_API +RsvgHandle *rsvg_handle_new (void); + +/** + * rsvg_handle_write: + * @handle: an #RsvgHandle + * @buf: (array length=count) (element-type guchar): pointer to svg data + * @count: length of the @buf buffer in bytes + * @error: (optional): a location to store a #GError, or %NULL + * + * Loads the next @count bytes of the image. + * + * Before calling this function for the first time, you may need to call + * rsvg_handle_set_base_uri() or rsvg_handle_set_base_gfile() to set the "base + * file" for resolving references to external resources. SVG elements like + * <image> which reference external resources will be + * resolved relative to the location you specify with those functions. + * + * Returns: %TRUE on success, or %FALSE on error. + * + * Deprecated: 2.46. Use rsvg_handle_read_stream_sync() or the constructor + * functions rsvg_handle_new_from_gfile_sync() or + * rsvg_handle_new_from_stream_sync(). This function is deprecated because it + * will accumulate data from the @buf in memory until rsvg_handle_close() gets + * called. To avoid a big temporary buffer, use the suggested functions, which + * take a #GFile or a #GInputStream and do not require a temporary buffer. + **/ +RSVG_DEPRECATED_FOR(rsvg_handle_read_stream_sync) +gboolean rsvg_handle_write (RsvgHandle *handle, + const guchar *buf, + gsize count, + GError **error); + +/** + * rsvg_handle_close: + * @handle: a #RsvgHandle + * @error: (optional): a location to store a #GError, or %NULL + * + * Closes @handle, to indicate that loading the image is complete. This will + * return %TRUE if the loader closed successfully and the SVG data was parsed + * correctly. Note that @handle isn't freed until @g_object_unref is called. + * + * Returns: %TRUE on success, or %FALSE on error. + * + * Deprecated: 2.46. Use rsvg_handle_read_stream_sync() or the constructor + * functions rsvg_handle_new_from_gfile_sync() or + * rsvg_handle_new_from_stream_sync(). See the deprecation notes for + * rsvg_handle_write() for more information. + **/ +RSVG_DEPRECATED_FOR(rsvg_handle_read_stream_sync) +gboolean rsvg_handle_close (RsvgHandle *handle, GError **error); + +/** + * rsvg_handle_get_pixbuf: + * @handle: An #RsvgHandle + * + * Returns the pixbuf loaded by @handle. The pixbuf returned will be reffed, so + * the caller of this function must assume that ref. If insufficient data has + * been read to create the pixbuf, or an error occurred in loading, then %NULL + * will be returned. Note that the pixbuf may not be complete until + * @rsvg_handle_close has been called. + * + * This function depends on the #RsvgHandle's DPI to compute dimensions in + * pixels, so you should call rsvg_handle_set_dpi() beforehand. + * + * Returns: (transfer full) (nullable): the pixbuf loaded by @handle, or %NULL. + **/ +RSVG_API +GdkPixbuf *rsvg_handle_get_pixbuf (RsvgHandle *handle); + +/** + * rsvg_handle_get_pixbuf_sub: + * @handle: An #RsvgHandle + * @id: (nullable): An element's id within the SVG, starting with "##" (a single + * hash character), for example, "##layer1". This notation corresponds to a + * URL's fragment ID. Alternatively, pass %NULL to use the whole SVG. + * + * Creates a #GdkPixbuf the same size as the entire SVG loaded into @handle, but + * only renders the sub-element that has the specified @id (and all its + * sub-sub-elements recursively). If @id is #NULL, this function renders the + * whole SVG. + * + * This function depends on the #RsvgHandle's DPI to compute dimensions in + * pixels, so you should call rsvg_handle_set_dpi() beforehand. + * + * If you need to render an image which is only big enough to fit a particular + * sub-element of the SVG, consider using rsvg_handle_render_cairo_sub(), upon a + * surface that is just the size returned by rsvg_handle_get_dimensions_sub(). + * You will need to offset the rendering by the amount returned in + * rsvg_handle_get_position_sub(). + * + * Element IDs should look like an URL fragment identifier; for example, pass + * "##foo" (hash foo) to get the geometry of the element that + * has an id="foo" attribute. + * + * Returns: (transfer full) (nullable): a pixbuf, or %NULL if an error occurs + * during rendering. + * + * Since: 2.14 + **/ +RSVG_API +GdkPixbuf *rsvg_handle_get_pixbuf_sub (RsvgHandle *handle, const char *id); + +/** + * rsvg_handle_get_base_uri: + * @handle: A #RsvgHandle + * + * Gets the base uri for this #RsvgHandle. + * + * Returns: the base uri, possibly null + * Since: 2.8 + */ +RSVG_API +const char *rsvg_handle_get_base_uri (RsvgHandle *handle); + +/** + * rsvg_handle_set_base_uri: + * @handle: A #RsvgHandle + * @base_uri: The base uri + * + * Set the base URI for this SVG. + * + * Note: This function may only be called before rsvg_handle_write() or + * rsvg_handle_read_stream_sync() have been called. + * + * Since: 2.9 + */ +RSVG_API +void rsvg_handle_set_base_uri (RsvgHandle *handle, const char *base_uri); + +/** + * rsvg_handle_get_dimensions: + * @handle: A #RsvgHandle + * @dimension_data: (out): A place to store the SVG's size + * + * Get the SVG's size. Do not call from within the size_func callback, because + * an infinite loop will occur. + * + * This function depends on the #RsvgHandle's DPI to compute dimensions in + * pixels, so you should call rsvg_handle_set_dpi() beforehand. + * + * Since: 2.14 + */ +RSVG_API +void rsvg_handle_get_dimensions (RsvgHandle *handle, RsvgDimensionData *dimension_data); + +/** + * rsvg_handle_get_dimensions_sub: + * @handle: A #RsvgHandle + * @dimension_data: (out): A place to store the SVG's size + * @id: (nullable): An element's id within the SVG, starting with "##" (a single + * hash character), for example, "##layer1". This notation corresponds to a + * URL's fragment ID. Alternatively, pass %NULL to use the whole SVG. + * + * Get the size of a subelement of the SVG file. Do not call from within the + * size_func callback, because an infinite loop will occur. + * + * This function depends on the #RsvgHandle's DPI to compute dimensions in + * pixels, so you should call rsvg_handle_set_dpi() beforehand. + * + * Element IDs should look like an URL fragment identifier; for example, pass + * "##foo" (hash foo) to get the geometry of the element that + * has an id="foo" attribute. + * + * Deprecated: 2.46. Use rsvg_handle_get_geometry_for_layer() instead. + * + * Since: 2.22 + */ +RSVG_DEPRECATED_FOR(rsvg_handle_get_geometry_for_layer) +gboolean rsvg_handle_get_dimensions_sub (RsvgHandle *handle, + RsvgDimensionData *dimension_data, + const char *id); + +/** + * rsvg_handle_get_position_sub: + * @handle: A #RsvgHandle + * @position_data: (out): A place to store the SVG fragment's position. + * @id: (nullable): An element's id within the SVG, starting with "##" (a single + * hash character), for example, "##layer1". This notation corresponds to a + * URL's fragment ID. Alternatively, pass %NULL to use the whole SVG. + * + * Get the position of a subelement of the SVG file. Do not call from within + * the size_func callback, because an infinite loop will occur. + * + * This function depends on the #RsvgHandle's DPI to compute dimensions in + * pixels, so you should call rsvg_handle_set_dpi() beforehand. + * + * Element IDs should look like an URL fragment identifier; for example, pass + * "##foo" (hash foo) to get the geometry of the element that + * has an id="foo" attribute. + * + * Deprecated: 2.46. Use rsvg_handle_get_geometry_for_layer() instead. + * + * Since: 2.22 + */ +RSVG_DEPRECATED_FOR(rsvg_handle_get_geometry_for_layer) +gboolean rsvg_handle_get_position_sub (RsvgHandle *handle, + RsvgPositionData *position_data, + const char *id); + +/** + * rsvg_handle_has_sub: + * @handle: a #RsvgHandle + * @id: An element's id within the SVG, starting with "##" (a single hash + * character), for example, "##layer1". This notation corresponds to a URL's + * fragment ID. + * + * Checks whether the element @id exists in the SVG document. + * + * Element IDs should look like an URL fragment identifier; for example, pass + * "##foo" (hash foo) to get the geometry of the element that + * has an id="foo" attribute. + * + * Returns: %TRUE if @id exists in the SVG document, %FALSE otherwise. + * + * Since: 2.22 + */ +RSVG_API +gboolean rsvg_handle_has_sub (RsvgHandle *handle, const char *id); + +/** + * RsvgUnit: + * @RSVG_UNIT_PERCENT: percentage values; where 1.0 means 100%. + * @RSVG_UNIT_PX: pixels + * @RSVG_UNIT_EM: em, or the current font size + * @RSVG_UNIT_EX: x-height of the current font + * @RSVG_UNIT_IN: inches + * @RSVG_UNIT_CM: centimeters + * @RSVG_UNIT_MM: millimeters + * @RSVG_UNIT_PT: points, or 1/72 inch + * @RSVG_UNIT_PC: picas, or 1/6 inch (12 points) + * + * Units for the #RsvgLength struct. These have the same meaning as CSS length + * units. + */ +typedef enum { + RSVG_UNIT_PERCENT, + RSVG_UNIT_PX, + RSVG_UNIT_EM, + RSVG_UNIT_EX, + RSVG_UNIT_IN, + RSVG_UNIT_CM, + RSVG_UNIT_MM, + RSVG_UNIT_PT, + RSVG_UNIT_PC +} RsvgUnit; + +/** + * RsvgLength: + * @length: numeric part of the length + * @unit: unit part of the length + * + * #RsvgLength values are used in rsvg_handle_get_intrinsic_dimensions(), for + * example, to return the CSS length values of the width and + * height attributes of an <svg> + * element. + * + * This is equivalent to CSS lengths. + * + * It is up to the calling application to convert lengths in non-pixel units + * (i.e. those where the @unit field is not #RSVG_UNIT_PX) into something + * meaningful to the application. For example, if your application knows the + * dots-per-inch (DPI) it is using, it can convert lengths with @unit in + * #RSVG_UNIT_IN or other physical units. + */ +typedef struct { + double length; + RsvgUnit unit; +} RsvgLength; + +/** + * rsvg_handle_get_intrinsic_dimensions: + * @handle: An #RsvgHandle + * @out_has_width: (out)(optional): Will be set to #TRUE if the toplevel SVG has a width attribute + * @out_width: (out)(optional): Will be set to the value of the width attribute in the toplevel SVG + * @out_has_height: (out)(optional): Will be set to #TRUE if the toplevel SVG has a height attribute + * @out_height: (out)(optional): Will be set to the value of the height attribute in the toplevel SVG + * @out_has_viewbox: (out)(optional): Will be set to #TRUE if the toplevel SVG has a viewBox attribute + * @out_viewbox: (out)(optional): Will be set to the value of the viewBox attribute in the toplevel SVG + * + * Queries the width, height, and + * viewBox attributes in an SVG document. + * + * If you are calling this function to compute a scaling factor to render the SVG, + * consider simply using rsvg_handle_render_document() instead; it will do the + * scaling computations automatically. + * + * As an example, the following SVG element has a width of 100 pixels and a height of 400 pixels, but no viewBox: + * + * |[ + * + * ]| + * + * Conversely, the following element has a viewBox, but no width or height: + * + * |[ + * + * ]| + * + * Note that the #RsvgLength return values have #RsvgUnits in them; you should + * not assume that they are always in pixels. For example, the following SVG element + * will return a width value whose units field is RSVG_UNIT_MM. + * + * |[ + * + * ]| + * + * API ordering: This function must be called on a fully-loaded @handle. See + * the section API ordering for details. + * + * Panics: this function will panic if the @handle is not fully-loaded. + * + * Since: 2.46 + */ +RSVG_API +void rsvg_handle_get_intrinsic_dimensions (RsvgHandle *handle, + gboolean *out_has_width, + RsvgLength *out_width, + gboolean *out_has_height, + RsvgLength *out_height, + gboolean *out_has_viewbox, + RsvgRectangle *out_viewbox); + +/** + * rsvg_handle_get_intrinsic_size_in_pixels: + * @handle: An #RsvgHandle + * @out_width: (out)(optional): Will be set to the computed width + * @out_height: (out)(optional): Will be set to the computed height + * + * Converts an SVG document's intrinsic dimensions to pixels, and returns the result. + * + * This function is able to extract the size in pixels from an SVG document if the + * document has both width and height attributes + * with physical units (px, in, cm, mm, pt, pc) or font-based units (em, ex). For + * physical units, the dimensions are normalized to pixels using the dots-per-inch (DPI) + * value set previously with rsvg_handle_set_dpi(). For font-based units, this function + * uses the computed value of the `font-size` property for the toplevel + * <svg> element. In those cases, this function returns %TRUE. + * + * This function is not able to extract the size in pixels directly from the intrinsic + * dimensions of the SVG document if the width or + * height are in percentage units (or if they do not exist, in which + * case the SVG spec mandates that they default to 100%), as these require a + * viewport to be resolved to a final size. In this case, the + * function returns %FALSE. + * + * For example, the following document fragment has intrinsic dimensions that will resolve + * to 20x30 pixels. + * + * |[ + * + * ]| + * + * Similarly, if the DPI is set to 96, this document will resolve to 192x288 pixels (i.e. 96*2 x 96*3). + * + * |[ + * + * ]| + * + * The dimensions of the following documents cannot be resolved to pixels directly, and + * this function would return %FALSE for them: + * + * |[ + * + * + * + * + * + * ]| + * + * + * Returns: %TRUE if the dimensions could be converted directly to pixels; in this case + * @out_width and @out_height will be set accordingly. If the dimensions cannot be converted + * to pixels, returns %FALSE and puts 0.0 in both @out_width and @out_height. + * + * Since: 2.52 + */ +RSVG_API +gboolean rsvg_handle_get_intrinsic_size_in_pixels (RsvgHandle *handle, + gdouble *out_width, + gdouble *out_height); + +/* GIO APIs */ + +/** + * RsvgHandleFlags: + * @RSVG_HANDLE_FLAGS_NONE: No flags are set. + * @RSVG_HANDLE_FLAG_UNLIMITED: Disable safety limits in the XML parser. + * Libxml2 has several + * limits designed to keep malicious XML content from consuming too + * much memory while parsing. For security reasons, this should only be used + * for trusted input! + * Since: 2.40.3 + * @RSVG_HANDLE_FLAG_KEEP_IMAGE_DATA: Use this if the Cairo surface to which you + * are rendering is a PDF, PostScript, SVG, or Win32 Printing surface. This + * will make librsvg and Cairo use the original, compressed data for images in + * the final output, instead of passing uncompressed images. This will make a + * Keeps the image data when loading images, for use by cairo when painting to + * e.g. a PDF surface. For example, this will make the a resulting PDF file + * smaller and faster. Please see the + * Cairo documentation for details. + * Since: 2.40.3 + */ +typedef enum /*< flags >*/ +{ + RSVG_HANDLE_FLAGS_NONE = 0, + RSVG_HANDLE_FLAG_UNLIMITED = 1 << 0, + RSVG_HANDLE_FLAG_KEEP_IMAGE_DATA = 1 << 1 +} RsvgHandleFlags; + +RSVG_API +GType rsvg_handle_flags_get_type (void); +#define RSVG_TYPE_HANDLE_FLAGS (rsvg_handle_flags_get_type()) + +/** + * rsvg_handle_new_with_flags: + * @flags: flags from #RsvgHandleFlags + * + * Creates a new #RsvgHandle with flags @flags. After calling this function, + * you can feed the resulting handle with SVG data by using + * rsvg_handle_read_stream_sync(). + * + * Returns: (transfer full): a new #RsvgHandle + * + * Since: 2.36 + **/ +RSVG_API +RsvgHandle *rsvg_handle_new_with_flags (RsvgHandleFlags flags); + +/** + * rsvg_handle_set_base_gfile: + * @handle: a #RsvgHandle + * @base_file: a #GFile + * + * Set the base URI for @handle from @file. + * + * Note: This function may only be called before rsvg_handle_write() or + * rsvg_handle_read_stream_sync() have been called. + * + * Since: 2.32 + */ +RSVG_API +void rsvg_handle_set_base_gfile (RsvgHandle *handle, + GFile *base_file); + +/** + * rsvg_handle_read_stream_sync: + * @handle: a #RsvgHandle + * @stream: a #GInputStream + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: (optional): a location to store a #GError, or %NULL + * + * Reads @stream and writes the data from it to @handle. + * + * Before calling this function, you may need to call rsvg_handle_set_base_uri() + * or rsvg_handle_set_base_gfile() to set the "base file" for resolving + * references to external resources. SVG elements like + * <image> which reference external resources will be + * resolved relative to the location you specify with those functions. + * + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the + * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be + * returned. + * + * Returns: %TRUE if reading @stream succeeded, or %FALSE otherwise + * with @error filled in + * + * Since: 2.32 + */ +RSVG_API +gboolean rsvg_handle_read_stream_sync (RsvgHandle *handle, + GInputStream *stream, + GCancellable *cancellable, + GError **error); + +/** + * rsvg_handle_new_from_gfile_sync: + * @file: a #GFile + * @flags: flags from #RsvgHandleFlags + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: (optional): a location to store a #GError, or %NULL + * + * Creates a new #RsvgHandle for @file. + * + * This function sets the "base file" of the handle to be @file itself, so SVG + * elements like <image> which reference external + * resources will be resolved relative to the location of @file. + * + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the + * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be + * returned in @error. + * + * Returns: a new #RsvgHandle on success, or %NULL with @error filled in + * + * Since: 2.32 + */ +RSVG_API +RsvgHandle *rsvg_handle_new_from_gfile_sync (GFile *file, + RsvgHandleFlags flags, + GCancellable *cancellable, + GError **error); + +/** + * rsvg_handle_new_from_stream_sync: + * @input_stream: a #GInputStream + * @base_file: (nullable): a #GFile, or %NULL + * @flags: flags from #RsvgHandleFlags + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: (optional): a location to store a #GError, or %NULL + * + * Creates a new #RsvgHandle for @stream. + * + * This function sets the "base file" of the handle to be @base_file if + * provided. SVG elements like <image> which reference + * external resources will be resolved relative to the location of @base_file. + * + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the + * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be + * returned in @error. + * + * Returns: a new #RsvgHandle on success, or %NULL with @error filled in + * + * Since: 2.32 + */ +RSVG_API +RsvgHandle *rsvg_handle_new_from_stream_sync (GInputStream *input_stream, + GFile *base_file, + RsvgHandleFlags flags, + GCancellable *cancellable, + GError **error); + +/** + * rsvg_handle_new_from_data: + * @data: (array length=data_len): The SVG data + * @data_len: The length of @data, in bytes + * @error: (optional): return location for errors + * + * Loads the SVG specified by @data. Note that this function creates an + * #RsvgHandle without a base URL, and without any #RsvgHandleFlags. If you + * need these, use rsvg_handle_new_from_stream_sync() instead by creating + * a #GMemoryInputStream from your data. + * + * Returns: A #RsvgHandle or %NULL if an error occurs. + * Since: 2.14 + */ +RSVG_API +RsvgHandle *rsvg_handle_new_from_data (const guint8 *data, gsize data_len, GError **error); + +/** + * rsvg_handle_new_from_file: + * @filename: The file name to load, or a URI. + * @error: (optional): return location for errors + * + * Loads the SVG specified by @file_name. Note that this function, like + * rsvg_handle_new(), does not specify any loading flags for the resulting + * handle. If you require the use of #RsvgHandleFlags, use + * rsvg_handle_new_from_gfile_sync(). + * + * Returns: A #RsvgHandle or %NULL if an error occurs. + * Since: 2.14 + */ +RSVG_API +RsvgHandle *rsvg_handle_new_from_file (const gchar *filename, GError **error); + +/** + * rsvg_handle_set_stylesheet: + * @handle: A #RsvgHandle. + * @css: (array length=css_len): String with CSS data; must be valid UTF-8. + * @css_len: Length of the @css data in bytes. + * @error: (optional): return location for errors. + * + * Sets a CSS stylesheet to use for an SVG document. + * + * The @css_len argument is mandatory; this function will not compute the length + * of the @css string. This is because a provided stylesheet, which the calling + * program could read from a file, can have nul characters in it. + * + * During the CSS cascade, the specified stylesheet will be used with a "User" + * origin. + * + * Note that `@import` rules will not be resolved, except for `data:` URLs. + * + * Since: 2.48 + */ +RSVG_API +gboolean rsvg_handle_set_stylesheet (RsvgHandle *handle, + const guint8 *css, + gsize css_len, + GError **error); + +#ifndef __GTK_DOC_IGNORE__ +/** + * rsvg_handle_internal_set_testing: + * @handle: a #RsvgHandle + * @testing: Whether to enable testing mode + * + * Do not call this function. This is intended for librsvg's internal + * test suite only. + **/ +RSVG_API +void rsvg_handle_internal_set_testing (RsvgHandle *handle, gboolean testing); +#endif /* __GTK_DOC_IGNORE__ */ + +/* BEGIN deprecated APIs. Do not use! */ + +#ifndef __GI_SCANNER__ + +/** + * rsvg_init: + * + * This function does nothing. + * + * Since: 2.9 + * Deprecated: 2.36: There is no need to initialize librsvg. + **/ +RSVG_DEPRECATED_FOR(g_type_init) +void rsvg_init (void); + +/** + * rsvg_term: + * + * This function does nothing. + * + * Since: 2.9 + * Deprecated: 2.36: There is no need to de-initialize librsvg. + **/ +RSVG_DEPRECATED +void rsvg_term (void); + +/** + * rsvg_handle_free: + * @handle: An #RsvgHandle + * + * Frees @handle. + * Deprecated: Use g_object_unref() instead. + **/ +RSVG_DEPRECATED_FOR(g_object_unref) +void rsvg_handle_free (RsvgHandle *handle); + +/** + * RsvgSizeFunc: + * @width: (out): the width of the SVG + * @height: (out): the height of the SVG + * @user_data: user data + * + * Function to let a user of the library specify the SVG's dimensions + * + * Deprecated: 2.14. Set up a cairo matrix and use rsvg_handle_render_cairo() instead. + * See the documentation for rsvg_handle_set_size_callback() for an example, and + * for the reasons for deprecation. + */ +typedef void (*RsvgSizeFunc) (gint * width, gint * height, gpointer user_data); + +/** + * rsvg_handle_set_size_callback: + * @handle: An #RsvgHandle + * @size_func: (nullable): A sizing function, or %NULL + * @user_data: User data to pass to @size_func, or %NULL + * @user_data_destroy: Function to be called to destroy the data passed in @user_data, + * or %NULL. + * + * Sets the sizing function for the @handle, which can be used to override the + * size that librsvg computes for SVG images. The @size_func is called from the + * following functions: + * + * + * rsvg_handle_get_dimensions() + * rsvg_handle_get_dimensions_sub() + * rsvg_handle_get_position_sub() + * rsvg_handle_render_cairo() + * rsvg_handle_render_cairo_sub() + * + * + * Librsvg computes the size of the SVG being rendered, and passes it to the + * @size_func, which may then modify these values to set the final size of the + * generated image. + * + * Deprecated: 2.14. Set up a cairo matrix and use rsvg_handle_render_cairo() instead. + * You can call rsvg_handle_get_dimensions() to figure out the size of your SVG, + * and then scale it to the desired size via Cairo. For example, the following + * code renders an SVG at a specified size, scaled proportionally from whatever + * original size it may have had: + * + * |[ + * void + * render_scaled_proportionally (RsvgHandle *handle, cairo_t cr, int width, int height) + * { + * RsvgDimensionData dimensions; + * double x_factor, y_factor; + * double scale_factor; + * + * rsvg_handle_get_dimensions (handle, &dimensions); + * + * x_factor = (double) width / dimensions.width; + * y_factor = (double) height / dimensions.height; + * + * scale_factor = MIN (x_factor, y_factor); + * + * cairo_scale (cr, scale_factor, scale_factor); + * + * rsvg_handle_render_cairo (handle, cr); + * } + * ]| + * + * This function was deprecated because when the @size_func is used, it makes it + * unclear when the librsvg functions which call the @size_func will use the + * size computed originally, or the callback-specified size, or whether it + * refers to the whole SVG or to just a sub-element of it. It is easier, and + * unambiguous, to use code similar to the example above. + **/ +RSVG_DEPRECATED +void rsvg_handle_set_size_callback (RsvgHandle *handle, + RsvgSizeFunc size_func, + gpointer user_data, + GDestroyNotify user_data_destroy); + +/* GdkPixbuf convenience API */ + +/** + * SECTION: rsvg-pixbuf + * @short_description: How to render SVGs into GdkPixbufs, for easy use in GTK+ + * applications + * + * GdkPixbuf is a library for image loading and manipulation. It is part of the + * cross-platform GTK+ widget toolkit. + */ + +/** + * rsvg_pixbuf_from_file: + * @filename: A file name + * @error: return location for errors + * + * Loads a new #GdkPixbuf from @filename and returns it. The caller must + * assume the reference to the reurned pixbuf. If an error occurred, @error is + * set and %NULL is returned. + * + * Return value: A newly allocated #GdkPixbuf, or %NULL + * Deprecated: Set up a cairo matrix and use rsvg_handle_new_from_file() + rsvg_handle_render_cairo() instead. + **/ +RSVG_DEPRECATED +GdkPixbuf *rsvg_pixbuf_from_file (const gchar *filename, + GError **error); + +/** + * rsvg_pixbuf_from_file_at_zoom: + * @filename: A file name + * @x_zoom: The horizontal zoom factor + * @y_zoom: The vertical zoom factor + * @error: return location for errors + * + * Loads a new #GdkPixbuf from @filename and returns it. This pixbuf is scaled + * from the size indicated by the file by a factor of @x_zoom and @y_zoom. The + * caller must assume the reference to the returned pixbuf. If an error + * occurred, @error is set and %NULL is returned. + * + * Return value: A newly allocated #GdkPixbuf, or %NULL + * Deprecated: Set up a cairo matrix and use rsvg_handle_new_from_file() + rsvg_handle_render_cairo() instead. + **/ +RSVG_DEPRECATED +GdkPixbuf *rsvg_pixbuf_from_file_at_zoom (const gchar *filename, + double x_zoom, + double y_zoom, + GError **error); + +/** + * rsvg_pixbuf_from_file_at_size: + * @filename: A file name + * @width: The new width, or -1 + * @height: The new height, or -1 + * @error: return location for errors + * + * Loads a new #GdkPixbuf from @filename and returns it. This pixbuf is scaled + * from the size indicated to the new size indicated by @width and @height. If + * both of these are -1, then the default size of the image being loaded is + * used. The caller must assume the reference to the returned pixbuf. If an + * error occurred, @error is set and %NULL is returned. + * + * Return value: A newly allocated #GdkPixbuf, or %NULL + * Deprecated: Set up a cairo matrix and use rsvg_handle_new_from_file() + rsvg_handle_render_cairo() instead. + **/ +RSVG_DEPRECATED +GdkPixbuf *rsvg_pixbuf_from_file_at_size (const gchar *filename, + gint width, + gint height, + GError **error); + +/** + * rsvg_pixbuf_from_file_at_max_size: + * @filename: A file name + * @max_width: The requested max width + * @max_height: The requested max height + * @error: return location for errors + * + * Loads a new #GdkPixbuf from @filename and returns it. This pixbuf is uniformly + * scaled so that the it fits into a rectangle of size max_width * max_height. The + * caller must assume the reference to the returned pixbuf. If an error occurred, + * @error is set and %NULL is returned. + * + * Return value: A newly allocated #GdkPixbuf, or %NULL + * Deprecated: Set up a cairo matrix and use rsvg_handle_new_from_file() + rsvg_handle_render_cairo() instead. + **/ +RSVG_DEPRECATED +GdkPixbuf *rsvg_pixbuf_from_file_at_max_size (const gchar *filename, + gint max_width, + gint max_height, + GError **error); +/** + * rsvg_pixbuf_from_file_at_zoom_with_max: + * @filename: A file name + * @x_zoom: The horizontal zoom factor + * @y_zoom: The vertical zoom factor + * @max_width: The requested max width + * @max_height: The requested max height + * @error: return location for errors + * + * Loads a new #GdkPixbuf from @filename and returns it. This pixbuf is scaled + * from the size indicated by the file by a factor of @x_zoom and @y_zoom. If the + * resulting pixbuf would be larger than max_width/max_heigh it is uniformly scaled + * down to fit in that rectangle. The caller must assume the reference to the + * returned pixbuf. If an error occurred, @error is set and %NULL is returned. + * + * Return value: A newly allocated #GdkPixbuf, or %NULL + * Deprecated: Set up a cairo matrix and use rsvg_handle_new_from_file() + rsvg_handle_render_cairo() instead. + **/ +RSVG_DEPRECATED +GdkPixbuf *rsvg_pixbuf_from_file_at_zoom_with_max (const gchar *filename, + double x_zoom, + double y_zoom, + gint max_width, + gint max_height, + GError **error); + +/** + * rsvg_handle_get_title: + * @handle: An #RsvgHandle + * + * Returns: (nullable): This function always returns NULL. + * + * Since: 2.4 + * + * Deprecated: 2.36. Librsvg does not read the metadata/desc/title elements; + * this function always returns #NULL. + */ +RSVG_DEPRECATED +const char *rsvg_handle_get_title (RsvgHandle *handle); + +/** + * rsvg_handle_get_desc: + * @handle: An #RsvgHandle + * + * Returns: (nullable): This function always returns NULL. + * + * Since: 2.4 + * + * Deprecated: 2.36. Librsvg does not read the metadata/desc/title elements; + * this function always returns #NULL. + */ +RSVG_DEPRECATED +const char *rsvg_handle_get_desc (RsvgHandle *handle); + +/** + * rsvg_handle_get_metadata: + * @handle: An #RsvgHandle + * + * Returns: (nullable): This function always returns #NULL. + * + * Since: 2.9 + * + * Deprecated: 2.36. Librsvg does not read the metadata/desc/title elements; + * this function always returns #NULL. + */ +RSVG_DEPRECATED +const char *rsvg_handle_get_metadata (RsvgHandle *handle); + +#endif /* !__GI_SCANNER__ */ + +/* END deprecated APIs. */ + +G_END_DECLS + +#include "rsvg-features.h" +#include "rsvg-version.h" +#include "rsvg-cairo.h" + +#undef __RSVG_RSVG_H_INSIDE__ + +#endif /* RSVG_H */ -- cgit v1.2.1