Inline data: GDK-PixBuf Reference Manual

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

## Functions

gpointer | gdk_pixdata_from_pixbuf ()
GdkPixbuf * | gdk_pixbuf_from_pixdata ()
guint8 * | gdk_pixdata_serialize ()
gboolean | gdk_pixdata_deserialize ()
GString * | gdk_pixdata_to_csource ()

## Types and Values

struct | GdkPixdata
enum | GdkPixdataType
enum | GdkPixdataDumpType
#define | GDK_PIXBUF_MAGIC_NUMBER
#define | GDK_PIXDATA_HEADER_LENGTH

## Includes

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

## Description

Using GdkPixdata, images can be compiled into an application, making it unnecessary to refer to external image files at runtime. GdkPixBuf 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.

GdkPixdata should not be used any more. GResource should be used to save the original compressed images inside the program's binary.

## Functions

### gdk_pixdata_from_pixbuf ()

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

`gdk_pixdata_from_pixbuf` has been deprecated since version 2.32 and should not be used in newly-written code.

Use GResource instead.

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.

[skip]

#### Parameters

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 `use_rle` is `TRUE`, a pointer to the newly-allocated memory for the run-length encoded pixel data, otherwise `NULL`.

[nullable]

### gdk_pixbuf_from_pixdata ()

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

`gdk_pixbuf_from_pixdata` has been deprecated since version 2.32 and should not be used in newly-written code.

Use GResource instead.

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.

#### Parameters

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);

`gdk_pixdata_serialize` has been deprecated since version 2.32 and should not be used in newly-written code.

Use GResource instead.

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.

#### Parameters

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);

`gdk_pixdata_deserialize` has been deprecated since version 2.32 and should not be used in newly-written code.

Use GResource instead.

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_ERROR_CORRUPT_IMAGE` or `GDK_PIXBUF_ERROR_UNKNOWN_TYPE`.

#### Parameters

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);

`gdk_pixdata_to_csource` has been deprecated since version 2.32 and should not be used in newly-written code.

Use GResource instead.

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.

#### Parameters

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

## Types and Values

### 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;
    };

`GdkPixdata` is deprecated and should not be used in newly-written code.

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

#### Members

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

`GdkPixdataType` is deprecated and should not be used in newly-written code.

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.

#### Members

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

`GdkPixdataDumpType` is deprecated and should not be used in newly-written code.

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.

#### Members

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

### GDK_PIXBUF_MAGIC_NUMBER

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

`GDK_PIXBUF_MAGIC_NUMBER` is deprecated and should not be used in newly-written code.

Magic number for GdkPixdata structures.

### GDK_PIXDATA_HEADER_LENGTH

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

`GDK_PIXDATA_HEADER_LENGTH` is deprecated and should not be used in newly-written code.

The length of a GdkPixdata structure without the `pixel_data` pointer.