Inline data
3
GDK-PIXBUF Library

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