<refentry id="gdk-pixbuf-creating">
<refmeta>
<refentrytitle>Image Data in Memory</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDK-PIXBUF Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Image Data in Memory</refname><refpurpose>Creating a pixbuf from image data that is already in memory.</refpurpose>
</refnamediv>

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

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


<link linkend="GdkPixbuf">GdkPixbuf</link>*  <link linkend="gdk-pixbuf-new">gdk_pixbuf_new</link>                  (<link linkend="GdkColorspace">GdkColorspace</link> colorspace,
                                             <link linkend="gboolean">gboolean</link> has_alpha,
                                             int bits_per_sample,
                                             int width,
                                             int height);
<link linkend="GdkPixbuf">GdkPixbuf</link>*  <link linkend="gdk-pixbuf-new-from-data">gdk_pixbuf_new_from_data</link>        (const <link linkend="guchar">guchar</link> *data,
                                             <link linkend="GdkColorspace">GdkColorspace</link> colorspace,
                                             <link linkend="gboolean">gboolean</link> has_alpha,
                                             int bits_per_sample,
                                             int width,
                                             int height,
                                             int rowstride,
                                             <link linkend="GdkPixbufDestroyNotify">GdkPixbufDestroyNotify</link> destroy_fn,
                                             <link linkend="gpointer">gpointer</link> destroy_fn_data);
<link linkend="GdkPixbuf">GdkPixbuf</link>*  <link linkend="gdk-pixbuf-new-from-xpm-data">gdk_pixbuf_new_from_xpm_data</link>    (const char **data);
<link linkend="GdkPixbuf">GdkPixbuf</link>*  <link linkend="gdk-pixbuf-new-from-inline">gdk_pixbuf_new_from_inline</link>      (<link linkend="gint">gint</link> data_length,
                                             const <link linkend="guint8">guint8</link> *data,
                                             <link linkend="gboolean">gboolean</link> copy_pixels,
                                             <link linkend="GError">GError</link> **error);
<link linkend="GdkPixbuf">GdkPixbuf</link>*  <link linkend="gdk-pixbuf-new-subpixbuf">gdk_pixbuf_new_subpixbuf</link>        (<link linkend="GdkPixbuf">GdkPixbuf</link> *src_pixbuf,
                                             int src_x,
                                             int src_y,
                                             int width,
                                             int height);
