From a9f8f347f5e1142bab4eaa37687af23aaf310ebb Mon Sep 17 00:00:00 2001 From: Paolo Borelli Date: Sat, 2 Jan 2021 19:53:12 +0100 Subject: [PATCH 1/2] gdk-pixbuf: update from git to include pixbuf loader API --- GdkPixbuf-2.0.gir | 826 +++++++- GdkPixdata-2.0.gir | 4725 ++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 5331 insertions(+), 220 deletions(-) diff --git a/GdkPixbuf-2.0.gir b/GdkPixbuf-2.0.gir index 2ee8ee06..a883bccb 100644 --- a/GdkPixbuf-2.0.gir +++ b/GdkPixbuf-2.0.gir @@ -359,13 +359,13 @@ interpolation is just as fast and results in higher quality. - + Micro version of gdk-pixbuf library, that is the "2" in "0.8.2" for example. - + Minor version of gdk-pixbuf library, that is the "8" in "0.8.2" for example. @@ -392,7 +392,7 @@ interpolation is just as fast and results in higher quality. - + Contains the full version of the gdk-pixbuf header as a string. This is the version being compiled against; contrast with #gdk_pixbuf_version. @@ -2534,7 +2534,7 @@ be at least as large as the width of the pixbuf. - + 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 @@ -2543,6 +2543,7 @@ 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. + it is unused since 2.42. A bilevel clipping mask (black and white) will be created and used to draw the image. Pixels below 0.5 opacity @@ -2554,8 +2555,9 @@ back to a bilevel clipping mask. In the future it will do full alpha compositing. - + An opaque struct representing an animation. + 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 @@ -2674,6 +2676,109 @@ result of the operation. + + 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(). + +@start_time would normally come from g_get_current_time(), and marks +the beginning of animation playback. After creating an iterator, you +should immediately display the pixbuf returned by +gdk_pixbuf_animation_iter_get_pixbuf(). Then, you should install +a timeout (with g_timeout_add()) or by some other mechanism ensure +that you'll update the image after +gdk_pixbuf_animation_iter_get_delay_time() milliseconds. Each time +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 +g_get_current_time() will be used automatically. + +To update the image (i.e. possibly change the result of +gdk_pixbuf_animation_iter_get_pixbuf() to a new frame of the animation), +call gdk_pixbuf_animation_iter_advance(). + +If you're using #GdkPixbufLoader, in addition to updating the image +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 +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." + + + an iterator to move over the animation + + + + + a #GdkPixbufAnimation + + + + time when the animation starts playing + + + + + + + + + + + + + + + + + + + + + + + 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. + + + unanimated image representing the animation + + + + + a #GdkPixbufAnimation + + + + + + 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 +the image. + + + %TRUE if the "animation" was really just an image + + + + + a #GdkPixbufAnimation + + + + Queries the height of the bounding box of a pixbuf animation. @@ -2817,10 +2922,191 @@ the image. + + + - + + Modules supporting animations must derive a type from +#GdkPixbufAnimation, providing suitable implementations of the +virtual functions. + + + the parent class + + + + + + + %TRUE if the "animation" was really just an image + + + + + a #GdkPixbufAnimation + + + + + + + + + + unanimated image representing the animation + + + + + a #GdkPixbufAnimation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + an iterator to move over the animation + + + + + a #GdkPixbufAnimation + + + + time when the animation starts playing + + + + + + + An opaque struct representing an iterator which points to a certain position in an animation. + + + 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 +gdk_pixbuf_animation_get_iter(), and must increase or remain +unchanged each time gdk_pixbuf_animation_iter_get_pixbuf() is +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() +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 +display, assuming the display had been rendered prior to advancing; +if %TRUE, you need to call gdk_pixbuf_animation_iter_get_pixbuf() +and update the display with the new pixbuf. + + + %TRUE if the image may need updating + + + + + a #GdkPixbufAnimationIter + + + + current time + + + + + + 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. + +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 +for GIF images is currently 20 milliseconds. + + + delay time in milliseconds (thousandths of a second) + + + + + an animation iterator + + + + + + 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. + + + the pixbuf to be displayed + + + + + an animation iterator + + + + + + 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. + + + %TRUE if the frame we're on is partially loaded, or the last frame + + + + + a #GdkPixbufAnimationIter + + + + Possibly advances an animation to a new frame. Chooses the frame based on the start time passed to gdk_pixbuf_animation_get_iter(). @@ -2920,7 +3206,84 @@ the updated area. + + + + + Modules supporting animations must derive a type from +#GdkPixbufAnimationIter, providing suitable implementations of the +virtual functions. + + + the parent class + + + + + + + delay time in milliseconds (thousandths of a second) + + + + + an animation iterator + + + + + + + + + + the pixbuf to be displayed + + + + + an animation iterator + + + + + + + + + + %TRUE if the frame we're on is partially loaded, or the last frame + + + + + a #GdkPixbufAnimationIter + + + + + + + + + + %TRUE if the image may need updating + + + + + a #GdkPixbufAnimationIter + + + + current time + + + + + + A function of this type is responsible for freeing the pixel array of a pixbuf. The gdk_pixbuf_new_from_data() function lets you @@ -2978,8 +3341,49 @@ domain. - + + A #GdkPixbufFormat contains information about the image format accepted by a +module. Only modules should access the fields directly, applications should +use the <function>gdk_pixbuf_format_*</function> functions. + + the name of the image format. + + + + the signature of the module. + + + + the message domain for the @description. + + + + a description of the image format. + + + + a %NULL-terminated array of MIME types for the image format. + + + + a %NULL-terminated array of typical filename extensions for the + image format. + + + + a combination of #GdkPixbufFormatFlags. + + + + a boolean determining whether the loader is disabled. + + + + a string containing license information, typically set to + shorthands like "GPL", "LGPL", etc. + + Creates a copy of @format @@ -3176,6 +3580,21 @@ with an inappropriate license, see gdk_pixbuf_format_get_license(). + + Flags which allow a module to specify further details about the supported +operations. + + + the module can write out images in the format. + + + the image format is scalable + + + the module is threadsafe. gdk-pixbuf + ignores modules that are not marked as threadsafe. (Since 2.28). + + The GdkPixbufLoader struct contains only private fields. @@ -3620,6 +4039,399 @@ the desired size to which the image should be scaled. + + 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 <function>fill_vtable</function>, which will get called when the module +is loaded and must set the function pointers of the #GdkPixbufModule. + + + the name of the module, usually the same as the + usual file extension for images of this type, eg. "xpm", "jpeg" or "png". + + + + the path from which the module is loaded. + + + + the loaded #GModule. + + + + a #GdkPixbufFormat holding information about the module. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Defines the type of the function used to fill a +#GdkPixbufFormat structure with information about a module. + + + + + + + a #GdkPixbufFormat. + + + + + + Defines the type of the function used to set the vtable of a +#GdkPixbufModule when it is loaded. + + + + + + + a #GdkPixbufModule. + + + + + + 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 +' ', '!', 'x', 'z', and 'n' to indicate bytes that must be matched, +not matched, "don't-care"-bytes, zeros and non-zeros. +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'. + +The signature of a module is stored as an array of +#GdkPixbufModulePatterns. The array is terminated by a pattern +where the @prefix is %NULL. + + +<informalexample><programlisting> +GdkPixbufModulePattern *signature[] = { + { "abcdx", " !x z", 100 }, + { "bla", NULL, 90 }, + { NULL, NULL, 0 } +}; +</programlisting> +The example matches e.g. "auud\0" with relevance 100, and "blau" with +relevance 90.</informalexample> + + + the prefix for this pattern + + + + mask containing bytes which modify how the prefix is matched against + test data + + + + relevance of this pattern + + + + + Defines the type of the function that gets called once the initial +setup of @pixbuf is done. + +#GdkPixbufLoader uses a function of this type to emit the +"<link linkend="GdkPixbufLoader-area-prepared">area_prepared</link>" +signal. + + + + + + + the #GdkPixbuf that is currently being loaded. + + + + if an animation is being loaded, the #GdkPixbufAnimation, else %NULL. + + + + the loader. + + + + + + Defines the type of the function that gets called once the size +of the loaded image is known. + +The function is expected to set @width and @height to the desired +size to which the image should be scaled. If a module has no efficient +way to achieve the desired scaling during the loading of the image, it may +either ignore the size request, or only approximate it - gdk-pixbuf will +then perform the required scaling on the completely loaded image. + +If the function sets @width or @height to zero, the module should interpret +this as a hint that it will be closed soon and shouldn't allocate further +resources. This convention is used to implement gdk_pixbuf_get_file_info() +efficiently. + + + + + + + pointer to a location containing the current image width + + + + pointer to a location containing the current image height + + + + the loader. + + + + + + Defines the type of the function that gets called every time a region +of @pixbuf is updated. + +#GdkPixbufLoader uses a function of this type to emit the +"<link linkend="GdkPixbufLoader-area-updated">area_updated</link>" +signal. + + + + + + + the #GdkPixbuf that is currently being loaded. + + + + the X origin of the updated area. + + + + the Y origin of the updated area. + + + + the width of the updated area. + + + + the height of the updated area. + + + + the loader. + + + + + + + + + + + + + + + + + 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. diff --git a/GdkPixdata-2.0.gir b/GdkPixdata-2.0.gir index ca310f01..a883bccb 100644 --- a/GdkPixdata-2.0.gir +++ b/GdkPixdata-2.0.gir @@ -3,274 +3,4573 @@ To affect the contents of this file, edit the original C definitions, and/or use gtk-doc annotations. --> - + + - - - - Magic number for #GdkPixdata structures. + + + + This enumeration defines the color spaces that are supported by +the gdk-pixbuf library. Currently only RGB is supported. + + Indicates a red/green/blue additive color space. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + +**Note**: Cubic filtering is missing from the list; hyperbolic +interpolation is just as fast and results in higher quality. + + Nearest neighbor sampling; this is the fastest + and lowest quality mode. Quality is normally unacceptable when scaling + down, but may be OK when scaling up. + + + This is an accurate simulation of the PostScript + image operator without any interpolation enabled. Each pixel is + rendered as a tiny parallelogram of solid color, the edges of which + are implemented with antialiasing. It resembles nearest neighbor for + enlargement, and bilinear for reduction. + + + Best quality/speed balance; use this mode by + default. Bilinear interpolation. For enlargement, it is + equivalent to point-sampling the ideal bilinear-interpolated image. + For reduction, it is equivalent to laying down small tiles and + integrating over the coverage area. + + + This is the slowest and highest quality + reconstruction function. It is derived from the hyperbolic filters in + Wolberg's "Digital Image Warping", and is formally defined as the + hyperbolic-filter sampling the ideal hyperbolic-filter interpolated + image (the filter is designed to be idempotent for 1:1 pixel mapping). + **Deprecated**: this interpolation filter is deprecated, as in reality + it has a lower quality than the @GDK_INTERP_BILINEAR filter + (Since: 2.38) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Macro to test the version of GdkPixbuf being compiled against. + + + + major version (e.g. 2 for version 2.34.0) + + + minor version (e.g. 34 for version 2.34.0) + + + micro version (e.g. 0 for version 2.34.0) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Major version of gdk-pixbuf library, that is the "0" in +"0.8.2" for example. + + + + + Micro version of gdk-pixbuf library, that is the "2" in +"0.8.2" for example. + + + + + Minor version of gdk-pixbuf library, that is the "8" in +"0.8.2" for example. + + + + + + + + + + + + + + + + + + + + + + + + + + Contains the full version of the gdk-pixbuf header as a string. +This is the version being compiled against; contrast with +#gdk_pixbuf_version. + + + + + 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). + + + + Creates a new #GdkPixbuf structure and allocates a buffer for it. The +buffer has an optimal rowstride. Note that the buffer is not cleared; +you will have to fill it completely yourself. + + + A newly-created #GdkPixbuf with a reference count of 1, or +%NULL if not enough memory could be allocated for the image buffer. + + + + + Color space for image + + + + Whether the image should have transparency information + + + + Number of bits per color sample + + + + Width of image in pixels, must be > 0 + + + + Height of image in pixels, must be > 0 + + + + + + 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(). + + + A newly-created #GdkPixbuf structure with a reference count of 1. + + + + + Image data in 8-bit/sample packed format inside a #GBytes + + + + Colorspace for the image data + + + + Whether the data has an opacity channel + + + + Number of bits per sample + + + + Width of the image in pixels, must be > 0 + + + + Height of the image in pixels, must be > 0 + + + + Distance in bytes between row starts + + + + + + 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 +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(). + + + A newly-created #GdkPixbuf structure with a reference count of 1. + + + + + Image data in 8-bit/sample packed format + + + + + + Colorspace for the image data + + + + Whether the data has an opacity channel + + + + Number of bits per sample + + + + Width of the image in pixels, must be > 0 + + + + Height of the image in pixels, must be > 0 + + + + Distance in bytes between row starts + + + + Function used to free the data when the pixbuf's reference count +drops to zero, or %NULL if the data should not be freed + + + + Closure data to pass to the destroy notification function + + + + + + 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. + + + 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. + + + + + Name of file to load, in the GLib file + name encoding + + + + + + 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 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. 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 +allowed since 2.8. + + + 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. + + + + + Name of file to load, in the GLib file + name encoding + + + + The width the image should have or -1 to not constrain the width + + + + The height the image should have or -1 to not constrain the height + + + + %TRUE to preserve the image's aspect ratio + + + + + + 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 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 +and image at the requested size, regardless of aspect ratio, use +gdk_pixbuf_new_from_file_at_scale(). + + + 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. + + + + + Name of file to load, in the GLib file + name encoding + + + + The width the image should have or -1 to not constrain the width + + + + The height the image should have or -1 to not constrain the height + + + + + + 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. + +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 +]| + +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.) + +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: +|[ +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. + Use #GResource instead. + + + A newly-created #GdkPixbuf structure with a reference, + count of 1, or %NULL if an error occurred. + + + + + Length in bytes of the @data argument or -1 to + disable length checks + + + + Byte data containing a + serialized #GdkPixdata structure + + + + + + Whether to copy the pixel data, or use direct pointers + @data for the resulting pixbuf + + + + + + Creates a new pixbuf by loading an image from an resource. + +The file format is detected automatically. If %NULL is returned, then +@error will be set. + + + 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. + + + + + the path of the resource file + + + + + + Creates a new pixbuf by loading an image from an resource. + +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 +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. 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. + + + 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. + + + + + the path of the resource file + + + + The width the image should have or -1 to not constrain the width + + + + The height the image should have or -1 to not constrain the height + + + + %TRUE to preserve the image's aspect ratio + + + + + + 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 stream is not closed. + + + 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. + + + + + a #GInputStream to load the pixbuf from + + + + optional #GCancellable object, %NULL to ignore + + + + + + 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 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 +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 +scale the image at all in that dimension. + +The stream is not closed. + + + 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. + + + + + a #GInputStream to load the pixbuf from + + + + The width the image should have or -1 to not constrain the width + + + + The height the image should have or -1 to not constrain the height + + + + %TRUE to preserve the image's aspect ratio + + + + optional #GCancellable object, %NULL to ignore + + + + + + Finishes an asynchronous pixbuf creation operation started with +gdk_pixbuf_new_from_stream_async(). + + + a #GdkPixbuf or %NULL on error. Free the returned +object with g_object_unref(). + + + + + a #GAsyncResult + + + + + + 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. + + + A newly-created pixbuf with a reference count of 1. + + + + + Pointer to inline XPM data. + + + + + + + + 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. + + + the rowstride for the given values, or -1 in case of error. + + + + + Color space for image + + + + Whether the image should have transparency information + + + + Number of bits per color sample + + + + Width of image in pixels, must be > 0 + + + + Height of image in pixels, must be > 0 + + + + + + Parses an image file far enough to determine its format and size. + + + 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. + + + + + The name of the file to identify. + + + + Return location for the width of the + image, or %NULL + + + + Return location for the height of the + image, or %NULL + + + + + + Asynchronously parses an image file far enough to determine its +format and size. + +For more details see gdk_pixbuf_get_file_info(), 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_get_file_info_finish() to +get the result of the operation. + + + + + + + The name of the file to identify + + + + optional #GCancellable object, %NULL to ignore + + + + a #GAsyncReadyCallback to call when the file info is available + + + + the data to pass to the callback function + + + + + + Finishes an asynchronous pixbuf parsing operation started with +gdk_pixbuf_get_file_info_async(). + + + 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. + + + + + a #GAsyncResult + + + + Return location for the width of the image, or %NULL + + + + Return location for the height of the image, or %NULL + + + + + + Obtains the available information about the image formats supported +by GdkPixbuf. + + + 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. + + + + + + + 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 +in a different location from the system ones. + +This is needed when the OS or runtime ships a minimal number of loaders +so as to reduce the potential attack surface of carefully crafted image +files, especially for uncommon file types. Applications that require +broader image file types coverage, such as image viewers, would be +expected to ship the gdk-pixbuf modules in a separate location, bundled +with the application in a separate directory from the OS or runtime- +provided modules. + + + + + + + Path to directory where the loaders.cache is installed + + + + + + Creates a new pixbuf by asynchronously loading an image from an input stream. + +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. +You can then call gdk_pixbuf_new_from_stream_finish() to get the result of the operation. + + + + + + + a #GInputStream from which to load the pixbuf + + + + optional #GCancellable object, %NULL to ignore + + + + a #GAsyncReadyCallback to call when the pixbuf is loaded + + + + the data to pass to the callback function + + + + + + Creates a new pixbuf by asynchronously loading an image from an input stream. + +For more details see gdk_pixbuf_new_from_stream_at_scale(), 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_new_from_stream_finish() to get the result of the operation. + + + + + + + a #GInputStream from which to load the pixbuf + + + + the width the image should have or -1 to not constrain the width + + + + the height the image should have or -1 to not constrain the height + + + + %TRUE to preserve the image's aspect ratio + + + + optional #GCancellable object, %NULL to ignore + + + + a #GAsyncReadyCallback to call when the pixbuf is loaded + + + + the data to pass to the callback function + + + + + + Finishes an asynchronous pixbuf save operation started with +gdk_pixbuf_save_to_stream_async(). + + + %TRUE if the pixbuf was saved successfully, %FALSE if an error was set. + + + + + a #GAsyncResult + + + + + + 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. + + + A newly-created pixbuf with a reference count of 1. + + + + + A #GdkPixbuf. + + + + Whether to set a color to zero opacity. If this +is %FALSE, then the (@r, @g, @b) arguments will be ignored. + + + + Red value to substitute. + + + + Green value to substitute. + + + + Blue value to substitute. + + + + + + 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. + + + 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). + + + + + A #GdkPixbuf. + + + + + + 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 +original destination image. + +When the destination rectangle contains parts not in the source +image, the data at the edges of the source image is replicated +to infinity. + +![](composite.png) + + + + + + + a #GdkPixbuf + + + + the #GdkPixbuf into which to render the results + + + + the left coordinate for region to render + + + + the top coordinate for region to render + + + + the width of the region to render + + + + the height of the region to render + + + + the offset in the X direction (currently rounded to an integer) + + + + the offset in the Y direction (currently rounded to an integer) + + + + the scale factor in the X direction + + + + the scale factor in the Y direction + + + + the interpolation type for the transformation. + + + + overall alpha for source image (0..255) + + + + + + Creates a transformation of the source image @src by scaling by +@scale_x and @scale_y then translating by @offset_x and @offset_y, +then alpha blends the rectangle (@dest_x ,@dest_y, @dest_width, +@dest_height) of the resulting image with a checkboard of the +colors @color1 and @color2 and renders it onto the destination +image. + +If the source image has no alpha channel, and @overall_alpha is 255, a fast +path is used which omits the alpha blending and just performs the scaling. + +See gdk_pixbuf_composite_color_simple() for a simpler variant of this +function suitable for many tasks. + + + + + + + a #GdkPixbuf + + + + the #GdkPixbuf into which to render the results + + + + the left coordinate for region to render + + + + the top coordinate for region to render + + + + the width of the region to render + + + + the height of the region to render + + + + the offset in the X direction (currently rounded to an integer) + + + + the offset in the Y direction (currently rounded to an integer) + + + + the scale factor in the X direction + + + + the scale factor in the Y direction + + + + the interpolation type for the transformation. + + + + overall alpha for source image (0..255) + + + + the X offset for the checkboard (origin of checkboard is at -@check_x, -@check_y) + + + + the Y offset for the checkboard + + + + the size of checks in the checkboard (must be a power of two) + + + + the color of check at upper left + + + + 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. + + + the new #GdkPixbuf, or %NULL if not enough memory could be +allocated for it. + + + + + a #GdkPixbuf + + + + the width of destination image + + + + the height of destination image + + + + the interpolation type for the transformation. + + + + overall alpha for source image (0..255) + + + + the size of checks in the checkboard (must be a power of two) + + + + the color of check at upper left + + + + the color of the other check + + + + + + 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. + + + A newly-created pixbuf with a reference count of 1, or %NULL if +not enough memory could be allocated. + + + + + A pixbuf. + + + + + + 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. +Therefore, you can not use this function to scroll a pixbuf. + + + + + + + Source pixbuf. + + + + Source X coordinate within @src_pixbuf. + + + + Source Y coordinate within @src_pixbuf. + + + + Width of the area to copy. + + + + Height of the area to copy. + + + + Destination pixbuf. + + + + X coordinate within @dest_pixbuf. + + + + Y coordinate within @dest_pixbuf. + + + + + + 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. + + + %TRUE on success. + + + + + a #GdkPixbuf to copy options from + + + + the #GdkPixbuf to copy options to + + + + + + 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. + + + + + + + a #GdkPixbuf + + + + RGBA pixel to clear to + (0xffffffff is opaque white, 0x00000000 transparent black) + + + + + + Flips a pixbuf horizontally or vertically and returns the +result in a new pixbuf. + + + the new #GdkPixbuf, or %NULL +if not enough memory could be allocated for it. + + + + + a #GdkPixbuf + + + + %TRUE to flip horizontally, %FALSE to flip vertically + + + + + + Queries the number of bits per color sample in a pixbuf. + + + Number of bits per color sample. + + + + + A pixbuf. + + + + + + Returns the length of the pixel data, in bytes. + + + The length of the pixel data. + + + + + A pixbuf + + + + + + Queries the color space of a pixbuf. + + + Color space. + + + + + A pixbuf. + + + + + + Queries whether a pixbuf has an alpha channel (opacity information). + + + %TRUE if it has an alpha channel, %FALSE otherwise. + + + + + A pixbuf. + + + + + + Queries the height of a pixbuf. + + + Height in pixels. + + + + + A pixbuf. + + + + + + Queries the number of channels of a pixbuf. + + + Number of channels. + + + + + A pixbuf. + + + + + + Looks up @key in the list of 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(). + +For instance, the ANI loader provides "Title" and "Artist" options. +The ICO, XBM, and XPM loaders provide "x_hot" and "y_hot" hot-spot +options for cursor definitions. The PNG loader provides the tEXt ancillary +chunk key/value pairs as options. Since 2.12, the TIFF and JPEG loaders +return an "orientation" option string that corresponds to the embedded +TIFF/Exif orientation tag (if present). Since 2.32, the TIFF loader sets +the "multipage" option string to "yes" when a multi-page TIFF is loaded. +Since 2.32 the JPEG and PNG loaders set "x-dpi" and "y-dpi" if the file +contains image density information in dots per inch. +Since 2.36.6, the JPEG loader sets the "comment" option with the comment +EXIF tag. + + + the value associated with @key. This is a nul-terminated +string that should not be freed or %NULL if @key was not found. + + + + + a #GdkPixbuf + + + + a nul-terminated string. + + + + + + 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(). + +See gdk_pixbuf_get_option() for more details. + + + a #GHashTable of key/values + + + + + + + + a #GdkPixbuf + + + + + + Queries a pointer to the pixel data of a pixbuf. + + + 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. + + + + + + + A pixbuf. + + + + + + Queries a pointer to the pixel data of a pixbuf. + + + 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. + + + + + + + A pixbuf. + + + + The length of the binary data. + + + + + + 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. + + + Distance between row starts. + + + + + A pixbuf. + + + + + + Queries the width of a pixbuf. + + + Width in pixels. + + + + + A 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 +pixbuf is finalized. + +Note that if @src_pixbuf is read-only, this function will force it +to be mutable. + + + a new pixbuf + + + + + a #GdkPixbuf + + + + X coord in @src_pixbuf + + + + Y coord in @src_pixbuf + + + + width of region in @src_pixbuf + + + + height of region in @src_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. + + + A new reference to a read-only copy of + the pixel data. Note that for mutable pixbufs, this function will + incur a one-time copy of the pixel data for conversion into the + returned #GBytes. + + + + + 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. + + + a read-only pointer to the raw pixel data + + + + + A pixbuf + + + + + + Adds a reference to a pixbuf. + Use g_object_ref(). + + + The same as the @pixbuf argument. + + + + + A pixbuf. + + + + + + Remove the key/value pair option attached to a #GdkPixbuf. + + + %TRUE if an option was removed, %FALSE if not. + + + + + a #GdkPixbuf + + + + a nul-terminated string representing the key to remove. + + + + + + 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. + + + the new #GdkPixbuf, or %NULL +if not enough memory could be allocated for it. + + + + + a #GdkPixbuf + + + + the angle to rotate by + + + + + + 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 +rowstride. + + + + + + + source image + + + + place to write modified version of @src + + + + saturation factor + + + + whether to pixelate + + + + + + 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: + +|[ +void add_if_writable (GdkPixbufFormat *data, GSList **list) +{ + if (gdk_pixbuf_format_is_writable (data)) + *list = g_slist_prepend (*list, data); +} + +GSList *formats = gdk_pixbuf_get_formats (); +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. + +The variable argument list should be %NULL-terminated; if not empty, +it should contain pairs of strings that modify the save +parameters. For example: +|[ +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. + +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]. + +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; +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); +]| + +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. + + + whether an error was set + + + + + a #GdkPixbuf. + + + + name of file to save. + + + + name of file format. + + + + return location for error, or %NULL + + + + list of key-value save options, followed by %NULL + + + + + + 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 +domain. + +See gdk_pixbuf_save() for more details. + + + whether an error was set + + + + + a #GdkPixbuf. + + + + location to receive a pointer + to the new buffer. + + + + + + location to receive the size of the new buffer. + + + + name of file format. + + + + 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", +"tiff", "png", "ico" or "bmp". See gdk_pixbuf_save_to_buffer() +for more details. + + + whether an error was set + + + + + a #GdkPixbuf. + + + + + location to receive a pointer to the new buffer. + + + + + + location to receive the size of the new buffer. + + + + name of file format. + + + + name of options to set, %NULL-terminated + + + + + + values for named 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 +function generates. + +See gdk_pixbuf_save() for more details. + + + whether an error was set + + + + + a #GdkPixbuf. + + + + a function that is called to save each block of data that + the save routine generates. + + + + user data to pass to the save function. + + + + name of file format. + + + + return location for error, or %NULL + + + + list of key-value save options + + + + + + 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. + + + whether an error was set + + + + + a #GdkPixbuf. + + + + a function that is called to save each block of data that + the save routine generates. + + + + user data to pass to the save function. + + + + name of file format. + + + + name of options to set, %NULL-terminated + + + + + + values for named options + + + + + + + + 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. + +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. + + + %TRUE if the pixbuf was saved successfully, %FALSE if an + error was set. + + + + + a #GdkPixbuf + + + + a #GOutputStream to save the pixbuf to + + + + name of file format + + + + optional #GCancellable object, %NULL to ignore + + + + return location for error, or %NULL + + + + list of key-value save options + + + + + + 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. + + + + + + + a #GdkPixbuf + + + + a #GOutputStream to which to save the pixbuf + + + + name of file format + + + + optional #GCancellable object, %NULL to ignore + + + + a #GAsyncReadyCallback to call when the pixbuf is saved + + + + the data to pass to the callback function + + + + list of key-value save options + + + + + + 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. + + + %TRUE if the pixbuf was saved successfully, %FALSE if an + error was set. + + + + + a #GdkPixbuf + + + + a #GOutputStream to save the pixbuf to + + + + name of file format + + + + name of options to set, %NULL-terminated + + + + + + values for named options + + + + + + optional #GCancellable object, %NULL to ignore + + + + + + 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. + + + + + + + a #GdkPixbuf + + + + a #GOutputStream to which to save the pixbuf + + + + name of file format + + + + name of options to set, %NULL-terminated + + + + + + values for named options + + + + + + optional #GCancellable object, %NULL to ignore + + + + a #GAsyncReadyCallback to call when the pixbuf is saved + + + + the data to pass to the callback function + + + + + + 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. + + + whether an error was set + + + + + a #GdkPixbuf. + + + + name of file to save. + + + + name of file format. + + + + name of options to set, %NULL-terminated + + + + + + values for named options + + + + + + + + Creates a transformation of the source image @src by scaling by +@scale_x and @scale_y then translating by @offset_x and @offset_y, +then renders the rectangle (@dest_x, @dest_y, @dest_width, +@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 +gdk_pixbuf_scale_simple() isn't powerful enough. + +If the source rectangle overlaps the destination rectangle on the +same pixbuf, it will be overwritten during the scaling which +results in rendering artifacts. + + + + + + + a #GdkPixbuf + + + + the #GdkPixbuf into which to render the results + + + + the left coordinate for region to render + + + + the top coordinate for region to render + + + + the width of the region to render + + + + the height of the region to render + + + + the offset in the X direction (currently rounded to an integer) + + + + the offset in the Y direction (currently rounded to an integer) + + + + the scale factor in the X direction + + + + the scale factor in the Y direction + + + + 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. + +You can scale a sub-portion of @src by creating a sub-pixbuf +pointing into @src; see gdk_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. + +For more complicated scaling/alpha blending see gdk_pixbuf_scale() +and gdk_pixbuf_composite(). + + + the new #GdkPixbuf, or %NULL if not enough memory could be +allocated for it. + + + + + a #GdkPixbuf + + + + the width of destination image + + + + the height of destination image + + + + the interpolation type for the transformation. + + + + + + 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. + + + %TRUE on success. + + + + + a #GdkPixbuf + + + + a nul-terminated string. + + + + a nul-terminated string. + + + + + + Removes a reference from a pixbuf. + Use g_object_unref(). + + + + + + + A pixbuf. + + + + + + The number of bits per sample. +Currently only 8 bit per sample are supported. + + + + + + + + + + + + + The number of samples per pixel. +Currently, only 3 or 4 samples per pixel are supported. + + + + + + + + + + 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. + + + + + + + + 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. + it is unused since 2.42. + + A bilevel clipping mask (black and white) + will be created and used to draw the image. Pixels below 0.5 opacity + will be considered fully transparent, and all others will be + considered fully opaque. + + + For now falls back to #GDK_PIXBUF_ALPHA_BILEVEL. + In the future it will do full alpha compositing. + + + + An opaque struct representing an animation. + + + 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. + + + 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. + + + + + Name of file to load, in the GLib file + name encoding + + + + + + Creates a new pixbuf animation by loading an image from an resource. + +The file format is detected automatically. If %NULL is returned, then +@error will be set. + + + 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. + + + + + the path of the resource file + + + + + + 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 stream is not closed. + + + 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. + + + + + a #GInputStream to load the pixbuf from + + + + optional #GCancellable object, %NULL to ignore + + + + + + Finishes an asynchronous pixbuf animation creation operation started with +gdk_pixbuf_animation_new_from_stream_async(). + + + a #GdkPixbufAnimation or %NULL on error. Free the returned +object with g_object_unref(). + + + + + a #GAsyncResult + + + + + + Creates a new animation by asynchronously loading an image from an input stream. + +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. +You can then call gdk_pixbuf_animation_new_from_stream_finish() to get the +result of the operation. + + + + + + + a #GInputStream from which to load the animation + + + + optional #GCancellable object, %NULL to ignore + + + + a #GAsyncReadyCallback to call when the pixbuf is loaded + + + + the data to pass to the callback function + + + + + + 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(). + +@start_time would normally come from g_get_current_time(), and marks +the beginning of animation playback. After creating an iterator, you +should immediately display the pixbuf returned by +gdk_pixbuf_animation_iter_get_pixbuf(). Then, you should install +a timeout (with g_timeout_add()) or by some other mechanism ensure +that you'll update the image after +gdk_pixbuf_animation_iter_get_delay_time() milliseconds. Each time +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 +g_get_current_time() will be used automatically. + +To update the image (i.e. possibly change the result of +gdk_pixbuf_animation_iter_get_pixbuf() to a new frame of the animation), +call gdk_pixbuf_animation_iter_advance(). + +If you're using #GdkPixbufLoader, in addition to updating the image +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 +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." + + + an iterator to move over the animation + + + + + a #GdkPixbufAnimation + + + + time when the animation starts playing + + + + + + + + + + + + + + + + + + + + + + + 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. + + + unanimated image representing the animation + + + + + a #GdkPixbufAnimation + + + + + + 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 +the image. + + + %TRUE if the "animation" was really just an image + + + + + a #GdkPixbufAnimation + + + + + + Queries the height of the bounding box of a pixbuf animation. + + + Height of the bounding box of the animation. + + + + + An animation. + + + + + + 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(). + +@start_time would normally come from g_get_current_time(), and marks +the beginning of animation playback. After creating an iterator, you +should immediately display the pixbuf returned by +gdk_pixbuf_animation_iter_get_pixbuf(). Then, you should install +a timeout (with g_timeout_add()) or by some other mechanism ensure +that you'll update the image after +gdk_pixbuf_animation_iter_get_delay_time() milliseconds. Each time +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 +g_get_current_time() will be used automatically. + +To update the image (i.e. possibly change the result of +gdk_pixbuf_animation_iter_get_pixbuf() to a new frame of the animation), +call gdk_pixbuf_animation_iter_advance(). + +If you're using #GdkPixbufLoader, in addition to updating the image +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 +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." + + + an iterator to move over the animation + + + + + a #GdkPixbufAnimation + + + + time when the animation starts playing + + + + + + 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. + + + unanimated image representing the animation + + + + + a #GdkPixbufAnimation + + + + + + Queries the width of the bounding box of a pixbuf animation. + + + Width of the bounding box of the animation. + + + + + An animation. + + + + + + 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 +the image. + + + %TRUE if the "animation" was really just an image + + + + + a #GdkPixbufAnimation + + + + + + Adds a reference to an animation. + Use g_object_ref(). + + + The same as the @animation argument. + + + + + An animation. + + + + + + Removes a reference from an animation. + Use g_object_unref(). + + + + + + + An animation. + + + + + + + + + + Modules supporting animations must derive a type from +#GdkPixbufAnimation, providing suitable implementations of the +virtual functions. - - - - The length of a #GdkPixdata structure without the @pixel_data pointer. + + the parent class + + + + + + + %TRUE if the "animation" was really just an image + + + + + a #GdkPixbufAnimation + + + + + + + + + + unanimated image representing the animation + + + + + a #GdkPixbufAnimation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + an iterator to move over the animation + + + + + a #GdkPixbufAnimation + + + + time when the animation starts playing + + + + + + + + An opaque struct representing an iterator which points to a +certain position in an animation. - - - - A #GdkPixdata contains pixbuf information in a form suitable for -serialization and streaming. + + 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 +gdk_pixbuf_animation_get_iter(), and must increase or remain +unchanged each time gdk_pixbuf_animation_iter_get_pixbuf() is +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() +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 +display, assuming the display had been rendered prior to advancing; +if %TRUE, you need to call gdk_pixbuf_animation_iter_get_pixbuf() +and update the display with the new pixbuf. + + + %TRUE if the image may need updating + + + + + a #GdkPixbufAnimationIter + + + + current time + + + + + + 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. + +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 +for GIF images is currently 20 milliseconds. + + + delay time in milliseconds (thousandths of a second) + + + + + an animation iterator + + + + + + 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. + + + the pixbuf to be displayed + + + + + an animation iterator + + + + + + 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. + + + %TRUE if the frame we're on is partially loaded, or the last frame + + + + + a #GdkPixbufAnimationIter + + + + + + 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 +gdk_pixbuf_animation_get_iter(), and must increase or remain +unchanged each time gdk_pixbuf_animation_iter_get_pixbuf() is +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() +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 +display, assuming the display had been rendered prior to advancing; +if %TRUE, you need to call gdk_pixbuf_animation_iter_get_pixbuf() +and update the display with the new pixbuf. + + + %TRUE if the image may need updating + + + + + a #GdkPixbufAnimationIter + + + + current time + + + + + + 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. + +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 +for GIF images is currently 20 milliseconds. + + + delay time in milliseconds (thousandths of a second) + + + + + an animation iterator + + + + + + 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. + + + the pixbuf to be displayed + + + + + an animation iterator + + + + + + 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. + + + %TRUE if the frame we're on is partially loaded, or the last frame + + + + + a #GdkPixbufAnimationIter + + + + + + + + + + Modules supporting animations must derive a type from +#GdkPixbufAnimationIter, providing suitable implementations of the +virtual functions. - - magic number. A valid #GdkPixdata structure must have - #GDK_PIXBUF_MAGIC_NUMBER here. - + + the parent class + - - less than 1 to disable length checks, otherwise - #GDK_PIXDATA_HEADER_LENGTH + length of @pixel_data. - + + + + + delay time in milliseconds (thousandths of a second) + + + + + an animation iterator + + + + - - information about colorspace, sample width and - encoding, in a #GdkPixdataType. - + + + + + the pixbuf to be displayed + + + + + an animation iterator + + + + - - Distance in bytes between rows. - + + + + + %TRUE if the frame we're on is partially loaded, or the last frame + + + + + a #GdkPixbufAnimationIter + + + + - - Width of the image in pixels. - + + + + + %TRUE if the image may need updating + + + + + a #GdkPixbufAnimationIter + + + + current time + + + + + + + + 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. + + + + + + + The pixel array of the pixbuf + that is being finalized. + + + + + + User closure data. + + + + + + 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 image file was broken somehow. + + + Not enough memory. + + + A bad option was passed to a pixbuf save module. + + + Unknown image type. + + + Don't know how to perform the + given operation on the type of image at hand. + + + Generic failure code, something went wrong. + + + Only part of the animation was loaded. + + + + + + + + + A #GdkPixbufFormat contains information about the image format accepted by a +module. Only modules should access the fields directly, applications should +use the <function>gdk_pixbuf_format_*</function> functions. + + + the name of the image format. + + + + the signature of the module. + + + + the message domain for the @description. + - - Height of the image in pixels. + + a description of the image format. + + + + a %NULL-terminated array of MIME types for the image format. + + + + a %NULL-terminated array of typical filename extensions for the + image format. + + + + a combination of #GdkPixbufFormatFlags. - - @width x @height pixels, encoded according to @pixdata_type - and @rowstride. - - - - - - 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 -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. - Use #GResource instead. + + a boolean determining whether the loader is disabled. + + + + a string containing license information, typically set to + shorthands like "GPL", "LGPL", etc. + + + + Creates a copy of @format + + + the newly allocated copy of a #GdkPixbufFormat. Use + gdk_pixbuf_format_free() to free the resources when done + + + + + a #GdkPixbufFormat + + + + + + Frees the resources allocated when copying a #GdkPixbufFormat +using gdk_pixbuf_format_copy() + + + + + + + a #GdkPixbufFormat + + + + + + Returns a description of the format. + + + a description of the format. + + + + + a #GdkPixbufFormat + + + + + + Returns the filename extensions typically used for files in the +given format. + + + a %NULL-terminated array of filename extensions which must be +freed with g_strfreev() when it is no longer needed. + + + + + + + a #GdkPixbufFormat + + + + + + 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. + + + a string describing the license of @format. + + + + + a #GdkPixbufFormat + + + + + + Returns the mime types supported by the format. + + + a %NULL-terminated array of mime types which must be freed with +g_strfreev() when it is no longer needed. + + + + + + + a #GdkPixbufFormat + + + + + + Returns the name of the format. + + + the name of the format. + + + + + a #GdkPixbufFormat + + + + + + Returns whether this image format is disabled. See +gdk_pixbuf_format_set_disabled(). + + + whether this image format is disabled. + + + + + a #GdkPixbufFormat + + + + + + 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. + + + %TRUE if the specified option is supported + + + + + a #GdkPixbufFormat + + + + the name of an option + + + + + + 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. + + + whether this image format is scalable. + + + + + a #GdkPixbufFormat + + + + + + Returns whether pixbufs can be saved in the given format. + + + whether pixbufs can be saved in the given format. + + + + + a #GdkPixbufFormat + + + + + + 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(). + + + + + + + a #GdkPixbufFormat + + + + %TRUE to disable the format @format + + + + + + + Flags which allow a module to specify further details about the supported +operations. + + + the module can write out images in the format. + + + the image format is scalable + + + the module is threadsafe. gdk-pixbuf + ignores modules that are not marked as threadsafe. (Since 2.28). + + + + The GdkPixbufLoader struct contains only private +fields. + + + Creates a new pixbuf loader object. + + + A newly-created pixbuf loader. + + + + + 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. + +The list of supported mime types depends on what image loaders +are installed, but typically "image/png", "image/jpeg", "image/gif", +"image/tiff" and "image/x-xpixmap" are among the supported mime types. +To obtain the full list of supported mime types, call +gdk_pixbuf_format_get_mime_types() on each of the #GdkPixbufFormat +structs returned by gdk_pixbuf_get_formats(). + + + A newly-created pixbuf loader. + + + + + the mime type to be loaded + + + + + + 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. + +The list of supported image formats depends on what image loaders +are installed, but typically "png", "jpeg", "gif", "tiff" and +"xpm" are among the supported formats. To obtain the full list of +supported image formats, call gdk_pixbuf_format_get_name() on each +of the #GdkPixbufFormat structs returned by gdk_pixbuf_get_formats(). + + + A newly-created pixbuf loader. + + + + + name of the image format to be loaded with the image + + + + + - Upon successful deserialization %TRUE is returned, -%FALSE otherwise. - + + + + + + + + + + + + - - a #GdkPixdata structure to be filled in. - + + - - length of the stream used for deserialization. - + + - - stream of bytes containing a - serialized #GdkPixdata structure. - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + %TRUE if all image data written so far was successfully + passed out via the update_area signal + + + + + A pixbuf loader. + + - - 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. - Use #GResource instead. + + 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. + + + The #GdkPixbufAnimation that the loader is loading, or %NULL if +not enough data has been read to determine the information. + + + + + A pixbuf loader + + + + + + Obtains the available information about the format of the +currently loading image file. - If @use_rle is %TRUE, a pointer to the - newly-allocated memory for the run-length encoded pixel data, - otherwise %NULL. - + A #GdkPixbufFormat or +%NULL. The return value is owned by GdkPixbuf and should not be +freed. + - - a #GdkPixdata to fill. - + + A pixbuf loader. + - - the data to fill @pixdata with. - + + + + 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()). + + + The #GdkPixbuf that the loader is creating, or %NULL if not +enough data has been read to determine how to create the image buffer. + + + + + A pixbuf loader. + + + + + + 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 +emission of the ::size-prepared signal. + + + + + + + A pixbuf loader. + + + + The desired width of the image being loaded. + - - whether to use run-length encoding for the pixel data. - + + The desired height of the image being loaded. + - - Serializes a #GdkPixdata structure into a byte stream. -The byte stream consists of a straightforward writeout of the -#GdkPixdata fields in network byte order, plus the @pixel_data -bytes the structure points to. - Use #GResource instead. + + 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. - - A -newly-allocated string containing the serialized #GdkPixdata -structure. - - - + + %TRUE if the write was successful, or %FALSE if the loader +cannot parse the buffer. + - - a valid #GdkPixdata structure to serialize. - + + A pixbuf loader. + - - location to store the resulting stream length in. - + + Pointer to image data. + + + + + + Length of the @buf buffer in bytes. + - - Generates C source code suitable for compiling images directly -into programs. + + 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. -gdk-pixbuf ships with a program called -[gdk-pixbuf-csource][gdk-pixbuf-csource], which offers a command -line interface to this function. - Use #GResource instead. +See also: gdk_pixbuf_loader_write() - - a newly-allocated string containing the C source form - of @pixdata. - + + %TRUE if the write was successful, or %FALSE if the loader +cannot parse the buffer. + - - a #GdkPixdata to convert to C source. - + + A pixbuf loader. + - - used for naming generated data structures or macros. - - - - a #GdkPixdataDumpType determining the kind of C - source to be generated. - + + The image data as a #GBytes + + + + + + + + + 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. + + + + + + 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 +areas of an image that is being loaded. + + + + + + X offset of upper-left corner of the updated area. + + + + Y offset of upper-left corner of the updated area. + + + + Width of updated area. + + + + Height of updated area. + + + + + + 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. + + + + + + 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. + + + + + + the original width of the image + + + + the original height of the image + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - An enumeration which is used by gdk_pixdata_to_csource() to -determine the form of C source to be generated. The three values -@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. - - - Generate pixbuf data stream (a single - string containing a serialized #GdkPixdata structure in network byte - order). - - - Generate #GdkPixdata structure (needs - the #GdkPixdata structure definition from gdk-pixdata.h). - - - Generate <function>*_ROWSTRIDE</function>, - <function>*_WIDTH</function>, <function>*_HEIGHT</function>, - <function>*_BYTES_PER_PIXEL</function> and - <function>*_RLE_PIXEL_DATA</function> or <function>*_PIXEL_DATA</function> - macro definitions for the image. - - - Generate GLib data types instead of - standard C data types. - - - Generate standard C data types instead of - GLib data types. - - - Generate static symbols. - - - Generate const symbols. - - - Provide a <function>*_RUN_LENGTH_DECODE(image_buf, rle_data, size, bpp)</function> - macro definition to decode run-length encoded image data. - - - - 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. + + 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 <function>fill_vtable</function>, which will get called when the module +is loaded and must set the function pointers of the #GdkPixbufModule. - - each pixel has red, green and blue samples. - - - each pixel has red, green and blue samples - and an alpha value. - - - mask for the colortype flags of the enum. - - - each sample has 8 bits. - - - mask for the sample width flags of the enum. + + the name of the module, usually the same as the + usual file extension for images of this type, eg. "xpm", "jpeg" or "png". + + + + the path from which the module is loaded. + + + + the loaded #GModule. + + + + a #GdkPixbufFormat holding information about the module. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Defines the type of the function used to fill a +#GdkPixbufFormat structure with information about a module. + + + + + + + a #GdkPixbufFormat. + + + + + + Defines the type of the function used to set the vtable of a +#GdkPixbufModule when it is loaded. + + + + + + + a #GdkPixbufModule. + + + + + + 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 +' ', '!', 'x', 'z', and 'n' to indicate bytes that must be matched, +not matched, "don't-care"-bytes, zeros and non-zeros. +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'. + +The signature of a module is stored as an array of +#GdkPixbufModulePatterns. The array is terminated by a pattern +where the @prefix is %NULL. + + +<informalexample><programlisting> +GdkPixbufModulePattern *signature[] = { + { "abcdx", " !x z", 100 }, + { "bla", NULL, 90 }, + { NULL, NULL, 0 } +}; +</programlisting> +The example matches e.g. "auud\0" with relevance 100, and "blau" with +relevance 90.</informalexample> + + + the prefix for this pattern + + + + mask containing bytes which modify how the prefix is matched against + test data + + + + relevance of this pattern + + + + + Defines the type of the function that gets called once the initial +setup of @pixbuf is done. + +#GdkPixbufLoader uses a function of this type to emit the +"<link linkend="GdkPixbufLoader-area-prepared">area_prepared</link>" +signal. + + + + + + + the #GdkPixbuf that is currently being loaded. + + + + if an animation is being loaded, the #GdkPixbufAnimation, else %NULL. + + + + the loader. + + + + + + Defines the type of the function that gets called once the size +of the loaded image is known. + +The function is expected to set @width and @height to the desired +size to which the image should be scaled. If a module has no efficient +way to achieve the desired scaling during the loading of the image, it may +either ignore the size request, or only approximate it - gdk-pixbuf will +then perform the required scaling on the completely loaded image. + +If the function sets @width or @height to zero, the module should interpret +this as a hint that it will be closed soon and shouldn't allocate further +resources. This convention is used to implement gdk_pixbuf_get_file_info() +efficiently. + + + + + + + pointer to a location containing the current image width + + + + pointer to a location containing the current image height + + + + the loader. + + + + + + Defines the type of the function that gets called every time a region +of @pixbuf is updated. + +#GdkPixbufLoader uses a function of this type to emit the +"<link linkend="GdkPixbufLoader-area-updated">area_updated</link>" +signal. + + + + + + + the #GdkPixbuf that is currently being loaded. + + + + the X origin of the updated area. + + + + the Y origin of the updated area. + + + + the width of the updated area. + + + + the height of the updated area. + + + + the loader. + + + + + + + + + + + + + + + + + + + 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. + + No rotation. - - the pixel data is in raw form. + + Rotate by 90 degrees. - - the pixel data is run-length encoded. Runs may - be up to 127 bytes long; their length is stored in a single byte - preceding the pixel data for the run. If a run is constant, its length - byte has the high bit set and the pixel data consists of a single pixel - which must be repeated. + + Rotate by 180 degrees. - - mask for the encoding flags of the enum. + + Rotate by 270 degrees. - - - 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. - Use #GResource instead. - - - a new #GdkPixbuf. - + + + 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() +will fail with the same error. + + + %TRUE if successful, %FALSE (with @error set) if failed. + - - a #GdkPixdata to convert into a #GdkPixbuf. - + + bytes to be written. + + + - - whether to copy raw pixel data; run-length encoded - pixel data is always copied. - + + number of bytes in @buf. + + + + A location to return an error. + + + + user data passed to gdk_pixbuf_save_to_callback(). + + + + An opaque struct representing a simple animation. + + + Creates a new, empty animation. + + + a newly allocated #GdkPixbufSimpleAnim + + + + + the width of the animation + + + + the height of the animation + + + + the speed of the animation, in frames per second + + + + + + Adds a new frame to @animation. The @pixbuf must +have the dimensions specified when the animation +was constructed. + + + + + + + a #GdkPixbufSimpleAnim + + + + the pixbuf to add + + + + + + Gets whether @animation should loop indefinitely when it reaches the end. + + + %TRUE if the animation loops forever, %FALSE otherwise + + + + + a #GdkPixbufSimpleAnim + + + + + + Sets whether @animation should loop indefinitely when it reaches the end. + + + + + + + a #GdkPixbufSimpleAnim + + + + whether to loop the animation + + + + + + Whether the animation should loop when it reaches the end. + + + + + + + + + + + + From 7025225c706edd390e256d7b60d5a5e7318ee2bc Mon Sep 17 00:00:00 2001 From: Paolo Borelli Date: Sun, 3 Jan 2021 18:18:28 +0100 Subject: [PATCH 2/2] fix.sh: change unsupported GModule field in GdkPixbufModule to a gpointer --- GdkPixbuf-2.0.gir | 2 +- fix.sh | 6 ++++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/GdkPixbuf-2.0.gir b/GdkPixbuf-2.0.gir index a883bccb..4e123799 100644 --- a/GdkPixbuf-2.0.gir +++ b/GdkPixbuf-2.0.gir @@ -4059,7 +4059,7 @@ is loaded and must set the function pointers of the #GdkPixbufModule. the loaded #GModule. - + a #GdkPixbufFormat holding information about the module. diff --git a/fix.sh b/fix.sh index 0022c8c1..e3d9057d 100755 --- a/fix.sh +++ b/fix.sh @@ -56,6 +56,12 @@ xmlstarlet ed -P -L \ -u '//_:method[@c:identifier="gdk_frame_clock_get_timings"]/_:return-value/@transfer-ownership' -v "none" \ Gdk-3.0.gir +# replace gmodule with gpointer +xmlstarlet ed -P -L \ + -u '//_:record[@name="PixbufModule"]/_:field[@name="module"]/_:type/@name' -v "gpointer" \ + -u '//_:record[@name="PixbufModule"]/_:field[@name="module"]/_:type/@c:type' -v "gpointer" \ + GdkPixbuf-2.0.gir + # replace "gint" response_id parameters with "ResponseType" xmlstarlet ed -P -L \ -u '//_:parameter[@name="response_id"]/_:type[@name="gint"]/@c:type' -v "GtkResponseType" \