diff options
-rw-r--r-- | docs/reference/gdk-pixbuf/Makefile.am | 1 | ||||
-rw-r--r-- | gdk-pixbuf/gdk-pixbuf-io.c | 71 | ||||
-rw-r--r-- | gdk-pixbuf/gdk-pixbuf-loader.c | 61 | ||||
-rw-r--r-- | gdk-pixbuf/gdk-pixbuf-scale.c | 21 | ||||
-rw-r--r-- | gdk-pixbuf/gdk-pixbuf.c | 35 | ||||
-rw-r--r-- | gdk-pixbuf/gdk-pixdata.c | 26 |
6 files changed, 86 insertions, 129 deletions
diff --git a/docs/reference/gdk-pixbuf/Makefile.am b/docs/reference/gdk-pixbuf/Makefile.am index 61cfe49f4..71ac69b92 100644 --- a/docs/reference/gdk-pixbuf/Makefile.am +++ b/docs/reference/gdk-pixbuf/Makefile.am @@ -45,7 +45,6 @@ GTKDOC_LIBS = \ # Extra options to supply to gtkdoc-mkdb MKDB_OPTIONS= \ --main-sgml-file=$(DOC_MAIN_SGML_FILE) \ - --sgml-mode \ --source-dir=../../../contrib/gdk-pixbuf-xlib \ --output-format=xml \ --name-space=gdk_pixbuf diff --git a/gdk-pixbuf/gdk-pixbuf-io.c b/gdk-pixbuf/gdk-pixbuf-io.c index 426c0fdbc..bd17000fe 100644 --- a/gdk-pixbuf/gdk-pixbuf-io.c +++ b/gdk-pixbuf/gdk-pixbuf-io.c @@ -84,51 +84,39 @@ * 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 <function>fill_info</function> and + * #GdkPixbufModuleFillInfoFunc function named `fill_info` and * a #GdkPixbufModuleFillVtableFunc function named - * <function>fill_vtable</function>. - * + * `fill_vtable`. * * 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 <function>fill_info</function> - * function. An external utility, <command>gdk-pixbuf-query-loaders</command>, - * 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 available loaders and their signatures. - * + * 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 + * 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 - * <function>fill_vtable</function> function will simply not set the corresponding + * `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. * - * * Installing a module is a two-step process: - * <itemizedlist> - * <listitem><para>copy the module file(s) to the loader directory (normally - * <filename><replaceable>libdir</replaceable>/gtk-2.0/<replaceable>version</replaceable>/loaders</filename>, - * unless overridden by the environment variable - * <envar>GDK_PIXBUF_MODULEDIR</envar>) - * </para></listitem> - * <listitem><para>call <command>gdk-pixbuf-query-loaders</command> to update the - * module file (normally - * <filename><replaceable>sysconfdir</replaceable>/gtk-2.0/gdk-pixbuf.loaders</filename>, - * unless overridden by the environment variable - * <envar>GDK_PIXBUF_MODULE_FILE</envar>) - * </para></listitem> - * </itemizedlist> - * + * - copy the module file(s) to the loader directory (normally + * `$libdir/gtk-2.0/$version/loaders`, unless overridden by the + * environment variable `GDK_PIXBUF_MODULEDIR`) + * - call gdk-pixbuf-query-loaders to update the module file (normally + * `$sysconfdir/gtk-2.0/gdk-pixbuf.loaders`, unless overridden by the + * environment variable `GDK_PIXBUF_MODULE_FILE`) * * The GdkPixBuf interfaces needed for implementing modules are contained in - * <filename>gdk-pixbuf-io.h</filename> (and - * <filename>gdk-pixbuf-animation.h</filename> 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 - * <literal>#ifdef GDK_PIXBUF_ENABLE_BACKEND</literal>. + * `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`. */ @@ -2235,10 +2223,9 @@ gdk_pixbuf_real_save_to_callback (GdkPixbuf *pixbuf, * The variable argument list should be %NULL-terminated; if not empty, * it should contain pairs of strings that modify the save * parameters. For example: - * <informalexample><programlisting> - * gdk_pixbuf_save (pixbuf, handle, "jpeg", &error, - * "quality", "100", NULL); - * </programlisting></informalexample> + * |[ + * 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]. @@ -2253,16 +2240,14 @@ gdk_pixbuf_real_save_to_callback (GdkPixbuf *pixbuf, * The "icc-profile" value should be the complete ICC profile encoded * into base64. * - * <informalexample><programlisting> + * |[ * gchar *contents; * gchar *contents_encode; * gsize length; * g_file_get_contents ("/home/hughsie/.color/icc/L225W.icm", &contents, &length, NULL); * contents_encode = g_base64_encode ((const guchar *) contents, length); - * gdk_pixbuf_save (pixbuf, handle, "png", &error, - * "icc-profile", contents_encode, - * NULL); - * </programlisting></informalexample> + * gdk_pixbuf_save (pixbuf, handle, "png", &error, "icc-profile", contents_encode, NULL); + * ]| * * TIFF images recognize a "compression" option which acceps an integer value. * Among the codecs are 1 None, 2 Huffman, 5 LZW, 7 JPEG and 8 Deflate, see @@ -2274,7 +2259,6 @@ gdk_pixbuf_real_save_to_callback (GdkPixbuf *pixbuf, * * Return value: whether an error was set **/ - gboolean gdk_pixbuf_save (GdkPixbuf *pixbuf, const char *filename, @@ -3133,10 +3117,9 @@ _gdk_pixbuf_get_format (GdkPixbufModule *module) * by GdkPixbuf. * * Returns: (transfer container) (element-type GdkPixbufFormat): A list of - * #GdkPixbufFormat<!-- -->s 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. + * #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. * * Since: 2.2 */ diff --git a/gdk-pixbuf/gdk-pixbuf-loader.c b/gdk-pixbuf/gdk-pixbuf-loader.c index 3518a01e7..edcc9055e 100644 --- a/gdk-pixbuf/gdk-pixbuf-loader.c +++ b/gdk-pixbuf/gdk-pixbuf-loader.c @@ -48,49 +48,38 @@ * 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, "<link - * linkend="GdkPixbufLoader-size-prepared">size_prepared</link>", - * will be called as soon as the image has enough information to + * 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, "<link - * linkend="GdkPixbufLoader-area-prepared">area_prepared</link>", - * will be called 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. - * In addition, no actual information will be passed in yet, so the - * pixbuf can be safely filled with any temporary graphics (or an - * initial color) as needed. You can also call - * gdk_pixbuf_loader_get_pixbuf() later and get the same pixbuf. + * 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. In addition, no actual information will be passed in yet, so the + * pixbuf can be safely filled with any temporary graphics (or an initial + * color) as needed. 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. * - * The last signal, "<link - * linkend="GdkPixbufLoader-area-updated">area_updated</link>" gets - * called 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 area updated. For - * example, in an interlaced image, you need to make several passes - * before the image is done loading. - * - * - * <refsect2> - * <title>Loading an animation</title> - * <para> - * Loading an animation is almost as easy as loading an - * image. Once the first "<link - * linkend="GdkPixbufLoader-area-prepared">area_prepared</link>" 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 an #GdkPixbufAnimationIter for displaying it. - * </para> - * </refsect2> + * # 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. */ diff --git a/gdk-pixbuf/gdk-pixbuf-scale.c b/gdk-pixbuf/gdk-pixbuf-scale.c index 89e2f6607..acae7cd66 100644 --- a/gdk-pixbuf/gdk-pixbuf-scale.c +++ b/gdk-pixbuf/gdk-pixbuf-scale.c @@ -52,7 +52,7 @@ * 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. + * setting the `GDK_DISABLE_MEDIALIB` environment variable. * * * The following example demonstrates handling an expose event by @@ -64,11 +64,9 @@ * gdk_pixbuf_composite_color() function has exactly the same effect * as calling gdk_pixbuf_scale(). * - * - * <example> - * <title>Handling an expose event.</title> - * <para> - * <programlisting> + * ## Handling an expose event + * + * |[ * gboolean * expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data) * { @@ -93,9 +91,7 @@ * * return TRUE; * } - * </programlisting> - * </para> - * </example> + * ]| */ @@ -181,11 +177,8 @@ gdk_pixbuf_scale (const GdkPixbuf *src, * image, the data at the edges of the source image is replicated * to infinity. * - * <figure id="pixbuf-composite-diagram"> - * <title>Compositing of pixbufs</title> - * <graphic fileref="composite.png" format="PNG"/> - * </figure> - **/ + * ![](composite.png) + */ void gdk_pixbuf_composite (const GdkPixbuf *src, GdkPixbuf *dest, diff --git a/gdk-pixbuf/gdk-pixbuf.c b/gdk-pixbuf/gdk-pixbuf.c index c2c021994..6a907cc6e 100644 --- a/gdk-pixbuf/gdk-pixbuf.c +++ b/gdk-pixbuf/gdk-pixbuf.c @@ -53,19 +53,16 @@ * in %NULL as the destroy notification function so that the data * will not be freed. * - * * 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 <function>malloc()</function> 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. - * + * 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 gdk_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 @@ -87,14 +84,11 @@ * 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. * - * <note> - * 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. - * </note> - * - * <emphasis>Finalizing</emphasis> a pixbuf means to free its pixel + * 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; @@ -621,8 +615,8 @@ 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 <xref linkend="image-data"/> for information about how - * the pixel data is stored in memory. + * Please see the section on [image data](image-data) for information + * about how the pixel data is stored in memory. **/ guchar * gdk_pixbuf_get_pixels (const GdkPixbuf *pixbuf) @@ -640,9 +634,8 @@ gdk_pixbuf_get_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 <xref linkend="image-data"/> - * for information about how the pixel data is stored in - * memory. + * pixel data. Please see the section on [image data](image-data) + * for information about how the pixel data is stored in memory. * * Rename to: gdk_pixbuf_get_pixels * @@ -696,8 +689,8 @@ gdk_pixbuf_get_height (const GdkPixbuf *pixbuf) * gdk_pixbuf_get_rowstride: * @pixbuf: A pixbuf. * - * Queries the rowstride of a pixbuf, which is the number of bytes between the start of a row - * and the start of the next row. + * Queries the rowstride of a pixbuf, which is the number of bytes between + * the start of a row and the start of the next row. * * Return value: Distance between row starts. **/ diff --git a/gdk-pixbuf/gdk-pixdata.c b/gdk-pixbuf/gdk-pixdata.c index 47a50f5dd..9c992b6ac 100644 --- a/gdk-pixbuf/gdk-pixdata.c +++ b/gdk-pixbuf/gdk-pixdata.c @@ -621,8 +621,9 @@ save_rle_decoder (GString *gstring, * Generates C source code suitable for compiling images directly * into programs. * - * gdk-pixbuf ships with a program called <command>gdk-pixbuf-csource</command> - * which offers a command line interface to this function. + * gdk-pixbuf ships with a program called + * [gdk-pixbuf-csource][gdk-pixbuf-csource], which offers a command + * line interface to this function. * * Returns: a newly-allocated string containing the C source form * of @pixdata. @@ -864,28 +865,27 @@ gdk_pixdata_to_csource (GdkPixdata *pixdata, * ship a program with images, but don't want to depend on any * external files. * - * gdk-pixbuf ships with a program called <command>gdk-pixbuf-csource</command> + * 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 <option>--raw</option> flag to - * <command>gdk-pixbuf-csource</command>. A sample invocation would be: + * In almost all cases, you should pass the `--raw` option to + * `gdk-pixbuf-csource`. A sample invocation would be: * - * <informalexample><programlisting> + * |[ * gdk-pixbuf-csource --raw --name=myimage_inline myimage.png - * </programlisting></informalexample> + * ]| * * 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 - * <option>--rle</option> to <command>gdk-pixbuf-csource</command>, 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: - * <informalexample><programlisting> + * |[ * pixbuf = gdk_pixbuf_new_from_inline (-1, myimage_inline, FALSE, NULL); - * </programlisting></informalexample> + * ]| * * 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 |