<refentry id="gdk-pixbuf-inline">
<refmeta>
<refentrytitle>Inline data</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDK-PIXBUF Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Inline data</refname><refpurpose>Functions for inlined pixbuf handling.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gdk-pixbuf/gdk-pixbuf.h&gt;


struct      <link linkend="GdkPixdata">GdkPixdata</link>;
enum        <link linkend="GdkPixdataType">GdkPixdataType</link>;
enum        <link linkend="GdkPixdataDumpType">GdkPixdataDumpType</link>;
#define     <link linkend="GDK-PIXBUF-MAGIC-NUMBER-CAPS">GDK_PIXBUF_MAGIC_NUMBER</link>
#define     <link linkend="GDK-PIXDATA-HEADER-LENGTH-CAPS">GDK_PIXDATA_HEADER_LENGTH</link>
<link linkend="gpointer">gpointer</link>    <link linkend="gdk-pixdata-from-pixbuf">gdk_pixdata_from_pixbuf</link>         (<link linkend="GdkPixdata">GdkPixdata</link> *pixdata,
                                             const <link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf,
                                             <link linkend="gboolean">gboolean</link> use_rle);
<link linkend="GdkPixbuf">GdkPixbuf</link>*  <link linkend="gdk-pixbuf-from-pixdata">gdk_pixbuf_from_pixdata</link>         (const <link linkend="GdkPixdata">GdkPixdata</link> *pixdata,
                                             <link linkend="gboolean">gboolean</link> copy_pixels,
                                             <link linkend="GError">GError</link> **error);
<link linkend="guint8">guint8</link>*     <link linkend="gdk-pixdata-serialize">gdk_pixdata_serialize</link>           (const <link linkend="GdkPixdata">GdkPixdata</link> *pixdata,
                                             <link linkend="guint">guint</link> *stream_length_p);
<link linkend="gboolean">gboolean</link>    <link linkend="gdk-pixdata-deserialize">gdk_pixdata_deserialize</link>         (<link linkend="GdkPixdata">GdkPixdata</link> *pixdata,
                                             <link linkend="guint">guint</link> stream_length,
                                             const <link linkend="guint8">guint8</link> *stream,
                                             <link linkend="GError">GError</link> **error);
<link linkend="GString">GString</link>*    <link linkend="gdk-pixdata-to-csource">gdk_pixdata_to_csource</link>          (<link linkend="GdkPixdata">GdkPixdata</link> *pixdata,
                                             const <link linkend="gchar">gchar</link> *name,
                                             <link linkend="GdkPixdataDumpType">GdkPixdataDumpType</link> dump_type);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
  <para>

  </para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GdkPixdata">struct GdkPixdata</title>
<programlisting>struct GdkPixdata
{
  guint32 magic;        /* GDK_PIXBUF_MAGIC_NUMBER */
  gint32  length;       /* &lt;1 to disable length checks, otherwise:
			 * GDK_PIXDATA_HEADER_LENGTH + pixel_data length
			 */
  guint32 pixdata_type; /* GdkPixdataType */
  guint32 rowstride;    /* maybe 0 to indicate non-padded data */
  guint32 width;
  guint32 height;
  guint8 *pixel_data;
};
</programlisting>
<para>
A <link linkend="GdkPixdata">GdkPixdata</link> contains pixbuf information in a form suitable for 
serialization and streaming.</para>
  <para>

  </para><informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><link linkend="guint32">guint32</link> <structfield>magic</structfield></entry>
<entry> magic number. A valid <link linkend="GdkPixdata">GdkPixdata</link> structure must have 
   <link linkend="GDK-PIXBUF-MAGIC-NUMBER-CAPS">GDK_PIXBUF_MAGIC_NUMBER</link> here.
</entry>
</row>
<row>
<entry><link linkend="gint32">gint32</link> <structfield>length</structfield></entry>
<entry> less than 1 to disable length checks, otherwise 
   <link linkend="GDK-PIXDATA-HEADER-LENGTH-CAPS">GDK_PIXDATA_HEADER_LENGTH</link> + length of <parameter>pixel_data</parameter>. 
</entry>
</row>
<row>
<entry><link linkend="guint32">guint32</link> <structfield>pixdata_type</structfield></entry>
<entry> information about colorspace, sample width and 
   encoding, in a <link linkend="GdkPixdataType">GdkPixdataType</link>. 
</entry>
</row>
<row>
<entry><link linkend="guint32">guint32</link> <structfield>rowstride</structfield></entry>
<entry> padding used in <parameter>pixel_data</parameter> or 0 to indicate no padding.
</entry>
</row>
<row>
<entry><link linkend="guint32">guint32</link> <structfield>width</structfield></entry>
<entry> the width.
</entry>
</row>
<row>
<entry><link linkend="guint32">guint32</link> <structfield>height</structfield></entry>
<entry> the height.
</entry>
</row>
<row>
<entry><link linkend="guint8">guint8</link> *<structfield>pixel_data</structfield></entry>
<entry> <parameter>width</parameter> x <parameter>height</parameter> pixels, encoded according to <parameter>pixdata_type</parameter>
  and <parameter>rowstride</parameter>.
</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GdkPixdataType">enum GdkPixdataType</title>
<programlisting>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 &lt;&lt; 16,
  GDK_PIXDATA_SAMPLE_WIDTH_MASK = 0x0f &lt;&lt; 16,
  /* encoding */
  GDK_PIXDATA_ENCODING_RAW      = 0x01 &lt;&lt; 24,
  GDK_PIXDATA_ENCODING_RLE      = 0x02 &lt;&lt; 24,
  GDK_PIXDATA_ENCODING_MASK     = 0x0f &lt;&lt; 24
} GdkPixdataType;
</programlisting>
<para>
An enumeration containing three sets of flags for a <link linkend="GdkPixdata">GdkPixdata</link> struct: 
one for the used colorspace, one for the width of the samples and one 
for the encoding of the pixel data.</para>
  <para>

  </para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>GDK_PIXDATA_COLOR_TYPE_RGB</literal></entry>
<entry>  each pixel has red, green and blue samples.
</entry>
</row>
<row>
<entry><literal>GDK_PIXDATA_COLOR_TYPE_RGBA</literal></entry>
<entry> each pixel has red, green and blue samples 
   and an alpha value.
</entry>
</row>
<row>
<entry><literal>GDK_PIXDATA_COLOR_TYPE_MASK</literal></entry>
<entry> mask for the colortype flags of the enum.
</entry>
</row>
<row>
<entry><literal>GDK_PIXDATA_SAMPLE_WIDTH_8</literal></entry>
<entry> each sample has 8 bits.
</entry>
</row>
<row>
<entry><literal>GDK_PIXDATA_SAMPLE_WIDTH_MASK</literal></entry>
<entry> mask for the sample width flags of the enum.
</entry>
</row>
<row>
<entry><literal>GDK_PIXDATA_ENCODING_RAW</literal></entry>
<entry> the pixel data is in raw form. 
</entry>
</row>
<row>
<entry><literal>GDK_PIXDATA_ENCODING_RLE</literal></entry>
<entry> 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. 
</entry>
</row>
<row>
<entry><literal>GDK_PIXDATA_ENCODING_MASK</literal></entry>
<entry> mask for the encoding flags of the enum.
</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GdkPixdataDumpType">enum GdkPixdataDumpType</title>
<programlisting>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 &lt;&lt; 8,
  GDK_PIXDATA_DUMP_STATIC		= 1 &lt;&lt; 9,
  GDK_PIXDATA_DUMP_CONST		= 1 &lt;&lt; 10,
  /* save RLE decoder macro? */
  GDK_PIXDATA_DUMP_RLE_DECODER		= 1 &lt;&lt; 16
} GdkPixdataDumpType;
</programlisting>
<para>
An enumeration which is used by <link linkend="gdk-pixdata-to-csource">gdk_pixdata_to_csource</link>() to
determine the form of C source to be generated. The three values
<parameter>GDK_PIXDATA_DUMP_PIXDATA_STREAM</parameter>, <parameter>GDK_PIXDATA_DUMP_PIXDATA_STRUCT</parameter>
and <parameter>GDK_PIXDATA_DUMP_MACROS</parameter> are mutually exclusive, as are
<parameter>GDK_PIXBUF_DUMP_GTYPES</parameter> and <parameter>GDK_PIXBUF_DUMP_CTYPES</parameter>. The remaining
elements are optional flags that can be freely added.</para>
  <para>

  </para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>GDK_PIXDATA_DUMP_PIXDATA_STREAM</literal></entry>
