Inline data

Inline data — Functions for inlined pixbuf handling.

Synopsis


#include <gdk-pixbuf/gdk-pixdata.h>

                    GdkPixdata;
enum                GdkPixdataType;
enum                GdkPixdataDumpType;
#define             GDK_PIXBUF_MAGIC_NUMBER
#define             GDK_PIXDATA_HEADER_LENGTH
gpointer            gdk_pixdata_from_pixbuf             (GdkPixdata *pixdata,
                                                         const GdkPixbuf *pixbuf,
                                                         gboolean use_rle);
GdkPixbuf*          gdk_pixbuf_from_pixdata             (const GdkPixdata *pixdata,
                                                         gboolean copy_pixels,
                                                         GError **error);
guint8*             gdk_pixdata_serialize               (const GdkPixdata *pixdata,
                                                         guint *stream_length_p);
gboolean            gdk_pixdata_deserialize             (GdkPixdata *pixdata,
                                                         guint stream_length,
                                                         const guint8 *stream,
                                                         GError **error);
GString*            gdk_pixdata_to_csource              (GdkPixdata *pixdata,
                                                         const gchar *name,
                                                         GdkPixdataDumpType dump_type);

Description

Using GdkPixdata, images can be compiled into an application, making it unnecessary to refer to external image files at runtime. gdk-pixbuf includes a utility named gdk-pixbuf-csource, which can be used to convert image files into GdkPixdata structures suitable for inclusion in C sources. To convert the GdkPixdata structures back into GdkPixbufs, use gdk_pixbuf_from_pixdata.

Details

GdkPixdata

typedef struct {
  guint32 magic;        /* GDK_PIXBUF_MAGIC_NUMBER */
  gint32  length;       /* <1 to disable length checks, otherwise:
			 * GDK_PIXDATA_HEADER_LENGTH + pixel_data length
			 */
  guint32 pixdata_type; /* GdkPixdataType */
  guint32 rowstride;
  guint32 width;
  guint32 height;
  guint8 *pixel_data;
} GdkPixdata;

A GdkPixdata contains pixbuf information in a form suitable for serialization and streaming.

guint32 `magic`;	magic number. A valid GdkPixdata structure must have GDK_PIXBUF_MAGIC_NUMBER here.
gint32 `length`;	less than 1 to disable length checks, otherwise GDK_PIXDATA_HEADER_LENGTH + length of `pixel_data`.
guint32 `pixdata_type`;	information about colorspace, sample width and encoding, in a GdkPixdataType.
guint32 `rowstride`;	Distance in bytes between rows.
guint32 `width`;	Width of the image in pixels.
guint32 `height`;	Height of the image in pixels.
guint8 *`pixel_data`;	`width` x `height` pixels, encoded according to `pixdata_type` and `rowstride`.

enum GdkPixdataType

typedef enum
{
  /* colorspace + alpha */
  GDK_PIXDATA_COLOR_TYPE_RGB    = 0x01,
  GDK_PIXDATA_COLOR_TYPE_RGBA   = 0x02,
  GDK_PIXDATA_COLOR_TYPE_MASK   = 0xff,
  /* width, support 8bits only currently */
  GDK_PIXDATA_SAMPLE_WIDTH_8    = 0x01 << 16,
  GDK_PIXDATA_SAMPLE_WIDTH_MASK = 0x0f << 16,
  /* encoding */
  GDK_PIXDATA_ENCODING_RAW      = 0x01 << 24,
  GDK_PIXDATA_ENCODING_RLE      = 0x02 << 24,
  GDK_PIXDATA_ENCODING_MASK     = 0x0f << 24
} GdkPixdataType;

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.

`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.

enum GdkPixdataDumpType

typedef enum
{
  /* type of source to save */
  GDK_PIXDATA_DUMP_PIXDATA_STREAM	= 0,
  GDK_PIXDATA_DUMP_PIXDATA_STRUCT	= 1,
  GDK_PIXDATA_DUMP_MACROS		= 2,
  /* type of variables to use */
  GDK_PIXDATA_DUMP_GTYPES		= 0,
  GDK_PIXDATA_DUMP_CTYPES		= 1 << 8,
  GDK_PIXDATA_DUMP_STATIC		= 1 << 9,
  GDK_PIXDATA_DUMP_CONST		= 1 << 10,
  /* save RLE decoder macro? */
  GDK_PIXDATA_DUMP_RLE_DECODER		= 1 << 16
} GdkPixdataDumpType;

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.

`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 `_ROWSTRIDE`, `_WIDTH`, `_HEIGHT`, `_BYTES_PER_PIXEL` and `_RLE_PIXEL_DATA` or `_PIXEL_DATA` 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 `*_RUN_LENGTH_DECODE(image_buf, rle_data, size, bpp)` macro definition to decode run-length encoded image data.

GDK_PIXBUF_MAGIC_NUMBER

#define GDK_PIXBUF_MAGIC_NUMBER (0x47646b50)    /* 'GdkP' */

Magic number for GdkPixdata structures.

GDK_PIXDATA_HEADER_LENGTH

#define	GDK_PIXDATA_HEADER_LENGTH	(4 + 4 + 4 + 4 + 4 + 4)

The length of a GdkPixdata structure without the pixel_data pointer.

gdk_pixdata_from_pixbuf ()

gpointer            gdk_pixdata_from_pixbuf             (GdkPixdata *pixdata,
                                                         const GdkPixbuf *pixbuf,
                                                         gboolean use_rle);

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.

`pixdata` :	a GdkPixdata to fill.
`pixbuf` :	the data to fill `pixdata` with.
`use_rle` :	whether to use run-length encoding for the pixel data.
Returns :	If `ure_rle` is `TRUE`, a pointer to the newly-allocated memory for the run-length encoded pixel data, otherwise `NULL`.

gdk_pixbuf_from_pixdata ()

GdkPixbuf*          gdk_pixbuf_from_pixdata             (const GdkPixdata *pixdata,
                                                         gboolean copy_pixels,
                                                         GError **error);

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.

`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.
Returns :	a new GdkPixbuf.

gdk_pixdata_serialize ()

guint8*             gdk_pixdata_serialize               (const GdkPixdata *pixdata,
                                                         guint *stream_length_p);

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.

`pixdata` :	a valid GdkPixdata structure to serialize.
`stream_length_p` :	location to store the resulting stream length in.
Returns :	A newly-allocated string containing the serialized GdkPixdata structure.

gdk_pixdata_deserialize ()

gboolean            gdk_pixdata_deserialize             (GdkPixdata *pixdata,
                                                         guint stream_length,
                                                         const guint8 *stream,
                                                         GError **error);

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 for validity. This function may fail with GDK_PIXBUF_CORRUPT_IMAGE or GDK_PIXBUF_ERROR_UNKNOWN_TYPE.

`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).
Returns :	Upon successful deserialization `TRUE` is returned, `FALSE` otherwise.

gdk_pixdata_to_csource ()

GString*            gdk_pixdata_to_csource              (GdkPixdata *pixdata,
                                                         const gchar *name,
                                                         GdkPixdataDumpType dump_type);

Generates C source code suitable for compiling images directly into programs.

GTK+ ships with a program called gdk-pixbuf-csource which offers a command line interface to this function.

`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.
Returns :	a newly-allocated string containing the C source form of `pixdata`.