New file with utility and convenience functions for pixbufs.

1999-12-02  Federico Mena Quintero  <federico@redhat.com>

	* src/gdk-pixbuf-util.c: New file with utility and convenience
	functions for pixbufs.

	* src/Makefile.am (libgdk_pixbuf_la_SOURCES): Added gdk-pixbuf-util.c.

	* doc/gdk-pixbuf-sections.txt: Added section for utility functions.

	* doc/Makefile.am (tmpl_sources): Added tmpl/util.sgml.

	* doc/gdk-pixbuf.sgml: Added the utilities section.

	* doc/tmpl/util.sgml: Documentation for the utility functions.

docs/reference/gdk-pixbuf/Makefile.am

@@ -24,7 +24,8 @@ tmpl_sources =					\
 	tmpl/gdk-pixbuf.sgml			\
 	tmpl/gnome-canvas-pixbuf.sgml		\
 	tmpl/refcounting.sgml			\
-	tmpl/rendering.sgml
+	tmpl/rendering.sgml			\
+	tmpl/util.sgml
 
 gdk_pixbuf_docdir = $(HTML_DIR)
 gdk_pixbuf_doc_DATA =			\

docs/reference/gdk-pixbuf/gdk-pixbuf-decl.txt

@@ -145,6 +145,11 @@ guchar *data, ArtPixFormat format, gboolean has_alpha,int width, int height, int
 <RETURNS>GdkPixbuf  *</RETURNS>
 const gchar **data
 </FUNCTION>
+<FUNCTION>
+<NAME>gdk_pixbuf_add_alpha</NAME>
+<RETURNS>GdkPixbuf  *</RETURNS>
+GdkPixbuf *pixbuf, gboolean substitute_color,guchar r, guchar g, guchar b
+</FUNCTION>
 <ENUM>
 <NAME>GdkPixbufAlphaMode</NAME>
 typedef enum {

docs/reference/gdk-pixbuf/gdk-pixbuf-sections.txt

@@ -40,6 +40,11 @@ gdk_pixbuf_render_to_drawable
 gdk_pixbuf_render_threshold_alpha
 </SECTION>
 
+<SECTION>
+<FILE>util</FILE>
+gdk_pixbuf_add_alpha
+</SECTION>
+
 <SECTION>
 <FILE>gnome-canvas-pixbuf</FILE>
 GNOME_CANVAS_PIXBUF

docs/reference/gdk-pixbuf/gdk-pixbuf.sgml

@@ -4,6 +4,7 @@
 <!entity gdk-pixbuf-file-loading SYSTEM "sgml/file-loading.sgml">
 <!entity gdk-pixbuf-creating SYSTEM "sgml/creating.sgml">
 <!entity gdk-pixbuf-rendering SYSTEM "sgml/rendering.sgml">
+<!entity gdk-pixbuf-util SYSTEM "sgml/util.sgml">
 <!entity GnomeCanvasPixbuf SYSTEM "sgml/gnome-canvas-pixbuf.sgml">
 <!entity GdkPixbufLoader SYSTEM "sgml/gdk-pixbuf-loader.sgml">
 ]>
@@ -46,6 +47,7 @@
     &gdk-pixbuf-file-loading;
     &gdk-pixbuf-creating;
     &gdk-pixbuf-rendering;
+    &gdk-pixbuf-util;
     &GnomeCanvasPixbuf;
     &GdkPixbufLoader;
   </reference>

docs/reference/gdk-pixbuf/gdk-pixbuf.signals

@@ -1,22 +1,22 @@
 <SIGNAL>
 <NAME>GdkPixbufLoader::area-updated</NAME>
 <RETURNS>void</RETURNS>
-GdkPixbufLoader *loader
+GdkPixbufLoader *gdkpixbufloader
-gint  x
+gint  arg1
-gint  y
+gint  arg2
-gint  width
+gint  arg3
-gint  height
+gint  arg4
 </SIGNAL>
 
 <SIGNAL>
 <NAME>GdkPixbufLoader::area-prepared</NAME>
 <RETURNS>void</RETURNS>