<entry> Generate pixbuf data stream (a single 
   string containing a serialized <link linkend="GdkPixdata">GdkPixdata</link> structure in network byte 
   order).
</entry>
</row>
<row>
<entry><literal>GDK_PIXDATA_DUMP_PIXDATA_STRUCT</literal></entry>
<entry> Generate <link linkend="GdkPixdata">GdkPixdata</link> structure (needs 
   the <link linkend="GdkPixdata">GdkPixdata</link> structure definition from gdk-pixdata.h).
</entry>
</row>
<row>
<entry><literal>GDK_PIXDATA_DUMP_MACROS</literal></entry>
<entry> 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.
</entry>
</row>
<row>
<entry><literal>GDK_PIXDATA_DUMP_GTYPES</literal></entry>
<entry> Generate GLib data types instead of 
   standard C data types.
</entry>
</row>
<row>
<entry><literal>GDK_PIXDATA_DUMP_CTYPES</literal></entry>
<entry> Generate standard C data types instead of 
   GLib data types.
</entry>
</row>
<row>
<entry><literal>GDK_PIXDATA_DUMP_STATIC</literal></entry>
<entry> Generate static symbols.
</entry>
</row>
<row>
<entry><literal>GDK_PIXDATA_DUMP_CONST</literal></entry>
<entry> Generate const symbols.
</entry>
</row>
<row>
<entry><literal>GDK_PIXDATA_DUMP_RLE_DECODER</literal></entry>
<entry> Provide a <function>*_RUN_LENGTH_DECODE(image_buf, rle_data, size, bpp)</function> 
   macro definition  to  decode  run-length encoded image data.
</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GDK-PIXBUF-MAGIC-NUMBER-CAPS">GDK_PIXBUF_MAGIC_NUMBER</title>
<programlisting>#define GDK_PIXBUF_MAGIC_NUMBER (0x47646b50)    /* 'GdkP' */
</programlisting>
<para>
Magic number for <link linkend="GdkPixdata">GdkPixdata</link> structures.</para>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="GDK-PIXDATA-HEADER-LENGTH-CAPS">GDK_PIXDATA_HEADER_LENGTH</title>
<programlisting>#define	GDK_PIXDATA_HEADER_LENGTH	(4 + 4 + 4 + 4 + 4 + 4)
</programlisting>
<para>
The length of a <link linkend="GdkPixdata">GdkPixdata</link> structure without the <parameter>pixel_data</parameter> pointer.</para>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="gdk-pixdata-from-pixbuf">gdk_pixdata_from_pixbuf ()</title>
<programlisting><link linkend="gpointer">gpointer</link>    gdk_pixdata_from_pixbuf         (<link linkend="GdkPixdata">GdkPixdata</link> *pixdata,
                                             const <link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf,
                                             <link linkend="gboolean">gboolean</link> use_rle);</programlisting>
<para>
Converts a <link linkend="GdkPixbuf">GdkPixbuf</link> to a <link linkend="GdkPixdata">GdkPixdata</link>. If <parameter>use_rle</parameter> is <literal>TRUE</literal>, the
pixel data is run-length encoded into newly-allocated memory and a 
pointer to that memory is returned.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pixdata</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkPixdata">GdkPixdata</link> to fill.
</entry></row>
<row><entry align="right"><parameter>pixbuf</parameter>&nbsp;:</entry>
<entry> the data to fill <parameter>pixdata</parameter> with.
</entry></row>
<row><entry align="right"><parameter>use_rle</parameter>&nbsp;:</entry>
<entry> whether to use run-length encoding for the pixel data.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> If <parameter>ure_rle</parameter> is <literal>TRUE</literal>, a pointer to the newly-allocated memory 
  for the run-length encoded pixel data, otherwise <literal>NULL</literal>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-from-pixdata">gdk_pixbuf_from_pixdata ()</title>
