From 0a670deb9cddadde1fb37635edb166d822e9690b Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sat, 20 Mar 2021 19:04:56 +0000 Subject: docs: Fix the deprecation annotation for AlphaMode The syntax is "Deprecated: version: message". --- gdk-pixbuf/gdk-pixbuf-core.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gdk-pixbuf/gdk-pixbuf-core.h b/gdk-pixbuf/gdk-pixbuf-core.h index 9e6ba6fab..e03357d71 100644 --- a/gdk-pixbuf/gdk-pixbuf-core.h +++ b/gdk-pixbuf/gdk-pixbuf-core.h @@ -54,7 +54,7 @@ G_BEGIN_DECLS * compositing onto arbitrary drawables. For now both cases fall * back to a bilevel clipping mask. * - * Deprecated: it is unused since 2.42. + * Deprecated: 2.42: There is no user of GdkPixbufAlphaMode */ typedef enum { -- cgit v1.2.1 From 073a947e9f11236ea0c7f4fcbcb12ad4e35b7a29 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sat, 20 Mar 2021 19:15:15 +0000 Subject: Fix inclusion guards for gdk-pixbuf-features.h Use the idiomatic form: #ifndef __FOO_H__ #define __FOO_H__ ... #endif /* __FOO_H__ */ --- gdk-pixbuf/gdk-pixbuf-features.h.in | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/gdk-pixbuf/gdk-pixbuf-features.h.in b/gdk-pixbuf/gdk-pixbuf-features.h.in index 4fdb6bffa..7efdc0e39 100644 --- a/gdk-pixbuf/gdk-pixbuf-features.h.in +++ b/gdk-pixbuf/gdk-pixbuf-features.h.in @@ -1,10 +1,10 @@ +#ifndef __GDK_PIXBUF_FEATURES_H__ +#define __GDK_PIXBUF_FEATURES_H__ + #if defined(GDK_PIXBUF_DISABLE_SINGLE_INCLUDES) && !defined (GDK_PIXBUF_H_INSIDE) && !defined (GDK_PIXBUF_COMPILATION) #error "Only can be included directly." #endif -#ifndef GDK_PIXBUF_FEATURES_H -#define GDK_PIXBUF_FEATURES_H 1 - #include /** @@ -120,4 +120,4 @@ GDK_PIXBUF_VAR const guint gdk_pixbuf_minor_version; GDK_PIXBUF_VAR const guint gdk_pixbuf_micro_version; GDK_PIXBUF_VAR const char *gdk_pixbuf_version; -#endif /* GDK_PIXBUF_FEATURES_H */ +#endif /* __GDK_PIXBUF_FEATURES_H__ */ -- cgit v1.2.1 From 0c545e3f4e3fc321b6e8aea796871d3edceff685 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sat, 20 Mar 2021 19:17:15 +0000 Subject: Port gdk-pixbuf to gi-docgen Follow in the steps of Pango and GTK. --- docs/gdk-pixbuf-from-drawables.xml | 26 ----- docs/gdk-pixbuf-rendering.xml | 26 ----- docs/gdk-pixbuf.toml.in | 126 ++++++++++++++++++++ docs/gdk-pixbuf.xml | 229 ------------------------------------- docs/meson.build | 96 ++++++---------- docs/urlmap.js | 13 +++ docs/version.xml.in | 1 - subprojects/gi-docgen.wrap | 6 + 8 files changed, 182 insertions(+), 341 deletions(-) delete mode 100644 docs/gdk-pixbuf-from-drawables.xml delete mode 100644 docs/gdk-pixbuf-rendering.xml create mode 100644 docs/gdk-pixbuf.toml.in delete mode 100644 docs/gdk-pixbuf.xml create mode 100644 docs/urlmap.js delete mode 100644 docs/version.xml.in create mode 100644 subprojects/gi-docgen.wrap diff --git a/docs/gdk-pixbuf-from-drawables.xml b/docs/gdk-pixbuf-from-drawables.xml deleted file mode 100644 index 99fe3be07..000000000 --- a/docs/gdk-pixbuf-from-drawables.xml +++ /dev/null @@ -1,26 +0,0 @@ - - - - -Drawables to Pixbufs -3 -GDK-PIXBUF Library - - - -Drawables to PixbufsGetting parts of a GDK drawable's image data into a pixbuf. - - - -Description - - The functions to take the image data from a GDK windowing system surface - and store them into a GdkPixbuf are provided by GDK; see - the - GDK documentation. - - - - diff --git a/docs/gdk-pixbuf-rendering.xml b/docs/gdk-pixbuf-rendering.xml deleted file mode 100644 index 26c8776cc..000000000 --- a/docs/gdk-pixbuf-rendering.xml +++ /dev/null @@ -1,26 +0,0 @@ - - - - -Rendering -3 -GDK-PIXBUF Library - - - -RenderingRendering a pixbuf to a GDK drawable. - - - - -Description - - The functions to render pixbufs to GDK drawables are provided by GDK, see - the GDK - documentation. - - - - diff --git a/docs/gdk-pixbuf.toml.in b/docs/gdk-pixbuf.toml.in new file mode 100644 index 000000000..50299e5fd --- /dev/null +++ b/docs/gdk-pixbuf.toml.in @@ -0,0 +1,126 @@ +# SPDX-FileCopyrightText: 2021 GNOME Foundation +# +# SPDX-License-Identifier: CC0-1.0 + +[library] +name = "gdk-pixbuf" +version = "@VERSION@" +browse_url = "https://gitlab.gnome.org/GNOME/gdk-pixbuf/" +repository_url = "https://gitlab.gnome.org/GNOME/gdk-pixbuf.git" +website_url = "https://www.gtk.org" +authors = "GTK Development Team" +license = "GPL-2.1-or-later" +description = "Image loading library" +dependencies = [ "gobject", "gio" ] +devhelp = true +search_index = true + + [dependencies.gobject] + name = "GObject" + description = "The base type system library" + docs_url = "https://developer.gnome.org/gobject/stable" + + [dependencies.gio] + name = "GIO" + description = "GObject Interfaces and Objects" + docs_url = "https://developer.gnome.org/gio/stable" + +[theme] +name = "basic" +show_index_summary = true + +[source-location] +base_url = "https://gitlab.gnome.org/GNOME/gdk-pixbuf/-/blob/master/" + +[extra] +urlmap_file = "urlmap.js" +content_images = [ + 'apple-red-1a.png', + 'apple-red-2c.png', + 'composite.png', + 'gnome-gmush-1.png', +] + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_0_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_2_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_4_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_6_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_8_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_10_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_12_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_14_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_16_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_18_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_20_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_22_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_24_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_26_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_28_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_30_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_32_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_34_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_36_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_38_FOR" +hidden = true + +[[object]] +name = "PIXBUF_DEPRECATED_IN_2_40_FOR" +hidden = true diff --git a/docs/gdk-pixbuf.xml b/docs/gdk-pixbuf.xml deleted file mode 100644 index efe977bdd..000000000 --- a/docs/gdk-pixbuf.xml +++ /dev/null @@ -1,229 +0,0 @@ - - - -]> - - - GDK-PixBuf Reference Manual - - Version &version; - The latest version of this documentation can be found on-line at - http://library.gnome.org/devel/gdk-pixbuf/unstable/. - - - - Federico - Mena Quintero - -
- federico@gimp.org -
- - - - - - 2000 - The Free Software Foundation - - - - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free - Documentation License, Version 1.1 or any later - version published by the Free Software Foundation with no - Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. You may obtain a copy of the GNU Free - Documentation License from the Free Software - Foundation by visiting their Web site or by writing - to: - -
- The Free Software Foundation, Inc., - 59 Temple Place - Suite 330, - Boston, MA 02111-1307, - USA -
- - - - Many of the names used by companies to distinguish their - products and services are claimed as trademarks. Where those - names appear in any GNOME documentation, and those trademarks - are made aware to the members of the GNOME Documentation - Project, the names have been printed in caps or initial caps. - - - - - - API Reference - - - - This part presents the class and function reference for the - gdk-pixbuf library. Classes are described together with - their methods; individual functions are grouped by functional - group. - - - - - - - - - - - - - - - - - Loadable modules - - - - - - GDK integration (deprecated) - - - - - - - Tools Reference - - - - This part presents the tools which are shipped with the gdk-pixbuf library. - - - - - - - - - Index of all symbols - - - - Index of deprecated symbols - - - - Index of new symbols in 2.2 - - - - Index of new symbols in 2.4 - - - - Index of new symbols in 2.6 - - - - Index of new symbols in 2.8 - - - - Index of new symbols in 2.12 - - - - Index of new symbols in 2.14 - - - - Index of new symbols in 2.18 - - - - Index of new symbols in 2.22 - - - - Index of new symbols in 2.24 - - - - Index of new symbols in 2.26 - - - - Index of new symbols in 2.28 - - - - Index of new symbols in 2.30 - - - - Index of new symbols in 2.32 - - - - Index of new symbols in 2.36 - - - - Index of new symbols in 2.36.8 - - - - Index of new symbols in 2.38 - - - - Index of new symbols in 2.40 - - - - - - - License - - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Library General - Public License as published by the Free Software - Foundation; either version 2 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 Library General Public License for - more details. - - - - You may obtain a copy of the GNU Library General - Public License from the Free Software Foundation by - visiting their Web - site or by writing to: - -
- Free Software Foundation, Inc. - 59 Temple Place - Suite 330 - Boston, MA 02111-1307 - USA -
- - - - - - - diff --git a/docs/meson.build b/docs/meson.build index c7c8fe721..d40ba61c0 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -1,69 +1,47 @@ -version_xml = configuration_data() -version_xml.set('GDK_PIXBUF_VERSION', meson.project_version()) -configure_file(input: 'version.xml.in', - output: 'version.xml', - configuration: version_xml) +gidocgen_dep = dependency('gi-docgen', + version: '>= 2021.1', + fallback: ['gi-docgen', 'dummy_dep'], + required: get_option('gtk_doc'), +) -if gobject_dep.type_name() == 'pkgconfig' - glib_prefix = gobject_dep.get_pkgconfig_variable('prefix') -else - glib_prefix = get_option('prefix') -endif -glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html') -docpath = join_paths(gdk_pixbuf_datadir, 'gtk-doc', 'html') -private_headers = [ - 'pixops', - 'gdk-pixbuf.h', - 'gdk-pixbuf-alias.h', - 'gdk-pixbuf-autocleanups.h', - 'gdk-pixbuf-buffer-queue-private.h', - 'gdk-pixbuf-marshal.h', - 'gdk-pixbuf-private.h', - 'gdk-pixbuf-scaled-anim.h', - 'io-ani-animation.h', - 'io-gdip-animation.h', - 'io-gdip-native.h', - 'io-gdip-propertytags.h', - 'io-gdip-utils.h', - 'io-gif-animation.h', - 'xpm-color-table.h', - 'test-images.h', - 'lzw.h', +toml_conf = configuration_data() +toml_conf.set('VERSION', meson.project_version()) +toml = configure_file(input: 'gdk-pixbuf.toml.in', output: 'gdk-pixbuf.toml', configuration: toml_conf) + +gidocgen = find_program('gi-docgen', required: get_option('gtk_doc')) + +docs_dir = gdk_pixbuf_datadir / 'doc/gdk-pixbuf/reference' + +expand_content_md_files = [ ] +build_docs = get_option('gtk_doc') if get_option('docs') - warning('The "docs" build option is deprecated; please use "gtk_doc=true"') + warning('The docs option is deprecated; use -Dgtk_doc=true') + build_docs = true endif -if get_option('gtk_doc') or get_option('docs') - gnome.gtkdoc('gdk-pixbuf', - main_xml: 'gdk-pixbuf.xml', - src_dir: [ gdk_pixbuf_inc ], - dependencies: gdkpixbuf_dep, - gobject_typesfile: 'gdk-pixbuf.types', - scan_args: [ - '--rebuild-types', - '--deprecated-guards="GDK_PIXBUF_ENABLE_BROKEN|GDK_PIXBUF_DISABLE_DEPRECATED"', - '--ignore-headers=' + ' '.join(private_headers), - ], - fixxref_args: [ - '--html-dir=@0@'.format(docpath), - '--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')), - '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')), - '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')), - ], - html_assets: [ - 'composite.png', - ], - content_files: [ - 'gdk-pixbuf-from-drawables.xml', - 'gdk-pixbuf-rendering.xml', - 'gdk-pixbuf.xml', - 'gdk-pixbuf-csource.xml', - 'gdk-pixbuf-query-loaders.xml', - ], - install: true) +if build_docs + custom_target('gdk-pixbuf-doc', + input: [ toml, gdkpixbuf_gir[0] ], + output: 'gdk-pixbuf', + command: [ + gidocgen, + 'generate', + '--quiet', + '--add-include-path=@0@'.format(meson.current_build_dir() / '../gdk-pixbuf'), + '--config=@INPUT0@', + '--output-dir=@OUTPUT@', + '--no-namespace-dir', + '--content-dir=@0@'.format(meson.current_source_dir()), + '@INPUT1@', + ], + depend_files: [ expand_content_md_files ], + build_by_default: true, + install: true, + install_dir: docs_dir, + ) endif xsltproc = find_program('xsltproc', required: false) diff --git a/docs/urlmap.js b/docs/urlmap.js new file mode 100644 index 000000000..eaf2de988 --- /dev/null +++ b/docs/urlmap.js @@ -0,0 +1,13 @@ +// SPDX-FileCopyrightText: 2021 GNOME Foundation +// SPDX-License-Identifier: LGPL-2.1-or-later + +// A map between namespaces and base URLs for their online documentation +baseURLs = [ + [ 'Gdk', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4/' ], + [ 'GdkWayland', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-wayland/' ], + [ 'GdkX11', 'https://gnome.pages.gitlab.gnome.org/gtk/gdk4-x11/' ], + [ 'Gsk', 'https://gnome.pages.gitlab.gnome.org/gtk/gsk4/' ], + [ 'Gtk', 'https://gnome.pages.gitlab.gnome.org/gtk/gtk4/' ], + [ 'Pango', 'https://gnome.pages/gitlab.gnome.org/pango/pango/' ], + [ 'PangoCairo', 'https://gnome.pages.gitlab.gnome.org/pango/pangocairo/' ], +] diff --git a/docs/version.xml.in b/docs/version.xml.in deleted file mode 100644 index 90ff08b2b..000000000 --- a/docs/version.xml.in +++ /dev/null @@ -1 +0,0 @@ -@GDK_PIXBUF_VERSION@ diff --git a/subprojects/gi-docgen.wrap b/subprojects/gi-docgen.wrap new file mode 100644 index 000000000..e9c78c1e7 --- /dev/null +++ b/subprojects/gi-docgen.wrap @@ -0,0 +1,6 @@ +[wrap-git] +directory=gi-docgen +url=https://gitlab.gnome.org/ebassi/gi-docgen.git +push-url=ssh://git@gitlab.gnome.org:ebassi/gi-docgen.git +revision=main +depth=1 -- cgit v1.2.1 From 0ad5532347210a53490734b9b1dda31f73560a4d Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sat, 20 Mar 2021 22:52:01 +0000 Subject: docs: Port to the gi-docgen syntax and style Drop the gtk-doc SECTION markers, and move documentation to classes or separate documents. --- docs/gdk-pixbuf.toml.in | 3 + docs/meson.build | 1 + docs/scaling-compositing.md | 44 +++++++ gdk-pixbuf/gdk-pixbuf-animation.c | 27 +++-- gdk-pixbuf/gdk-pixbuf-animation.h | 11 -- gdk-pixbuf/gdk-pixbuf-core.h | 80 +++++++------ gdk-pixbuf/gdk-pixbuf-features.h.in | 20 +--- gdk-pixbuf/gdk-pixbuf-io.c | 109 ++++++++--------- gdk-pixbuf/gdk-pixbuf-io.h | 76 +++++------- gdk-pixbuf/gdk-pixbuf-loader.c | 83 ++++++------- gdk-pixbuf/gdk-pixbuf-loader.h | 8 +- gdk-pixbuf/gdk-pixbuf-scale.c | 43 ------- gdk-pixbuf/gdk-pixbuf-transform.h | 14 ++- gdk-pixbuf/gdk-pixbuf-util.c | 13 -- gdk-pixbuf/gdk-pixbuf.c | 230 +++++++++++++++++++----------------- 15 files changed, 363 insertions(+), 399 deletions(-) create mode 100644 docs/scaling-compositing.md diff --git a/docs/gdk-pixbuf.toml.in b/docs/gdk-pixbuf.toml.in index 50299e5fd..bd5cfe935 100644 --- a/docs/gdk-pixbuf.toml.in +++ b/docs/gdk-pixbuf.toml.in @@ -40,6 +40,9 @@ content_images = [ 'composite.png', 'gnome-gmush-1.png', ] +content_files = [ + 'scaling-compositing.md', +] [[object]] name = "PIXBUF_DEPRECATED_IN_2_0_FOR" diff --git a/docs/meson.build b/docs/meson.build index d40ba61c0..d4c5fe5ea 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -14,6 +14,7 @@ gidocgen = find_program('gi-docgen', required: get_option('gtk_doc')) docs_dir = gdk_pixbuf_datadir / 'doc/gdk-pixbuf/reference' expand_content_md_files = [ + 'scaling-compositing.md', ] build_docs = get_option('gtk_doc') diff --git a/docs/scaling-compositing.md b/docs/scaling-compositing.md new file mode 100644 index 000000000..3abc75e73 --- /dev/null +++ b/docs/scaling-compositing.md @@ -0,0 +1,44 @@ +Title: Scaling and compositing + +---- + +The `GdkPixBuf` class contains methods to scale pixbufs, to scale +pixbufs and alpha blend against an existing image, and to scale +pixbufs and alpha blend against a solid color or checkerboard. +Alpha blending a checkerboard is a common way to show an image with +an alpha channel in image-viewing and editing software. + +Note that in these functions, the terms ‘alpha blending’ and ‘compositing’ +are used synonymously. + +Since the full-featured functions [method@GdkPixbuf.Pixbuf.scale], +[method@GdkPixbuf.Pixbuf.composite], and [`method@GdkPixbuf.Pixbuf.composite_color`] +are rather complex to use and have many arguments, two simple +convenience functions are provided, [`method@GdkPixbuf.Pixbuf.scale_simple`] +and [`method@GdkPixbuf.Pixbuf.composite_color_simple`] which create a new +pixbuf of a given size, scale an original image to fit, and then return it. + +If the destination pixbuf was created from a read only source, these +operations will force a copy into a mutable buffer. + +Scaling and alpha blending functions take advantage of MMX hardware +acceleration on systems where MMX is supported. If `GdkPixbuf` is built +with the Sun mediaLib library, these functions are instead accelerated +using mediaLib, which provides hardware acceleration on Intel, AMD, +and Sparc chipsets. If desired, mediaLib support can be turned off by +setting the `GDK_DISABLE_MEDIALIB` environment variable. + +The alpha blending function used is: + +``` +Cd = Cs·As + Cd(1-As) +``` + +where `Cd` is the destination pixel color, `Cs` is the source pixel color, +and `As` is the source pixel alpha. + +**NOTE**: It is recommended to use [Cairo][cairo] for scaling and +compositing, by using the contents of a `GdkPixbuf` pixel buffer as the +data for a Cairo image surface. + +[cairo]: https://www.cairographics.org diff --git a/gdk-pixbuf/gdk-pixbuf-animation.c b/gdk-pixbuf/gdk-pixbuf-animation.c index c8f2695e3..9b7372e00 100644 --- a/gdk-pixbuf/gdk-pixbuf-animation.c +++ b/gdk-pixbuf/gdk-pixbuf-animation.c @@ -30,21 +30,30 @@ #include /** - * SECTION:animation - * @Short_description: Animated images. - * @Title: Animations - * @See_also: #GdkPixbufLoader. + * GdkPixbufAnimation: + * + * An opaque object representing an animation. * * The GdkPixBuf library provides a simple mechanism to load and * represent animations. An animation is conceptually a series of - * frames to be displayed over time. The animation may not be - * represented as a series of frames internally; for example, it may - * be stored as a sprite and instructions for moving the sprite around - * a background. To display an animation you don't need to understand - * its representation, however; you just ask GdkPixBuf what should + * frames to be displayed over time. + * + * The animation may not be represented as a series of frames + * internally; for example, it may be stored as a sprite and + * instructions for moving the sprite around a background. + * + * To display an animation you don't need to understand its + * representation, however; you just ask `GdkPixbuf` what should * be displayed at a given point in time. */ +/** + * GdkPixbufAnimationIter: + * + * An opaque object representing an iterator which points to a + * certain position in an animation. + */ + typedef struct _GdkPixbufNonAnim GdkPixbufNonAnim; typedef struct _GdkPixbufNonAnimClass GdkPixbufNonAnimClass; diff --git a/gdk-pixbuf/gdk-pixbuf-animation.h b/gdk-pixbuf/gdk-pixbuf-animation.h index ad0c39c3b..cae551edd 100644 --- a/gdk-pixbuf/gdk-pixbuf-animation.h +++ b/gdk-pixbuf/gdk-pixbuf-animation.h @@ -36,20 +36,9 @@ G_BEGIN_DECLS /* Animation support */ -/** - * GdkPixbufAnimation: - * - * An opaque struct representing an animation. - */ typedef struct _GdkPixbufAnimation GdkPixbufAnimation; -/** - * GdkPixbufAnimationIter: - * - * An opaque struct representing an iterator which points to a - * certain position in an animation. - */ typedef struct _GdkPixbufAnimationIter GdkPixbufAnimationIter; #define GDK_TYPE_PIXBUF_ANIMATION (gdk_pixbuf_animation_get_type ()) diff --git a/gdk-pixbuf/gdk-pixbuf-core.h b/gdk-pixbuf/gdk-pixbuf-core.h index e03357d71..4b8c9b9b2 100644 --- a/gdk-pixbuf/gdk-pixbuf-core.h +++ b/gdk-pixbuf/gdk-pixbuf-core.h @@ -44,17 +44,23 @@ G_BEGIN_DECLS * considered fully opaque. * @GDK_PIXBUF_ALPHA_FULL: For now falls back to #GDK_PIXBUF_ALPHA_BILEVEL. * In the future it will do full alpha compositing. - * - * These values can be passed to - * gdk_pixbuf_xlib_render_to_drawable_alpha() to control how the alpha - * channel of an image should be handled. This function can create a - * bilevel clipping mask (black and white) and use it while painting - * the image. In the future, when the X Window System gets an alpha - * channel extension, it will be possible to do full alpha - * compositing onto arbitrary drawables. For now both cases fall - * back to a bilevel clipping mask. * - * Deprecated: 2.42: There is no user of GdkPixbufAlphaMode + * Control the alpha channel for drawables. + * + * These values can be passed to gdk_pixbuf_xlib_render_to_drawable_alpha() + * in gdk-pixbuf-xlib to control how the alpha channel of an image should + * be handled. + * + * This function can create a bilevel clipping mask (black and white) and use + * it while painting the image. + * + * In the future, when the X Window System gets an alpha channel extension, + * it will be possible to do full alpha compositing onto arbitrary drawables. + * For now both cases fall back to a bilevel clipping mask. + * + * Deprecated: 2.42: There is no user of GdkPixbufAlphaMode in GdkPixbuf, + * and the Xlib utility functions have been split out to their own + * library, gdk-pixbuf-xlib */ typedef enum { @@ -67,7 +73,9 @@ typedef enum * @GDK_COLORSPACE_RGB: Indicates a red/green/blue additive color space. * * This enumeration defines the color spaces that are supported by - * the gdk-pixbuf library. Currently only RGB is supported. + * the gdk-pixbuf library. + * + * Currently only RGB is supported. */ /* Note that these values are encoded in inline pixbufs * as ints, so don't reorder them @@ -78,15 +86,6 @@ typedef enum { /* All of these are opaque structures */ -/** - * GdkPixbuf: - * - * This is the main structure in the gdk-pixbuf library. It is - * used to represent images. It contains information about the - * image's pixel data, its color space, bits per sample, width and - * height, and the rowstride (the number of bytes between the start of - * one row and the start of the next). - */ typedef struct _GdkPixbuf GdkPixbuf; #define GDK_TYPE_PIXBUF (gdk_pixbuf_get_type ()) @@ -101,20 +100,23 @@ typedef struct _GdkPixbuf GdkPixbuf; * @data: (closure): User closure data. * * A function of this type is responsible for freeing the pixel array - * of a pixbuf. The gdk_pixbuf_new_from_data() function lets you - * pass in a pre-allocated pixel array so that a pixbuf can be - * created from it; in this case you will need to pass in a function - * of #GdkPixbufDestroyNotify so that the pixel data can be freed - * when the pixbuf is finalized. + * of a pixbuf. + * + * The gdk_pixbuf_new_from_data() function lets you pass in a pre-allocated + * pixel array so that a pixbuf can be created from it; in this case you + * will need to pass in a function of type `GdkPixbufDestroyNotify` so that + * the pixel data can be freed when the pixbuf is finalized. */ typedef void (* GdkPixbufDestroyNotify) (guchar *pixels, gpointer data); /** * GDK_PIXBUF_ERROR: * - * Error domain used for pixbuf operations. Indicates that the error code - * will be in the #GdkPixbufError enumeration. See #GError for - * information on error domains and error codes. + * Error domain used for pixbuf operations. + * + * Indicates that the error code will be in the `GdkPixbufError` enumeration. + * + * See the `GError` for information on error domains and error codes. */ #define GDK_PIXBUF_ERROR gdk_pixbuf_error_quark () @@ -129,9 +131,10 @@ typedef void (* GdkPixbufDestroyNotify) (guchar *pixels, gpointer data); * @GDK_PIXBUF_ERROR_FAILED: Generic failure code, something went wrong. * @GDK_PIXBUF_ERROR_INCOMPLETE_ANIMATION: Only part of the animation was loaded. * - * An error code in the #GDK_PIXBUF_ERROR domain. Many gdk-pixbuf - * operations can cause errors in this domain, or in the #G_FILE_ERROR - * domain. + * An error code in the `GDK_PIXBUF_ERROR` domain. + * + * Many gdk-pixbuf operations can cause errors in this domain, or in + * the `G_FILE_ERROR` domain. */ typedef enum { /* image data hosed */ @@ -347,15 +350,18 @@ gboolean gdk_pixbuf_savev_utf8 (GdkPixbuf *pixbuf, * @error: (out): A location to return an error. * @data: (closure): user data passed to gdk_pixbuf_save_to_callback(). * - * Specifies the type of the function passed to - * gdk_pixbuf_save_to_callback(). It is called once for each block of - * bytes that is "written" by gdk_pixbuf_save_to_callback(). If - * successful it should return %TRUE. If an error occurs it should set - * @error and return %FALSE, in which case gdk_pixbuf_save_to_callback() + * Save functions used by [method@GdkPixbuf.Pixbuf.save_to_callback]. + * + * This function is called once for each block of bytes that is "written" + * by `gdk_pixbuf_save_to_callback()`. + * + * If successful it should return `TRUE`; if an error occurs it should set + * `error` and return `FALSE`, in which case `gdk_pixbuf_save_to_callback()` * will fail with the same error. + * + * Returns: `TRUE` if successful, `FALSE` otherwise * * Since: 2.4 - * Returns: %TRUE if successful, %FALSE (with @error set) if failed. */ typedef gboolean (*GdkPixbufSaveFunc) (const gchar *buf, diff --git a/gdk-pixbuf/gdk-pixbuf-features.h.in b/gdk-pixbuf/gdk-pixbuf-features.h.in index 7efdc0e39..600d03220 100644 --- a/gdk-pixbuf/gdk-pixbuf-features.h.in +++ b/gdk-pixbuf/gdk-pixbuf-features.h.in @@ -7,15 +7,6 @@ #include -/** - * SECTION:initialization_versions - * @Short_description: Library version numbers. - * @Title: Initialization and Versions - * - * These macros and variables let you check the version of gdk-pixbuf - * you're linking against. - */ - /** * GDK_PIXBUF_MAJOR: * @@ -37,9 +28,10 @@ /** * GDK_PIXBUF_VERSION: * - * Contains the full version of the gdk-pixbuf header as a string. + * Contains the full version of GdkPixbuf as a string. + * * This is the version being compiled against; contrast with - * #gdk_pixbuf_version. + * `gdk_pixbuf_version`. */ #define GDK_PIXBUF_MAJOR (@GDK_PIXBUF_MAJOR@) @@ -81,7 +73,7 @@ * * This variable is in the library, so represents the * gdk-pixbuf library you have linked against. Contrast with the - * #GDK_PIXBUF_MAJOR macro, which represents the major version of the + * `GDK_PIXBUF_MAJOR` macro, which represents the major version of the * gdk-pixbuf headers you have included. */ /** @@ -93,7 +85,7 @@ * * This variable is in the library, so represents the * gdk-pixbuf library you have linked against. Contrast with the - * #GDK_PIXBUF_MINOR macro, which represents the minor version of the + * `GDK_PIXBUF_MINOR` macro, which represents the minor version of the * gdk-pixbuf headers you have included. */ /** @@ -105,7 +97,7 @@ * * This variable is in the library, so represents the * gdk-pixbuf library you have linked against. Contrast with the - * #GDK_PIXBUF_MICRO macro, which represents the micro version of the + * `GDK_PIXBUF_MICRO` macro, which represents the micro version of the * gdk-pixbuf headers you have included. */ /** diff --git a/gdk-pixbuf/gdk-pixbuf-io.c b/gdk-pixbuf/gdk-pixbuf-io.c index 2dc2ea6da..13bf5af16 100644 --- a/gdk-pixbuf/gdk-pixbuf-io.c +++ b/gdk-pixbuf/gdk-pixbuf-io.c @@ -48,80 +48,69 @@ #endif /** - * SECTION:file-loading - * @Short_description: Loading a pixbuf from a file. - * @Title: File Loading - * @See_also: #GdkPixbufLoader. + * GdkPixbufModule: + * @module_name: the name of the module, usually the same as the + * usual file extension for images of this type, eg. "xpm", "jpeg" or "png". + * @module_path: the path from which the module is loaded. + * @module: the loaded #GModule. + * @info: a #GdkPixbufFormat holding information about the module. + * @load: loads an image from a file. + * @load_xpm_data: loads an image from data in memory. + * @begin_load: begins an incremental load. + * @stop_load: stops an incremental load. + * @load_increment: continues an incremental load. + * @load_animation: loads an animation from a file. + * @save: saves a #GdkPixbuf to a file. + * @save_to_callback: saves a #GdkPixbuf by calling the given #GdkPixbufSaveFunc. + * @is_save_option_supported: returns whether a save option key is supported by the module * - * The GdkPixBuf library provides a simple mechanism for loading - * an image from a file in synchronous fashion. This means that the - * library takes control of the application while the file is being - * loaded; from the user's point of view, the application will block - * until the image is done loading. + * A `GdkPixbufModule` contains the necessary functions to load and save + * images in a certain file format. * + * If `GdkPixbuf` has been compiled with `GModule` support, it can be extended + * by modules which can load (and perhaps also save) new image and animation + * formats. + * + * ## Implementing modules * - * This interface can be used by applications in which blocking is - * acceptable while an image is being loaded. It can also be used to - * load small images in general. Applications that need progressive - * loading can use the #GdkPixbufLoader functionality instead. - */ - -/** - * SECTION:file-saving - * @Short_description: Saving a pixbuf to a file. - * @Title: File saving - * - * These functions allow to save a #GdkPixbuf in a number of - * file formats. The formatted data can be written to a file - * or to a memory buffer. GdkPixBuf can also call a user-defined - * callback on the data, which allows to e.g. write the image - * to a socket or store it in a database. - */ - -/** - * SECTION:module_interface - * @Short_description: Extending GdkPixBuf - * @Title: Module Interface - * - * If GdkPixBuf has been compiled with GModule support, it can be extended by - * modules which can load (and perhaps also save) new image and animation - * formats. Each loadable module must export a - * #GdkPixbufModuleFillInfoFunc function named `fill_info` and - * a #GdkPixbufModuleFillVtableFunc function named - * `fill_vtable`. + * The `GdkPixbuf` interfaces needed for implementing modules are contained in + * `gdk-pixbuf-io.h` (and `gdk-pixbuf-animation.h` if the module supports + * animations). They are not covered by the same stability guarantees as the + * regular GdkPixbuf API. To underline this fact, they are protected by the + * `GDK_PIXBUF_ENABLE_BACKEND` pre-processor symbol. + * + * Each loadable module must contain a `GdkPixbufModuleFillVtableFunc` function + * named `fill_vtable`, which will get called when the module + * is loaded and must set the function pointers of the `GdkPixbufModule`. * * In order to make format-checking work before actually loading the modules - * (which may require dlopening image libraries), modules export their - * signatures (and other information) via the `fill_info` function. An - * external utility, gdk-pixbuf-query-loaders, uses this to create a text + * (which may require calling `dlopen` to load image libraries), modules export + * their signatures (and other information) via the `fill_info` function. An + * external utility, `gdk-pixbuf-query-loaders`, uses this to create a text * file containing a list of all available loaders and their signatures. - * This file is then read at runtime by GdkPixBuf to obtain the list of + * This file is then read at runtime by `GdkPixbuf` to obtain the list of * available loaders and their signatures. * * Modules may only implement a subset of the functionality available via - * #GdkPixbufModule. If a particular functionality is not implemented, the + * `GdkPixbufModule`. If a particular functionality is not implemented, the * `fill_vtable` function will simply not set the corresponding - * function pointers of the #GdkPixbufModule structure. If a module supports - * incremental loading (i.e. provides #begin_load, #stop_load and - * #load_increment), it doesn't have to implement #load, since GdkPixBuf can - * supply a generic #load implementation wrapping the incremental loading. + * function pointers of the `GdkPixbufModule` structure. If a module supports + * incremental loading (i.e. provides `begin_load`, `stop_load` and + * `load_increment`), it doesn't have to implement `load`, since `GdkPixbuf` + * can supply a generic `load` implementation wrapping the incremental loading. + * + * ## Installing modules * * Installing a module is a two-step process: - * - copy the module file(s) to the loader directory (normally - * `$libdir/gdk-pixbuf-2.0/$version/loaders`, unless overridden by the - * environment variable `GDK_PIXBUF_MODULEDIR`) - * - call gdk-pixbuf-query-loaders to update the module file (normally - * `$libdir/gdk-pixbuf-2.0/$version/loaders.cache`, unless overridden by the - * environment variable `GDK_PIXBUF_MODULE_FILE`) - * - * The GdkPixBuf interfaces needed for implementing modules are contained in - * `gdk-pixbuf-io.h` (and `gdk-pixbuf-animation.h` if the module supports - * animations). They are not covered by the same stability guarantees as the - * regular GdkPixBuf API. To underline this fact, they are protected by - * `#ifdef GDK_PIXBUF_ENABLE_BACKEND`. + * + * - copy the module file(s) to the loader directory (normally + * `$libdir/gdk-pixbuf-2.0/$version/loaders`, unless overridden by the + * environment variable `GDK_PIXBUF_MODULEDIR`) + * - call `gdk-pixbuf-query-loaders` to update the module file (normally + * `$libdir/gdk-pixbuf-2.0/$version/loaders.cache`, unless overridden + * by the environment variable `GDK_PIXBUF_MODULE_FILE`) */ - static gint format_check (GdkPixbufModule *module, guchar *buffer, int size) { diff --git a/gdk-pixbuf/gdk-pixbuf-io.h b/gdk-pixbuf/gdk-pixbuf-io.h index 89b0830e1..f8270f52c 100644 --- a/gdk-pixbuf/gdk-pixbuf-io.h +++ b/gdk-pixbuf/gdk-pixbuf-io.h @@ -173,34 +173,37 @@ typedef void (* GdkPixbufModuleUpdatedFunc) (GdkPixbuf *pixbuf, * @mask: mask containing bytes which modify how the prefix is matched against * test data * @relevance: relevance of this pattern + * + * The signature prefix for a module. * * The signature of a module is a set of prefixes. Prefixes are encoded as * pairs of ordinary strings, where the second string, called the mask, if - * not %NULL, must be of the same length as the first one and may contain + * not `NULL`, must be of the same length as the first one and may contain * ' ', '!', 'x', 'z', and 'n' to indicate bytes that must be matched, - * not matched, "don't-care"-bytes, zeros and non-zeros. + * not matched, "don't-care"-bytes, zeros and non-zeros, respectively. + * * Each prefix has an associated integer that describes the relevance of * the prefix, with 0 meaning a mismatch and 100 a "perfect match". * * Starting with gdk-pixbuf 2.8, the first byte of the mask may be '*', * indicating an unanchored pattern that matches not only at the beginning, * but also in the middle. Versions prior to 2.8 will interpret the '*' - * like an 'x'. + * like an 'x'. * * The signature of a module is stored as an array of - * #GdkPixbufModulePatterns. The array is terminated by a pattern - * where the @prefix is %NULL. - * + * `GdkPixbufModulePatterns`. The array is terminated by a pattern + * where the `prefix` is `NULL`. * - * + * ```c * GdkPixbufModulePattern *signature[] = { * { "abcdx", " !x z", 100 }, * { "bla", NULL, 90 }, * { NULL, NULL, 0 } * }; - * - * The example matches e.g. "auud\0" with relevance 100, and "blau" with - * relevance 90. + * ``` + * + * In the example above, the signature matches e.g. "auud\0" with + * relevance 100, and "blau" with relevance 90. * * Since: 2.2 */ @@ -211,31 +214,6 @@ struct _GdkPixbufModulePattern { int relevance; }; -/** - * GdkPixbufModule: - * @module_name: the name of the module, usually the same as the - * usual file extension for images of this type, eg. "xpm", "jpeg" or "png". - * @module_path: the path from which the module is loaded. - * @module: the loaded #GModule. - * @info: a #GdkPixbufFormat holding information about the module. - * @load: loads an image from a file. - * @load_xpm_data: loads an image from data in memory. - * @begin_load: begins an incremental load. - * @stop_load: stops an incremental load. - * @load_increment: continues an incremental load. - * @load_animation: loads an animation from a file. - * @save: saves a #GdkPixbuf to a file. - * @save_to_callback: saves a #GdkPixbuf by calling the given #GdkPixbufSaveFunc. - * @is_save_option_supported: returns whether a save option key is supported by the module - * - * A #GdkPixbufModule contains the necessary functions to load and save - * images in a certain file format. - * - * A #GdkPixbufModule can be loaded dynamically from a #GModule. - * Each loadable module must contain a #GdkPixbufModuleFillVtableFunc function - * named fill_vtable, which will get called when the module - * is loaded and must set the function pointers of the #GdkPixbufModule. - */ typedef struct _GdkPixbufModule GdkPixbufModule; struct _GdkPixbufModule { char *module_name; @@ -332,21 +310,23 @@ typedef enum /*< skip >*/ /** * GdkPixbufFormat: - * @name: the name of the image format. - * @signature: the signature of the module. - * @domain: the message domain for the @description. - * @description: a description of the image format. - * @mime_types: a %NULL-terminated array of MIME types for the image format. - * @extensions: a %NULL-terminated array of typical filename extensions for the - * image format. - * @flags: a combination of #GdkPixbufFormatFlags. - * @disabled: a boolean determining whether the loader is disabled. + * @name: the name of the image format + * @signature: the signature of the module + * @domain: the message domain for the `description` + * @description: a description of the image format + * @mime_types: (array zero-terminated=1): the MIME types for the image format + * @extensions: (array zero-terminated=1): typical filename extensions for the + * image format + * @flags: a combination of `GdkPixbufFormatFlags` + * @disabled: a boolean determining whether the loader is disabled` * @license: a string containing license information, typically set to - * shorthands like "GPL", "LGPL", etc. + * shorthands like "GPL", "LGPL", etc. * - * A #GdkPixbufFormat contains information about the image format accepted by a - * module. Only modules should access the fields directly, applications should - * use the gdk_pixbuf_format_* functions. + * A `GdkPixbufFormat` contains information about the image format accepted + * by a module. + * + * Only modules should access the fields directly, applications should + * use the `gdk_pixbuf_format_*` family of functions. * * Since: 2.2 */ diff --git a/gdk-pixbuf/gdk-pixbuf-loader.c b/gdk-pixbuf/gdk-pixbuf-loader.c index 81c5afb75..5ef462d0d 100644 --- a/gdk-pixbuf/gdk-pixbuf-loader.c +++ b/gdk-pixbuf/gdk-pixbuf-loader.c @@ -32,52 +32,53 @@ #include "gdk-pixbuf-marshal.h" /** - * SECTION:gdk-pixbuf-loader - * @Short_description: Application-driven progressive image loading. - * @Title: GdkPixbufLoader - * @See_also: gdk_pixbuf_new_from_file(), gdk_pixbuf_animation_new_from_file() + * GdkPixbufLoader: + * + * Incremental image loader. * - * #GdkPixbufLoader provides a way for applications to drive the + * `GdkPixbufLoader` provides a way for applications to drive the * process of loading an image, by letting them send the image data * directly to the loader instead of having the loader read the data - * from a file. Applications can use this functionality instead of - * gdk_pixbuf_new_from_file() or gdk_pixbuf_animation_new_from_file() - * when they need to parse image data in - * small chunks. For example, it should be used when reading an - * image from a (potentially) slow network connection, or when - * loading an extremely large file. - * - * - * To use #GdkPixbufLoader to load an image, just create a new one, and - * call gdk_pixbuf_loader_write() to send the data to it. When done, - * gdk_pixbuf_loader_close() should be called to end the stream and - * finalize everything. The loader will emit three important signals - * throughout the process. The first, #GdkPixbufLoader::size-prepared, - * will be emitted as soon as the image has enough information to - * determine the size of the image to be used. If you want to scale - * the image while loading it, you can call gdk_pixbuf_loader_set_size() - * in response to this signal. - * - * - * The second signal, #GdkPixbufLoader::area-prepared, will be emitted as - * soon as the pixbuf of the desired has been allocated. You can obtain it - * by calling gdk_pixbuf_loader_get_pixbuf(). If you want to use it, simply - * ref it. You can also call gdk_pixbuf_loader_get_pixbuf() later and get - * the same pixbuf. - * - * The last signal, #GdkPixbufLoader::area-updated, gets emitted every time - * a region is updated. This way you can update a partially completed image. - * Note that you do not know anything about the completeness of an image - * from the updated area. For example, in an interlaced image, you need to - * make several passes before the image is done loading. + * from a file. Applications can use this functionality instead of + * `gdk_pixbuf_new_from_file()` or `gdk_pixbuf_animation_new_from_file()` + * when they need to parse image data in small chunks. For example, + * it should be used when reading an image from a (potentially) slow + * network connection, or when loading an extremely large file. + * + * To use `GdkPixbufLoader` to load an image, create a new instance, + * and call [method@GdkPixbuf.PixbufLoader.write] to send the data + * to it. When done, [method@GdkPixbuf.PixbufLoader.close] should be + * called to end the stream and finalize everything. + * + * The loader will emit three important signals throughout the process: + * + * - [signal@GdkPixbuf.PixbufLoader::size-prepared] will be emitted as + * soon as the image has enough information to determine the size of + * the image to be used. If you want to scale the image while loading + * it, you can call [method@GdkPixbuf.PixbufLoader.set_size] in + * response to this signal. + * - [signal@GdkPixbuf.PixbufLoader::area-prepared] will be emitted as + * soon as the pixbuf of the desired has been allocated. You can obtain + * the `GdkPixbuf` instance by calling [method@GdkPixbuf.PixbufLoader.get_pixbuf]. + * If you want to use it, simply acquire a reference to it. You can + * also call `gdk_pixbuf_loader_get_pixbuf()` later to get the same + * pixbuf. + * - [signal@GdkPixbuf.PixbufLoader::area-updated] will be emitted every + * time a region is updated. This way you can update a partially + * completed image. Note that you do not know anything about the + * completeness of an image from the updated area. For example, in an + * interlaced image you will need to make several passes before the + * image is done loading. * - * # Loading an animation + * ## Loading an animation * - * Loading an animation is almost as easy as loading an image. Once the first - * #GdkPixbufLoader::area-prepared signal has been emitted, you can call - * gdk_pixbuf_loader_get_animation() to get the #GdkPixbufAnimation struct - * and gdk_pixbuf_animation_get_iter() to get a #GdkPixbufAnimationIter for - * displaying it. + * Loading an animation is almost as easy as loading an image. Once the + * first [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been + * emitted, you can call [method@GdkPixbuf.PixbufLoader.get_animation] to + * get the [class@GdkPixbuf.PixbufAnimation] instance, and then call + * and [method@GdkPixbuf.PixbufAnimation.get_iter] to get a + * [class@GdkPixbuf.PixbufAnimationIter] to retrieve the pixbuf for the + * desired time stamp. */ diff --git a/gdk-pixbuf/gdk-pixbuf-loader.h b/gdk-pixbuf/gdk-pixbuf-loader.h index 83648205f..1cc34136b 100644 --- a/gdk-pixbuf/gdk-pixbuf-loader.h +++ b/gdk-pixbuf/gdk-pixbuf-loader.h @@ -43,18 +43,12 @@ G_BEGIN_DECLS #define GDK_IS_PIXBUF_LOADER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GDK_TYPE_PIXBUF_LOADER)) #define GDK_PIXBUF_LOADER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GDK_TYPE_PIXBUF_LOADER, GdkPixbufLoaderClass)) -/** - * GdkPixbufLoader: - * - * The GdkPixbufLoader struct contains only private - * fields. - */ typedef struct _GdkPixbufLoader GdkPixbufLoader; struct _GdkPixbufLoader { + /*< private >*/ GObject parent_instance; - /*< private >*/ gpointer priv; }; diff --git a/gdk-pixbuf/gdk-pixbuf-scale.c b/gdk-pixbuf/gdk-pixbuf-scale.c index 84e8e10c3..863de8b83 100644 --- a/gdk-pixbuf/gdk-pixbuf-scale.c +++ b/gdk-pixbuf/gdk-pixbuf-scale.c @@ -25,49 +25,6 @@ #include "gdk-pixbuf-private.h" #include "pixops/pixops.h" -/** - * SECTION:scaling - * @Short_description: Scaling pixbufs and scaling and alpha blending pixbufs - * @Title: Scaling - * - * The GdkPixBuf contains functions to scale pixbufs, to scale - * pixbufs and alpha blend against an existing image, and to scale - * pixbufs and alpha blend against a solid color or checkerboard. - * Alpha blending a checkerboard is a common way to show an image with - * an alpha channel in image-viewing and editing software. - * - * Note that in these functions, the terms ‘alpha blending’ and ‘compositing’ - * are used synonymously. - * - * Since the full-featured functions (gdk_pixbuf_scale(), - * gdk_pixbuf_composite(), and gdk_pixbuf_composite_color()) are - * rather complex to use and have many arguments, two simple - * convenience functions are provided, gdk_pixbuf_scale_simple() and - * gdk_pixbuf_composite_color_simple() which create a new pixbuf of a - * given size, scale an original image to fit, and then return the - * new pixbuf. - * - * If the destination pixbuf was created from a readonly source, these - * operations will force a copy into a mutable buffer. - * - * Scaling and alpha blending functions take advantage of MMX hardware - * acceleration on systems where MMX is supported. If gdk-pixbuf is built - * with the Sun mediaLib library, these functions are instead accelerated - * using mediaLib, which provides hardware acceleration on Intel, AMD, - * and Sparc chipsets. If desired, mediaLib support can be turned off by - * setting the `GDK_DISABLE_MEDIALIB` environment variable. - * - * The alpha blending function used is: - * - * |[ - * Cd = Cs·As + Cd(1-As) - * ]| - * - * where `Cd` is the destination pixel color, `Cs` is the source pixel color, - * and `As` is the source pixel alpha. - */ - - /** * gdk_pixbuf_scale: * @src: a #GdkPixbuf diff --git a/gdk-pixbuf/gdk-pixbuf-transform.h b/gdk-pixbuf/gdk-pixbuf-transform.h index 24e5ad5ae..2ba28c49f 100644 --- a/gdk-pixbuf/gdk-pixbuf-transform.h +++ b/gdk-pixbuf/gdk-pixbuf-transform.h @@ -59,12 +59,13 @@ G_BEGIN_DECLS * **Deprecated**: this interpolation filter is deprecated, as in reality * it has a lower quality than the @GDK_INTERP_BILINEAR filter * (Since: 2.38) - * - * This enumeration describes the different interpolation modes that - * can be used with the scaling functions. @GDK_INTERP_NEAREST is - * the fastest scaling method, but has horrible quality when - * scaling down. @GDK_INTERP_BILINEAR is the best choice if you - * aren't sure what to choose, it has a good speed/quality balance. + * + * Interpolation modes for scaling functions. + * + * The `GDK_INTERP_NEAREST` mode is the fastest scaling method, but has + * horrible quality when scaling down; `GDK_INTERP_BILINEAR` is the best + * choice if you aren't sure what to choose, it has a good speed/quality + * balance. * * **Note**: Cubic filtering is missing from the list; hyperbolic * interpolation is just as fast and results in higher quality. @@ -84,6 +85,7 @@ typedef enum { * @GDK_PIXBUF_ROTATE_CLOCKWISE: Rotate by 270 degrees. * * The possible rotations which can be passed to gdk_pixbuf_rotate_simple(). + * * To make them easier to use, their numerical values are the actual degrees. */ typedef enum { diff --git a/gdk-pixbuf/gdk-pixbuf-util.c b/gdk-pixbuf/gdk-pixbuf-util.c index db1562b76..89d5a9792 100644 --- a/gdk-pixbuf/gdk-pixbuf-util.c +++ b/gdk-pixbuf/gdk-pixbuf-util.c @@ -26,19 +26,6 @@ #include "gdk-pixbuf-transform.h" #include "gdk-pixbuf-private.h" -/** - * SECTION:util - * @Short_description: Utility and miscellaneous convenience functions. - * @Title: Utilities - * @See_also: #GdkPixbuf - * - * These functions provide miscellaneous utilities for manipulating - * pixbufs. The pixel data in pixbufs may of course be manipulated - * directly by applications, but several common operations can be - * performed by these functions instead. - */ - - /** * gdk_pixbuf_add_alpha: * @pixbuf: A #GdkPixbuf. diff --git a/gdk-pixbuf/gdk-pixbuf.c b/gdk-pixbuf/gdk-pixbuf.c index 2594b99e9..383fe024b 100644 --- a/gdk-pixbuf/gdk-pixbuf.c +++ b/gdk-pixbuf/gdk-pixbuf.c @@ -21,152 +21,162 @@ * License along with this library; if not, see . */ -#include "config.h" - -#include -#include -#include - -#define GDK_PIXBUF_C_COMPILATION -#include "gdk-pixbuf-private.h" -#include "gdk-pixbuf-features.h" -#include "gdk-pixbuf-enum-types.h" - -/* Include the marshallers */ -#include -#include -#include "gdk-pixbuf-marshal.h" - /** - * SECTION:creating - * @Short_description: Creating a pixbuf from image data that is already in memory. - * @Title: Image Data in Memory - * @See_also: gdk_pixbuf_finalize(). + * GdkPixbuf: + * + * A pixel buffer. + * + * `GdkPixbuf` contains information about an image's pixel data, + * its color space, bits per sample, width and height, and the + * rowstride (the number of bytes between the start of one row + * and the start of the next). + * + * ## Creating new `GdkPixbuf` * * The most basic way to create a pixbuf is to wrap an existing pixel - * buffer with a #GdkPixbuf structure. You can use the - * gdk_pixbuf_new_from_data() function to do this You need to specify - * the destroy notification function that will be called when the - * data buffer needs to be freed; this will happen when a #GdkPixbuf - * is finalized by the reference counting functions If you have a - * chunk of static data compiled into your application, you can pass - * in %NULL as the destroy notification function so that the data - * will not be freed. + * buffer with a [class@GdkPixbuf.Pixbuf] instance. You can use the + * [`ctor@GdkPixbuf.Pixbuf.new_from_data`] function to do this. * - * The gdk_pixbuf_new() function can be used as a convenience to - * create a pixbuf with an empty buffer. This is equivalent to - * allocating a data buffer using malloc() and then wrapping it with - * gdk_pixbuf_new_from_data(). The gdk_pixbuf_new() function will - * compute an optimal rowstride so that rendering can be performed - * with an efficient algorithm. + * Every time you create a new `GdkPixbuf` instance for some data, you + * will need to specify the destroy notification function that will be + * called when the data buffer needs to be freed; this will happen when + * a `GdkPixbuf` is finalized by the reference counting functions. If + * you have a chunk of static data compiled into your application, you + * can pass in `NULL` as the destroy notification function so that the + * data will not be freed. * - * As a special case, you can use the gdk_pixbuf_new_from_xpm_data() + * The [`ctor@GdkPixbuf.Pixbuf.new`] constructor function can be used + * as a convenience to create a pixbuf with an empty buffer; this is + * equivalent to allocating a data buffer using `malloc()` and then + * wrapping it with `gdk_pixbuf_new_from_data()`. The `gdk_pixbuf_new()` + * function will compute an optimal rowstride so that rendering can be + * performed with an efficient algorithm. + * + * As a special case, you can use the [`ctor@GdkPixbuf.Pixbuf.new_from_xpm_data`] * function to create a pixbuf from inline XPM image data. * - * You can also copy an existing pixbuf with the gdk_pixbuf_copy() - * function. This is not the same as just doing a g_object_ref() - * on the old pixbuf; the copy function will actually duplicate the - * pixel data in memory and create a new #GdkPixbuf structure for it. - */ - -/** - * SECTION:refcounting - * @Short_description: Functions for reference counting and memory management on pixbufs. - * @Title: Reference Counting and Memory Mangement - * @See_also: #GdkPixbuf, gdk_pixbuf_new_from_data(). + * You can also copy an existing pixbuf with the [method@Pixbuf.copy] + * function. This is not the same as just acquiring a reference to + * the old pixbuf instance: the copy function will actually duplicate + * the pixel data in memory and create a new [class@Pixbuf] instance + * for it. + * + * ## Reference counting * - * #GdkPixbuf structures are reference counted. This means that an + * `GdkPixbuf` structures are reference counted. This means that an * application can share a single pixbuf among many parts of the - * code. When a piece of the program needs to keep a pointer to a - * pixbuf, it should add a reference to it by calling g_object_ref(). - * When it no longer needs the pixbuf, it should subtract a reference - * by calling g_object_unref(). The pixbuf will be destroyed when - * its reference count drops to zero. Newly-created #GdkPixbuf - * structures start with a reference count of one. - * - * > As #GdkPixbuf is derived from #GObject now, gdk_pixbuf_ref() and - * > gdk_pixbuf_unref() are deprecated in favour of g_object_ref() - * > and g_object_unref() resp. - * - * Finalizing a pixbuf means to free its pixel data and to free the - * #GdkPixbuf structure itself. Most of the library functions that - * create #GdkPixbuf structures create the pixel data by themselves - * and define the way it should be freed; you do not need to worry - * about those. - * - * To provide preallocated pixel data, use - * gdk_pixbuf_new_from_bytes(). The gdk_pixbuf_new_from_data() API is - * an older variant that predates the existence of #GBytes. - */ - -/** - * SECTION:gdk-pixbuf - * @Short_description: Information that describes an image. - * @Title: The GdkPixbuf Structure + * code. When a piece of the program needs to use a pixbuf, it should + * acquire a reference to it by calling `g_object_ref()`; when it no + * longer needs the pixbuf, it should release the reference it acquired + * by calling `g_object_unref()`. The resources associated with a + * `GdkPixbuf` will be freed when its reference count drops to zero. + * Newly-created `GdkPixbuf` instances start with a reference count + * of one. * - * The #GdkPixbuf structure contains - * information that describes an image in memory. + * ## Image Data * - * ## Image Data ## {#image-data} + * Image data in a pixbuf is stored in memory in an uncompressed, + * packed format. Rows in the image are stored top to bottom, and + * in each row pixels are stored from left to right. * - * Image data in a pixbuf is stored in memory in uncompressed, - * packed format. Rows in the image are stored top to bottom, and - * in each row pixels are stored from left to right. There may be - * padding at the end of a row. The "rowstride" value of a pixbuf, - * as returned by gdk_pixbuf_get_rowstride(), indicates the number - * of bytes between rows. + * There may be padding at the end of a row. * - * ## put_pixel() Example ## {#put-pixel} + * The "rowstride" value of a pixbuf, as returned by [`method@GdkPixbuf.Pixbuf.get_rowstride`], + * indicates the number of bytes between rows. * - * The following code illustrates a simple put_pixel() + * **NOTE**: If you are copying raw pixbuf data with `memcpy()` note that the + * last row in the pixbuf may not be as wide as the full rowstride, but rather + * just as wide as the pixel data needs to be; that is: it is unsafe to do + * `memcpy (dest, pixels, rowstride * height)` to copy a whole pixbuf. Use + * [method@GdkPixbuf.Pixbuf.copy] instead, or compute the width in bytes of the + * last row as: + * + * ```c + * last_row = width * ((n_channels * bits_per_sample + 7) / 8); + * ``` + * + * The same rule applies when iterating over each row of a `GdkPixbuf` pixels + * array. + * + * The following code illustrates a simple `put_pixel()` * function for RGB pixbufs with 8 bits per channel with an alpha - * channel. It is not included in the gdk-pixbuf library for - * performance reasons; rather than making several function calls - * for each pixel, your own code can take shortcuts. + * channel. * - * |[ + * ```c * static void - * put_pixel (GdkPixbuf *pixbuf, int x, int y, guchar red, guchar green, guchar blue, guchar alpha) + * put_pixel (GdkPixbuf *pixbuf, + * int x, + * int y, + * guchar red, + * guchar green, + * guchar blue, + * guchar alpha) * { - * int width, height, rowstride, n_channels; - * guchar *pixels, *p; - * - * n_channels = gdk_pixbuf_get_n_channels (pixbuf); + * int n_channels = gdk_pixbuf_get_n_channels (pixbuf); * + * // Ensure that the pixbuf is valid * g_assert (gdk_pixbuf_get_colorspace (pixbuf) == GDK_COLORSPACE_RGB); * g_assert (gdk_pixbuf_get_bits_per_sample (pixbuf) == 8); * g_assert (gdk_pixbuf_get_has_alpha (pixbuf)); * g_assert (n_channels == 4); * - * width = gdk_pixbuf_get_width (pixbuf); - * height = gdk_pixbuf_get_height (pixbuf); + * int width = gdk_pixbuf_get_width (pixbuf); + * int height = gdk_pixbuf_get_height (pixbuf); * + * // Ensure that the coordinates are in a valid range * g_assert (x >= 0 && x < width); * g_assert (y >= 0 && y < height); * - * rowstride = gdk_pixbuf_get_rowstride (pixbuf); - * pixels = gdk_pixbuf_get_pixels (pixbuf); + * int rowstride = gdk_pixbuf_get_rowstride (pixbuf); * - * p = pixels + y * rowstride + x * n_channels; + * // The pixel buffer in the GdkPixbuf instance + * guchar *pixels = gdk_pixbuf_get_pixels (pixbuf); + * + * // The pixel we wish to modify + * guchar *p = pixels + y * rowstride + x * n_channels; * p[0] = red; * p[1] = green; * p[2] = blue; * p[3] = alpha; * } - * ]| - * - * This function will not work for pixbufs with images that are - * other than 8 bits per sample or channel, but it will work for - * most of the pixbufs that GTK+ uses. - * - * If you are doing memcpy() of raw pixbuf data, note that the last row - * in the pixbuf may not be as wide as the full rowstride, but rather - * just as wide as the pixel data needs to be. That is, it is unsafe to - * do `memcpy (dest, pixels, rowstride * height)` to copy a whole pixbuf. - * Use gdk_pixbuf_copy() instead, or compute the width in bytes of the - * last row as `width * ((n_channels * bits_per_sample + 7) / 8)`. + * ``` + * + * ## Loading images + * + * The `GdkPixBuf` class provides a simple mechanism for loading + * an image from a file in synchronous and asynchronous fashion. + * + * For GUI applications, it is recommended to use the asynchronous + * stream API to avoid blocking the control flow of the application. + * + * Additionally, `GdkPixbuf` provides the [class@GdkPixbuf.PixbufLoader`] + * API for progressive image loading. + * + * ## Saving images + * + * The `GdkPixbuf` class provides methods for saving image data in + * a number of file formats. The formatted data can be written to a + * file or to a memory buffer. `GdkPixbuf` can also call a user-defined + * callback on the data, which allows to e.g. write the image + * to a socket or store it in a database. */ +#include "config.h" + +#include +#include +#include + +#define GDK_PIXBUF_C_COMPILATION +#include "gdk-pixbuf-private.h" +#include "gdk-pixbuf-features.h" +#include "gdk-pixbuf-enum-types.h" + +/* Include the marshallers */ +#include +#include +#include "gdk-pixbuf-marshal.h" + static void gdk_pixbuf_finalize (GObject *object); static void gdk_pixbuf_set_property (GObject *object, guint prop_id, -- cgit v1.2.1 From 9de2b14bc03c9f3352ae07b5eece266f6292c0cc Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sat, 20 Mar 2021 22:58:59 +0000 Subject: docs: Generate the GdkPixdata API reference Different introspection file, different API reference. --- docs/gdk-pixdata.toml.in | 41 +++++++++++++++++++++++++++++++++++++++++ docs/meson.build | 24 ++++++++++++++++++++++-- docs/urlmap.js | 1 + gdk-pixbuf/gdk-pixdata.c | 33 +++++++++++++++++++++++---------- gdk-pixbuf/gdk-pixdata.h | 27 ++++++++------------------- 5 files changed, 95 insertions(+), 31 deletions(-) create mode 100644 docs/gdk-pixdata.toml.in diff --git a/docs/gdk-pixdata.toml.in b/docs/gdk-pixdata.toml.in new file mode 100644 index 000000000..47f37cb25 --- /dev/null +++ b/docs/gdk-pixdata.toml.in @@ -0,0 +1,41 @@ +# SPDX-FileCopyrightText: 2021 GNOME Foundation +# +# SPDX-License-Identifier: CC0-1.0 + +[library] +name = "gdk-pixdata" +version = "@VERSION@" +browse_url = "https://gitlab.gnome.org/GNOME/gdk-pixbuf/" +repository_url = "https://gitlab.gnome.org/GNOME/gdk-pixbuf.git" +website_url = "https://www.gtk.org" +authors = "GTK Development Team" +license = "GPL-2.1-or-later" +description = "Inline image data" +dependencies = [ "gobject", "gio", "gdk-pixbuf" ] +devhelp = true +search_index = true + + [dependencies.gobject] + name = "GObject" + description = "The base type system library" + docs_url = "https://developer.gnome.org/gobject/stable" + + [dependencies.gio] + name = "GIO" + description = "GObject Interfaces and Objects" + docs_url = "https://developer.gnome.org/gio/stable" + + [dependencies."gdk-pixbuf"] + name = "GdkPixbuf" + description = "Image loading library" + docs_url = "../gdk-pixbuf/index.html" + +[theme] +name = "basic" +show_index_summary = true + +[source-location] +base_url = "https://gitlab.gnome.org/GNOME/gdk-pixbuf/-/blob/master/" + +[extra] +urlmap_file = "urlmap.js" diff --git a/docs/meson.build b/docs/meson.build index d4c5fe5ea..c9a16a49b 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -7,7 +7,8 @@ gidocgen_dep = dependency('gi-docgen', toml_conf = configuration_data() toml_conf.set('VERSION', meson.project_version()) -toml = configure_file(input: 'gdk-pixbuf.toml.in', output: 'gdk-pixbuf.toml', configuration: toml_conf) +pixbuf_toml = configure_file(input: 'gdk-pixbuf.toml.in', output: 'gdk-pixbuf.toml', configuration: toml_conf) +pixdata_toml = configure_file(input: 'gdk-pixdata.toml.in', output: 'gdk-pixdata.toml', configuration: toml_conf) gidocgen = find_program('gi-docgen', required: get_option('gtk_doc')) @@ -25,7 +26,7 @@ endif if build_docs custom_target('gdk-pixbuf-doc', - input: [ toml, gdkpixbuf_gir[0] ], + input: [ pixbuf_toml, gdkpixbuf_gir[0] ], output: 'gdk-pixbuf', command: [ gidocgen, @@ -43,6 +44,25 @@ if build_docs install: true, install_dir: docs_dir, ) + + custom_target('gdk-pixdata-doc', + input: [ pixdata_toml, gdkpixdata_gir[0] ], + output: 'gdk-pixdata', + command: [ + gidocgen, + 'generate', + '--quiet', + '--add-include-path=@0@'.format(meson.current_build_dir() / '../gdk-pixbuf'), + '--config=@INPUT0@', + '--output-dir=@OUTPUT@', + '--no-namespace-dir', + '--content-dir=@0@'.format(meson.current_source_dir()), + '@INPUT1@', + ], + build_by_default: true, + install: true, + install_dir: docs_dir, + ) endif xsltproc = find_program('xsltproc', required: false) diff --git a/docs/urlmap.js b/docs/urlmap.js index eaf2de988..caaee10f0 100644 --- a/docs/urlmap.js +++ b/docs/urlmap.js @@ -10,4 +10,5 @@ baseURLs = [ [ 'Gtk', 'https://gnome.pages.gitlab.gnome.org/gtk/gtk4/' ], [ 'Pango', 'https://gnome.pages/gitlab.gnome.org/pango/pango/' ], [ 'PangoCairo', 'https://gnome.pages.gitlab.gnome.org/pango/pangocairo/' ], + [ 'GdkPixbuf', 'https://gnome.pages.gitlab.gnome.org/gdk-pixbuf/' ], ] diff --git a/gdk-pixbuf/gdk-pixdata.c b/gdk-pixbuf/gdk-pixdata.c index df1036a9a..35f90dffc 100644 --- a/gdk-pixbuf/gdk-pixdata.c +++ b/gdk-pixbuf/gdk-pixdata.c @@ -23,19 +23,32 @@ G_GNUC_BEGIN_IGNORE_DEPRECATIONS /** - * SECTION:inline - * @Short_description: Functions for inlined pixbuf handling. - * @Title: Inline data + * GdkPixdata: + * @magic: magic number. A valid `GdkPixdata` structure must have + * `GDK_PIXBUF_MAGIC_NUMBER` here + * @length: less than 1 to disable length checks, otherwise + * `GDK_PIXDATA_HEADER_LENGTH` plus the length of `pixel_data` + * @pixdata_type: information about colorspace, sample width and + * encoding, in a `GdkPixdataType` + * @rowstride: Distance in bytes between rows + * @width: Width of the image in pixels + * @height: Height of the image in pixels + * @pixel_data: (array) (element-type guint8): `width` x `height` + * pixels, encoded according to `pixdata_type` and `rowstride` + * + * A pixel buffer suitable for serialization and streaming. * - * Using #GdkPixdata, images can be compiled into an application, + * Using `GdkPixdata`, images can be compiled into an application, * making it unnecessary to refer to external image files at runtime. - * GdkPixBuf includes a utility named gdk-pixbuf-csource, which - * can be used to convert image files into #GdkPixdata structures suitable - * for inclusion in C sources. To convert the #GdkPixdata structures back - * into #GdkPixbufs, use gdk_pixbuf_from_pixdata. * - * #GdkPixdata should not be used any more. #GResource should be used to save - * the original compressed images inside the program's binary. + * `GdkPixbuf` includes a utility named `gdk-pixbuf-csource`, which + * can be used to convert image files into `GdkPixdata` structures suitable + * for inclusion in C sources. To convert the `GdkPixdata` structures back + * into a `GdkPixbuf`, use `gdk_pixbuf_from_pixdata()`. + * + * Deprecated: 2.32: `GdkPixdata` should not be used any more. `GResource` + * should be used to save the original compressed images inside the + * program's binary */ #define APPEND g_string_append_printf diff --git a/gdk-pixbuf/gdk-pixdata.h b/gdk-pixbuf/gdk-pixdata.h index 0aa2a2550..4c25698a2 100644 --- a/gdk-pixbuf/gdk-pixdata.h +++ b/gdk-pixbuf/gdk-pixdata.h @@ -47,7 +47,9 @@ G_BEGIN_DECLS * * An enumeration containing three sets of flags for a #GdkPixdata struct: * one for the used colorspace, one for the width of the samples and one - * for the encoding of the pixel data. + * for the encoding of the pixel data. + * + * Deprecated: 2.32 **/ typedef enum { @@ -64,23 +66,6 @@ typedef enum GDK_PIXDATA_ENCODING_MASK = 0x0f << 24 } GdkPixdataType; -/** - * GdkPixdata: - * @magic: magic number. A valid #GdkPixdata structure must have - * #GDK_PIXBUF_MAGIC_NUMBER here. - * @length: less than 1 to disable length checks, otherwise - * #GDK_PIXDATA_HEADER_LENGTH + length of @pixel_data. - * @pixdata_type: information about colorspace, sample width and - * encoding, in a #GdkPixdataType. - * @rowstride: Distance in bytes between rows. - * @width: Width of the image in pixels. - * @height: Height of the image in pixels. - * @pixel_data: (array) (element-type guint8): @width x @height pixels, encoded according to @pixdata_type - * and @rowstride. - * - * A #GdkPixdata contains pixbuf information in a form suitable for - * serialization and streaming. - **/ typedef struct _GdkPixdata GdkPixdata; struct _GdkPixdata { @@ -99,6 +84,8 @@ struct _GdkPixdata * GDK_PIXDATA_HEADER_LENGTH: * * The length of a #GdkPixdata structure without the @pixel_data pointer. + * + * Deprecated: 2.32 **/ #define GDK_PIXDATA_HEADER_LENGTH (4 + 4 + 4 + 4 + 4 + 4) @@ -145,7 +132,9 @@ GdkPixbuf* gdk_pixbuf_from_pixdata (const GdkPixdata *pixdata, * @GDK_PIXDATA_DUMP_PIXDATA_STREAM, @GDK_PIXDATA_DUMP_PIXDATA_STRUCT * and @GDK_PIXDATA_DUMP_MACROS are mutually exclusive, as are * @GDK_PIXBUF_DUMP_GTYPES and @GDK_PIXBUF_DUMP_CTYPES. The remaining - * elements are optional flags that can be freely added. + * elements are optional flags that can be freely added. + * + * Deprecated: 2.32 **/ typedef enum { -- cgit v1.2.1 From baf188d8694eb9ca87edfb48fbada788600c19a1 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sat, 20 Mar 2021 23:11:46 +0000 Subject: ci: Update the Docker image We need to satisfy the dependencies for gi-docgen. --- .gitlab-ci.yml | 2 +- .gitlab/ci/fedora.Dockerfile | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 7e1c7febd..83bdd6f6d 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -10,7 +10,7 @@ variables: COMMON_MESON_FLAGS: "-Dwerror=true -Dglib:werror=false" LOADERS_FLAGS: "-Dpng=true -Djpeg=true -Dtiff=true" MESON_TEST_TIMEOUT_MULTIPLIER: 3 - FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/gdk-pixbuf/fedora:v1" + FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/gdk-pixbuf/fedora:v2" .only-default: only: diff --git a/.gitlab/ci/fedora.Dockerfile b/.gitlab/ci/fedora.Dockerfile index 83fe27d98..804024823 100644 --- a/.gitlab/ci/fedora.Dockerfile +++ b/.gitlab/ci/fedora.Dockerfile @@ -23,8 +23,11 @@ RUN dnf -y install \ meson \ python3 \ python3-jinja2 \ + python3-markdown \ python3-pip \ python3-pygments \ + python3-toml \ + python3-typogrify \ python3-wheel \ redhat-rpm-config \ shared-mime-info \ -- cgit v1.2.1 From 5030bb133d10b5cefbff4623d58b0a6abf52e72a Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sat, 20 Mar 2021 23:02:29 +0000 Subject: ci: Update reference and dist jobs Point the CI to the right location for the API references. --- .gitlab-ci.yml | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 83bdd6f6d..0d52caf6b 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -23,8 +23,8 @@ variables: before_script: - mkdir -p _ccache script: - - meson ${COMMON_MESON_FLAGS} ${LOADERS_FLAGS} ${BUILD_OPTS} _build . - - ninja -C _build + - meson setup ${COMMON_MESON_FLAGS} ${LOADERS_FLAGS} ${BUILD_OPTS} _build . + - meson compile -C _build - .gitlab/scripts/run-tests.sh _build artifacts: when: always @@ -69,7 +69,7 @@ macos: - export PATH=/Users/gitlabrunner/Library/Python/3.7/bin:$PATH script: - meson setup -Dintrospection=disabled -Dinstalled_tests=false -Dman=false -Dgtk_doc=false _build - - meson compile -C_build + - meson compile -C _build artifacts: when: always paths: @@ -90,9 +90,11 @@ reference: variables: BUILD_OPTS: "-Dbuildtype=release -Dgtk_doc=true" script: - - meson ${COMMON_MESON_FLAGS} ${LOADERS_FLAGS} ${BUILD_OPTS} _build . - - ninja -C _build gdk-pixbuf-doc - - mv _build/docs/html _reference + - meson setup ${COMMON_MESON_FLAGS} ${LOADERS_FLAGS} ${BUILD_OPTS} _build . + - meson compile -C _build + - mkdir -p _reference + - mv _build/docs/gdk-pixbuf/ _reference/gdk-pixbuf/ + - mv _build/docs/gdk-pixdata/ _reference/gdk-pixdata/ artifacts: when: on_success paths: @@ -105,7 +107,7 @@ static-scan: variables: BUILD_OPTS: "--buildtype=debug" script: - - meson ${COMMON_MESON_FLAGS} ${LOADERS_FLAGS} ${BUILD_OPTS} _scan_build + - meson setup ${COMMON_MESON_FLAGS} ${LOADERS_FLAGS} ${BUILD_OPTS} _scan_build - ninja -C _scan_build scan-build artifacts: paths: @@ -121,8 +123,8 @@ asan-build: needs: [] variables: script: - - CC=clang meson --buildtype=debugoptimized -Db_sanitize=address -Db_lundef=false -Dintrospection=disabled _build - - ninja -C _build + - CC=clang meson setup --buildtype=debugoptimized -Db_sanitize=address -Db_lundef=false -Dintrospection=disabled _build + - meson compile -C _build - .gitlab/scripts/run-tests.sh _build artifacts: paths: @@ -139,13 +141,14 @@ release-dist: - meson ${COMMON_MESON_FLAGS} ${LOADERS_FLAGS} ${BUILD_OPTS} _build . - meson compile -C _build - meson dist -C _build - - ninja -C _build gdk-pixbuf-doc - - tar -c -J -f _build/gdk-pixbuf-docs-${CI_COMMIT_TAG}.tar.xz _build/docs/ + - tar -c -J -f _build/gdk-pixbuf-docs-${CI_COMMIT_TAG}.tar.xz _build/docs/gdk-pixbuf/ + - tar -c -J -f _build/gdk-pixdata-docs-${CI_COMMIT_TAG}.tar.xz _build/docs/gdk-pixdata/ artifacts: when: on_success paths: - _build/meson-dist/gdk-pixbuf-${CI_COMMIT_TAG}.tar.xz - _build/gdk-pixbuf-docs-${CI_COMMIT_TAG}.tar.xz + - _build/gdk-pixdata-docs-${CI_COMMIT_TAG}.tar.xz only: - tags -- cgit v1.2.1 From 63e3081997f40bf0464bff714e91169bef86da9a Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sat, 20 Mar 2021 23:51:03 +0000 Subject: docs: Clean up GdkPixbuf's core API Use proper summaries; remove gtk-doc'isms; document properties. --- gdk-pixbuf/gdk-pixbuf.c | 176 +++++++++++++++++++++++++++++------------------- 1 file changed, 106 insertions(+), 70 deletions(-) diff --git a/gdk-pixbuf/gdk-pixbuf.c b/gdk-pixbuf/gdk-pixbuf.c index 383fe024b..01b53f088 100644 --- a/gdk-pixbuf/gdk-pixbuf.c +++ b/gdk-pixbuf/gdk-pixbuf.c @@ -238,7 +238,8 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass) /** * GdkPixbuf:n-channels: * - * The number of samples per pixel. + * The number of samples per pixel. + * * Currently, only 3 or 4 samples per pixel are supported. */ g_object_class_install_property (object_class, @@ -250,7 +251,13 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass) G_MAXINT, 3, PIXBUF_PARAM_FLAGS)); - + /** + * GdkPixbuf:colorspace: + * + * The color space of the pixbuf. + * + * Currently, only `GDK_COLORSPACE_RGB` is supported. + */ g_object_class_install_property (object_class, PROP_COLORSPACE, g_param_spec_enum ("colorspace", @@ -259,7 +266,11 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass) GDK_TYPE_COLORSPACE, GDK_COLORSPACE_RGB, PIXBUF_PARAM_FLAGS)); - + /** + * GdkPixbuf:has-alpha: + * + * Whether the pixbuf has an alpha channel. + */ g_object_class_install_property (object_class, PROP_HAS_ALPHA, g_param_spec_boolean ("has-alpha", @@ -267,11 +278,11 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass) _("Whether the pixbuf has an alpha channel"), FALSE, PIXBUF_PARAM_FLAGS)); - /** * GdkPixbuf:bits-per-sample: * * The number of bits per sample. + * * Currently only 8 bit per sample are supported. */ g_object_class_install_property (object_class, @@ -283,7 +294,11 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass) 16, 8, PIXBUF_PARAM_FLAGS)); - + /** + * GdkPixbuf:width: + * + * The number of columns of the pixbuf. + */ g_object_class_install_property (object_class, PROP_WIDTH, g_param_spec_int ("width", @@ -293,7 +308,11 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass) G_MAXINT, 1, PIXBUF_PARAM_FLAGS)); - + /** + * GdkPixbuf:height: + * + * The number of rows of the pixbuf. + */ g_object_class_install_property (object_class, PROP_HEIGHT, g_param_spec_int ("height", @@ -303,13 +322,14 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass) G_MAXINT, 1, PIXBUF_PARAM_FLAGS)); - /** * GdkPixbuf:rowstride: * * The number of bytes between the start of a row and - * the start of the next row. This number must (obviously) - * be at least as large as the width of the pixbuf. + * the start of the next row. + * + * This number must (obviously) be at least as large as the + * width of the pixbuf. */ g_object_class_install_property (object_class, PROP_ROWSTRIDE, @@ -320,18 +340,22 @@ gdk_pixbuf_class_init (GdkPixbufClass *klass) G_MAXINT, 1, PIXBUF_PARAM_FLAGS)); - + /** + * GdkPixbuf:pixels: + * + * A pointer to the pixel data of the pixbuf. + */ g_object_class_install_property (object_class, PROP_PIXELS, g_param_spec_pointer ("pixels", _("Pixels"), _("A pointer to the pixel data of the pixbuf"), PIXBUF_PARAM_FLAGS)); - /** * GdkPixbuf::pixel-bytes: * * If set, this pixbuf was created from read-only #GBytes. + * * Replaces GdkPixbuf::pixels. * * Since: 2.32 @@ -539,8 +563,10 @@ free_buffer (guchar *pixels, gpointer data) * @height: Height of image in pixels, must be > 0 * * Calculates the rowstride that an image created with those values would - * have. This is useful for front-ends and backends that want to sanity - * check image values without needing to create them. + * have. + * + * This function is useful for front-ends and backends that want to check + * image values without needing to create a `GdkPixbuf`. * * Return value: the rowstride for the given values, or -1 in case of error. * @@ -578,12 +604,14 @@ gdk_pixbuf_calculate_rowstride (GdkColorspace colorspace, * @width: Width of image in pixels, must be > 0 * @height: Height of image in pixels, must be > 0 * - * Creates a new #GdkPixbuf structure and allocates a buffer for it. The - * buffer has an optimal rowstride. Note that the buffer is not cleared; + * Creates a new `GdkPixbuf` structure and allocates a buffer for it. + * + * If the allocation of the buffer failed, this function will return `NULL`. + * + * The buffer has an optimal rowstride. Note that the buffer is not cleared; * you will have to fill it completely yourself. * - * Return value: (nullable): A newly-created #GdkPixbuf with a reference count of 1, or - * %NULL if not enough memory could be allocated for the image buffer. + * Return value: (transfer full) (nullable): A newly-created pixel buffer **/ GdkPixbuf * gdk_pixbuf_new (GdkColorspace colorspace, @@ -616,12 +644,13 @@ gdk_pixbuf_new (GdkColorspace colorspace, * gdk_pixbuf_copy: * @pixbuf: A pixbuf. * - * Creates a new #GdkPixbuf with a copy of the information in the specified - * @pixbuf. Note that this does not copy the options set on the original #GdkPixbuf, + * Creates a new `GdkPixbuf` with a copy of the information in the specified + * `pixbuf`. + * + * Note that this does not copy the options set on the original `GdkPixbuf`, * use gdk_pixbuf_copy_options() for this. * - * Return value: (nullable) (transfer full): A newly-created pixbuf with a reference count of 1, or %NULL if - * not enough memory could be allocated. + * Return value: (nullable) (transfer full): A newly-created pixbuf **/ GdkPixbuf * gdk_pixbuf_copy (const GdkPixbuf *pixbuf) @@ -655,19 +684,20 @@ gdk_pixbuf_copy (const GdkPixbuf *pixbuf) /** * gdk_pixbuf_new_subpixbuf: - * @src_pixbuf: a #GdkPixbuf + * @src_pixbuf: a `GdkPixbuf` * @src_x: X coord in @src_pixbuf * @src_y: Y coord in @src_pixbuf * @width: width of region in @src_pixbuf * @height: height of region in @src_pixbuf * - * Creates a new pixbuf which represents a sub-region of @src_pixbuf. + * Creates a new pixbuf which represents a sub-region of `src_pixbuf`. + * * The new pixbuf shares its pixels with the original pixbuf, so * writing to one affects both. The new pixbuf holds a reference to - * @src_pixbuf, so @src_pixbuf will not be finalized until the new + * `src_pixbuf`, so `src_pixbuf` will not be finalized until the new * pixbuf is finalized. * - * Note that if @src_pixbuf is read-only, this function will force it + * Note that if `src_pixbuf` is read-only, this function will force it * to be mutable. * * Return value: (transfer full): a new pixbuf @@ -752,7 +782,7 @@ gdk_pixbuf_get_n_channels (const GdkPixbuf *pixbuf) * * Queries whether a pixbuf has an alpha channel (opacity information). * - * Return value: %TRUE if it has an alpha channel, %FALSE otherwise. + * Return value: `TRUE` if it has an alpha channel, `FALSE` otherwise. **/ gboolean gdk_pixbuf_get_has_alpha (const GdkPixbuf *pixbuf) @@ -784,12 +814,13 @@ gdk_pixbuf_get_bits_per_sample (const GdkPixbuf *pixbuf) * * Queries a pointer to the pixel data of a pixbuf. * - * Return value: (array): A pointer to the pixbuf's pixel data. - * Please see the section on [image data][image-data] for information - * about how the pixel data is stored in memory. - * * This function will cause an implicit copy of the pixbuf data if the * pixbuf was created from read-only data. + * + * Please see the section on [image data](#image-data) for information + * about how the pixel data is stored in memory. + * + * Return value: (array): A pointer to the pixbuf's pixel data. **/ guchar * gdk_pixbuf_get_pixels (const GdkPixbuf *pixbuf) @@ -830,13 +861,15 @@ downgrade_to_pixels (const GdkPixbuf *pixbuf) * * Queries a pointer to the pixel data of a pixbuf. * - * Return value: (array length=length): A pointer to the pixbuf's - * pixel data. Please see the section on [image data][image-data] - * for information about how the pixel data is stored in memory. - * * This function will cause an implicit copy of the pixbuf data if the * pixbuf was created from read-only data. * + * Please see the section on [image data](#image-data) for information + * about how the pixel data is stored in memory. + * + * Return value: (array length=length): A pointer to the pixbuf's + * pixel data. + * * Since: 2.26 */ guchar * @@ -858,10 +891,10 @@ gdk_pixbuf_get_pixels_with_length (const GdkPixbuf *pixbuf, * gdk_pixbuf_read_pixels: * @pixbuf: A pixbuf * - * Provides a read-only pointer to the raw pixel data; must not be - * modified. This function allows skipping the implicit copy that - * must be made if gdk_pixbuf_get_pixels() is called on a read-only - * pixbuf. + * Provides a read-only pointer to the raw pixel data. + * + * This function allows skipping the implicit copy that must be made + * if gdk_pixbuf_get_pixels() is called on a read-only pixbuf. * * Returns: a read-only pointer to the raw pixel data * @@ -893,9 +926,10 @@ gdk_pixbuf_read_pixels (const GdkPixbuf *pixbuf) * @pixbuf: A pixbuf * * Provides a #GBytes buffer containing the raw pixel data; the data - * must not be modified. This function allows skipping the implicit - * copy that must be made if gdk_pixbuf_get_pixels() is called on a - * read-only pixbuf. + * must not be modified. + * + * This function allows skipping the implicit copy that must be made + * if gdk_pixbuf_get_pixels() is called on a read-only pixbuf. * * Returns: (transfer full): A new reference to a read-only copy of * the pixel data. Note that for mutable pixbufs, this function will @@ -1008,15 +1042,16 @@ gdk_pixbuf_error_quark (void) /** * gdk_pixbuf_fill: - * @pixbuf: a #GdkPixbuf - * @pixel: RGBA pixel to clear to - * (0xffffffff is opaque white, 0x00000000 transparent black) + * @pixbuf: a `GdkPixbuf` + * @pixel: RGBA pixel to used to clear (`0xffffffff` is opaque white, + * `0x00000000` transparent black) * * Clears a pixbuf to the given RGBA value, converting the RGBA value into - * the pixbuf's pixel format. The alpha will be ignored if the pixbuf - * doesn't have an alpha channel. - * - **/ + * the pixbuf's pixel format. + * + * The alpha component will be ignored if the pixbuf doesn't have an alpha + * channel. + */ void gdk_pixbuf_fill (GdkPixbuf *pixbuf, guint32 pixel) @@ -1075,7 +1110,7 @@ gdk_pixbuf_fill (GdkPixbuf *pixbuf, /** * gdk_pixbuf_get_option: - * @pixbuf: a #GdkPixbuf + * @pixbuf: a `GdkPixbuf` * @key: a nul-terminated string. * * Looks up @key in the list of options that may have been attached to the @@ -1094,8 +1129,7 @@ gdk_pixbuf_fill (GdkPixbuf *pixbuf, * Since 2.36.6, the JPEG loader sets the "comment" option with the comment * EXIF tag. * - * Return value: the value associated with @key. This is a nul-terminated - * string that should not be freed or %NULL if @key was not found. + * Return value: (transfer none) (nullable): the value associated with `key` **/ const gchar * gdk_pixbuf_get_option (GdkPixbuf *pixbuf, @@ -1121,15 +1155,14 @@ gdk_pixbuf_get_option (GdkPixbuf *pixbuf, /** * gdk_pixbuf_get_options: - * @pixbuf: a #GdkPixbuf + * @pixbuf: a `GdkPixbuf` * - * Returns a #GHashTable with a list of all the options that may have been - * attached to the @pixbuf when it was loaded, or that may have been - * attached by another function using gdk_pixbuf_set_option(). + * Returns a `GHashTable` with a list of all the options that may have been + * attached to the `pixbuf` when it was loaded, or that may have been + * attached by another function using [method@GdkPixbuf.Pixbuf.set_option]. * - * See gdk_pixbuf_get_option() for more details. - * - * Return value: (transfer container) (element-type utf8 utf8): a #GHashTable of key/values + * Return value: (transfer container) (element-type utf8 utf8): a #GHashTable + * of key/values pairs * * Since: 2.32 **/ @@ -1157,12 +1190,12 @@ gdk_pixbuf_get_options (GdkPixbuf *pixbuf) /** * gdk_pixbuf_remove_option: - * @pixbuf: a #GdkPixbuf + * @pixbuf: a `GdkPixbuf` * @key: a nul-terminated string representing the key to remove. * - * Remove the key/value pair option attached to a #GdkPixbuf. + * Removes the key/value pair option attached to a `GdkPixbuf`. * - * Return value: %TRUE if an option was removed, %FALSE if not. + * Return value: `TRUE` if an option was removed, `FALSE` if not. * * Since: 2.36 **/ @@ -1223,15 +1256,16 @@ gdk_pixbuf_remove_option (GdkPixbuf *pixbuf, /** * gdk_pixbuf_set_option: - * @pixbuf: a #GdkPixbuf + * @pixbuf: a `GdkPixbuf` * @key: a nul-terminated string. * @value: a nul-terminated string. * - * Attaches a key/value pair as an option to a #GdkPixbuf. If @key already - * exists in the list of options attached to @pixbuf, the new value is - * ignored and %FALSE is returned. + * Attaches a key/value pair as an option to a `GdkPixbuf`. + * + * If `key` already exists in the list of options attached to the `pixbuf`, + * the new value is ignored and `FALSE` is returned. * - * Return value: %TRUE on success. + * Return value: `TRUE` on success * * Since: 2.2 **/ @@ -1276,15 +1310,17 @@ gdk_pixbuf_set_option (GdkPixbuf *pixbuf, /** * gdk_pixbuf_copy_options: - * @src_pixbuf: a #GdkPixbuf to copy options from - * @dest_pixbuf: the #GdkPixbuf to copy options to + * @src_pixbuf: the source pixbuf + * @dest_pixbuf: the destination pixbuf + * + * Copies the key/value pair options attached to a `GdkPixbuf` to another + * `GdkPixbuf`. * - * Copy the key/value pair options attached to a #GdkPixbuf to another. * This is useful to keep original metadata after having manipulated * a file. However be careful to remove metadata which you've already * applied, such as the "orientation" option after rotating the image. * - * Return value: %TRUE on success. + * Return value: `TRUE` on success. * * Since: 2.36 **/ -- cgit v1.2.1 From f2a11232efeb7372256634c5e0f8c8e2aa161f9e Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sun, 21 Mar 2021 12:29:51 +0000 Subject: docs: Update gdk-pixbuf-io style --- gdk-pixbuf/gdk-pixbuf-io.c | 585 ++++++++++++++++++++++++--------------------- 1 file changed, 313 insertions(+), 272 deletions(-) diff --git a/gdk-pixbuf/gdk-pixbuf-io.c b/gdk-pixbuf/gdk-pixbuf-io.c index 13bf5af16..eb442e3bc 100644 --- a/gdk-pixbuf/gdk-pixbuf-io.c +++ b/gdk-pixbuf/gdk-pixbuf-io.c @@ -52,16 +52,16 @@ * @module_name: the name of the module, usually the same as the * usual file extension for images of this type, eg. "xpm", "jpeg" or "png". * @module_path: the path from which the module is loaded. - * @module: the loaded #GModule. - * @info: a #GdkPixbufFormat holding information about the module. + * @module: the loaded `GModule`. + * @info: a `GdkPixbufFormat` holding information about the module. * @load: loads an image from a file. * @load_xpm_data: loads an image from data in memory. * @begin_load: begins an incremental load. * @stop_load: stops an incremental load. * @load_increment: continues an incremental load. * @load_animation: loads an animation from a file. - * @save: saves a #GdkPixbuf to a file. - * @save_to_callback: saves a #GdkPixbuf by calling the given #GdkPixbufSaveFunc. + * @save: saves a `GdkPixbuf` to a file. + * @save_to_callback: saves a `GdkPixbuf` by calling the given `GdkPixbufSaveFunc`. * @is_save_option_supported: returns whether a save option key is supported by the module * * A `GdkPixbufModule` contains the necessary functions to load and save @@ -557,10 +557,10 @@ gdk_pixbuf_io_init_modules (const char *filename, /** * gdk_pixbuf_init_modules: - * @path: Path to directory where the loaders.cache is installed - * @error: return location for a #GError + * @path: Path to directory where the `loaders.cache` is installed + * @error: return location for a `GError` * - * Initalizes the gdk-pixbuf loader modules referenced by the loaders.cache + * Initalizes the gdk-pixbuf loader modules referenced by the `loaders.cache` * file present inside that directory. * * This is to be used by applications that want to ship certain loaders @@ -1080,20 +1080,26 @@ _gdk_pixbuf_generic_image_load (GdkPixbufModule *module, FILE *f, GError **error } /** - * gdk_pixbuf_new_from_file: + * gdk_pixbuf_new_from_file: (constructor) * @filename: (type filename): Name of file to load, in the GLib file - * name encoding - * @error: Return location for an error + * name encoding + * @error: (out): Return location for an error * - * Creates a new pixbuf by loading an image from a file. The file format is - * detected automatically. If %NULL is returned, then @error will be set. - * Possible errors are in the #GDK_PIXBUF_ERROR and #G_FILE_ERROR domains. + * Creates a new pixbuf by loading an image from a file. * - * Return value: A newly-created pixbuf with a reference count of 1, or %NULL if - * any of several error conditions occurred: the file could not be opened, - * there was no loader for the file's format, there was not enough memory to - * allocate the image buffer, or the image file contained invalid data. - **/ + * The file format is detected automatically. + * + * If `NULL` is returned, then @error will be set. Possible errors are: + * + * - the file could not be opened + * - there is no loader for the file's format + * - there is not enough memory to allocate the image buffer + * - the image buffer contains invalid data + * + * The error domains are `GDK_PIXBUF_ERROR` and `G_FILE_ERROR`. + * + * Return value: (transfer full) (nullable): A newly-created pixbuf + */ GdkPixbuf * gdk_pixbuf_new_from_file (const char *filename, GError **error) @@ -1179,7 +1185,7 @@ gdk_pixbuf_new_from_file (const char *filename, * * Same as gdk_pixbuf_new_from_file() * - * Return value: A newly-created pixbuf with a reference count of 1, or %NULL if + * Return value: A newly-created pixbuf with a reference count of 1, or `NULL` if * any of several error conditions occurred: the file could not be opened, * there was no loader for the file's format, there was not enough memory to * allocate the image buffer, or the image file contained invalid data. @@ -1195,29 +1201,33 @@ gdk_pixbuf_new_from_file_utf8 (const char *filename, /** - * gdk_pixbuf_new_from_file_at_size: + * gdk_pixbuf_new_from_file_at_size: (constructor) * @filename: (type filename): Name of file to load, in the GLib file * name encoding * @width: The width the image should have or -1 to not constrain the width * @height: The height the image should have or -1 to not constrain the height - * @error: Return location for an error + * @error: (out): Return location for an error + * + * Creates a new pixbuf by loading an image from a file. * - * Creates a new pixbuf by loading an image from a file. - * The file format is detected automatically. If %NULL is returned, then - * @error will be set. Possible errors are in the #GDK_PIXBUF_ERROR and - * #G_FILE_ERROR domains. + * The file format is detected automatically. + * + * If `NULL` is returned, then @error will be set. Possible errors are: + * + * - the file could not be opened + * - there is no loader for the file's format + * - there is not enough memory to allocate the image buffer + * - the image buffer contains invalid data + * + * The error domains are `GDK_PIXBUF_ERROR` and `G_FILE_ERROR`. * * The image will be scaled to fit in the requested size, preserving * the image's aspect ratio. Note that the returned pixbuf may be smaller - * than @width x @height, if the aspect ratio requires it. To load + * than `width` x `height`, if the aspect ratio requires it. To load * and image at the requested size, regardless of aspect ratio, use - * gdk_pixbuf_new_from_file_at_scale(). + * [ctor@GdkPixbuf.Pixbuf.new_from_file_at_scale]. * - * Return value: A newly-created pixbuf with a reference count of 1, or - * %NULL if any of several error conditions occurred: the file could not - * be opened, there was no loader for the file's format, there was not - * enough memory to allocate the image buffer, or the image file contained - * invalid data. + * Return value: (transfer full) (nullable): A newly-created pixbuf * * Since: 2.4 **/ @@ -1244,7 +1254,7 @@ gdk_pixbuf_new_from_file_at_size (const char *filename, * Same as gdk_pixbuf_new_from_file_at_size() * * Return value: A newly-created pixbuf with a reference count of 1, or - * %NULL if any of several error conditions occurred: the file could not + * `NULL` if any of several error conditions occurred: the file could not * be opened, there was no loader for the file's format, there was not * enough memory to allocate the image buffer, or the image file contained * invalid data. @@ -1318,31 +1328,38 @@ at_scale_size_prepared_cb (GdkPixbufLoader *loader, } /** - * gdk_pixbuf_new_from_file_at_scale: + * gdk_pixbuf_new_from_file_at_scale: (constructor) * @filename: (type filename): Name of file to load, in the GLib file * name encoding * @width: The width the image should have or -1 to not constrain the width * @height: The height the image should have or -1 to not constrain the height - * @preserve_aspect_ratio: %TRUE to preserve the image's aspect ratio + * @preserve_aspect_ratio: `TRUE` to preserve the image's aspect ratio * @error: Return location for an error * - * Creates a new pixbuf by loading an image from a file. The file format is - * detected automatically. If %NULL is returned, then @error will be set. - * Possible errors are in the #GDK_PIXBUF_ERROR and #G_FILE_ERROR domains. + * Creates a new pixbuf by loading an image from a file. + * + * The file format is detected automatically. + * + * If `NULL` is returned, then @error will be set. Possible errors are: + * + * - the file could not be opened + * - there is no loader for the file's format + * - there is not enough memory to allocate the image buffer + * - the image buffer contains invalid data + * + * The error domains are `GDK_PIXBUF_ERROR` and `G_FILE_ERROR`. + * * The image will be scaled to fit in the requested size, optionally preserving * the image's aspect ratio. * - * When preserving the aspect ratio, a @width of -1 will cause the image - * to be scaled to the exact given height, and a @height of -1 will cause + * When preserving the aspect ratio, a `width` of -1 will cause the image + * to be scaled to the exact given height, and a `height` of -1 will cause * the image to be scaled to the exact given width. When not preserving - * aspect ratio, a @width or @height of -1 means to not scale the image - * at all in that dimension. Negative values for @width and @height are + * aspect ratio, a `width` or `height` of -1 means to not scale the image + * at all in that dimension. Negative values for `width` and `height` are * allowed since 2.8. * - * Return value: A newly-created pixbuf with a reference count of 1, or %NULL - * if any of several error conditions occurred: the file could not be opened, - * there was no loader for the file's format, there was not enough memory to - * allocate the image buffer, or the image file contained invalid data. + * Return value: (transfer full) (nullable): A newly-created pixbuf * * Since: 2.6 **/ @@ -1447,12 +1464,12 @@ gdk_pixbuf_new_from_file_at_scale (const char *filename, * @filename: (type filename): Name of file to load, in the GLib file name encoding * @width: The width the image should have or -1 to not constrain the width * @height: The height the image should have or -1 to not constrain the height - * @preserve_aspect_ratio: %TRUE to preserve the image's aspect ratio + * @preserve_aspect_ratio: `TRUE` to preserve the image's aspect ratio * @error: Return location for an error * * Same as gdk_pixbuf_new_from_file_at_scale(). * - * Return value: A newly-created pixbuf with a reference count of 1, or %NULL + * Return value: A newly-created pixbuf with a reference count of 1, or `NULL` * if any of several error conditions occurred: the file could not be opened, * there was no loader for the file's format, there was not enough memory to * allocate the image buffer, or the image file contained invalid data. @@ -1517,40 +1534,37 @@ load_from_stream (GdkPixbufLoader *loader, /** - * gdk_pixbuf_new_from_stream_at_scale: - * @stream: a #GInputStream to load the pixbuf from + * gdk_pixbuf_new_from_stream_at_scale: (constructor) + * @stream: a `GInputStream` to load the pixbuf from * @width: The width the image should have or -1 to not constrain the width * @height: The height the image should have or -1 to not constrain the height - * @preserve_aspect_ratio: %TRUE to preserve the image's aspect ratio - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @preserve_aspect_ratio: `TRUE` to preserve the image's aspect ratio + * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore * @error: Return location for an error * * Creates a new pixbuf by loading an image from an input stream. * - * The file format is detected automatically. If %NULL is returned, then + * The file format is detected automatically. If `NULL` is returned, then * @error will be set. The @cancellable can be used to abort the operation * from another thread. If the operation was cancelled, the error - * %G_IO_ERROR_CANCELLED will be returned. Other possible errors are in - * the #GDK_PIXBUF_ERROR and %G_IO_ERROR domains. + * `G_IO_ERROR_CANCELLED` will be returned. Other possible errors are in + * the `GDK_PIXBUF_ERROR` and `G_IO_ERROR` domains. * * The image will be scaled to fit in the requested size, optionally * preserving the image's aspect ratio. * - * When preserving the aspect ratio, a @width of -1 will cause the image to be - * scaled to the exact given height, and a @height of -1 will cause the image - * to be scaled to the exact given width. If both @width and @height are + * When preserving the aspect ratio, a `width` of -1 will cause the image to be + * scaled to the exact given height, and a `height` of -1 will cause the image + * to be scaled to the exact given width. If both `width` and `height` are * given, this function will behave as if the smaller of the two values * is passed as -1. * - * When not preserving aspect ratio, a @width or @height of -1 means to not + * When not preserving aspect ratio, a `width` or `height` of -1 means to not * scale the image at all in that dimension. * * The stream is not closed. * - * Return value: A newly-created pixbuf, or %NULL if any of several error - * conditions occurred: the file could not be opened, the image format is - * not supported, there was not enough memory to allocate the image buffer, - * the stream contained invalid data, or the operation was cancelled. + * Return value: (transfer full) (nullable): A newly-created pixbuf * * Since: 2.14 */ @@ -1633,12 +1647,12 @@ out: /** * gdk_pixbuf_new_from_stream_at_scale_async: - * @stream: a #GInputStream from which to load the pixbuf + * @stream: a `GInputStream` from which to load the pixbuf * @width: the width the image should have or -1 to not constrain the width * @height: the height the image should have or -1 to not constrain the height - * @preserve_aspect_ratio: %TRUE to preserve the image's aspect ratio - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback to call when the pixbuf is loaded + * @preserve_aspect_ratio: `TRUE` to preserve the image's aspect ratio + * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore + * @callback: a `GAsyncReadyCallback` to call when the pixbuf is loaded * @user_data: the data to pass to the callback function * * Creates a new pixbuf by asynchronously loading an image from an input stream. @@ -1694,25 +1708,25 @@ gdk_pixbuf_new_from_stream_at_scale_async (GInputStream *stream, } /** - * gdk_pixbuf_new_from_stream: - * @stream: a #GInputStream to load the pixbuf from - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * gdk_pixbuf_new_from_stream: (constructor) + * @stream: a `GInputStream` to load the pixbuf from + * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore * @error: Return location for an error * * Creates a new pixbuf by loading an image from an input stream. * - * The file format is detected automatically. If %NULL is returned, then - * @error will be set. The @cancellable can be used to abort the operation - * from another thread. If the operation was cancelled, the error - * %G_IO_ERROR_CANCELLED will be returned. Other possible errors are in - * the #GDK_PIXBUF_ERROR and %G_IO_ERROR domains. + * The file format is detected automatically. + * + * If `NULL` is returned, then `error` will be set. + * + * The `cancellable` can be used to abort the operation from another thread. + * If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be + * returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and + * `G_IO_ERROR` domains. * * The stream is not closed. * - * Return value: A newly-created pixbuf, or %NULL if any of several error - * conditions occurred: the file could not be opened, the image format is - * not supported, there was not enough memory to allocate the image buffer, - * the stream contained invalid data, or the operation was cancelled. + * Return value: (transfer full) (nullable): A newly-created pixbuf * * Since: 2.14 **/ @@ -1770,19 +1784,16 @@ G_GNUC_END_IGNORE_DEPRECATIONS } /** - * gdk_pixbuf_new_from_resource: + * gdk_pixbuf_new_from_resource: (constructor) * @resource_path: the path of the resource file * @error: Return location for an error * * Creates a new pixbuf by loading an image from an resource. * - * The file format is detected automatically. If %NULL is returned, then + * The file format is detected automatically. If `NULL` is returned, then * @error will be set. * - * Return value: A newly-created pixbuf, or %NULL if any of several error - * conditions occurred: the file could not be opened, the image format is - * not supported, there was not enough memory to allocate the image buffer, - * the stream contained invalid data, or the operation was cancelled. + * Return value: (transfer full) (nullable): A newly-created pixbuf * * Since: 2.26 **/ @@ -1807,16 +1818,16 @@ gdk_pixbuf_new_from_resource (const gchar *resource_path, } /** - * gdk_pixbuf_new_from_resource_at_scale: + * gdk_pixbuf_new_from_resource_at_scale: (constructor) * @resource_path: the path of the resource file * @width: The width the image should have or -1 to not constrain the width * @height: The height the image should have or -1 to not constrain the height - * @preserve_aspect_ratio: %TRUE to preserve the image's aspect ratio + * @preserve_aspect_ratio: `TRUE` to preserve the image's aspect ratio * @error: Return location for an error * * Creates a new pixbuf by loading an image from an resource. * - * The file format is detected automatically. If %NULL is returned, then + * The file format is detected automatically. If `NULL` is returned, then * @error will be set. * * The image will be scaled to fit in the requested size, optionally @@ -1828,10 +1839,7 @@ gdk_pixbuf_new_from_resource (const gchar *resource_path, * * The stream is not closed. * - * Return value: A newly-created pixbuf, or %NULL if any of several error - * conditions occurred: the file could not be opened, the image format is - * not supported, there was not enough memory to allocate the image buffer, - * the stream contained invalid data, or the operation was cancelled. + * Return value: (transfer full) (nullable): A newly-created pixbuf * * Since: 2.26 */ @@ -1856,9 +1864,9 @@ gdk_pixbuf_new_from_resource_at_scale (const char *resource_path, /** * gdk_pixbuf_new_from_stream_async: - * @stream: a #GInputStream from which to load the pixbuf - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback to call when the pixbuf is loaded + * @stream: a `GInputStream` from which to load the pixbuf + * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore + * @callback: a `GAsyncReadyCallback` to call when the pixbuf is loaded * @user_data: the data to pass to the callback function * * Creates a new pixbuf by asynchronously loading an image from an input stream. @@ -1867,7 +1875,8 @@ gdk_pixbuf_new_from_resource_at_scale (const char *resource_path, * version of this function. * * When the operation is finished, @callback will be called in the main thread. - * You can then call gdk_pixbuf_new_from_stream_finish() to get the result of the operation. + * You can then call gdk_pixbuf_new_from_stream_finish() to get the result of + * the operation. * * Since: 2.24 **/ @@ -1897,14 +1906,13 @@ gdk_pixbuf_new_from_stream_async (GInputStream *stream, /** * gdk_pixbuf_new_from_stream_finish: - * @async_result: a #GAsyncResult - * @error: a #GError, or %NULL + * @async_result: a `GAsyncResult` + * @error: a `GError`, or `NULL` * * Finishes an asynchronous pixbuf creation operation started with * gdk_pixbuf_new_from_stream_async(). * - * Return value: a #GdkPixbuf or %NULL on error. Free the returned - * object with g_object_unref(). + * Return value: (transfer full) (nullable): the newly created pixbuf * * Since: 2.24 **/ @@ -1949,17 +1957,13 @@ info_cb (GdkPixbufLoader *loader, /** * gdk_pixbuf_get_file_info: * @filename: (type filename): The name of the file to identify. - * @width: (optional) (out): Return location for the width of the - * image, or %NULL - * @height: (optional) (out): Return location for the height of the - * image, or %NULL + * @width: (optional) (out): Return location for the width of the image + * @height: (optional) (out): Return location for the height of the image * * Parses an image file far enough to determine its format and size. * - * Returns: (nullable) (transfer none): A #GdkPixbufFormat describing - * the image format of the file or %NULL if the image format wasn't - * recognized. The return value is owned by #GdkPixbuf and should - * not be freed. + * Returns: (nullable) (transfer none): A `GdkPixbufFormat` describing + * the image format of the file * * Since: 2.4 **/ @@ -2051,8 +2055,8 @@ get_file_info_thread (GTask *task, /** * gdk_pixbuf_get_file_info_async: * @filename: (type filename): The name of the file to identify - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback to call when the file info is available + * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore + * @callback: a `GAsyncReadyCallback` to call when the file info is available * @user_data: the data to pass to the callback function * * Asynchronously parses an image file far enough to determine its @@ -2093,18 +2097,16 @@ gdk_pixbuf_get_file_info_async (const gchar *filename, /** * gdk_pixbuf_get_file_info_finish: - * @async_result: a #GAsyncResult - * @width: (out): Return location for the width of the image, or %NULL - * @height: (out): Return location for the height of the image, or %NULL - * @error: a #GError, or %NULL + * @async_result: a `GAsyncResult` + * @width: (out): Return location for the width of the image, or `NULL` + * @height: (out): Return location for the height of the image, or `NULL` + * @error: a `GError`, or `NULL` * * Finishes an asynchronous pixbuf parsing operation started with * gdk_pixbuf_get_file_info_async(). * - * Returns: (transfer none): A #GdkPixbufFormat describing the image - * format of the file or %NULL if the image format wasn't - * recognized. The return value is owned by GdkPixbuf and should - * not be freed. + * Returns: (transfer none) (nullable): A `GdkPixbufFormat` describing the + * image format of the file * * Since: 2.32 **/ @@ -2140,10 +2142,12 @@ gdk_pixbuf_get_file_info_finish (GAsyncResult *async_result, * gdk_pixbuf_new_from_xpm_data: * @data: (array zero-terminated=1): Pointer to inline XPM data. * - * Creates a new pixbuf by parsing XPM data in memory. This data is commonly - * the result of including an XPM file into a program's C source. + * Creates a new pixbuf by parsing XPM data in memory. + * + * This data is commonly the result of including an XPM file into a + * program's C source. * - * Return value: A newly-created pixbuf with a reference count of 1. + * Return value: A newly-created pixbuf **/ GdkPixbuf * gdk_pixbuf_new_from_xpm_data (const char **data) @@ -2404,18 +2408,18 @@ gdk_pixbuf_real_save_to_callback (GdkPixbuf *pixbuf, /** * gdk_pixbuf_save: - * @pixbuf: a #GdkPixbuf. + * @pixbuf: a `GdkPixbuf`. * @filename: (type filename): name of file to save. * @type: name of file format. - * @error: (allow-none): return location for error, or %NULL - * @...: list of key-value save options, followed by %NULL + * @error: (nullable): return location for error + * @...: list of key-value save options, followed by `NULL` * * Saves pixbuf to a file in format @type. By default, "jpeg", "png", "ico" * and "bmp" are possible file formats to save in, but more formats may be * installed. The list of all writable formats can be determined in the * following way: * - * |[ + * ```c * void add_if_writable (GdkPixbufFormat *data, GSList **list) * { * if (gdk_pixbuf_format_is_writable (data)) @@ -2426,55 +2430,63 @@ gdk_pixbuf_real_save_to_callback (GdkPixbuf *pixbuf, * GSList *writable_formats = NULL; * g_slist_foreach (formats, add_if_writable, &writable_formats); * g_slist_free (formats); - * ]| + * ``` * - * If @error is set, %FALSE will be returned. Possible errors include - * those in the #GDK_PIXBUF_ERROR domain and those in the #G_FILE_ERROR domain. + * If `error` is set, `FALSE` will be returned. Possible errors include + * those in the `GDK_PIXBUF_ERROR` domain and those in the `G_FILE_ERROR` + * domain. * - * The variable argument list should be %NULL-terminated; if not empty, + * The variable argument list should be `NULL`-terminated; if not empty, * it should contain pairs of strings that modify the save * parameters. For example: - * |[ + * + * ```c * gdk_pixbuf_save (pixbuf, handle, "jpeg", &error, "quality", "100", NULL); - * ]| + * ``` * - * Currently only few parameters exist. JPEG images can be saved with a - * "quality" parameter; its value should be in the range [0,100]. JPEG - * and PNG density can be set by setting the "x-dpi" and "y-dpi" parameters - * to the appropriate values in dots per inch. + * Currently only few parameters exist. + * + * JPEG images can be saved with a "quality" parameter; its value should be + * in the range `[0, 100]`. JPEG and PNG density can be set by setting the + * "x-dpi" and "y-dpi" parameters to the appropriate values in dots per inch. * * Text chunks can be attached to PNG images by specifying parameters of * the form "tEXt::key", where key is an ASCII string of length 1-79. * The values are UTF-8 encoded strings. The PNG compression level can * be specified using the "compression" parameter; it's value is in an - * integer in the range of [0,9]. + * integer in the range of `[0, 9]`. * * ICC color profiles can also be embedded into PNG, JPEG and TIFF images. * The "icc-profile" value should be the complete ICC profile encoded * into base64. * - * |[ - * gchar *contents; - * gchar *contents_encode; + * ```c + * char *contents; * gsize length; - * g_file_get_contents ("/home/hughsie/.color/icc/L225W.icm", &contents, &length, NULL); - * contents_encode = g_base64_encode ((const guchar *) contents, length); + * + * // icm_path is set elsewhere + * g_file_get_contents (icm_path, &contents, &length, NULL); + * + * char *contents_encode = g_base64_encode ((const guchar *) contents, length); + * * gdk_pixbuf_save (pixbuf, handle, "png", &error, "icc-profile", contents_encode, NULL); - * ]| + * ``` * - * TIFF images recognize: (1) a "bits-per-sample" option (integer) which - * can be either 1 for saving bi-level CCITTFAX4 images, or 8 for saving - * 8-bits per sample; (2) a "compression" option (integer) which can be - * 1 for no compression, 2 for Huffman, 5 for LZW, 7 for JPEG and 8 for - * DEFLATE (see the libtiff documentation and tiff.h for all supported - * codec values); (3) an "icc-profile" option (zero-terminated string) - * containing a base64 encoded ICC color profile. + * TIFF images recognize: + * + * 1. a "bits-per-sample" option (integer) which can be either 1 for saving + * bi-level CCITTFAX4 images, or 8 for saving 8-bits per sample + * 2. a "compression" option (integer) which can be 1 for no compression, + * 2 for Huffman, 5 for LZW, 7 for JPEG and 8 for DEFLATE (see the libtiff + * documentation and tiff.h for all supported codec values) + * 3. an "icc-profile" option (zero-terminated string) containing a base64 + * encoded ICC color profile. * * ICO images can be saved in depth 16, 24, or 32, by using the "depth" * parameter. When the ICO saver is given "x_hot" and "y_hot" parameters, * it produces a CUR instead of an ICO. * - * Return value: whether an error was set + * Return value: `TRUE` on success, and `FALSE` otherwise **/ gboolean gdk_pixbuf_save (GdkPixbuf *pixbuf, @@ -2508,16 +2520,20 @@ gdk_pixbuf_save (GdkPixbuf *pixbuf, /** * gdk_pixbuf_savev: - * @pixbuf: a #GdkPixbuf. + * @pixbuf: a `GdkPixbuf`. * @filename: (type filename): name of file to save. * @type: name of file format. - * @option_keys: (array zero-terminated=1): name of options to set, %NULL-terminated - * @option_values: (array zero-terminated=1): values for named options - * @error: (allow-none): return location for error, or %NULL + * @option_keys: (array zero-terminated=1) (element-type utf8) (nullable): name of options to set + * @option_values: (array zero-terminated=1) (element-type utf8) (nullable): values for named options + * @error: (allow-none): return location for error, or `NULL` + * + * Vector version of `gdk_pixbuf_save()`. + * + * Saves pixbuf to a file in `type`, which is currently "jpeg", "png", "tiff", "ico" or "bmp". * - * Saves pixbuf to a file in @type, which is currently "jpeg", "png", "tiff", "ico" or "bmp". - * If @error is set, %FALSE will be returned. - * See gdk_pixbuf_save () for more details. + * If @error is set, `FALSE` will be returned. + * + * See [method@GdkPixbuf.Pixbuf.save] for more details. * * Return value: whether an error was set **/ @@ -2589,12 +2605,12 @@ gdk_pixbuf_savev (GdkPixbuf *pixbuf, /** * gdk_pixbuf_savev_utf8: - * @pixbuf: a #GdkPixbuf. + * @pixbuf: a `GdkPixbuf`. * @filename: name of file to save. * @type: name of file format. - * @option_keys: (array zero-terminated=1): name of options to set, %NULL-terminated - * @option_values: (array zero-terminated=1): values for named options - * @error: (allow-none): return location for error, or %NULL + * @option_keys: (array zero-terminated=1) (element-type utf8) (nullable): name of options to set + * @option_values: (array zero-terminated=1) (element-type utf8) (nullable): values for named options + * @error: (allow-none): return location for error, or `NULL` * * Same as gdk_pixbuf_savev() * @@ -2616,22 +2632,25 @@ gdk_pixbuf_savev_utf8 (GdkPixbuf *pixbuf, /** * gdk_pixbuf_save_to_callback: - * @pixbuf: a #GdkPixbuf. + * @pixbuf: a `GdkPixbuf`. * @save_func: (scope call): a function that is called to save each block of data that * the save routine generates. * @user_data: user data to pass to the save function. * @type: name of file format. - * @error: (allow-none): return location for error, or %NULL + * @error: (allow-none): return location for error, or `NULL` * @...: list of key-value save options * - * Saves pixbuf in format @type by feeding the produced data to a - * callback. Can be used when you want to store the image to something - * other than a file, such as an in-memory buffer or a socket. - * If @error is set, %FALSE will be returned. Possible errors - * include those in the #GDK_PIXBUF_ERROR domain and whatever the save + * Saves pixbuf in format `type` by feeding the produced data to a + * callback. + * + * This function can be used when you want to store the image to something + * other than a file, such as an in-memory buffer or a socket. + * + * If @error is set, `FALSE` will be returned. Possible errors + * include those in the `GDK_PIXBUF_ERROR` domain and whatever the save * function generates. * - * See gdk_pixbuf_save() for more details. + * See [method@GdkPixbuf.Pixbuf.save] for more details. * * Return value: whether an error was set * @@ -2670,18 +2689,23 @@ gdk_pixbuf_save_to_callback (GdkPixbuf *pixbuf, /** * gdk_pixbuf_save_to_callbackv: - * @pixbuf: a #GdkPixbuf. + * @pixbuf: a `GdkPixbuf`. * @save_func: (scope call): a function that is called to save each block of data that * the save routine generates. * @user_data: (closure): user data to pass to the save function. * @type: name of file format. - * @option_keys: (array zero-terminated=1) (element-type utf8): name of options to set, %NULL-terminated - * @option_values: (array zero-terminated=1) (element-type utf8): values for named options - * @error: (allow-none): return location for error, or %NULL + * @option_keys: (array zero-terminated=1) (element-type utf8) (nullable): name of options to set + * @option_values: (array zero-terminated=1) (element-type utf8) (nullable): values for named options + * @error: (allow-none): return location for error, or `NULL` + * + * Vector version of `gdk_pixbuf_save_to_callback()`. * * Saves pixbuf to a callback in format @type, which is currently "jpeg", - * "png", "tiff", "ico" or "bmp". If @error is set, %FALSE will be returned. See - * gdk_pixbuf_save_to_callback () for more details. + * "png", "tiff", "ico" or "bmp". + * + * If @error is set, `FALSE` will be returned. + * + * See [method@GdkPixbuf.Pixbuf.save_to_callback] for more details. * * Return value: whether an error was set * @@ -2721,23 +2745,28 @@ gdk_pixbuf_save_to_callbackv (GdkPixbuf *pixbuf, /** * gdk_pixbuf_save_to_buffer: - * @pixbuf: a #GdkPixbuf. + * @pixbuf: a `GdkPixbuf`. * @buffer: (array length=buffer_size) (out) (element-type guint8): location to receive a pointer * to the new buffer. * @buffer_size: location to receive the size of the new buffer. * @type: name of file format. - * @error: (allow-none): return location for error, or %NULL + * @error: (allow-none): return location for error, or `NULL` * @...: list of key-value save options * - * Saves pixbuf to a new buffer in format @type, which is currently "jpeg", - * "png", "tiff", "ico" or "bmp". This is a convenience function that uses - * gdk_pixbuf_save_to_callback() to do the real work. Note that the buffer - * is not nul-terminated and may contain embedded nuls. - * If @error is set, %FALSE will be returned and @buffer will be set to - * %NULL. Possible errors include those in the #GDK_PIXBUF_ERROR + * Saves pixbuf to a new buffer in format `type`, which is currently "jpeg", + * "png", "tiff", "ico" or "bmp". + * + * This is a convenience function that uses `gdk_pixbuf_save_to_callback()` + * to do the real work. + * + * Note that the buffer is not `NUL`-terminated and may contain embedded `NUL` + * characters. + * + * If @error is set, `FALSE` will be returned and @buffer will be set to + * `NULL`. Possible errors include those in the `GDK_PIXBUF_ERROR` * domain. * - * See gdk_pixbuf_save() for more details. + * See `gdk_pixbuf_save()` for more details. * * Return value: whether an error was set * @@ -2809,18 +2838,21 @@ save_to_buffer_callback (const gchar *data, /** * gdk_pixbuf_save_to_bufferv: - * @pixbuf: a #GdkPixbuf. + * @pixbuf: a `GdkPixbuf`. * @buffer: (array length=buffer_size) (out) (element-type guint8): * location to receive a pointer to the new buffer. * @buffer_size: location to receive the size of the new buffer. * @type: name of file format. - * @option_keys: (array zero-terminated=1): name of options to set, %NULL-terminated - * @option_values: (array zero-terminated=1): values for named options - * @error: (allow-none): return location for error, or %NULL + * @option_keys: (array zero-terminated=1) (element-type utf8) (nullable): name of options to set + * @option_values: (array zero-terminated=1) (element-type utf8) (nullable): values for named options + * @error: (allow-none): return location for error, or `NULL` + * + * Vector version of `gdk_pixbuf_save_to_buffer()`. * * Saves pixbuf to a new buffer in format @type, which is currently "jpeg", - * "tiff", "png", "ico" or "bmp". See gdk_pixbuf_save_to_buffer() - * for more details. + * "tiff", "png", "ico" or "bmp". + * + * See [method@GdkPixbuf.Pixbuf.save_to_buffer] for more details. * * Return value: whether an error was set * @@ -2908,21 +2940,23 @@ save_to_stream (const gchar *buffer, /** * gdk_pixbuf_save_to_streamv: - * @pixbuf: a #GdkPixbuf - * @stream: a #GOutputStream to save the pixbuf to + * @pixbuf: a `GdkPixbuf` + * @stream: a `GOutputStream` to save the pixbuf to * @type: name of file format - * @option_keys: (array zero-terminated=1): name of options to set, %NULL-terminated - * @option_values: (array zero-terminated=1): values for named options - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @error: (allow-none): return location for error, or %NULL + * @option_keys: (array zero-terminated=1) (element-type utf8) (nullable): name of options to set + * @option_values: (array zero-terminated=1) (element-type utf8) (nullable): values for named options + * @cancellable: (nullable): optional `GCancellable` object, `NULL` to ignore + * @error: return location for error * - * Saves @pixbuf to an output stream. + * Saves `pixbuf` to an output stream. * * Supported file formats are currently "jpeg", "tiff", "png", "ico" or - * "bmp". See gdk_pixbuf_save_to_stream() for more details. + * "bmp". * - * Returns: %TRUE if the pixbuf was saved successfully, %FALSE if an - * error was set. + * See [method@GdkPixbuf.Pixbuf.save_to_stream] for more details. + * + * Returns: `TRUE` if the pixbuf was saved successfully, `FALSE` if an + * error was set. * * Since: 2.36 */ @@ -2948,27 +2982,27 @@ gdk_pixbuf_save_to_streamv (GdkPixbuf *pixbuf, /** * gdk_pixbuf_save_to_stream: - * @pixbuf: a #GdkPixbuf - * @stream: a #GOutputStream to save the pixbuf to + * @pixbuf: a `GdkPixbuf` + * @stream: a `GOutputStream` to save the pixbuf to * @type: name of file format - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @error: (allow-none): return location for error, or %NULL + * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore + * @error: (allow-none): return location for error, or `NULL` * @...: list of key-value save options * - * Saves @pixbuf to an output stream. + * Saves `pixbuf` to an output stream. * * Supported file formats are currently "jpeg", "tiff", "png", "ico" or - * "bmp". See gdk_pixbuf_save_to_buffer() for more details. + * "bmp". See `gdk_pixbuf_save_to_buffer()` for more details. * - * The @cancellable can be used to abort the operation from another - * thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED - * will be returned. Other possible errors are in the #GDK_PIXBUF_ERROR - * and %G_IO_ERROR domains. + * The `cancellable` can be used to abort the operation from another + * thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` + * will be returned. Other possible errors are in the `GDK_PIXBUF_ERROR` + * and `G_IO_ERROR` domains. * - * The stream is not closed. + * The stream is not closed at the end of this call. * - * Returns: %TRUE if the pixbuf was saved successfully, %FALSE if an - * error was set. + * Returns: `TRUE` if the pixbuf was saved successfully, `FALSE` if an + * error was set. * * Since: 2.14 */ @@ -3044,22 +3078,24 @@ save_to_stream_thread (GTask *task, /** * gdk_pixbuf_save_to_streamv_async: - * @pixbuf: a #GdkPixbuf - * @stream: a #GOutputStream to which to save the pixbuf + * @pixbuf: a `GdkPixbuf` + * @stream: a `GOutputStream` to which to save the pixbuf * @type: name of file format - * @option_keys: (array zero-terminated=1): name of options to set, %NULL-terminated - * @option_values: (array zero-terminated=1): values for named options - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback to call when the pixbuf is saved + * @option_keys: (array zero-terminated=1) (element-type utf8) (nullable): name of options to set + * @option_values: (array zero-terminated=1) (element-type utf8) (nullable): values for named options + * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore + * @callback: a `GAsyncReadyCallback` to call when the pixbuf is saved * @user_data: the data to pass to the callback function * - * Saves @pixbuf to an output stream asynchronously. + * Saves `pixbuf` to an output stream asynchronously. * * For more details see gdk_pixbuf_save_to_streamv(), which is the synchronous * version of this function. * - * When the operation is finished, @callback will be called in the main thread. - * You can then call gdk_pixbuf_save_to_stream_finish() to get the result of the operation. + * When the operation is finished, `callback` will be called in the main thread. + * + * You can then call gdk_pixbuf_save_to_stream_finish() to get the result of + * the operation. * * Since: 2.36 **/ @@ -3100,21 +3136,23 @@ gdk_pixbuf_save_to_streamv_async (GdkPixbuf *pixbuf, /** * gdk_pixbuf_save_to_stream_async: - * @pixbuf: a #GdkPixbuf - * @stream: a #GOutputStream to which to save the pixbuf + * @pixbuf: a `GdkPixbuf` + * @stream: a `GOutputStream` to which to save the pixbuf * @type: name of file format - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback to call when the pixbuf is saved + * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore + * @callback: a `GAsyncReadyCallback` to call when the pixbuf is saved * @user_data: the data to pass to the callback function * @...: list of key-value save options * - * Saves @pixbuf to an output stream asynchronously. + * Saves `pixbuf` to an output stream asynchronously. * * For more details see gdk_pixbuf_save_to_stream(), which is the synchronous * version of this function. * - * When the operation is finished, @callback will be called in the main thread. - * You can then call gdk_pixbuf_save_to_stream_finish() to get the result of the operation. + * When the operation is finished, `callback` will be called in the main thread. + * + * You can then call gdk_pixbuf_save_to_stream_finish() to get the result of + * the operation. * * Since: 2.24 **/ @@ -3153,13 +3191,13 @@ gdk_pixbuf_save_to_stream_async (GdkPixbuf *pixbuf, /** * gdk_pixbuf_save_to_stream_finish: - * @async_result: a #GAsyncResult - * @error: a #GError, or %NULL + * @async_result: a `GAsyncResult` + * @error: a `GError`, or `NULL` * * Finishes an asynchronous pixbuf save operation started with * gdk_pixbuf_save_to_stream_async(). * - * Return value: %TRUE if the pixbuf was saved successfully, %FALSE if an error was set. + * Return value: `TRUE` if the pixbuf was saved successfully, `FALSE` if an error was set. * * Since: 2.24 **/ @@ -3185,7 +3223,7 @@ gdk_pixbuf_save_to_stream_finish (GAsyncResult *async_result, /** * gdk_pixbuf_format_get_name: - * @format: a #GdkPixbufFormat + * @format: a `GdkPixbufFormat` * * Returns the name of the format. * @@ -3203,7 +3241,7 @@ gdk_pixbuf_format_get_name (GdkPixbufFormat *format) /** * gdk_pixbuf_format_get_description: - * @format: a #GdkPixbufFormat + * @format: a `GdkPixbufFormat` * * Returns a description of the format. * @@ -3229,12 +3267,11 @@ gdk_pixbuf_format_get_description (GdkPixbufFormat *format) /** * gdk_pixbuf_format_get_mime_types: - * @format: a #GdkPixbufFormat + * @format: a `GdkPixbufFormat` * * Returns the mime types supported by the format. * - * Return value: (transfer full): a %NULL-terminated array of mime types which must be freed with - * g_strfreev() when it is no longer needed. + * Return value: (transfer full) (array zero-terminated=1): an array of mime types * * Since: 2.2 */ @@ -3248,13 +3285,13 @@ gdk_pixbuf_format_get_mime_types (GdkPixbufFormat *format) /** * gdk_pixbuf_format_get_extensions: - * @format: a #GdkPixbufFormat + * @format: a `GdkPixbufFormat` * * Returns the filename extensions typically used for files in the * given format. * - * Return value: (transfer full): a %NULL-terminated array of filename extensions which must be - * freed with g_strfreev() when it is no longer needed. + * Return value: (transfer full) (array zero-terminated=1): an array of + * filename extensions * * Since: 2.2 */ @@ -3268,7 +3305,7 @@ gdk_pixbuf_format_get_extensions (GdkPixbufFormat *format) /** * gdk_pixbuf_format_is_writable: - * @format: a #GdkPixbufFormat + * @format: a `GdkPixbufFormat` * * Returns whether pixbufs can be saved in the given format. * @@ -3286,12 +3323,13 @@ gdk_pixbuf_format_is_writable (GdkPixbufFormat *format) /** * gdk_pixbuf_format_is_scalable: - * @format: a #GdkPixbufFormat + * @format: a `GdkPixbufFormat` * - * Returns whether this image format is scalable. If a file is in a - * scalable format, it is preferable to load it at the desired size, - * rather than loading it at the default size and scaling the - * resulting pixbuf to the desired size. + * Returns whether this image format is scalable. + * + * If a file is in a scalable format, it is preferable to load it at + * the desired size, rather than loading it at the default size and + * scaling the resulting pixbuf to the desired size. * * Return value: whether this image format is scalable. * @@ -3307,10 +3345,11 @@ gdk_pixbuf_format_is_scalable (GdkPixbufFormat *format) /** * gdk_pixbuf_format_is_disabled: - * @format: a #GdkPixbufFormat + * @format: a `GdkPixbufFormat` + * + * Returns whether this image format is disabled. * - * Returns whether this image format is disabled. See - * gdk_pixbuf_format_set_disabled(). + * See gdk_pixbuf_format_set_disabled(). * * Return value: whether this image format is disabled. * @@ -3326,13 +3365,16 @@ gdk_pixbuf_format_is_disabled (GdkPixbufFormat *format) /** * gdk_pixbuf_format_set_disabled: - * @format: a #GdkPixbufFormat - * @disabled: %TRUE to disable the format @format + * @format: a `GdkPixbufFormat` + * @disabled: `TRUE` to disable the format @format * - * Disables or enables an image format. If a format is disabled, - * gdk-pixbuf won't use the image loader for this format to load - * images. Applications can use this to avoid using image loaders - * with an inappropriate license, see gdk_pixbuf_format_get_license(). + * Disables or enables an image format. + * + * If a format is disabled, GdkPixbuf won't use the image loader for + * this format to load images. + * + * Applications can use this to avoid using image loaders with an + * inappropriate license, see gdk_pixbuf_format_get_license(). * * Since: 2.6 */ @@ -3347,14 +3389,14 @@ gdk_pixbuf_format_set_disabled (GdkPixbufFormat *format, /** * gdk_pixbuf_format_get_license: - * @format: a #GdkPixbufFormat + * @format: a pixbuf format * - * Returns information about the license of the image loader for the format. The - * returned string should be a shorthand for a wellknown license, e.g. "LGPL", - * "GPL", "QPL", "GPL/QPL", or "other" to indicate some other license. This - * string should be freed with g_free() when it's no longer needed. + * Returns information about the license of the image loader for the format. * - * Returns: a string describing the license of @format. + * The returned string should be a shorthand for a well known license, e.g. + * "LGPL", "GPL", "QPL", "GPL/QPL", or "other" to indicate some other license. + * + * Returns: (transfer full): a string describing the license of the pixbuf format * * Since: 2.6 */ @@ -3381,9 +3423,7 @@ _gdk_pixbuf_get_format (GdkPixbufModule *module) * by GdkPixbuf. * * Returns: (transfer container) (element-type GdkPixbufFormat): A list of - * #GdkPixbufFormats describing the supported image formats. The list should - * be freed when it is no longer needed, but the structures themselves are - * owned by #GdkPixbuf and should not be freed. + * support image formats. * * Since: 2.2 */ @@ -3404,11 +3444,11 @@ gdk_pixbuf_get_formats (void) /** * gdk_pixbuf_format_copy: - * @format: a #GdkPixbufFormat + * @format: a pixbuf format * - * Creates a copy of @format + * Creates a copy of `format`. * - * Return value: the newly allocated copy of a #GdkPixbufFormat. Use + * Return value: the newly allocated copy of a `GdkPixbufFormat`. Use * gdk_pixbuf_format_free() to free the resources when done * * Since: 2.22 @@ -3424,9 +3464,9 @@ gdk_pixbuf_format_copy (const GdkPixbufFormat *format) /** * gdk_pixbuf_format_free: - * @format: a #GdkPixbufFormat + * @format: a pixbuf format * - * Frees the resources allocated when copying a #GdkPixbufFormat + * Frees the resources allocated when copying a `GdkPixbufFormat` * using gdk_pixbuf_format_copy() * * Since: 2.22 @@ -3440,14 +3480,15 @@ gdk_pixbuf_format_free (GdkPixbufFormat *format) /** * gdk_pixbuf_format_is_save_option_supported: - * @format: a #GdkPixbufFormat + * @format: a pixbuf format * @option_key: the name of an option * - * Returns %TRUE if the save option specified by @option_key is supported when + * Returns `TRUE` if the save option specified by @option_key is supported when * saving a pixbuf using the module implementing @format. + * * See gdk_pixbuf_save() for more information about option keys. * - * Returns: %TRUE if the specified option is supported + * Returns: `TRUE` if the specified option is supported * * Since: 2.36 */ -- cgit v1.2.1 From 27f5e96604763535be0213ee218f4ca7676bc410 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sun, 21 Mar 2021 12:45:56 +0000 Subject: docs: Update pixdata style --- gdk-pixbuf/gdk-pixdata.c | 117 +++++++++++++++++++++++++---------------------- 1 file changed, 63 insertions(+), 54 deletions(-) diff --git a/gdk-pixbuf/gdk-pixdata.c b/gdk-pixbuf/gdk-pixdata.c index 35f90dffc..621167611 100644 --- a/gdk-pixbuf/gdk-pixdata.c +++ b/gdk-pixbuf/gdk-pixdata.c @@ -202,20 +202,24 @@ get_uint32 (const guint8 *stream, guint *result) * @stream_length: length of the stream used for deserialization. * @stream: (array length=stream_length): stream of bytes containing a * serialized #GdkPixdata structure. - * @error: #GError location to indicate failures (maybe %NULL to ignore errors). + * @error: #GError location to indicate failures (maybe `NULL` to ignore errors). * * Deserializes (reconstruct) a #GdkPixdata structure from a byte stream. + * * The byte stream consists of a straightforward writeout of the - * #GdkPixdata fields in network byte order, plus the @pixel_data + * `GdkPixdata` fields in network byte order, plus the `pixel_data` * bytes the structure points to. - * The @pixdata contents are reconstructed byte by byte and are checked - * for validity. This function may fail with %GDK_PIXBUF_ERROR_CORRUPT_IMAGE - * or %GDK_PIXBUF_ERROR_UNKNOWN_TYPE. * - * Return value: Upon successful deserialization %TRUE is returned, - * %FALSE otherwise. + * The `pixdata` contents are reconstructed byte by byte and are checked + * for validity. * - * Deprecated: 2.32: Use #GResource instead. + * This function may fail with `GDK_PIXBUF_ERROR_CORRUPT_IMAGE` + * or `GDK_PIXBUF_ERROR_UNKNOWN_TYPE`. + * + * Return value: Upon successful deserialization `TRUE` is returned, + * `FALSE` otherwise. + * + * Deprecated: 2.32: Use `GResource` instead. **/ gboolean gdk_pixdata_deserialize (GdkPixdata *pixdata, @@ -333,17 +337,18 @@ free_buffer (guchar *pixels, gpointer data) /** * gdk_pixdata_from_pixbuf: (skip) - * @pixdata: a #GdkPixdata to fill. - * @pixbuf: the data to fill @pixdata with. + * @pixdata: a `GdkPixdata` to fill. + * @pixbuf: the data to fill `pixdata` with. * @use_rle: whether to use run-length encoding for the pixel data. * - * Converts a #GdkPixbuf to a #GdkPixdata. If @use_rle is %TRUE, the - * pixel data is run-length encoded into newly-allocated memory and a - * pointer to that memory is returned. + * Converts a `GdkPixbuf` to a `GdkPixdata`. + * + * If `use_rle` is `TRUE`, the pixel data is run-length encoded into + * newly-allocated memory and a pointer to that memory is returned. * - * Returns: (nullable): If @use_rle is %TRUE, a pointer to the - * newly-allocated memory for the run-length encoded pixel data, - * otherwise %NULL. + * Returns: (nullable) (array) (element-type guint8): If `use_rle` is + * `TRUE`, a pointer to the newly-allocated memory for the run-length + * encoded pixel data, otherwise `NULL`. * * Deprecated: 2.32: Use #GResource instead. **/ @@ -432,17 +437,20 @@ gdk_pixdata_from_pixbuf (GdkPixdata *pixdata, /** * gdk_pixbuf_from_pixdata: - * @pixdata: a #GdkPixdata to convert into a #GdkPixbuf. + * @pixdata: a #GdkPixdata to convert into a `GdkPixbuf`. * @copy_pixels: whether to copy raw pixel data; run-length encoded - * pixel data is always copied. + * pixel data is always copied. * @error: location to store possible errors. * - * Converts a #GdkPixdata to a #GdkPixbuf. If @copy_pixels is %TRUE or - * if the pixel data is run-length-encoded, the pixel data is copied into - * newly-allocated memory; otherwise it is reused. + * Converts a `GdkPixdata` to a `GdkPixbuf`. * - * Returns: (transfer full): a new #GdkPixbuf. - * Deprecated: 2.32: Use #GResource instead. + * If `copy_pixels` is `TRUE` or if the pixel data is run-length-encoded, + * the pixel data is copied into newly-allocated memory; otherwise it is + * reused. + * + * Returns: (transfer full): a new pixbuf + * + * Deprecated: 2.32: Use `GResource` instead. **/ GdkPixbuf* gdk_pixbuf_from_pixdata (const GdkPixdata *pixdata, @@ -702,20 +710,19 @@ save_rle_decoder (GString *gstring, /** * gdk_pixdata_to_csource: - * @pixdata: a #GdkPixdata to convert to C source. - * @name: used for naming generated data structures or macros. - * @dump_type: a #GdkPixdataDumpType determining the kind of C - * source to be generated. + * @pixdata: a `GdkPixdata` to convert to C source + * @name: used for naming generated data structures or macros + * @dump_type: the kind of C source to be generated * * Generates C source code suitable for compiling images directly * into programs. * - * gdk-pixbuf ships with a program called - * [gdk-pixbuf-csource][gdk-pixbuf-csource], which offers a command - * line interface to this function. + * GdkPixbuf ships with a program called `gdk-pixbuf-csource`, which offers + * a command line interface to this function. + * + * Returns: (transfer full): a newly-allocated string buffer containing + * the C source form of `pixdata`. * - * Returns: a newly-allocated string containing the C source form - * of @pixdata. * Deprecated: 2.32: Use #GResource instead. **/ GString* @@ -943,49 +950,51 @@ gdk_pixdata_to_csource (GdkPixdata *pixdata, /** * gdk_pixbuf_new_from_inline: - * @data_length: Length in bytes of the @data argument or -1 to - * disable length checks + * @data_length: Length in bytes of the `data` argument or -1 to + * disable length checks * @data: (array length=data_length): Byte data containing a - * serialized #GdkPixdata structure + * serialized `GdkPixdata` structure * @copy_pixels: Whether to copy the pixel data, or use direct pointers - * @data for the resulting pixbuf - * @error: #GError return location, may be %NULL to ignore errors + * `data` for the resulting pixbuf + * @error: #GError return location, may be `NULL` to ignore errors + * + * Creates a `GdkPixbuf` from a flat representation that is suitable for + * storing as inline data in a program. * - * Create a #GdkPixbuf from a flat representation that is suitable for - * storing as inline data in a program. This is useful if you want to - * ship a program with images, but don't want to depend on any - * external files. + * This is useful if you want to ship a program with images, but don't want + * to depend on any external files. + * + * GdkPixbuf ships with a program called `gdk-pixbuf-csource`, which allows + * for conversion of `GdkPixbuf`s into such a inline representation. * - * gdk-pixbuf ships with a program called [gdk-pixbuf-csource][gdk-pixbuf-csource], - * which allows for conversion of #GdkPixbufs into such a inline representation. * In almost all cases, you should pass the `--raw` option to * `gdk-pixbuf-csource`. A sample invocation would be: * - * |[ - * gdk-pixbuf-csource --raw --name=myimage_inline myimage.png - * ]| + * ``` + * gdk-pixbuf-csource --raw --name=myimage_inline myimage.png + * ``` * * For the typical case where the inline pixbuf is read-only static data, * you don't need to copy the pixel data unless you intend to write to - * it, so you can pass %FALSE for @copy_pixels. (If you pass `--rle` to - * `gdk-pixbuf-csource`, a copy will be made even if @copy_pixels is %FALSE, - * so using this option is generally a bad idea.) + * it, so you can pass `FALSE` for `copy_pixels`. If you pass `--rle` to + * `gdk-pixbuf-csource`, a copy will be made even if `copy_pixels` is `FALSE`, + * so using this option is generally a bad idea. * * If you create a pixbuf from const inline data compiled into your * program, it's probably safe to ignore errors and disable length checks, * since things will always succeed: - * |[ + * + * ```c * pixbuf = gdk_pixbuf_new_from_inline (-1, myimage_inline, FALSE, NULL); - * ]| + * ``` * * For non-const inline data, you could get out of memory. For untrusted * inline data located at runtime, you could have corrupt inline data in * addition. * - * Return value: A newly-created #GdkPixbuf structure with a reference, - * count of 1, or %NULL if an error occurred. + * Return value: A newly-created pixbuf * - * Deprecated: 2.32: Use #GResource instead. + * Deprecated: 2.32: Use `GResource` instead. **/ GdkPixbuf* gdk_pixbuf_new_from_inline (gint data_length, -- cgit v1.2.1 From 1dd020c40dd89b9d03bbe0289bc46d6f54f7abbc Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sun, 21 Mar 2021 12:51:00 +0000 Subject: docs: Update pixbuf-data style --- gdk-pixbuf/gdk-pixbuf-data.c | 60 ++++++++++++++++++++++++++++---------------- 1 file changed, 38 insertions(+), 22 deletions(-) diff --git a/gdk-pixbuf/gdk-pixbuf-data.c b/gdk-pixbuf/gdk-pixbuf-data.c index cd968d4ae..958bcb73f 100644 --- a/gdk-pixbuf/gdk-pixbuf-data.c +++ b/gdk-pixbuf/gdk-pixbuf-data.c @@ -39,23 +39,30 @@ * drops to zero, or %NULL if the data should not be freed * @destroy_fn_data: (closure): Closure data to pass to the destroy notification function * - * Creates a new #GdkPixbuf out of in-memory image data. Currently only RGB - * images with 8 bits per sample are supported. + * Creates a new #GdkPixbuf out of in-memory image data. + * + * Currently only RGB images with 8 bits per sample are supported. * * Since you are providing a pre-allocated pixel buffer, you must also * specify a way to free that data. This is done with a function of - * type #GdkPixbufDestroyNotify. When a pixbuf created with is + * type `GdkPixbufDestroyNotify`. When a pixbuf created with is * finalized, your destroy notification function will be called, and * it is its responsibility to free the pixel array. * - * See also gdk_pixbuf_new_from_bytes(). + * See also: [ctor@GdkPixbuf.Pixbuf.new_from_bytes] * - * Return value: (transfer full): A newly-created #GdkPixbuf structure with a reference count of 1. + * Return value: (transfer full): A newly-created pixbuf **/ GdkPixbuf * -gdk_pixbuf_new_from_data (const guchar *data, GdkColorspace colorspace, gboolean has_alpha, - int bits_per_sample, int width, int height, int rowstride, - GdkPixbufDestroyNotify destroy_fn, gpointer destroy_fn_data) +gdk_pixbuf_new_from_data (const guchar *data, + GdkColorspace colorspace, + gboolean has_alpha, + int bits_per_sample, + int width, + int height, + int rowstride, + GdkPixbufDestroyNotify destroy_fn, + gpointer destroy_fn_data) { GdkPixbuf *pixbuf; @@ -95,15 +102,24 @@ gdk_pixbuf_new_from_data (const guchar *data, GdkColorspace colorspace, gboolean * @rowstride: Distance in bytes between row starts * * Creates a new #GdkPixbuf out of in-memory readonly image data. + * * Currently only RGB images with 8 bits per sample are supported. - * This is the #GBytes variant of gdk_pixbuf_new_from_data(). * - * Return value: (transfer full): A newly-created #GdkPixbuf structure with a reference count of 1. + * This is the `GBytes` variant of gdk_pixbuf_new_from_data(), useful + * for language bindings. + * + * Return value: (transfer full): A newly-created pixbuf + * * Since: 2.32 **/ GdkPixbuf * -gdk_pixbuf_new_from_bytes (GBytes *data, GdkColorspace colorspace, gboolean has_alpha, - int bits_per_sample, int width, int height, int rowstride) +gdk_pixbuf_new_from_bytes (GBytes *data, + GdkColorspace colorspace, + gboolean has_alpha, + int bits_per_sample, + int width, + int height, + int rowstride) { g_return_val_if_fail (data != NULL, NULL); g_return_val_if_fail (colorspace == GDK_COLORSPACE_RGB, NULL); @@ -112,14 +128,14 @@ gdk_pixbuf_new_from_bytes (GBytes *data, GdkColorspace colorspace, gboolean has_ g_return_val_if_fail (height > 0, NULL); g_return_val_if_fail (g_bytes_get_size (data) >= width * height * (has_alpha ? 4 : 3), NULL); - return (GdkPixbuf*) g_object_new (GDK_TYPE_PIXBUF, - "pixel-bytes", data, - "colorspace", colorspace, - "n-channels", has_alpha ? 4 : 3, - "bits-per-sample", bits_per_sample, - "has-alpha", has_alpha ? TRUE : FALSE, - "width", width, - "height", height, - "rowstride", rowstride, - NULL); + return g_object_new (GDK_TYPE_PIXBUF, + "pixel-bytes", data, + "colorspace", colorspace, + "n-channels", has_alpha ? 4 : 3, + "bits-per-sample", bits_per_sample, + "has-alpha", has_alpha ? TRUE : FALSE, + "width", width, + "height", height, + "rowstride", rowstride, + NULL); } -- cgit v1.2.1 From 8faf4668f28cba323725a6a0a5357bd0d95b6ddc Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sun, 21 Mar 2021 12:58:13 +0000 Subject: docs: Update pixbuf-util style --- gdk-pixbuf/gdk-pixbuf-util.c | 76 ++++++++++++++++++++++++++------------------ 1 file changed, 45 insertions(+), 31 deletions(-) diff --git a/gdk-pixbuf/gdk-pixbuf-util.c b/gdk-pixbuf/gdk-pixbuf-util.c index 89d5a9792..0e80299f5 100644 --- a/gdk-pixbuf/gdk-pixbuf-util.c +++ b/gdk-pixbuf/gdk-pixbuf-util.c @@ -29,26 +29,33 @@ /** * gdk_pixbuf_add_alpha: * @pixbuf: A #GdkPixbuf. - * @substitute_color: Whether to set a color to zero opacity. If this - * is %FALSE, then the (@r, @g, @b) arguments will be ignored. + * @substitute_color: Whether to set a color to zero opacity. * @r: Red value to substitute. * @g: Green value to substitute. * @b: Blue value to substitute. * * Takes an existing pixbuf and adds an alpha channel to it. + * * If the existing pixbuf already had an alpha channel, the channel * values are copied from the original; otherwise, the alpha channel * is initialized to 255 (full opacity). * - * If @substitute_color is %TRUE, then the color specified by (@r, @g, @b) will be - * assigned zero opacity. That is, if you pass (255, 255, 255) for the - * substitute color, all white pixels will become fully transparent. + * If `substitute_color` is `TRUE`, then the color specified by the + * (`r`, `g`, `b`) arguments will be assigned zero opacity. That is, + * if you pass `(255, 255, 255)` for the substitute color, all white + * pixels will become fully transparent. + * + * If `substitute_color` is `FALSE`, then the (`r`, `g`, `b`) arguments + * will be ignored. * - * Return value: (transfer full): A newly-created pixbuf with a reference count of 1. + * Return value: (transfer full): A newly-created pixbuf **/ GdkPixbuf * gdk_pixbuf_add_alpha (const GdkPixbuf *pixbuf, - gboolean substitute_color, guchar r, guchar g, guchar b) + gboolean substitute_color, + guchar r, + guchar g, + guchar b) { GdkPixbuf *new_pixbuf; int x, y; @@ -122,8 +129,9 @@ gdk_pixbuf_add_alpha (const GdkPixbuf *pixbuf, * @dest_x: X coordinate within @dest_pixbuf. * @dest_y: Y coordinate within @dest_pixbuf. * - * Copies a rectangular area from @src_pixbuf to @dest_pixbuf. Conversion of - * pixbuf formats is done automatically. + * Copies a rectangular area from `src_pixbuf` to `dest_pixbuf`. + * + * Conversion of pixbuf formats is done automatically. * * If the source rectangle overlaps the destination rectangle on the * same pixbuf, it will be overwritten during the copy operation. @@ -168,21 +176,27 @@ gdk_pixbuf_copy_area (const GdkPixbuf *src_pixbuf, * @saturation: saturation factor * @pixelate: whether to pixelate * - * Modifies saturation and optionally pixelates @src, placing the result in - * @dest. @src and @dest may be the same pixbuf with no ill effects. If - * @saturation is 1.0 then saturation is not changed. If it's less than 1.0, - * saturation is reduced (the image turns toward grayscale); if greater than - * 1.0, saturation is increased (the image gets more vivid colors). If @pixelate - * is %TRUE, then pixels are faded in a checkerboard pattern to create a - * pixelated image. @src and @dest must have the same image format, size, and + * Modifies saturation and optionally pixelates `src`, placing the result in + * `dest`. + * + * The `src` and `dest` pixbufs must have the same image format, size, and * rowstride. + * + * The `src` and `dest` arguments may be the same pixbuf with no ill effects. + * + * If `saturation` is 1.0 then saturation is not changed. If it's less than 1.0, + * saturation is reduced (the image turns toward grayscale); if greater than + * 1.0, saturation is increased (the image gets more vivid colors). + * + * If `pixelate` is `TRUE`, then pixels are faded in a checkerboard pattern to + * create a pixelated image. * **/ void -gdk_pixbuf_saturate_and_pixelate(const GdkPixbuf *src, - GdkPixbuf *dest, - gfloat saturation, - gboolean pixelate) +gdk_pixbuf_saturate_and_pixelate (const GdkPixbuf *src, + GdkPixbuf *dest, + gfloat saturation, + gboolean pixelate) { /* NOTE that src and dest MAY be the same pixbuf! */ @@ -258,20 +272,20 @@ gdk_pixbuf_saturate_and_pixelate(const GdkPixbuf *src, /** * gdk_pixbuf_apply_embedded_orientation: - * @src: A #GdkPixbuf. + * @src: a pixbuf with an orientation option * * Takes an existing pixbuf and checks for the presence of an - * associated "orientation" option, which may be provided by the - * jpeg loader (which reads the exif orientation tag) or the - * tiff loader (which reads the tiff orientation tag, and - * compensates it for the partial transforms performed by - * libtiff). If an orientation option/tag is present, the - * appropriate transform will be performed so that the pixbuf - * is oriented correctly. + * associated "orientation" option. + * + * The orientation option may be provided by the JPEG loader (which + * reads the exif orientation tag) or the TIFF loader (which reads + * the TIFF orientation tag, and compensates it for the partial + * transforms performed by libtiff). + * + * If an orientation option/tag is present, the appropriate transform + * will be performed so that the pixbuf is oriented correctly. * - * Return value: (transfer full): A newly-created pixbuf, %NULL if - * not enough memory could be allocated for it, or a reference to the - * input pixbuf (with an increased reference count). + * Return value: (transfer full) (nullable): A newly-created pixbuf * * Since: 2.12 **/ -- cgit v1.2.1 From 3b49374085cd00b391ab715c3299dbdd46588ae9 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sun, 21 Mar 2021 13:06:35 +0000 Subject: docs: Update pixbuf-scale style --- gdk-pixbuf/gdk-pixbuf-scale.c | 55 +++++++++++++++++++++---------------------- 1 file changed, 27 insertions(+), 28 deletions(-) diff --git a/gdk-pixbuf/gdk-pixbuf-scale.c b/gdk-pixbuf/gdk-pixbuf-scale.c index 863de8b83..82dfad77b 100644 --- a/gdk-pixbuf/gdk-pixbuf-scale.c +++ b/gdk-pixbuf/gdk-pixbuf-scale.c @@ -45,8 +45,8 @@ * @dest_height) of the resulting image onto the destination image * replacing the previous contents. * - * Try to use gdk_pixbuf_scale_simple() first, this function is - * the industrial-strength power tool you can fall back to if + * Try to use gdk_pixbuf_scale_simple() first; this function is + * the industrial-strength power tool you can fall back to, if * gdk_pixbuf_scale_simple() isn't powerful enough. * * If the source rectangle overlaps the destination rectangle on the @@ -105,6 +105,7 @@ gdk_pixbuf_scale (const GdkPixbuf *src, * * Creates a transformation of the source image @src by scaling by * @scale_x and @scale_y then translating by @offset_x and @offset_y. + * * This gives an image in the coordinates of the destination pixbuf. * The rectangle (@dest_x, @dest_y, @dest_width, @dest_height) * is then alpha blended onto the corresponding rectangle of the @@ -186,7 +187,6 @@ gdk_pixbuf_composite (const GdkPixbuf *src, * * See gdk_pixbuf_composite_color_simple() for a simpler variant of this * function suitable for many tasks. - * **/ void gdk_pixbuf_composite_color (const GdkPixbuf *src, @@ -240,24 +240,26 @@ gdk_pixbuf_composite_color (const GdkPixbuf *src, * @dest_height: the height of destination image * @interp_type: the interpolation type for the transformation. * - * Create a new #GdkPixbuf containing a copy of @src scaled to - * @dest_width x @dest_height. Leaves @src unaffected. @interp_type - * should be #GDK_INTERP_NEAREST if you want maximum speed (but when - * scaling down #GDK_INTERP_NEAREST is usually unusably ugly). The - * default @interp_type should be #GDK_INTERP_BILINEAR which offers - * reasonable quality and speed. + * Create a new pixbuf containing a copy of `src` scaled to + * `dest_width` x `dest_height`. + * + * This function leaves `src` unaffected. + * + * The `interp_type` should be `GDK_INTERP_NEAREST` if you want maximum + * speed (but when scaling down `GDK_INTERP_NEAREST` is usually unusably + * ugly). The default `interp_type` should be `GDK_INTERP_BILINEAR` which + * offers reasonable quality and speed. * - * You can scale a sub-portion of @src by creating a sub-pixbuf - * pointing into @src; see gdk_pixbuf_new_subpixbuf(). + * You can scale a sub-portion of `src` by creating a sub-pixbuf + * pointing into `src`; see [method@GdkPixbuf.Pixbuf.new_subpixbuf]. * - * If @dest_width and @dest_height are equal to the @src width and height, a - * copy of @src is returned, avoiding any scaling. + * If `dest_width` and `dest_height` are equal to the width and height of + * `src`, this function will return an unscaled copy of `src`. * - * For more complicated scaling/alpha blending see gdk_pixbuf_scale() - * and gdk_pixbuf_composite(). + * For more complicated scaling/alpha blending see [method@GdkPixbuf.Pixbuf.scale] + * and [method@GdkPixbuf.Pixbuf.composite]. * - * Return value: (nullable) (transfer full): the new #GdkPixbuf, or %NULL if not enough memory could be - * allocated for it. + * Return value: (nullable) (transfer full): the new pixbuf **/ GdkPixbuf * gdk_pixbuf_scale_simple (const GdkPixbuf *src, @@ -298,12 +300,11 @@ gdk_pixbuf_scale_simple (const GdkPixbuf *src, * @color1: the color of check at upper left * @color2: the color of the other check * - * Creates a new #GdkPixbuf by scaling @src to @dest_width x - * @dest_height and alpha blending the result with a checkboard of colors - * @color1 and @color2. + * Creates a new pixbuf by scaling `src` to `dest_width` x `dest_height` + * and alpha blending the result with a checkboard of colors `color1` + * and `color2`. * - * Return value: (nullable) (transfer full): the new #GdkPixbuf, or %NULL if not enough memory could be - * allocated for it. + * Return value: (nullable) (transfer full): the new pixbuf **/ GdkPixbuf * gdk_pixbuf_composite_color_simple (const GdkPixbuf *src, @@ -344,10 +345,9 @@ gdk_pixbuf_composite_color_simple (const GdkPixbuf *src, * Rotates a pixbuf by a multiple of 90 degrees, and returns the * result in a new pixbuf. * - * If @angle is 0, a copy of @src is returned, avoiding any rotation. + * If `angle` is 0, this function will return a copy of `src`. * - * Returns: (nullable) (transfer full): the new #GdkPixbuf, or %NULL - * if not enough memory could be allocated for it. + * Returns: (nullable) (transfer full): the new pixbuf * * Since: 2.6 */ @@ -446,13 +446,12 @@ gdk_pixbuf_rotate_simple (const GdkPixbuf *src, /** * gdk_pixbuf_flip: * @src: a #GdkPixbuf - * @horizontal: %TRUE to flip horizontally, %FALSE to flip vertically + * @horizontal: `TRUE` to flip horizontally, `FALSE` to flip vertically * * Flips a pixbuf horizontally or vertically and returns the * result in a new pixbuf. * - * Returns: (nullable) (transfer full): the new #GdkPixbuf, or %NULL - * if not enough memory could be allocated for it. + * Returns: (nullable) (transfer full): the new pixbuf * * Since: 2.6 */ -- cgit v1.2.1 From d2cb184255008e19ac5ae4ee01c6d0ae8aa4bd6c Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sun, 21 Mar 2021 13:17:20 +0000 Subject: docs: Update pixbuf-animation style --- gdk-pixbuf/gdk-pixbuf-animation.c | 153 +++++++++++++++++++++----------------- 1 file changed, 83 insertions(+), 70 deletions(-) diff --git a/gdk-pixbuf/gdk-pixbuf-animation.c b/gdk-pixbuf/gdk-pixbuf-animation.c index 9b7372e00..6f2c170b8 100644 --- a/gdk-pixbuf/gdk-pixbuf-animation.c +++ b/gdk-pixbuf/gdk-pixbuf-animation.c @@ -147,18 +147,19 @@ noop_updated_notify (GdkPixbuf *pixbuf, /** * gdk_pixbuf_animation_new_from_file: * @filename: (type filename): Name of file to load, in the GLib file - * name encoding + * name encoding * @error: return location for error * - * Creates a new animation by loading it from a file. The file format is - * detected automatically. If the file's format does not support multi-frame - * images, then an animation with a single frame will be created. Possible errors - * are in the #GDK_PIXBUF_ERROR and #G_FILE_ERROR domains. + * Creates a new animation by loading it from a file. * - * Return value: A newly-created animation with a reference count of 1, or %NULL - * if any of several error conditions ocurred: the file could not be opened, - * there was no loader for the file's format, there was not enough memory to - * allocate the image buffer, or the image file contained invalid data. + * The file format is detected automatically. + * + * If the file's format does not support multi-frame images, then an animation + * with a single frame will be created. + * + * Possible errors are in the `GDK_PIXBUF_ERROR` and `G_FILE_ERROR` domains. + * + * Return value: (transfer full) (nullable): A newly-created animation */ GdkPixbufAnimation * gdk_pixbuf_animation_new_from_file (const gchar *filename, @@ -329,7 +330,7 @@ fail_begin_load: * * Same as gdk_pixbuf_animation_new_from_file() * - * Return value: A newly-created animation with a reference count of 1, or %NULL + * Return value: A newly-created animation with a reference count of 1, or `NULL` * if any of several error conditions ocurred: the file could not be opened, * there was no loader for the file's format, there was not enough memory to * allocate the image buffer, or the image file contained invalid data. @@ -344,24 +345,24 @@ gdk_pixbuf_animation_new_from_file_utf8 (const gchar *filename, /** * gdk_pixbuf_animation_new_from_stream: - * @stream: a #GInputStream to load the pixbuf from - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @stream: a `GInputStream` to load the pixbuf from + * @cancellable: (nullable): optional `GCancellable` object * @error: Return location for an error * * Creates a new animation by loading it from an input stream. * - * The file format is detected automatically. If %NULL is returned, then - * @error will be set. The @cancellable can be used to abort the operation - * from another thread. If the operation was cancelled, the error - * %G_IO_ERROR_CANCELLED will be returned. Other possible errors are in - * the #GDK_PIXBUF_ERROR and %G_IO_ERROR domains. + * The file format is detected automatically. + * + * If `NULL` is returned, then @error will be set. + * + * The @cancellable can be used to abort the operation from another thread. + * If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be + * returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and + * `G_IO_ERROR` domains. * * The stream is not closed. * - * Return value: A newly-created pixbuf, or %NULL if any of several error - * conditions occurred: the file could not be opened, the image format is - * not supported, there was not enough memory to allocate the image buffer, - * the stream contained invalid data, or the operation was cancelled. + * Return value: (transfer full) (nullable): A newly-created animation * * Since: 2.28 */ @@ -442,8 +443,8 @@ animation_new_from_stream_thread (GTask *task, /** * gdk_pixbuf_animation_new_from_stream_async: * @stream: a #GInputStream from which to load the animation - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback to call when the pixbuf is loaded + * @cancellable: (nullable): optional #GCancellable object + * @callback: a `GAsyncReadyCallback` to call when the pixbuf is loaded * @user_data: the data to pass to the callback function * * Creates a new animation by asynchronously loading an image from an input stream. @@ -451,7 +452,7 @@ animation_new_from_stream_thread (GTask *task, * For more details see gdk_pixbuf_new_from_stream(), which is the synchronous * version of this function. * - * When the operation is finished, @callback will be called in the main thread. + * When the operation is finished, `callback` will be called in the main thread. * You can then call gdk_pixbuf_animation_new_from_stream_finish() to get the * result of the operation. * @@ -478,13 +479,12 @@ gdk_pixbuf_animation_new_from_stream_async (GInputStream *stream, /** * gdk_pixbuf_animation_new_from_stream_finish: * @async_result: a #GAsyncResult - * @error: a #GError, or %NULL + * @error: a #GError, or `NULL` * * Finishes an asynchronous pixbuf animation creation operation started with - * gdk_pixbuf_animation_new_from_stream_async(). + * [func@GdkPixbuf.PixbufAnimation.new_from_stream_async]. * - * Return value: a #GdkPixbufAnimation or %NULL on error. Free the returned - * object with g_object_unref(). + * Return value: (transfer full) (nullable): the newly created animation * * Since: 2.28 **/ @@ -508,13 +508,10 @@ gdk_pixbuf_animation_new_from_stream_finish (GAsyncResult *async_result, * * Creates a new pixbuf animation by loading an image from an resource. * - * The file format is detected automatically. If %NULL is returned, then + * The file format is detected automatically. If `NULL` is returned, then * @error will be set. * - * Return value: A newly-created animation, or %NULL if any of several error - * conditions occurred: the file could not be opened, the image format is - * not supported, there was not enough memory to allocate the image buffer, - * the stream contained invalid data, or the operation was cancelled. + * Return value: (transfer full) (nullable): A newly-created animation * * Since: 2.28 */ @@ -576,12 +573,14 @@ gdk_pixbuf_animation_unref (GdkPixbufAnimation *animation) * gdk_pixbuf_animation_is_static_image: * @animation: a #GdkPixbufAnimation * + * Checks whether the animation is a static image. + * * If you load a file with gdk_pixbuf_animation_new_from_file() and it * turns out to be a plain, unanimated image, then this function will - * return %TRUE. Use gdk_pixbuf_animation_get_static_image() to retrieve + * return `TRUE`. Use gdk_pixbuf_animation_get_static_image() to retrieve * the image. * - * Return value: %TRUE if the "animation" was really just an image + * Return value: `TRUE` if the "animation" was really just an image */ gboolean gdk_pixbuf_animation_is_static_image (GdkPixbufAnimation *animation) @@ -595,12 +594,17 @@ gdk_pixbuf_animation_is_static_image (GdkPixbufAnimation *animation) * gdk_pixbuf_animation_get_static_image: * @animation: a #GdkPixbufAnimation * + * Retrieves a static image for the animation. + * * If an animation is really just a plain image (has only one frame), - * this function returns that image. If the animation is an animation, - * this function returns a reasonable thing to display as a static - * unanimated image, which might be the first frame, or something more - * sophisticated. If an animation hasn't loaded any frames yet, this - * function will return %NULL. + * this function returns that image. + * + * If the animation is an animation, this function returns a reasonable + * image to use as a static unanimated image, which might be the first + * frame, or something more sophisticated depending on the file format. + * + * If an animation hasn't loaded any frames yet, this function will + * return `NULL`. * * Return value: (transfer none): unanimated image representing the animation */ @@ -662,9 +666,10 @@ gdk_pixbuf_animation_get_height (GdkPixbufAnimation *animation) * @animation: a #GdkPixbufAnimation * @start_time: (allow-none): time when the animation starts playing * - * Get an iterator for displaying an animation. The iterator provides - * the frames that should be displayed at a given time. It should be - * freed after use with g_object_unref(). + * Get an iterator for displaying an animation. + * + * The iterator provides the frames that should be displayed at a + * given time. * * @start_time would normally come from g_get_current_time(), and marks * the beginning of animation playback. After creating an iterator, you @@ -676,7 +681,7 @@ gdk_pixbuf_animation_get_height (GdkPixbufAnimation *animation) * the image is updated, you should reinstall the timeout with the new, * possibly-changed delay time. * - * As a shortcut, if @start_time is %NULL, the result of + * As a shortcut, if @start_time is `NULL`, the result of * g_get_current_time() will be used automatically. * * To update the image (i.e. possibly change the result of @@ -687,14 +692,14 @@ gdk_pixbuf_animation_get_height (GdkPixbufAnimation *animation) * after the delay time, you should also update it whenever you * receive the area_updated signal and * gdk_pixbuf_animation_iter_on_currently_loading_frame() returns - * %TRUE. In this case, the frame currently being fed into the loader + * `TRUE`. In this case, the frame currently being fed into the loader * has received new data, so needs to be refreshed. The delay time for * a frame may also be modified after an area_updated signal, for * example if the delay time for a frame is encoded in the data after * the frame itself. So your timeout should be reinstalled after any * area_updated signal. * - * A delay time of -1 is possible, indicating "infinite." + * A delay time of -1 is possible, indicating "infinite". * * Return value: (transfer full): an iterator to move over the animation */ @@ -732,9 +737,10 @@ gdk_pixbuf_animation_iter_init (GdkPixbufAnimationIter *iter) * @iter: an animation iterator * * Gets the number of milliseconds the current pixbuf should be displayed, - * or -1 if the current pixbuf should be displayed forever. g_timeout_add() - * conveniently takes a timeout in milliseconds, so you can use a timeout - * to schedule the next update. + * or -1 if the current pixbuf should be displayed forever. + * + * The `g_timeout_add()` function conveniently takes a timeout in milliseconds, + * so you can use a timeout to schedule the next update. * * Note that some formats, like GIF, might clamp the timeout values in the * image file to avoid updates that are just too quick. The minimum timeout @@ -755,17 +761,21 @@ gdk_pixbuf_animation_iter_get_delay_time (GdkPixbufAnimationIter *iter) * gdk_pixbuf_animation_iter_get_pixbuf: * @iter: an animation iterator * - * Gets the current pixbuf which should be displayed; the pixbuf might not - * be the same size as the animation itself + * Gets the current pixbuf which should be displayed. + * + * The pixbuf might not be the same size as the animation itself * (gdk_pixbuf_animation_get_width(), gdk_pixbuf_animation_get_height()). - * This pixbuf should be displayed for - * gdk_pixbuf_animation_iter_get_delay_time() milliseconds. The caller - * of this function does not own a reference to the returned pixbuf; - * the returned pixbuf will become invalid when the iterator advances - * to the next frame, which may happen anytime you call - * gdk_pixbuf_animation_iter_advance(). Copy the pixbuf to keep it - * (don't just add a reference), as it may get recycled as you advance - * the iterator. + * + * This pixbuf should be displayed for gdk_pixbuf_animation_iter_get_delay_time() + * milliseconds. + * + * The caller of this function does not own a reference to the returned + * pixbuf; the returned pixbuf will become invalid when the iterator + * advances to the next frame, which may happen anytime you call + * gdk_pixbuf_animation_iter_advance(). + * + * Copy the pixbuf to keep it (don't just add a reference), as it may get + * recycled as you advance the iterator. * * Return value: (transfer none): the pixbuf to be displayed */ @@ -783,12 +793,13 @@ gdk_pixbuf_animation_iter_get_pixbuf (GdkPixbufAnimationIter *iter) * @iter: a #GdkPixbufAnimationIter * * Used to determine how to respond to the area_updated signal on - * #GdkPixbufLoader when loading an animation. area_updated is emitted - * for an area of the frame currently streaming in to the loader. So if - * you're on the currently loading frame, you need to redraw the screen for - * the updated area. + * #GdkPixbufLoader when loading an animation. * - * Return value: %TRUE if the frame we're on is partially loaded, or the last frame + * The `::area_updated` signal is emitted for an area of the frame currently + * streaming in to the loader. So if you're on the currently loading frame, + * you will need to redraw the screen for the updated area. + * + * Return value: `TRUE` if the frame we're on is partially loaded, or the last frame */ gboolean gdk_pixbuf_animation_iter_on_currently_loading_frame (GdkPixbufAnimationIter *iter) @@ -804,8 +815,10 @@ gdk_pixbuf_animation_iter_on_currently_loading_frame (GdkPixbufAnimationIter *it * @iter: a #GdkPixbufAnimationIter * @current_time: (allow-none): current time * - * Possibly advances an animation to a new frame. Chooses the frame based - * on the start time passed to gdk_pixbuf_animation_get_iter(). + * Possibly advances an animation to a new frame. + * + * Chooses the frame based on the start time passed to + * gdk_pixbuf_animation_get_iter(). * * @current_time would normally come from g_get_current_time(), and * must be greater than or equal to the time passed to @@ -814,17 +827,17 @@ gdk_pixbuf_animation_iter_on_currently_loading_frame (GdkPixbufAnimationIter *it * called. That is, you can't go backward in time; animations only * play forward. * - * As a shortcut, pass %NULL for the current time and g_get_current_time() + * As a shortcut, pass `NULL` for the current time and g_get_current_time() * will be invoked on your behalf. So you only need to explicitly pass * @current_time if you're doing something odd like playing the animation * at double speed. * - * If this function returns %FALSE, there's no need to update the animation + * If this function returns `FALSE`, there's no need to update the animation * display, assuming the display had been rendered prior to advancing; - * if %TRUE, you need to call gdk_pixbuf_animation_iter_get_pixbuf() + * if `TRUE`, you need to call gdk_pixbuf_animation_iter_get_pixbuf() * and update the display with the new pixbuf. * - * Returns: %TRUE if the image may need updating + * Returns: `TRUE` if the image may need updating */ gboolean gdk_pixbuf_animation_iter_advance (GdkPixbufAnimationIter *iter, -- cgit v1.2.1 From f75f9bfbbf57bde6eb32b304616349c9a50ccc2e Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sun, 21 Mar 2021 13:31:35 +0000 Subject: docs: Update pixbuf-loader style --- gdk-pixbuf/gdk-pixbuf-loader.c | 168 ++++++++++++++++++++++------------------- 1 file changed, 89 insertions(+), 79 deletions(-) diff --git a/gdk-pixbuf/gdk-pixbuf-loader.c b/gdk-pixbuf/gdk-pixbuf-loader.c index 5ef462d0d..51202b6f1 100644 --- a/gdk-pixbuf/gdk-pixbuf-loader.c +++ b/gdk-pixbuf/gdk-pixbuf-loader.c @@ -134,9 +134,11 @@ gdk_pixbuf_loader_class_init (GdkPixbufLoaderClass *class) * * This signal is emitted when the pixbuf loader has been fed the * initial amount of data that is required to figure out the size - * of the image that it will create. Applications can call - * gdk_pixbuf_loader_set_size() in response to this signal to set - * the desired size to which the image should be scaled. + * of the image that it will create. + * + * Applications can call gdk_pixbuf_loader_set_size() in response + * to this signal to set the desired size to which the image + * should be scaled. */ pixbuf_loader_signals[SIZE_PREPARED] = g_signal_new ("size-prepared", @@ -154,9 +156,11 @@ gdk_pixbuf_loader_class_init (GdkPixbufLoaderClass *class) * @loader: the object which received the signal. * * This signal is emitted when the pixbuf loader has allocated the - * pixbuf in the desired size. After this signal is emitted, - * applications can call gdk_pixbuf_loader_get_pixbuf() to fetch - * the partially-loaded pixbuf. + * pixbuf in the desired size. + * + * After this signal is emitted, applications can call + * gdk_pixbuf_loader_get_pixbuf() to fetch the partially-loaded + * pixbuf. */ pixbuf_loader_signals[AREA_PREPARED] = g_signal_new ("area-prepared", @@ -176,9 +180,12 @@ gdk_pixbuf_loader_class_init (GdkPixbufLoaderClass *class) * @height: Height of updated area. * * This signal is emitted when a significant area of the image being - * loaded has been updated. Normally it means that a complete - * scanline has been read in, but it could be a different area as - * well. Applications can use this signal to know when to repaint + * loaded has been updated. + * + * Normally it means that a complete scanline has been read in, but + * it could be a different area as well. + * + * Applications can use this signal to know when to repaint * areas of an image that is being loaded. */ pixbuf_loader_signals[AREA_UPDATED] = @@ -199,6 +206,7 @@ gdk_pixbuf_loader_class_init (GdkPixbufLoaderClass *class) * @loader: the object which received the signal. * * This signal is emitted when gdk_pixbuf_loader_close() is called. + * * It can be used by different parts of an application to receive * notification when an image loader is closed by the code that * drives it. @@ -255,9 +263,10 @@ gdk_pixbuf_loader_finalize (GObject *object) * @width: The desired width of the image being loaded. * @height: The desired height of the image being loaded. * - * Causes the image to be scaled while it is loaded. The desired - * image size can be determined relative to the original size of - * the image by calling gdk_pixbuf_loader_set_size() from a + * Causes the image to be scaled while it is loaded. + * + * The desired image size can be determined relative to the original + * size of the image by calling gdk_pixbuf_loader_set_size() from a * signal handler for the ::size-prepared signal. * * Attempts to set the desired image size are ignored after the @@ -501,15 +510,10 @@ gdk_pixbuf_loader_eat_header_write (GdkPixbufLoader *loader, * @count: Length of the @buf buffer in bytes. * @error: return location for errors * - * This will cause a pixbuf loader to parse the next @count bytes of - * an image. It will return %TRUE if the data was loaded successfully, - * and %FALSE if an error occurred. In the latter case, the loader - * will be closed, and will not accept further writes. If %FALSE is - * returned, @error will be set to an error from the #GDK_PIXBUF_ERROR - * or #G_FILE_ERROR domains. + * Parses the next `count` bytes in the given image buffer. * - * Return value: %TRUE if the write was successful, or %FALSE if the loader - * cannot parse the buffer. + * Return value: `TRUE` if the write was successful, or + * `FALSE` if the loader cannot parse the buffer **/ gboolean gdk_pixbuf_loader_write (GdkPixbufLoader *loader, @@ -563,20 +567,13 @@ gdk_pixbuf_loader_write (GdkPixbufLoader *loader, /** * gdk_pixbuf_loader_write_bytes: * @loader: A pixbuf loader. - * @buffer: The image data as a #GBytes + * @buffer: The image data as a `GBytes` buffer. * @error: return location for errors * - * This will cause a pixbuf loader to parse a buffer inside a #GBytes - * for an image. It will return %TRUE if the data was loaded successfully, - * and %FALSE if an error occurred. In the latter case, the loader - * will be closed, and will not accept further writes. If %FALSE is - * returned, @error will be set to an error from the #GDK_PIXBUF_ERROR - * or #G_FILE_ERROR domains. - * - * See also: gdk_pixbuf_loader_write() + * Parses the next contents of the given image buffer. * - * Return value: %TRUE if the write was successful, or %FALSE if the loader - * cannot parse the buffer. + * Return value: `TRUE` if the write was successful, or `FALSE` if + * the loader cannot parse the buffer * * Since: 2.30 */ @@ -612,14 +609,16 @@ gdk_pixbuf_loader_new (void) /** * gdk_pixbuf_loader_new_with_type: * @image_type: name of the image format to be loaded with the image - * @error: (allow-none): return location for an allocated #GError, or %NULL to ignore errors + * @error: (allow-none): return location for an allocated #GError, or `NULL` to ignore errors * * Creates a new pixbuf loader object that always attempts to parse * image data as if it were an image of type @image_type, instead of - * identifying the type automatically. Useful if you want an error if - * the image isn't the expected type, for loading image formats - * that can't be reliably identified by looking at the data, or if - * the user manually forces a specific type. + * identifying the type automatically. + * + * This function is useful if you want an error if the image isn't the + * expected type; for loading image formats that can't be reliably + * identified by looking at the data; or if the user manually forces + * a specific type. * * The list of supported image formats depends on what image loaders * are installed, but typically "png", "jpeg", "gif", "tiff" and @@ -655,14 +654,16 @@ gdk_pixbuf_loader_new_with_type (const char *image_type, /** * gdk_pixbuf_loader_new_with_mime_type: * @mime_type: the mime type to be loaded - * @error: (allow-none): return location for an allocated #GError, or %NULL to ignore errors + * @error: (allow-none): return location for an allocated #GError, or `NULL` to ignore errors * * Creates a new pixbuf loader object that always attempts to parse - * image data as if it were an image of mime type @mime_type, instead of - * identifying the type automatically. Useful if you want an error if - * the image isn't the expected mime type, for loading image formats - * that can't be reliably identified by looking at the data, or if - * the user manually forces a specific mime type. + * image data as if it were an image of MIME type @mime_type, instead of + * identifying the type automatically. + * + * This function is useful if you want an error if the image isn't the + * expected MIME type; for loading image formats that can't be reliably + * identified by looking at the data; or if the user manually forces a + * specific MIME type. * * The list of supported mime types depends on what image loaders * are installed, but typically "image/png", "image/jpeg", "image/gif", @@ -672,6 +673,7 @@ gdk_pixbuf_loader_new_with_type (const char *image_type, * structs returned by gdk_pixbuf_get_formats(). * * Return value: A newly-created pixbuf loader. + * * Since: 2.4 **/ GdkPixbufLoader * @@ -737,19 +739,23 @@ _gdk_pixbuf_loader_new_with_filename (const char *filename) * @loader: A pixbuf loader. * * Queries the #GdkPixbuf that a pixbuf loader is currently creating. + * * In general it only makes sense to call this function after the - * "area-prepared" signal has been emitted by the loader; this means - * that enough data has been read to know the size of the image that - * will be allocated. If the loader has not received enough data via - * gdk_pixbuf_loader_write(), then this function returns %NULL. The - * returned pixbuf will be the same in all future calls to the loader, - * so simply calling g_object_ref() should be sufficient to continue - * using it. Additionally, if the loader is an animation, it will - * return the "static image" of the animation - * (see gdk_pixbuf_animation_get_static_image()). + * [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been + * emitted by the loader; this means that enough data has been read + * to know the size of the image that will be allocated. + * + * If the loader has not received enough data via gdk_pixbuf_loader_write(), + * then this function returns `NULL`. + * + * The returned pixbuf will be the same in all future calls to the loader, + * so if you want to keep using it, you should acquire a reference to it. + * + * Additionally, if the loader is an animation, it will return the "static + * image" of the animation (see gdk_pixbuf_animation_get_static_image()). * - * Return value: (transfer none): The #GdkPixbuf that the loader is creating, or %NULL if not - * enough data has been read to determine how to create the image buffer. + * Return value: (transfer none) (nullable): The pixbuf that the loader is + * creating **/ GdkPixbuf * gdk_pixbuf_loader_get_pixbuf (GdkPixbufLoader *loader) @@ -771,14 +777,17 @@ gdk_pixbuf_loader_get_pixbuf (GdkPixbufLoader *loader) * @loader: A pixbuf loader * * Queries the #GdkPixbufAnimation that a pixbuf loader is currently creating. - * In general it only makes sense to call this function after the "area-prepared" - * signal has been emitted by the loader. If the loader doesn't have enough - * bytes yet (hasn't emitted the "area-prepared" signal) this function will - * return %NULL. - * - * Return value: (transfer none): The #GdkPixbufAnimation that the loader is loading, or %NULL if - * not enough data has been read to determine the information. -**/ + * + * In general it only makes sense to call this function after the + * [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been emitted by + * the loader. + * + * If the loader doesn't have enough bytes yet, and hasn't emitted the `area-prepared` + * signal, this function will return `NULL`. + * + * Return value: (transfer none) (nullable): The animation that the loader is + * currently loading + */ GdkPixbufAnimation * gdk_pixbuf_loader_get_animation (GdkPixbufLoader *loader) { @@ -794,24 +803,27 @@ gdk_pixbuf_loader_get_animation (GdkPixbufLoader *loader) /** * gdk_pixbuf_loader_close: * @loader: A pixbuf loader. - * @error: (allow-none): return location for a #GError, or %NULL to ignore errors + * @error: (allow-none): return location for a #GError, or `NULL` to ignore errors * * Informs a pixbuf loader that no further writes with * gdk_pixbuf_loader_write() will occur, so that it can free its - * internal loading structures. Also, tries to parse any data that - * hasn't yet been parsed; if the remaining data is partial or - * corrupt, an error will be returned. If %FALSE is returned, @error - * will be set to an error from the #GDK_PIXBUF_ERROR or #G_FILE_ERROR - * domains. If you're just cancelling a load rather than expecting it - * to be finished, passing %NULL for @error to ignore it is - * reasonable. - * - * Remember that this does not unref the loader, so if you plan not to - * use it anymore, please g_object_unref() it. - * - * Returns: %TRUE if all image data written so far was successfully - passed out via the update_area signal - **/ + * internal loading structures. + * + * This function also tries to parse any data that hasn't yet been parsed; + * if the remaining data is partial or corrupt, an error will be returned. + * + * If `FALSE` is returned, `error` will be set to an error from the + * `GDK_PIXBUF_ERROR` or `G_FILE_ERROR` domains. + * + * If you're just cancelling a load rather than expecting it to be finished, + * passing `NULL` for `error` to ignore it is reasonable. + * + * Remember that this function does not release a reference on the loader, so + * you will need to explicitly release any reference you hold. + * + * Returns: `TRUE` if all image data written so far was successfully + * passed out via the update_area signal + */ gboolean gdk_pixbuf_loader_close (GdkPixbufLoader *loader, GError **error) @@ -883,9 +895,7 @@ gdk_pixbuf_loader_close (GdkPixbufLoader *loader, * Obtains the available information about the format of the * currently loading image file. * - * Returns: (nullable) (transfer none): A #GdkPixbufFormat or - * %NULL. The return value is owned by GdkPixbuf and should not be - * freed. + * Returns: (nullable) (transfer none): A #GdkPixbufFormat * * Since: 2.2 */ -- cgit v1.2.1