Inline data

## Inline data Inline data — Functions for inlined pixbuf handling. |

## Synopsis

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

    struct              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

### struct GdkPixdata

    struct GdkPixdata {
      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;
    };

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`. [array][element-type guint8]

### 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. [transfer full]

### 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. [array length=stream_length_p][transfer full]

### 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. [array length=stream_length]
`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.

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