From 9d8e5e0ba8f6144dda85775b9dc4b2ac36246cfe Mon Sep 17 00:00:00 2001 From: Sebastian Wilhelmi Date: Sat, 3 Nov 2001 18:49:43 +0000 Subject: [PATCH] gdk_rgb_init() doesn't need to be called anymore. Use g_object_(un)_ref 2001-11-03 Sebastian Wilhelmi * gdk-pixbuf/tmpl/refcounting.sgml, gdk-pixbuf/porting-from-imlib.sgml, tmpl/creating.sgml: gdk_rgb_init() doesn't need to be called anymore. Use g_object_(un)_ref instead of gdk_pixbuf_(un)ref. * tmpl/module_interface.sgml: Typo fix. * gdk-pixbuf/gdk-pixbuf.sgml: Fixed jade complaining about '_' by replacing it with '-'. Now builds again. * gdk-pixbuf-loader.c, gdk-pixbuf-scale.c: Documentation fixes. --- docs/reference/ChangeLog | 12 +++++++ docs/reference/gdk-pixbuf/gdk-pixbuf.sgml | 8 ++--- .../gdk-pixbuf/porting-from-imlib.sgml | 24 +++++--------- docs/reference/gdk-pixbuf/tmpl/creating.sgml | 2 +- .../gdk-pixbuf/tmpl/module_interface.sgml | 2 +- .../gdk-pixbuf/tmpl/refcounting.sgml | 23 +++++++++---- gdk-pixbuf/ChangeLog | 4 +++ gdk-pixbuf/gdk-pixbuf-loader.c | 4 +-- gdk-pixbuf/gdk-pixbuf-scale.c | 33 ++++++++++--------- 9 files changed, 66 insertions(+), 46 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 3238c1abcc..ee01d58146 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,15 @@ +2001-11-03 Sebastian Wilhelmi + + * gdk-pixbuf/tmpl/refcounting.sgml, + gdk-pixbuf/porting-from-imlib.sgml, tmpl/creating.sgml: + gdk_rgb_init() doesn't need to be called anymore. Use + g_object_(un)_ref instead of gdk_pixbuf_(un)ref. + + * tmpl/module_interface.sgml: Typo fix. + + * gdk-pixbuf/gdk-pixbuf.sgml: Fixed jade complaining about '_' by + replacing it with '-'. Now builds again. + 2001-10-31 Matthias Clasen * gdk-pixbuf/gdk-pixbuf.sgml: include initialization_versions.sgml, diff --git a/docs/reference/gdk-pixbuf/gdk-pixbuf.sgml b/docs/reference/gdk-pixbuf/gdk-pixbuf.sgml index b19896b082..91264149be 100644 --- a/docs/reference/gdk-pixbuf/gdk-pixbuf.sgml +++ b/docs/reference/gdk-pixbuf/gdk-pixbuf.sgml @@ -10,8 +10,8 @@ - - + + @@ -87,7 +87,7 @@ - &initialization_versions; + &initialization-versions; &gdk-pixbuf-gdk-pixbuf; &gdk-pixbuf-refcounting; @@ -100,7 +100,7 @@ &gdk-pixbuf-animation; &GdkPixbufLoader; - &module_interface; + &module-interface; &gdk-pixbuf-gdk-pixbuf-xlib-init; &gdk-pixbuf-gdk-pixbuf-xlib-rendering; diff --git a/docs/reference/gdk-pixbuf/porting-from-imlib.sgml b/docs/reference/gdk-pixbuf/porting-from-imlib.sgml index b736200cfd..a87c26a294 100644 --- a/docs/reference/gdk-pixbuf/porting-from-imlib.sgml +++ b/docs/reference/gdk-pixbuf/porting-from-imlib.sgml @@ -62,11 +62,6 @@ The &gdk-pixbuf; library does not need to be initialized. - However, if you intend to use the rendering functions or - anything else from the GdkRGB - library, you should call gdk_rgb_init() - after calling gtk_init() or - gnome_init() in your program. @@ -101,14 +96,13 @@ a new GdkPixbuf structure, it is created with an initial reference count of 1. When another part of the program wants to keep a reference to the - pixbuf, it should call gdk_pixbuf_ref(); this will - increase the reference count by 1. When some part of the - program does not need to keep a reference to a pixbuf + pixbuf, it should call g_object_ref(); + this will increase the reference count by 1. When some part + of the program does not need to keep a reference to a pixbuf anymore and wants to release the pixbuf, it should call - gdk_pixbuf_unref(); - this will decrease the reference count by 1. When the - reference count drops to zero, the pixbuf gets destroyed or + g_object_unref(); this will decrease + the reference count by 1. When the reference count drops to + zero, the pixbuf gets destroyed or finalized and its memory is freed. @@ -131,9 +125,9 @@ Most applications will simply need to call - gdk_pixbuf_ref() when they want to keep + g_object_ref() when they want to keep an extra reference to a pixbuf, and then - gdk_pixbuf_unref() when they are done + g_object_unref() when they are done with it. @@ -232,7 +226,7 @@ After you have created a pixbuf, you can manipulate it in any way you please and then finally call - gdk_pixbuf_unref() when you are done + g_object_unref() when you are done with it. This can be thought of as a replacement for gdk_imlib_destroy_image() but with much cleaner semantics. diff --git a/docs/reference/gdk-pixbuf/tmpl/creating.sgml b/docs/reference/gdk-pixbuf/tmpl/creating.sgml index 0effa2aa12..818aa9eb4b 100644 --- a/docs/reference/gdk-pixbuf/tmpl/creating.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/creating.sgml @@ -33,7 +33,7 @@ Creating a pixbuf from image data that is already in memory. You can also copy an existing pixbuf with the gdk_pixbuf_copy() - function. This is not the same as just doing a gdk_pixbuf_ref() + function. This is not the same as just doing a g_object_ref() on the old pixbuf; the copy function will actually duplicate the pixel data in memory and create a new #GdkPixbuf structure for it. diff --git a/docs/reference/gdk-pixbuf/tmpl/module_interface.sgml b/docs/reference/gdk-pixbuf/tmpl/module_interface.sgml index b39ee2f2ae..e2a1cca025 100644 --- a/docs/reference/gdk-pixbuf/tmpl/module_interface.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/module_interface.sgml @@ -66,7 +66,7 @@ images in a certain file format. A #GdkPixbufModule can be loaded dynamically from a #GModule. Each loadable module must contain a #ModuleFillVtableFunc function named -gdk_pixbuf__module_name_fill_vtable. +gdk_pixbuf__module_name_fill_vtable. It will get called when the module is loaded and must set the function pointers of the #GdkPixbufModule. diff --git a/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml b/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml index f975e4f69a..bf6bc382a9 100644 --- a/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml @@ -8,15 +8,24 @@ Functions to perform reference counting and memory management on a - #GdkPixbuf structures are reference counted. This means that - an application can share a single pixbuf among many parts of the + #GdkPixbuf structures are reference counted. This means that an + application can share a single pixbuf among many parts of the code. When a piece of the program needs to keep a pointer to a - pixbuf, it should add a reference to it. When it no longer needs - the pixbuf, it should subtract a reference. The pixbuf will be - destroyed when its reference count drops to zero. Newly-created - #GdkPixbuf structures start with a reference count of one. + pixbuf, it should add a reference to it by calling g_object_ref(). + When it no longer needs the pixbuf, it should subtract a reference + by calling g_object_unref(). The pixbuf will be destroyed when + its reference count drops to zero. Newly-created #GdkPixbuf + structures start with a reference count of one. + + + As #GdkPixbuf is derived from #GObject now, gdk_pixbuf_ref() and + gdk_pixbuf_unref() are deprecated in favour of g_object_ref() + and g_object_unref () resp. + + + Finalizing a pixbuf means to free its pixel data and to free the #GdkPixbuf structure itself. Most of the @@ -35,7 +44,7 @@ Functions to perform reference counting and memory management on a As an extension to traditional reference counting, #GdkPixbuf structures support defining a handler for the last unref - operation. If gdk_pixbuf_unref() is called on a #GdkPixbuf + operation. If g_object_unref() is called on a #GdkPixbuf structure that has a reference count of 1, i.e. its last reference, then the pixbuf's last unref handler function will be called. It is up to this function to determine whether to diff --git a/gdk-pixbuf/ChangeLog b/gdk-pixbuf/ChangeLog index df906728e9..139931e95e 100644 --- a/gdk-pixbuf/ChangeLog +++ b/gdk-pixbuf/ChangeLog @@ -1,3 +1,7 @@ +2001-11-03 Sebastian Wilhelmi + + * gdk-pixbuf-loader.c, gdk-pixbuf-scale.c: Documentation fixes. + 2001-10-29 Tor Lillqvist * Makefile.am: Use -no-undefined on Win32. Make diff --git a/gdk-pixbuf/gdk-pixbuf-loader.c b/gdk-pixbuf/gdk-pixbuf-loader.c index 0149357b24..1a9e61fb32 100644 --- a/gdk-pixbuf/gdk-pixbuf-loader.c +++ b/gdk-pixbuf/gdk-pixbuf-loader.c @@ -438,13 +438,13 @@ gdk_pixbuf_loader_new_with_type (const char *image_type, * @loader: A pixbuf loader. * * Queries the GdkPixbuf that a pixbuf loader is currently creating. - * In general it only makes sense to call this function afer the + * 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 gdk_pixbuf_ref() should be sufficient to continue + * 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()). diff --git a/gdk-pixbuf/gdk-pixbuf-scale.c b/gdk-pixbuf/gdk-pixbuf-scale.c index 02169a8f66..355374b23a 100644 --- a/gdk-pixbuf/gdk-pixbuf-scale.c +++ b/gdk-pixbuf/gdk-pixbuf-scale.c @@ -41,10 +41,11 @@ * @scale_y: the scale factor in the Y direction * @interp_type: the interpolation type for the transformation. * - * Transforms the image by source image by scaling by @scale_x and @scale_y then - * translating by @offset_x and @offset_y, then renders the rectangle - * (@dest,@dest_y,@dest_width,@dest_height) of the resulting image onto the - * destination drawable replacing the previous contents. + * Transforms 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. **/ void gdk_pixbuf_scale (const GdkPixbuf *src, @@ -91,10 +92,10 @@ gdk_pixbuf_scale (const GdkPixbuf *src, * @interp_type: the interpolation type for the transformation. * @overall_alpha: overall alpha for source image (0..255) * - * Transforms the image by source image by scaling by @scale_x and @scale_y then - * translating by @offset_x and @offset_y, then composites the rectangle - * (@dest,@dest_y,@dest_width,@dest_height) of the resulting image onto the - * destination drawable. + * Transforms the source image @src by scaling by @scale_x and + * @scale_y then translating by @offset_x and @offset_y, then + * composites the rectangle (@dest_x, @dest_y, @dest_width, + * @dest_height) of the resulting image onto the destination image. **/ void gdk_pixbuf_composite (const GdkPixbuf *src, @@ -147,11 +148,11 @@ gdk_pixbuf_composite (const GdkPixbuf *src, * @color1: the color of check at upper left * @color2: the color of the other check * - * Transforms the image by source image by scaling by @scale_x and @scale_y then + * Transforms the source image @src by scaling by @scale_x and @scale_y then * translating by @offset_x and @offset_y, then composites the rectangle - * (@dest,@dest_y,@dest_width,@dest_height) of the resulting image with + * (@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 drawable. + * destination image. **/ void gdk_pixbuf_composite_color (const GdkPixbuf *src, @@ -198,8 +199,8 @@ gdk_pixbuf_composite_color (const GdkPixbuf *src, * @dest_height: the height of destination image * @interp_type: the interpolation type for the transformation. * - * Scale the #GdkPixbuf @src to @dest_width x @dest_height and render the result into - * a new #GdkPixbuf. + * Scale the #GdkPixbuf @src to @dest_width x @dest_height and render + * the result into a new #GdkPixbuf. * * Return value: the new #GdkPixbuf, or NULL if not enough memory could be * allocated for it. @@ -239,9 +240,9 @@ gdk_pixbuf_scale_simple (const GdkPixbuf *src, * @color1: the color of check at upper left * @color2: the color of the other check * - * Scale the #GdkPixbuf @src to @dest_width x @dest_height composite the result with - * a checkboard of colors @color1 and @color2 and render the result into - * a new #GdkPixbuf. + * Scale the #GdkPixbuf @src to @dest_width x @dest_height composite + * the result with a checkboard of colors @color1 and @color2 and + * render the result into a new #GdkPixbuf. * * Return value: the new #GdkPixbuf, or NULL if not enough memory could be * allocated for it.