File: //usr/share/gtk-doc/html/gdk-pixbuf/gdk-pixbuf-creating.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Image Data in Memory</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
<link rel="start" href="index.html" title="The gdk-pixbuf Library">
<link rel="up" href="rn01.html" title="API Reference">
<link rel="prev" href="gdk-pixbuf-file-saving.html" title="File saving">
<link rel="next" href="gdk-pixbuf-inline.html" title="Inline data">
<meta name="generator" content="GTK-Doc V1.6 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="reference" href="rn01.html" title="API Reference">
<link rel="reference" href="rn02.html" title="Tools Reference">
<link rel="index" href="ix01.html" title="Index">
<link rel="index" href="ix02.html" title="Index of deprecated symbols">
<link rel="index" href="ix03.html" title="Index of new symbols in 2.2">
<link rel="index" href="ix04.html" title="Index of new symbols in 2.4">
<link rel="index" href="ix05.html" title="Index of new symbols in 2.6">
<link rel="index" href="ix06.html" title="Index of new symbols in 2.8">
<link rel="appendix" href="apa.html" title="Appendix A. Porting applications from Imlib to gdk-pixbuf">
<link rel="appendix" href="license.html" title="Appendix B. License">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
<tr valign="middle">
<td><a accesskey="p" href="gdk-pixbuf-file-saving.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="rn01.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">The <span class="application">gdk-pixbuf</span> Library</th>
<td><a accesskey="n" href="gdk-pixbuf-inline.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts"><nobr><a href="#id3103049" class="shortcut">Top</a>
 | 
