Commit 4fc79615 authored by Matthias Clasen's avatar Matthias Clasen

Documentation. Spelling fixes.

        * gdk-pixdata.c, gdk-pixdata.h: Documentation.
        * gdk-pixbuf-csource.1: Spelling fixes.
parent 1ebe3b51
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> Wed Oct 10 11:52:17 2001 Owen Taylor <otaylor@redhat.com>
* gdk-pixdata.c gdk-pixbuf.h: Get rid of * gdk-pixdata.c gdk-pixbuf.h: Get rid of
......
...@@ -9,7 +9,7 @@ gdk-pixbuf-csource \- C code generation utility for GdkPixbuf images ...@@ -9,7 +9,7 @@ gdk-pixbuf-csource \- C code generation utility for GdkPixbuf images
.SH DESCRIPTION .SH DESCRIPTION
\fBgdk-pixbuf-csource\fP is a small utility that generates C code containing \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 .SH INVOCATION
...@@ -35,11 +35,11 @@ Generate *_ROWSTRIDE, *_WIDTH, *_HEIGHT, *_BYTES_PER_PIXEL and ...@@ -35,11 +35,11 @@ Generate *_ROWSTRIDE, *_WIDTH, *_HEIGHT, *_BYTES_PER_PIXEL and
.TP .TP
\fI--rle \fI--rle
Enables run length encoding for the generated pixel data (default). Enables run-length encoding for the generated pixel data (default).
.TP .TP
\fI--raw \fI--raw
Disables run length encoding for the generated pixel data (default). Disables run-length encoding for the generated pixel data.
.TP .TP
\fI--extern \fI--extern
...@@ -56,8 +56,8 @@ to decode run-length encoded image data. ...@@ -56,8 +56,8 @@ to decode run-length encoded image data.
.TP .TP
\fI--name=identifier \fI--name=identifier
Specifies the identifier name (prefix) for the generated variable or Specifies the identifier name (prefix) for the generated variables or
macros (usefull only if \fI--build-list\fP was not specified). macros (useful only if \fI--build-list\fP was not specified).
.TP .TP
\fI--build-list \fI--build-list
......
...@@ -80,16 +80,16 @@ pixdata_get_length (const GdkPixdata *pixdata) ...@@ -80,16 +80,16 @@ pixdata_get_length (const GdkPixdata *pixdata)
/** /**
* gdk_pixdata_serialize: * gdk_pixdata_serialize:
* @pixdata: A valid GdkPixdata structure to serialize * @pixdata: a valid #GdkPixdata structure to serialize.
* @stream_length_p: Location to store the resulting stream length in * @stream_length_p: location to store the resulting stream length in.
* *
* Serialize a #GdkPixdata structure into a byte stream. * Serializes a #GdkPixdata structure into a byte stream.
* The byte stream consists of a straight forward write out of the * The byte stream consists of a straightforward writeout of the
* #GdkPixdata fields in network byte order, plus the pixel_data * #GdkPixdata fields in network byte order, plus the @pixel_data
* bytes the structure points to. * bytes the structure points to.
* *
* Return value: A newly-allocated string containing the serialized * Return value: A newly-allocated string containing the serialized
* GdkPixdata structure * #GdkPixdata structure.
**/ **/
guint8* /* free result */ guint8* /* free result */
gdk_pixdata_serialize (const GdkPixdata *pixdata, gdk_pixdata_serialize (const GdkPixdata *pixdata,
...@@ -159,21 +159,21 @@ gdk_pixdata_serialize (const GdkPixdata *pixdata, ...@@ -159,21 +159,21 @@ gdk_pixdata_serialize (const GdkPixdata *pixdata,
/** /**
* gdk_pixdata_deserialize: * gdk_pixdata_deserialize:
* @pixdata: A GdkPixdata structure to be filled in * @pixdata: a #GdkPixdata structure to be filled in.
* @stream_length: Length of the stream used for deserialization * @stream_length: length of the stream used for deserialization.
* @stream: Stream of bytes containing a serialized pixdata structure * @stream: stream of bytes containing a serialized #GdkPixdata structure.
* @error: GError location to indicate failures (maybe NULL to ignore errors) * @error: #GError location to indicate failures (maybe %NULL to ignore errors).
* *
* Deserialize (reconstruct) a #GdkPixdata structure from a byte stream. * Deserializes (reconstruct) a #GdkPixdata structure from a byte stream.
* The byte stream consists of a straight forward write out of the * The byte stream consists of a straightforward writeout of the
* #GdkPixdata fields in network byte order, plus the pixel_data * #GdkPixdata fields in network byte order, plus the @pixel_data
* bytes the structure points to. * 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 * 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, * Return value: Upon successful deserialization %TRUE is returned,
* %FALSE otherwise * %FALSE otherwise.
**/ **/
gboolean gboolean
gdk_pixdata_deserialize (GdkPixdata *pixdata, gdk_pixdata_deserialize (GdkPixdata *pixdata,
...@@ -290,6 +290,19 @@ rl_encode_rgbx (guint8 *bp, /* dest buffer */ ...@@ -290,6 +290,19 @@ rl_encode_rgbx (guint8 *bp, /* dest buffer */
return bp; 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 gpointer
gdk_pixdata_from_pixbuf (GdkPixdata *pixdata, gdk_pixdata_from_pixbuf (GdkPixdata *pixdata,
const GdkPixbuf *pixbuf, const GdkPixbuf *pixbuf,
...@@ -345,6 +358,19 @@ gdk_pixdata_from_pixbuf (GdkPixdata *pixdata, ...@@ -345,6 +358,19 @@ gdk_pixdata_from_pixbuf (GdkPixdata *pixdata,
return free_me; 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* GdkPixbuf*
gdk_pixbuf_from_pixdata (const GdkPixdata *pixdata, gdk_pixbuf_from_pixdata (const GdkPixdata *pixdata,
gboolean copy_pixels, gboolean copy_pixels,
...@@ -543,6 +569,22 @@ save_rle_decoder (GString *gstring, ...@@ -543,6 +569,22 @@ save_rle_decoder (GString *gstring,
APPEND (gstring, " } } while (0)\n"); 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* GString*
gdk_pixdata_to_csource (GdkPixdata *pixdata, gdk_pixdata_to_csource (GdkPixdata *pixdata,
const gchar *name, const gchar *name,
...@@ -790,8 +832,8 @@ gdk_pixdata_to_csource (GdkPixdata *pixdata, ...@@ -790,8 +832,8 @@ gdk_pixdata_to_csource (GdkPixdata *pixdata,
* ship a program with images, but don't want to depend on any * ship a program with images, but don't want to depend on any
* external files. * external files.
* *
* Gtk+ ships with a program called gdk-pixbuf-csource which allowes * Gtk+ ships with a program called gdk-pixbuf-csource which allows
* for conversion of #GdkPixbufs into such a inline reprentation. * for conversion of #GdkPixbufs into such a inline representation.
* In almost all cases, you should pass the --raw flag to * In almost all cases, you should pass the --raw flag to
* gdk-pixbuf-csource. A sample invocation would be: * gdk-pixbuf-csource. A sample invocation would be:
* *
......
...@@ -25,9 +25,33 @@ ...@@ -25,9 +25,33 @@
extern "C" { extern "C" {
#endif /* __cplusplus */ #endif /* __cplusplus */
/**
* GDK_PIXBUF_MAGIC_NUMBER:
*
* Magic number for #GdkPixdata structures.
**/
#define GDK_PIXBUF_MAGIC_NUMBER (0x47646b50) /* 'GdkP' */ #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 typedef enum
{ {
/* colorspace + alpha */ /* colorspace + alpha */
...@@ -43,6 +67,23 @@ typedef enum ...@@ -43,6 +67,23 @@ typedef enum
GDK_PIXDATA_ENCODING_MASK = 0x0f << 24 GDK_PIXDATA_ENCODING_MASK = 0x0f << 24
} GdkPixdataType; } 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; typedef struct _GdkPixdata GdkPixdata;
struct _GdkPixdata struct _GdkPixdata
{ {
...@@ -56,6 +97,12 @@ struct _GdkPixdata ...@@ -56,6 +97,12 @@ struct _GdkPixdata
guint32 height; guint32 height;
guint8 *pixel_data; 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) #define GDK_PIXDATA_HEADER_LENGTH (4 + 4 + 4 + 4 + 4 + 4)
/* the returned stream is plain htonl of GdkPixdata members + pixel_data */ /* the returned stream is plain htonl of GdkPixdata members + pixel_data */
...@@ -71,6 +118,34 @@ gpointer gdk_pixdata_from_pixbuf (GdkPixdata *pixdata, ...@@ -71,6 +118,34 @@ gpointer gdk_pixdata_from_pixbuf (GdkPixdata *pixdata,
GdkPixbuf* gdk_pixbuf_from_pixdata (const GdkPixdata *pixdata, GdkPixbuf* gdk_pixbuf_from_pixdata (const GdkPixdata *pixdata,
gboolean copy_pixels, gboolean copy_pixels,
GError **error); 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 typedef enum
{ {
/* type of source to save */ /* type of source to save */
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment