Documentation. Spelling fixes.

        * gdk-pixdata.c, gdk-pixdata.h: Documentation.
        * gdk-pixbuf-csource.1: Spelling fixes.

4 files changed, 148 insertions, 25 deletions

diff --git a/gdk-pixbuf/ChangeLog b/gdk-pixbuf/ChangeLog
index e2c37c7e7..e60204ab0 100644
--- a/gdk-pixbuf/ChangeLog
+++ b/gdk-pixbuf/ChangeLog
@@ -1,3 +1,9 @@
+2001-10-16  Matthias Clasen  <matthiasc@poet.de>
+
+	* gdk-pixdata.c, gdk-pixdata.h: Documentation.
+
+	* gdk-pixbuf-csource.1: Spelling fixes.
+
 Wed Oct 10 11:52:17 2001  Owen Taylor  <otaylor@redhat.com>
 
 	* gdk-pixdata.c gdk-pixbuf.h: Get rid of 
diff --git a/gdk-pixbuf/gdk-pixbuf-csource.1 b/gdk-pixbuf/gdk-pixbuf-csource.1
index ebc056750..d992921b6 100644
--- a/gdk-pixbuf/gdk-pixbuf-csource.1
+++ b/gdk-pixbuf/gdk-pixbuf-csource.1
@@ -9,7 +9,7 @@ gdk-pixbuf-csource \- C code generation utility for GdkPixbuf images
 
 .SH DESCRIPTION
 \fBgdk-pixbuf-csource\fP is a small utility that generates C code containing
-images, usefull for compiling images directly into programs.
+images, useful for compiling images directly into programs.
 
 .SH INVOCATION
 
@@ -35,11 +35,11 @@ Generate *_ROWSTRIDE, *_WIDTH, *_HEIGHT, *_BYTES_PER_PIXEL and
 
 .TP
 \fI--rle
-Enables run length encoding for the generated pixel data (default).
+Enables run-length encoding for the generated pixel data (default).
 
 .TP
 \fI--raw
-Disables run length encoding for the generated pixel data (default).
+Disables run-length encoding for the generated pixel data.
 
 .TP
 \fI--extern
@@ -56,8 +56,8 @@ to decode run-length encoded image data.
 
 .TP
 \fI--name=identifier
-Specifies the identifier name (prefix) for the generated variable or
-macros (usefull only if \fI--build-list\fP was not specified).
+Specifies the identifier name (prefix) for the generated variables or
+macros (useful only if \fI--build-list\fP was not specified).
 
 .TP
 \fI--build-list