-GdkPixbufLoader *loader
+GdkPixbufLoader *gdkpixbufloader
 </SIGNAL>
 
 <SIGNAL>
 <NAME>GdkPixbufLoader::closed</NAME>
 <RETURNS>void</RETURNS>
-GdkPixbufLoader *loader
+GdkPixbufLoader *gdkpixbufloader
 </SIGNAL>
 

docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml

@@ -71,6 +71,12 @@ Application-driven image loading.
     areas of an image that is being loaded.
   </para>
 
+@gdkpixbufloader: the object which received the signal.
+@arg1: 
+@arg2: 
+@arg3: 
+@arg4: 
+<!-- # Unused Parameters # -->
 @loader: Loader which emitted the signal.
 @x: X offset of upper-left corner of the updated area.
 @y: Y offset of upper-left corner of the updated area.
@@ -86,6 +92,8 @@ Application-driven image loading.
     fetch the partially-loaded pixbuf.
   </para>
 
+@gdkpixbufloader: the object which received the signal.
+<!-- # Unused Parameters # -->
 @loader: Loader which emitted the signal.
 
 <!-- ##### SIGNAL GdkPixbufLoader::closed ##### -->
@@ -96,6 +104,8 @@ Application-driven image loading.
     drives it.
   </para>
 
+@gdkpixbufloader: the object which received the signal.
+<!-- # Unused Parameters # -->
 @loader: Loader which emitted the signal.
 
 <!--

docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml

@@ -253,14 +253,6 @@ Canvas item to display #GdkPixbuf images.
     linkend="GnomeCanvasPixbuf--x">x</link> argument.
   </para>
 
-
-<!--
-Local variables:
-mode: sgml
-sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
-End:
--->
-
 <!-- ##### ARG GnomeCanvasPixbuf:y_set ##### -->
   <para>
     Determines whether the <link
@@ -278,3 +270,9 @@ End:
     The default is %FALSE.
   </para>
 
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->

docs/reference/gdk-pixbuf/tmpl/rendering.sgml

@@ -96,7 +96,9 @@ In the future it will do full alpha compositing.
 @dest_y: 
 @width: 
 @height: 
-@alpha_threshold: <!--
+@alpha_threshold:
+
+<!--
 Local variables:
 mode: sgml
 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")

docs/reference/gdk-pixbuf/tmpl/util.sgml

@@ -0,0 +1,38 @@
+<!-- ##### SECTION Title ##### -->
+Utilities
+
+<!-- ##### SECTION Short_Description ##### -->
+Utility and miscellaneous convenience functions.
+
+<!-- ##### SECTION Long_Description ##### -->
+  <para>
+    These functions provide miscellaneous utilities for manipulating
+    pixbufs.  The pixel data in pixbufs may of course be manipulated
+    directly by applications, but several common operations can be
+    performed by these functions instead.
+  </para>
+
+<!-- ##### SECTION See_Also ##### -->
+  <para>
+    #GdkPixbuf
+  </para>
+
+<!-- ##### FUNCTION gdk_pixbuf_add_alpha ##### -->
+<para>
+
+</para>
+
+@pixbuf: 
+@substitute_color: 
+@r: 
+@g: 
+@b: 
+@Returns: 
+
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->

gdk-pixbuf/ChangeLog

@@ -1,3 +1,18 @@
+1999-12-02  Federico Mena Quintero  <federico@redhat.com>
+
+	* src/gdk-pixbuf-util.c: New file with utility and convenience
+	functions for pixbufs.
+
+	* src/Makefile.am (libgdk_pixbuf_la_SOURCES): Added gdk-pixbuf-util.c.
+
+	* doc/gdk-pixbuf-sections.txt: Added section for utility functions.
+
+	* doc/Makefile.am (tmpl_sources): Added tmpl/util.sgml.
+
+	* doc/gdk-pixbuf.sgml: Added the utilities section.
+
+	* doc/tmpl/util.sgml: Documentation for the utility functions.
+
 1999-11-29  Owen Taylor  <otaylor@redhat.com>
 
 	* src/gdk-pixbuf-render.c (gdk_pixbuf_render_to_drawable_alpha):

gdk-pixbuf/Makefile.am