<programlisting><link linkend="GdkPixbuf">GdkPixbuf</link>*  gdk_pixbuf_from_pixdata         (const <link linkend="GdkPixdata">GdkPixdata</link> *pixdata,
                                             <link linkend="gboolean">gboolean</link> copy_pixels,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Converts a <link linkend="GdkPixdata">GdkPixdata</link> to a <link linkend="GdkPixbuf">GdkPixbuf</link>. If <parameter>copy_pixels</parameter> is <literal>TRUE</literal> or
if the pixel data is run-length-encoded, the pixel data is copied into
newly-allocated memory; otherwise it is reused.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pixdata</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkPixdata">GdkPixdata</link> to convert into a <link linkend="GdkPixbuf">GdkPixbuf</link>.
</entry></row>
<row><entry align="right"><parameter>copy_pixels</parameter>&nbsp;:</entry>
<entry> whether to copy raw pixel data; run-length encoded
    pixel data is always copied.
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> location to store possible errors.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a new <link linkend="GdkPixbuf">GdkPixbuf</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixdata-serialize">gdk_pixdata_serialize ()</title>
<programlisting><link linkend="guint8">guint8</link>*     gdk_pixdata_serialize           (const <link linkend="GdkPixdata">GdkPixdata</link> *pixdata,
                                             <link linkend="guint">guint</link> *stream_length_p);</programlisting>
<para>
Serializes a <link linkend="GdkPixdata">GdkPixdata</link> structure into a byte stream.
The byte stream consists of a straightforward writeout of the
<link linkend="GdkPixdata">GdkPixdata</link> fields in network byte order, plus the <parameter>pixel_data</parameter>
bytes the structure points to.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pixdata</parameter>&nbsp;:</entry>
<entry> a valid <link linkend="GdkPixdata">GdkPixdata</link> structure to serialize.
</entry></row>
<row><entry align="right"><parameter>stream_length_p</parameter>&nbsp;:</entry>
<entry> location to store the resulting stream length in.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A newly-allocated string containing the serialized
<link linkend="GdkPixdata">GdkPixdata</link> structure.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixdata-deserialize">gdk_pixdata_deserialize ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gdk_pixdata_deserialize         (<link linkend="GdkPixdata">GdkPixdata</link> *pixdata,
                                             <link linkend="guint">guint</link> stream_length,
                                             const <link linkend="guint8">guint8</link> *stream,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Deserializes (reconstruct) a <link linkend="GdkPixdata">GdkPixdata</link> structure from a byte stream.
The byte stream consists of a straightforward writeout of the
<link linkend="GdkPixdata">GdkPixdata</link> fields in network byte order, plus the <parameter>pixel_data</parameter>
bytes the structure points to.
The <parameter>pixdata</parameter> contents are reconstructed byte by byte and are checked
for validity. This function may fail with <literal>GDK_PIXBUF_CORRUPT_IMAGE</literal>
or <literal>GDK_PIXBUF_ERROR_UNKNOWN_TYPE</literal>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pixdata</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkPixdata">GdkPixdata</link> structure to be filled in.
</entry></row>
<row><entry align="right"><parameter>stream_length</parameter>&nbsp;:</entry>
<entry> length of the stream used for deserialization.
</entry></row>
<row><entry align="right"><parameter>stream</parameter>&nbsp;:</entry>
<entry> stream of bytes containing a serialized <link linkend="GdkPixdata">GdkPixdata</link> structure.
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> <link linkend="GError">GError</link> location to indicate failures (maybe <literal>NULL</literal> to ignore errors).
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> Upon successful deserialization <literal>TRUE</literal> is returned,
<literal>FALSE</literal> otherwise.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixdata-to-csource">gdk_pixdata_to_csource ()</title>
<programlisting><link linkend="GString">GString</link>*    gdk_pixdata_to_csource          (<link linkend="GdkPixdata">GdkPixdata</link> *pixdata,
                                             const <link linkend="gchar">gchar</link> *name,
                                             <link linkend="GdkPixdataDumpType">GdkPixdataDumpType</link> dump_type);</programlisting>
<para>
Generates C source code suitable for compiling images directly 
into programs. 
</para>
<para>
GTK+ ships with a program called <command>gdk-pixbuf-csource</command> 
which offers a cmdline interface to this functions.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pixdata</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkPixdata">GdkPixdata</link> to convert to C source.
</entry></row>
<row><entry align="right"><parameter>name</parameter>&nbsp;:</entry>
<entry> used for naming generated data structures or macros.
</entry></row>
<row><entry align="right"><parameter>dump_type</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkPixdataDumpType">GdkPixdataDumpType</link> determining the kind of C
  source to be generated.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a newly-allocated string containing the C source form
  of <parameter>pixdata</parameter>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>




</refentry>