diff --git a/gdk-pixbuf/gdk-pixdata.c b/gdk-pixbuf/gdk-pixdata.c
index b9e4c70bb..57e2abecf 100644
--- a/gdk-pixbuf/gdk-pixdata.c
+++ b/gdk-pixbuf/gdk-pixdata.c
@@ -80,16 +80,16 @@ pixdata_get_length (const GdkPixdata *pixdata)
 
 /**
  * gdk_pixdata_serialize:
- * @pixdata: A valid GdkPixdata structure to serialize
- * @stream_length_p: Location to store the resulting stream length in
+ * @pixdata: a valid #GdkPixdata structure to serialize.
+ * @stream_length_p: location to store the resulting stream length in.
  *
- * Serialize a #GdkPixdata structure into a byte stream.
- * The byte stream consists of a straight forward write out of the
- * #GdkPixdata fields in network byte order, plus the pixel_data
+ * 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.
  *
  * Return value: A newly-allocated string containing the serialized
- * GdkPixdata structure
+ * #GdkPixdata structure.
  **/
 guint8* /* free result */
 gdk_pixdata_serialize (const GdkPixdata *pixdata,
@@ -159,21 +159,21 @@ gdk_pixdata_serialize (const GdkPixdata *pixdata,
 
 /**
  * gdk_pixdata_deserialize:
- * @pixdata: A GdkPixdata structure to be filled in
- * @stream_length: Length of the stream used for deserialization
- * @stream: Stream of bytes containing a serialized pixdata structure
- * @error: GError location to indicate failures (maybe NULL to ignore errors)
+ * @pixdata: a #GdkPixdata structure to be filled in.
+ * @stream_length: length of the stream used for deserialization.
+ * @stream: stream of bytes containing a serialized #GdkPixdata structure.
+ * @error: #GError location to indicate failures (maybe %NULL to ignore errors).
  *
- * Deserialize (reconstruct) a #GdkPixdata structure from a byte stream.
- * The byte stream consists of a straight forward write out of the
- * #GdkPixdata fields in network byte order, plus the pixel_data
+ * 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
+ * The @pixdata contents are reconstructed byte by byte and are checked
  * for validity. This function may fail with %GDK_PIXBUF_CORRUPT_IMAGE
- * or %GDK_PIXBUF_ERROR_UNKNOWN_TYPE
+ * or %GDK_PIXBUF_ERROR_UNKNOWN_TYPE.
  *
- * Return value: Upon successfull deserialization %TRUE is returned,
- * %FALSE otherwise
+ * Return value: Upon successful deserialization %TRUE is returned,
+ * %FALSE otherwise.
  **/
 gboolean
 gdk_pixdata_deserialize (GdkPixdata   *pixdata,
@@ -290,6 +290,19 @@ rl_encode_rgbx (guint8 *bp,	/* dest buffer */
   return bp;
 }
 
+/**
+ * gdk_pixdata_from_pixbuf:
+ * @pixdata: a #GdkPixdata to fill.
+ * @pixbuf: the data to fill @pixdata with.
+ * @use_rle: whether to use run-length encoding for the pixel data.
+ *
+ * Converts a #GdkPixbuf to a #GdkPixdata. If @use_rle is %TRUE, the
+ * pixel data is run-length encoded into newly-allocated memory and a 
+ * pointer to that memory is returned. 
+ *
+ * Returns: If @ure_rle is %TRUE, a pointer to the newly-allocated memory 
+ *   for the run-length encoded pixel data, otherwise %NULL.
+ **/
 gpointer
 gdk_pixdata_from_pixbuf (GdkPixdata      *pixdata,
 			 const GdkPixbuf *pixbuf,
@@ -345,6 +358,19 @@ gdk_pixdata_from_pixbuf (GdkPixdata      *pixdata,
   return free_me;
 }
 
+/**
+ * gdk_pixbuf_from_pixdata:
+ * @pixdata: a #GdkPixdata to convert into a #GdkPixbuf.
+ * @copy_pixels: whether to copy raw pixel data; run-length encoded
+ *     pixel data is always copied.
+ * @error: location to store possible errors.
+ * 
+ * Converts a #GdkPixdata to a #GdkPixbuf. If @copy_pixels is %TRUE or
+ * if the pixel data is run-length-encoded, the pixel data is copied into
+ * newly-allocated memory; otherwise it is reused.
+ *
+ * Returns: a new #GdkPixbuf.
+ **/
 GdkPixbuf*
 gdk_pixbuf_from_pixdata (const GdkPixdata *pixdata,
 			 gboolean          copy_pixels,
@@ -543,6 +569,22 @@ save_rle_decoder (GString     *gstring,
   APPEND (gstring, "  } } while (0)\n");
 }
 
+/**
+ * gdk_pixdata_to_csource:
+ * @pixdata: a #GdkPixdata to convert to C source.
+ * @name: used for naming generated data structures or macros.
+ * @dump_type: a #GdkPixdataDumpType determining the kind of C
+ *   source to be generated.
+ *
+ * Generates C source code suitable for compiling images directly 
+ * into programs. 
+ *
+ * Gtk+ ships with a program called gdk-pixbuf-csource which offers 
+ * a cmdline interface to this functions.
+ *
+ * Returns: a newly-allocated string containing the C source form
+ *   of @pixdata.
+ **/
 GString*
 gdk_pixdata_to_csource (GdkPixdata        *pixdata,
 			const gchar	  *name,
@@ -790,8 +832,8 @@ gdk_pixdata_to_csource (GdkPixdata        *pixdata,
  * ship a program with images, but don't want to depend on any
  * external files.
  *
- * Gtk+ ships with a program called gdk-pixbuf-csource which allowes
- * for conversion of #GdkPixbufs into such a inline reprentation.
+ * Gtk+ ships with a program called gdk-pixbuf-csource which allows
+ * for conversion of #GdkPixbufs into such a inline representation.
  * In almost all cases, you should pass the --raw flag to
  * gdk-pixbuf-csource. A sample invocation would be:
  *
diff --git a/gdk-pixbuf/gdk-pixdata.h b/gdk-pixbuf/gdk-pixdata.h
index 92ef3ecec..a51720099 100644
--- a/gdk-pixbuf/gdk-pixdata.h
+++ b/gdk-pixbuf/gdk-pixdata.h
@@ -25,9 +25,33 @@
 extern "C" {
 #endif /* __cplusplus */
 
-
+/**
+ * GDK_PIXBUF_MAGIC_NUMBER:
+ *
+ * Magic number for #GdkPixdata structures.
+ **/
 #define GDK_PIXBUF_MAGIC_NUMBER (0x47646b50)    /* 'GdkP' */
 
+/**
+ * GdkPixdataType:
+ * @GDK_PIXDATA_COLOR_TYPE_RGB:  each pixel has red, green and blue samples.
+ * @GDK_PIXDATA_COLOR_TYPE_RGBA: each pixel has red, green and blue samples 
+ *    and an alpha value.
+ * @GDK_PIXDATA_COLOR_TYPE_MASK: mask for the colortype flags of the enum.
+ * @GDK_PIXDATA_SAMPLE_WIDTH_8: each sample has 8 bits.
+ * @GDK_PIXDATA_SAMPLE_WIDTH_MASK: mask for the sample width flags of the enum.
+ * @GDK_PIXDATA_ENCODING_RAW: the pixel data is in raw form. 
+ * @GDK_PIXDATA_ENCODING_RLE: 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. 
+ * @GDK_PIXDATA_ENCODING_MASK: mask for the encoding flags of the enum.
+ *
+ * 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.  
+ **/
 typedef enum
 {
   /* colorspace + alpha */
@@ -43,6 +67,23 @@ typedef enum
   GDK_PIXDATA_ENCODING_MASK     = 0x0f << 24
 } GdkPixdataType;
 
+/**
+ * GdkPixdata:
+ * @magic: magic number. A valid #GdkPixdata structure must have 
+ *    #GDK_PIXBUF_MAGIC_NUMBER here.
+ * @length: less than 1 to disable length checks, otherwise 
+ *    #GDK_PIXDATA_HEADER_LENGTH + length of @pixel_data. 
+ * @pixdata_type: information about colorspace, sample width and 
+ *    encoding, in a #GdkPixdataType. 
+ * @rowstride: padding used in @pixel_data or 0 to indicate no padding.
+ * @width: the width.
+ * @height: the height.
+ * @pixel_data: @width x @height pixels, encoded according to @pixdata_type
+ *   and @rowstride.
+ *
+ * A #GdkPixdata contains pixbuf information in a form suitable for 
+ * serialization and streaming.
+ **/
 typedef struct _GdkPixdata GdkPixdata;
 struct _GdkPixdata
 {
@@ -56,6 +97,12 @@ struct _GdkPixdata
   guint32 height;
   guint8 *pixel_data;
 };
+
+/**
+ * GDK_PIXDATA_HEADER_LENGTH:
+ *
+ * The length of a #GdkPixdata structure without the @pixel_data pointer.
+ **/
 #define	GDK_PIXDATA_HEADER_LENGTH	(4 + 4 + 4 + 4 + 4 + 4)
 
 /* the returned stream is plain htonl of GdkPixdata members + pixel_data */
@@ -71,6 +118,34 @@ gpointer	gdk_pixdata_from_pixbuf	(GdkPixdata		*pixdata,
 GdkPixbuf*	gdk_pixbuf_from_pixdata	(const GdkPixdata	*pixdata,
 					 gboolean		 copy_pixels,
 					 GError		       **error);
+/** 
+ * GdkPixdataDumpType:
+ * @GDK_PIXDATA_DUMP_PIXDATA_STREAM: Generate pixbuf data stream (a single 
+ *    string containing a serialized #GdkPixdata structure in network byte 
+ *    order).
+ * @GDK_PIXDATA_DUMP_PIXDATA_STRUCT: Generate #GdkPixdata structure (needs 
+ *    the #GdkPixdata structure definition from gdk-pixdata.h).
+ * @GDK_PIXDATA_DUMP_MACROS: 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.
+ * @GDK_PIXDATA_DUMP_GTYPES: Generate GLib data types instead of 
+ *    standard C data types.
+ * @GDK_PIXDATA_DUMP_CTYPES: Generate standard C data types instead of 
+ *    GLib data types.
+ * @GDK_PIXDATA_DUMP_STATIC: Generate static symbols.
+ * @GDK_PIXDATA_DUMP_CONST: Generate const symbols.
+ * @GDK_PIXDATA_DUMP_RLE_DECODER: Provide a <function>*_RUN_LENGTH_DECODE(image_buf, rle_data, size, bpp)</function> 
+ *    macro definition  to  decode  run-length encoded image data.
+ *  
+ * 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. 
+ **/
 typedef enum
 {
   /* type of source to save */