@@ -74,6 +74,7 @@ libgdk_pixbuf_la_SOURCES = 	\
 	gdk-pixbuf-loader.c	\
 	gdk-pixbuf-render.c	\
 	gdk-pixbuf-drawable.c	\
+	gdk-pixbuf-util.c	\
 	$(CANVAS_SOURCEFILES)
 
 libgdk_pixbuf_la_LDFLAGS = -version-info 1:0:0

gdk-pixbuf/gdk-pixbuf-util.c

@@ -0,0 +1,95 @@
+/* GdkPixbuf library - Utilities and miscellaneous convenience functions
+ *
+ * Copyright (C) 1999 The Free Software Foundation
+ *
+ * Author: Federico Mena-Quintero <federico@gimp.org>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+#include <config.h>
+#include "gdk-pixbuf/gdk-pixbuf.h"
+
+
+
+/**
+ * gdk_pixbuf_add_alpha:
+ * @pixbuf: A pixbuf.
+ * @substitute_color: Whether to substitute a color for zero opacity.  If this
+ * is #FALSE, then the (@r, @g, @b) arguments will be ignored.
+ * @r: Red value to substitute.
+ * @g: Green value to substitute.
+ * @b: Blue value to substitute.
+ *
+ * Takes an existing pixbuf and adds an alpha channel to it.  If the original
+ * pixbuf already had alpha information, then the contents of the new pixbuf are
+ * exactly the same as the original's.  Otherwise, the new pixbuf will have all
+ * pixels with full opacity if @substitute_color is #FALSE.  If
+ * @substitute_color is #TRUE, then the color specified by (@r, @g, @b) will be
+ * substituted for zero opacity.
+ *
+ * Return value: A newly-created pixbuf with a reference count of 1.
+ **/
+GdkPixbuf *
+gdk_pixbuf_add_alpha (GdkPixbuf *pixbuf, gboolean substitute_color, guchar r, guchar g, guchar b)
+{
+	ArtPixBuf *apb;
+	ArtPixBuf *new_apb;
+	GdkPixbuf *new_pixbuf;
+	int x, y;
+
+	g_return_val_if_fail (pixbuf != NULL, NULL);
+
+	apb = pixbuf->art_pixbuf;
+	g_return_val_if_fail (apb->format == ART_PIX_RGB, NULL);
+	g_return_val_if_fail (apb->n_channels == 3 || apb->n_channels == 4, NULL);
+	g_return_val_if_fail (apb->bits_per_sample == 8, NULL);
+
+	if (apb->has_alpha) {
+		new_apb = art_pixbuf_duplicate (apb);
+		if (!new_apb)
+			return NULL;
+
+		return gdk_pixbuf_new_from_art_pixbuf (new_apb);
+	}
+
+	new_pixbuf = gdk_pixbuf_new (ART_PIX_RGB, TRUE, 8, apb->width, apb->height);
+	if (!new_pixbuf)
+		return NULL;
+
+	new_apb = new_pixbuf->art_pixbuf;
+
+	for (y = 0; y < apb->height; y++) {
+		guchar *src, *dest;
+		guchar tr, tg, tb;
+
+		src = apb->pixels + y * apb->rowstride;
+		dest = new_apb->pixels + y * new_apb->rowstride;
+
+		for (x = 0; x < apb->width; x++) {
+			tr = *dest++ = *src++;
+			tg = *dest++ = *src++;
+			tb = *dest++ = *src++;
+
+			if (substitute_color && tr == r && tg == g && tb == b)
+				*dest++ = 0;
+			else
+				*dest++ = 255;
+		}
+	}
+
+	return new_pixbuf;
+}

gdk-pixbuf/gdk-pixbuf.h

@@ -83,6 +83,11 @@ GdkPixbuf *gdk_pixbuf_new_from_data (guchar *data, ArtPixFormat format, gboolean
 				     ArtDestroyNotify dfunc, gpointer dfunc_data);
 GdkPixbuf *gdk_pixbuf_new_from_xpm_data (const gchar **data);
 
+/* Adding or removing alpha */
+
+GdkPixbuf *gdk_pixbuf_add_alpha (GdkPixbuf *pixbuf, gboolean substitute_color,
+				 guchar r, guchar g, guchar b);
+
 /* Rendering to a drawable */
 
 typedef enum {