<link linkend="GdkPixbuf">GdkPixbuf</link>*  <link linkend="gdk-pixbuf-copy">gdk_pixbuf_copy</link>                 (const <link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
  <para>
    The most basic way to create a pixbuf is to wrap an existing pixel
    buffer with a <link linkend="GdkPixbuf">GdkPixbuf</link> structure.  You can use the
    <link linkend="gdk-pixbuf-new-from-data">gdk_pixbuf_new_from_data</link>() function to do this You need to specify
    the destroy notification function that will be called when the
    data buffer needs to be freed; this will happen when a <link linkend="GdkPixbuf">GdkPixbuf</link>
    is finalized by the reference counting functions If you have a
    chunk of static data compiled into your application, you can pass
    in <literal>NULL</literal> as the destroy notification function so that the data
    will not be freed.
  </para>

  <para>
    The <link linkend="gdk-pixbuf-new">gdk_pixbuf_new</link>() function can be used as a convenience to
    create a pixbuf with an empty buffer.  This is equivalent to
    allocating a data buffer using <function><link linkend="malloc">malloc</link>()</function> and 
    then wrapping it with <link linkend="gdk-pixbuf-new-from-data">gdk_pixbuf_new_from_data</link>().  The <link linkend="gdk-pixbuf-new">gdk_pixbuf_new</link>() 
    function will compute an optimal rowstride so that rendering can be 
    performed with an efficient algorithm.
  </para>

  <para>
    As a special case, you can use the <link linkend="gdk-pixbuf-new-from-xpm-data">gdk_pixbuf_new_from_xpm_data</link>()
    function to create a pixbuf from inline XPM image data.
  </para>

  <para>
    You can also copy an existing pixbuf with the <link linkend="gdk-pixbuf-copy">gdk_pixbuf_copy</link>()
    function.  This is not the same as just doing a <link linkend="g-object-ref">g_object_ref</link>()
    on the old pixbuf; the copy function will actually duplicate the
    pixel data in memory and create a new <link linkend="GdkPixbuf">GdkPixbuf</link> structure for it.
  </para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="gdk-pixbuf-new">gdk_pixbuf_new ()</title>
<programlisting><link linkend="GdkPixbuf">GdkPixbuf</link>*  gdk_pixbuf_new                  (<link linkend="GdkColorspace">GdkColorspace</link> colorspace,
                                             <link linkend="gboolean">gboolean</link> has_alpha,
                                             int bits_per_sample,
                                             int width,
                                             int height);</programlisting>
<para>
Creates a new <link linkend="GdkPixbuf">GdkPixbuf</link> structure and allocates a buffer for it.  The 
buffer has an optimal rowstride.  Note that the buffer is not cleared;
you will have to fill it completely yourself.</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>colorspace</parameter>&nbsp;:</entry>
<entry> Color space for image.
</entry></row>
<row><entry align="right"><parameter>has_alpha</parameter>&nbsp;:</entry>
<entry> Whether the image should have transparency information.
</entry></row>
<row><entry align="right"><parameter>bits_per_sample</parameter>&nbsp;:</entry>
<entry> Number of bits per color sample.
</entry></row>
<row><entry align="right"><parameter>width</parameter>&nbsp;:</entry>
<entry> Width of image in pixels.
</entry></row>
<row><entry align="right"><parameter>height</parameter>&nbsp;:</entry>
<entry> Height of image in pixels.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A newly-created <link linkend="GdkPixbuf">GdkPixbuf</link> with a reference count of 1, or 
<literal>NULL</literal> if not enough memory could be allocated for the image buffer.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-new-from-data">gdk_pixbuf_new_from_data ()</title>
<programlisting><link linkend="GdkPixbuf">GdkPixbuf</link>*  gdk_pixbuf_new_from_data        (const <link linkend="guchar">guchar</link> *data,
                                             <link linkend="GdkColorspace">GdkColorspace</link> colorspace,
                                             <link linkend="gboolean">gboolean</link> has_alpha,
                                             int bits_per_sample,
                                             int width,
                                             int height,
                                             int rowstride,
                                             <link linkend="GdkPixbufDestroyNotify">GdkPixbufDestroyNotify</link> destroy_fn,
                                             <link linkend="gpointer">gpointer</link> destroy_fn_data);</programlisting>
<para>
Creates a new <link linkend="GdkPixbuf">GdkPixbuf</link> out of in-memory image data.  Currently only RGB
images with 8 bits per sample are supported.</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>data</parameter>&nbsp;:</entry>
<entry> Image data in 8-bit/sample packed format.
</entry></row>
<row><entry align="right"><parameter>colorspace</parameter>&nbsp;:</entry>
<entry> Colorspace for the image data.
</entry></row>
<row><entry align="right"><parameter>has_alpha</parameter>&nbsp;:</entry>
<entry> Whether the data has an opacity channel.
</entry></row>
<row><entry align="right"><parameter>bits_per_sample</parameter>&nbsp;:</entry>
<entry> Number of bits per sample.
</entry></row>
<row><entry align="right"><parameter>width</parameter>&nbsp;:</entry>
<entry> Width of the image in pixels.
</entry></row>
<row><entry align="right"><parameter>height</parameter>&nbsp;:</entry>
<entry> Height of the image in pixels.
</entry></row>
<row><entry align="right"><parameter>rowstride</parameter>&nbsp;:</entry>
<entry> Distance in bytes between rows.
</entry></row>
<row><entry align="right"><parameter>destroy_fn</parameter>&nbsp;:</entry>
<entry> Function used to free the data when the pixbuf's reference count
drops to zero, or <literal>NULL</literal> if the data should not be freed.
</entry></row>
<row><entry align="right"><parameter>destroy_fn_data</parameter>&nbsp;:</entry>
<entry> Closure data to pass to the destroy notification function.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A newly-created <link linkend="GdkPixbuf">GdkPixbuf</link> structure with a reference count of
1.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-new-from-xpm-data">gdk_pixbuf_new_from_xpm_data ()</title>
<programlisting><link linkend="GdkPixbuf">GdkPixbuf</link>*  gdk_pixbuf_new_from_xpm_data    (const char **data);</programlisting>
<para>
Creates a new pixbuf by parsing XPM data in memory.  This data is commonly
the result of including an XPM file into a program's C source.</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>data</parameter>&nbsp;:</entry>
<entry> Pointer to inline XPM data.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A newly-created pixbuf with a reference count of 1.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-new-from-inline">gdk_pixbuf_new_from_inline ()</title>
<programlisting><link linkend="GdkPixbuf">GdkPixbuf</link>*  gdk_pixbuf_new_from_inline      (<link linkend="gint">gint</link> data_length,
                                             const <link linkend="guint8">guint8</link> *data,
                                             <link linkend="gboolean">gboolean</link> copy_pixels,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Create a <link linkend="GdkPixbuf">GdkPixbuf</link> from a flat representation that is suitable for
storing as inline data in a program. This is useful if you want to
ship a program with images, but don't want to depend on any
external files.
</para>
<para>
GTK+ ships with a program called <command>gdk-pixbuf-csource</command> 
which allows for conversion of <link linkend="GdkPixbufs">GdkPixbufs</link> into such a inline representation.
In almost all cases, you should pass the <option>--raw</option> flag to
<command>gdk-pixbuf-csource</command>. A sample invocation would be:
</para>
<para>
<informalexample><programlisting>
 gdk-pixbuf-csource --raw --name=myimage_inline myimage.png
</programlisting></informalexample>
</para>
<para>
For the typical case where the inline pixbuf is read-only static data,
you don't need to copy the pixel data unless you intend to write to
it, so you can pass <literal>FALSE</literal> for <parameter>copy_pixels</parameter>.  (If you pass 
<option>--rle</option> to <command>gdk-pixbuf-csource</command>, a copy 
will be made even if <parameter>copy_pixels</parameter> is <literal>FALSE</literal>, so using this option is 
generally a bad idea.)
</para>
<para>
If you create a pixbuf from const inline data compiled into your
program, it's probably safe to ignore errors, since things will
always succeed.  For non-const inline data, you could get out of
memory. For untrusted inline data located at runtime, you could
have corrupt inline data in addition.</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>data_length</parameter>&nbsp;:</entry>
<entry> Length in bytes of the <parameter>data</parameter> argument
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry> Byte data containing a serialized <link linkend="GdkPixdata">GdkPixdata</link> structure
</entry></row>
<row><entry align="right"><parameter>copy_pixels</parameter>&nbsp;:</entry>
<entry> Whether to copy the pixel data, or use direct pointers
              <parameter>data</parameter> for the resulting pixbuf
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> <link linkend="GError">GError</link> return location, may be <literal>NULL</literal> to ignore errors
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A newly-created <link linkend="GdkPixbuf">GdkPixbuf</link> structure with a reference,
  count of 1, or <literal>NULL</literal> if error is set.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-new-subpixbuf">gdk_pixbuf_new_subpixbuf ()</title>
<programlisting><link linkend="GdkPixbuf">GdkPixbuf</link>*  gdk_pixbuf_new_subpixbuf        (<link linkend="GdkPixbuf">GdkPixbuf</link> *src_pixbuf,
                                             int src_x,
                                             int src_y,
                                             int width,
                                             int height);</programlisting>
<para>
Creates a new pixbuf which represents a sub-region of
<parameter>src_pixbuf</parameter>. The new pixbuf shares its pixels with the
original pixbuf, so writing to one affects both.
The new pixbuf holds a reference to <parameter>src_pixbuf</parameter>, so
<parameter>src_pixbuf</parameter> will not be finalized until the new pixbuf
is finalized.</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>src_pixbuf</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkPixbuf">GdkPixbuf</link>
</entry></row>
<row><entry align="right"><parameter>src_x</parameter>&nbsp;:</entry>
<entry> X coord in <parameter>src_pixbuf</parameter>
</entry></row>
<row><entry align="right"><parameter>src_y</parameter>&nbsp;:</entry>
<entry> Y coord in <parameter>src_pixbuf</parameter>
</entry></row>
<row><entry align="right"><parameter>width</parameter>&nbsp;:</entry>
<entry> width of region in <parameter>src_pixbuf</parameter>
</entry></row>
<row><entry align="right"><parameter>height</parameter>&nbsp;:</entry>
<entry> height of region in <parameter>src_pixbuf</parameter>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a new pixbuf 
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-copy">gdk_pixbuf_copy ()</title>
<programlisting><link linkend="GdkPixbuf">GdkPixbuf</link>*  gdk_pixbuf_copy                 (const <link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf);</programlisting>
<para>
Creates a new <link linkend="GdkPixbuf">GdkPixbuf</link> with a copy of the information in the specified
<parameter>pixbuf</parameter>.</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>pixbuf</parameter>&nbsp;:</entry>
<entry> A pixbuf.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A newly-created pixbuf with a reference count of 1, or <literal>NULL</literal> if
not enough memory could be allocated.
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
  <para>
    <link linkend="gdk-pixbuf-finalize">gdk_pixbuf_finalize</link>().
  </para>
</refsect1>

</refentry>