<a href="#id3103338" class="shortcut">Description</a></nobr></td></tr>
</table>
<div class="refentry" lang="en">
<a name="gdk-pixbuf-creating"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2>
<a name="id3103049"></a><span class="refentrytitle">Image Data in Memory</span>
</h2>
<p>Image Data in Memory — Creating a pixbuf from image data that is already in memory.</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<pre class="synopsis">
#include <gdk-pixbuf/gdk-pixbuf.h>
<a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf">GdkPixbuf</a>* <a href="gdk-pixbuf-creating.html#gdk-pixbuf-new">gdk_pixbuf_new</a> (<a href="gdk-pixbuf-gdk-pixbuf.html#GdkColorspace">GdkColorspace</a> colorspace,
<a
href="../glib/glib-Basic-Types.html#gboolean"
>gboolean</a> has_alpha,
int bits_per_sample,
int width,
int height);
<a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf">GdkPixbuf</a>* <a href="gdk-pixbuf-creating.html#gdk-pixbuf-new-from-data">gdk_pixbuf_new_from_data</a> (const <a
href="../glib/glib-Basic-Types.html#guchar"
>guchar</a> *data,
<a href="gdk-pixbuf-gdk-pixbuf.html#GdkColorspace">GdkColorspace</a> colorspace,
<a
href="../glib/glib-Basic-Types.html#gboolean"
>gboolean</a> has_alpha,
int bits_per_sample,
int width,
int height,
int rowstride,
<a href="gdk-pixbuf-refcounting.html#GdkPixbufDestroyNotify">GdkPixbufDestroyNotify</a> destroy_fn,
<a
href="../glib/glib-Basic-Types.html#gpointer"
>gpointer</a> destroy_fn_data);
<a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf">GdkPixbuf</a>* <a href="gdk-pixbuf-creating.html#gdk-pixbuf-new-from-xpm-data">gdk_pixbuf_new_from_xpm_data</a> (const char **data);
<a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf">GdkPixbuf</a>* <a href="gdk-pixbuf-creating.html#gdk-pixbuf-new-from-inline">gdk_pixbuf_new_from_inline</a> (<a
href="../glib/glib-Basic-Types.html#gint"
>gint</a> data_length,
const <a
href="../glib/glib-Basic-Types.html#guint8"
>guint8</a> *data,
<a
href="../glib/glib-Basic-Types.html#gboolean"
>gboolean</a> copy_pixels,
<a
href="../glib/glib-Error-Reporting.html#GError"
>GError</a> **error);
<a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf">GdkPixbuf</a>* <a href="gdk-pixbuf-creating.html#gdk-pixbuf-new-subpixbuf">gdk_pixbuf_new_subpixbuf</a> (<a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf">GdkPixbuf</a> *src_pixbuf,
int src_x,
int src_y,
int width,
int height);
<a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf">GdkPixbuf</a>* <a href="gdk-pixbuf-creating.html#gdk-pixbuf-copy">gdk_pixbuf_copy</a> (const <a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf">GdkPixbuf</a> *pixbuf);
</pre>
</div>
<div class="refsect1" lang="en">
<a name="id3103338"></a><h2>Description</h2>
<p>
The most basic way to create a pixbuf is to wrap an existing pixel
buffer with a <a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a> structure. You can use the
<a href="gdk-pixbuf-creating.html#gdk-pixbuf-new-from-data"><code class="function">gdk_pixbuf_new_from_data()</code></a> 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 <a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a>
is finalized by the reference counting functions If you have a
chunk of static data compiled into your application, you can pass
in <a
href="../glib/glib-Standard-Macros.html#NULL:CAPS"
><code class="literal">NULL</code></a> as the destroy notification function so that the data
will not be freed.
</p>
<p>
The <a href="gdk-pixbuf-creating.html#gdk-pixbuf-new"><code class="function">gdk_pixbuf_new()</code></a> function can be used as a convenience to
create a pixbuf with an empty buffer. This is equivalent to
allocating a data buffer using <code class="function"><code class="function">malloc()</code></code> and
then wrapping it with <a href="gdk-pixbuf-creating.html#gdk-pixbuf-new-from-data"><code class="function">gdk_pixbuf_new_from_data()</code></a>. The <a href="gdk-pixbuf-creating.html#gdk-pixbuf-new"><code class="function">gdk_pixbuf_new()</code></a>
function will compute an optimal rowstride so that rendering can be
performed with an efficient algorithm.
</p>
<p>
As a special case, you can use the <a href="gdk-pixbuf-creating.html#gdk-pixbuf-new-from-xpm-data"><code class="function">gdk_pixbuf_new_from_xpm_data()</code></a>
function to create a pixbuf from inline XPM image data.
</p>
<p>
You can also copy an existing pixbuf with the <a href="gdk-pixbuf-creating.html#gdk-pixbuf-copy"><code class="function">gdk_pixbuf_copy()</code></a>
function. This is not the same as just doing a <a
href="../gobject/gobject-The-Base-Object-Type.html#g-object-ref"
><code class="function">g_object_ref()</code></a>
on the old pixbuf; the copy function will actually duplicate the
pixel data in memory and create a new <a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a> structure for it.
</p>
</div>
<div class="refsect1" lang="en">
<a name="id3103505"></a><h2>Details</h2>
<div class="refsect2" lang="en">
<a name="id3103516"></a><h3>
<a name="gdk-pixbuf-new"></a>gdk_pixbuf_new ()</h3>
<a class="indexterm" name="id3103528"></a><pre class="programlisting"><a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf">GdkPixbuf</a>* gdk_pixbuf_new (<a href="gdk-pixbuf-gdk-pixbuf.html#GdkColorspace">GdkColorspace</a> colorspace,
<a
href="../glib/glib-Basic-Types.html#gboolean"
>gboolean</a> has_alpha,
int bits_per_sample,
int width,
int height);</pre>
<p>
Creates a new <a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a> 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.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>colorspace</code></em> :</span></td>
<td> Color space for image.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>has_alpha</code></em> :</span></td>
<td> Whether the image should have transparency information.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>bits_per_sample</code></em> :</span></td>
<td> Number of bits per color sample.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>width</code></em> :</span></td>
<td> Width of image in pixels.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>height</code></em> :</span></td>
<td> Height of image in pixels.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td> A newly-created <a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a> with a reference count of 1, or
<a
href="../glib/glib-Standard-Macros.html#NULL:CAPS"
><code class="literal">NULL</code></a> if not enough memory could be allocated for the image buffer.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3103706"></a><h3>
<a name="gdk-pixbuf-new-from-data"></a>gdk_pixbuf_new_from_data ()</h3>
<a class="indexterm" name="id3103718"></a><pre class="programlisting"><a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf">GdkPixbuf</a>* gdk_pixbuf_new_from_data (const <a
href="../glib/glib-Basic-Types.html#guchar"
>guchar</a> *data,
<a href="gdk-pixbuf-gdk-pixbuf.html#GdkColorspace">GdkColorspace</a> colorspace,
<a
href="../glib/glib-Basic-Types.html#gboolean"
>gboolean</a> has_alpha,
int bits_per_sample,
int width,
int height,
int rowstride,
<a href="gdk-pixbuf-refcounting.html#GdkPixbufDestroyNotify">GdkPixbufDestroyNotify</a> destroy_fn,
<a
href="../glib/glib-Basic-Types.html#gpointer"
>gpointer</a> destroy_fn_data);</pre>
<p>
Creates a new <a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a> out of in-memory image data. Currently only RGB
images with 8 bits per sample are supported.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>data</code></em> :</span></td>
<td> Image data in 8-bit/sample packed format.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>colorspace</code></em> :</span></td>
<td> Colorspace for the image data.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>has_alpha</code></em> :</span></td>
<td> Whether the data has an opacity channel.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>bits_per_sample</code></em> :</span></td>
<td> Number of bits per sample.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>width</code></em> :</span></td>
<td> Width of the image in pixels.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>height</code></em> :</span></td>
<td> Height of the image in pixels.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>rowstride</code></em> :</span></td>
<td> Distance in bytes between row starts.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>destroy_fn</code></em> :</span></td>
<td> Function used to free the data when the pixbuf's reference count
drops to zero, or <a
href="../glib/glib-Standard-Macros.html#NULL:CAPS"
><code class="literal">NULL</code></a> if the data should not be freed.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>destroy_fn_data</code></em> :</span></td>
<td> Closure data to pass to the destroy notification function.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td> A newly-created <a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a> structure with a reference count of 1.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3103984"></a><h3>
<a name="gdk-pixbuf-new-from-xpm-data"></a>gdk_pixbuf_new_from_xpm_data ()</h3>
<a class="indexterm" name="id3103998"></a><pre class="programlisting"><a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf">GdkPixbuf</a>* gdk_pixbuf_new_from_xpm_data (const char **data);</pre>
<p>
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.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>data</code></em> :</span></td>
<td> Pointer to inline XPM data.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td> A newly-created pixbuf with a reference count of 1.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3104061"></a><h3>
<a name="gdk-pixbuf-new-from-inline"></a>gdk_pixbuf_new_from_inline ()</h3>
<a class="indexterm" name="id3104075"></a><pre class="programlisting"><a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf">GdkPixbuf</a>* gdk_pixbuf_new_from_inline (<a
href="../glib/glib-Basic-Types.html#gint"
>gint</a> data_length,
const <a
href="../glib/glib-Basic-Types.html#guint8"
>guint8</a> *data,
<a
href="../glib/glib-Basic-Types.html#gboolean"
>gboolean</a> copy_pixels,
<a
href="../glib/glib-Error-Reporting.html#GError"
>GError</a> **error);</pre>
<p>
Create a <a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a> 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.
</p>
<p>
GTK+ ships with a program called <span><strong class="command">gdk-pixbuf-csource</strong></span>
which allows for conversion of <span class="type">GdkPixbufs</span> into such a inline representation.
In almost all cases, you should pass the <code class="option">--raw</code> flag to
<span><strong class="command">gdk-pixbuf-csource</strong></span>. A sample invocation would be:
</p>
<p>
</p>
<div class="informalexample"><pre class="programlisting">
gdk-pixbuf-csource --raw --name=myimage_inline myimage.png
</pre></div>
<p>
</p>
<p>
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 <a
href="../glib/glib-Standard-Macros.html#FALSE:CAPS"
><code class="literal">FALSE</code></a> for <em class="parameter"><code>copy_pixels</code></em>. (If you pass
<code class="option">--rle</code> to <span><strong class="command">gdk-pixbuf-csource</strong></span>, a copy
will be made even if <em class="parameter"><code>copy_pixels</code></em> is <a
href="../glib/glib-Standard-Macros.html#FALSE:CAPS"
><code class="literal">FALSE</code></a>, so using this option is
generally a bad idea.)
</p>
<p>
If you create a pixbuf from const inline data compiled into your
program, it's probably safe to ignore errors and disable length checks,
since things will always succeed:
</p>
<div class="informalexample"><pre class="programlisting">
pixbuf = gdk_pixbuf_new_from_inline (-1, myimage_inline, FALSE, NULL);
</pre></div>
<p>
</p>
<p>
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.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>data_length</code></em> :</span></td>
<td> Length in bytes of the <em class="parameter"><code>data</code></em> argument or -1 to
disable length checks
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>data</code></em> :</span></td>
<td> Byte data containing a serialized <a href="gdk-pixbuf-inline.html#GdkPixdata"><span class="type">GdkPixdata</span></a> structure
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>copy_pixels</code></em> :</span></td>
<td> Whether to copy the pixel data, or use direct pointers
<em class="parameter"><code>data</code></em> for the resulting pixbuf
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>error</code></em> :</span></td>
<td> <a
href="../glib/glib-Error-Reporting.html#GError"
><span class="type">GError</span></a> return location, may be <a
href="../glib/glib-Standard-Macros.html#NULL:CAPS"
><code class="literal">NULL</code></a> to ignore errors
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td> A newly-created <a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a> structure with a reference,
count of 1, or <a
href="../glib/glib-Standard-Macros.html#NULL:CAPS"
><code class="literal">NULL</code></a> if an error occurred.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3104383"></a><h3>
<a name="gdk-pixbuf-new-subpixbuf"></a>gdk_pixbuf_new_subpixbuf ()</h3>
<a class="indexterm" name="id3104396"></a><pre class="programlisting"><a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf">GdkPixbuf</a>* gdk_pixbuf_new_subpixbuf (<a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf">GdkPixbuf</a> *src_pixbuf,
int src_x,
int src_y,
int width,
int height);</pre>
<p>
Creates a new pixbuf which represents a sub-region of
<em class="parameter"><code>src_pixbuf</code></em>. The new pixbuf shares its pixels with the
original pixbuf, so writing to one affects both.
The new pixbuf holds a reference to <em class="parameter"><code>src_pixbuf</code></em>, so
<em class="parameter"><code>src_pixbuf</code></em> will not be finalized until the new pixbuf
is finalized.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>src_pixbuf</code></em> :</span></td>
<td> a <a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a>
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>src_x</code></em> :</span></td>
<td> X coord in <em class="parameter"><code>src_pixbuf</code></em>
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>src_y</code></em> :</span></td>
<td> Y coord in <em class="parameter"><code>src_pixbuf</code></em>
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>width</code></em> :</span></td>
<td> width of region in <em class="parameter"><code>src_pixbuf</code></em>
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>height</code></em> :</span></td>
<td> height of region in <em class="parameter"><code>src_pixbuf</code></em>
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td> a new pixbuf
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3104592"></a><h3>
<a name="gdk-pixbuf-copy"></a>gdk_pixbuf_copy ()</h3>
<a class="indexterm" name="id3104605"></a><pre class="programlisting"><a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf">GdkPixbuf</a>* gdk_pixbuf_copy (const <a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf">GdkPixbuf</a> *pixbuf);</pre>
<p>
Creates a new <a href="gdk-pixbuf-gdk-pixbuf.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a> with a copy of the information in the specified
<em class="parameter"><code>pixbuf</code></em>.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>pixbuf</code></em> :</span></td>
<td> A pixbuf.
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td> A newly-created pixbuf with a reference count of 1, or <a
href="../glib/glib-Standard-Macros.html#NULL:CAPS"
><code class="literal">NULL</code></a> if
not enough memory could be allocated.
</td>
</tr>
</tbody>
</table></div>
</div>
</div>
<div class="refsect1" lang="en">
<a name="id3104692"></a><h2>See Also</h2>
<p>
<code class="function">gdk_pixbuf_finalize()</code>.
</p>
</div>
</div>
</body>
</html>