Commit b0145a64 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 deac4df6
......@@ -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
......
......@@ -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:
*
......
......@@ -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 */
......
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