<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">

<!ENTITY gdk-pixbuf "<application>gdk-pixbuf</application>">
<!ENTITY Imlib "<application>Imlib</application>">
]>
<refentry id="gdk-pixbuf-file-loading">
<refmeta>
<refentrytitle role="top_of_page" id="gdk-pixbuf-file-loading.top_of_page">File Loading</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDK-PIXBUF Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>File Loading</refname>
<refpurpose>Loading a pixbuf from a file.</refpurpose>
</refnamediv>

<refsynopsisdiv id="gdk-pixbuf-file-loading.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

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

<link linkend="GdkPixbuf">GdkPixbuf</link> *         <link linkend="gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file</link>            (const <link linkend="char">char</link> *filename,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="GdkPixbuf">GdkPixbuf</link> *         <link linkend="gdk-pixbuf-new-from-file-at-size">gdk_pixbuf_new_from_file_at_size</link>    (const <link linkend="char">char</link> *filename,
                                                         <link linkend="int">int</link> width,
                                                         <link linkend="int">int</link> height,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="GdkPixbuf">GdkPixbuf</link> *         <link linkend="gdk-pixbuf-new-from-file-at-scale">gdk_pixbuf_new_from_file_at_scale</link>   (const <link linkend="char">char</link> *filename,
                                                         <link linkend="int">int</link> width,
                                                         <link linkend="int">int</link> height,
                                                         <link linkend="gboolean">gboolean</link> preserve_aspect_ratio,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="GdkPixbufFormat">GdkPixbufFormat</link> *   <link linkend="gdk-pixbuf-get-file-info">gdk_pixbuf_get_file_info</link>            (const <link linkend="gchar">gchar</link> *filename,
                                                         <link linkend="gint">gint</link> *width,
                                                         <link linkend="gint">gint</link> *height);
<link linkend="GdkPixbuf">GdkPixbuf</link> *         <link linkend="gdk-pixbuf-new-from-stream">gdk_pixbuf_new_from_stream</link>          (<link linkend="GInputStream">GInputStream</link> *stream,
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="GdkPixbuf">GdkPixbuf</link> *         <link linkend="gdk-pixbuf-new-from-stream-at-scale">gdk_pixbuf_new_from_stream_at_scale</link> (<link linkend="GInputStream">GInputStream</link> *stream,
                                                         <link linkend="gint">gint</link> width,
                                                         <link linkend="gint">gint</link> height,
                                                         <link linkend="gboolean">gboolean</link> preserve_aspect_ratio,
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
                                                         <link linkend="GError">GError</link> **error);
</synopsis>
</refsynopsisdiv>









<refsect1 id="gdk-pixbuf-file-loading.description" role="desc">
<title role="desc.title">Description</title>
  <para>
    The &gdk-pixbuf; library provides a simple mechanism for loading
    an image from a file in synchronous fashion.  This means that the
    library takes control of the application while the file is being
    loaded; from the user's point of view, the application will block
    until the image is done loading.
  </para>
  <para>
    This interface can be used by applications in which blocking is
    acceptable while an image is being loaded.  It can also be used to
    load small images in general.  Applications that need progressive
    loading can use the <link linkend="GdkPixbufLoader"><type>GdkPixbufLoader</type></link> functionality instead.
  </para>
</refsect1>

<refsect1 id="gdk-pixbuf-file-loading.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="gdk-pixbuf-new-from-file" role="function">
<title>gdk_pixbuf_new_from_file ()</title>
<indexterm zone="gdk-pixbuf-new-from-file"><primary sortas="new_from_file">gdk_pixbuf_new_from_file</primary></indexterm><programlisting><link linkend="GdkPixbuf">GdkPixbuf</link> *         gdk_pixbuf_new_from_file            (const <link linkend="char">char</link> *filename,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Creates a new pixbuf by loading an image from a file.  The file format is
detected automatically. If <link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned, then <parameter>error</parameter> will be set.
Possible errors are in the <link linkend="GDK-PIXBUF-ERROR--CAPS"><type>GDK_PIXBUF_ERROR</type></link> and <link linkend="G-FILE-ERROR--CAPS"><type>G_FILE_ERROR</type></link> domains.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>filename</parameter>&#160;:</term>
<listitem><simpara> Name of file to load, in the GLib file name encoding
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> Return location for an error
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A newly-created pixbuf with a reference count of 1, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if
any of several error conditions occurred:  the file could not be opened,
there was no loader for the file's format, there was not enough memory to
allocate the image buffer, or the image file contained invalid data.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gdk-pixbuf-new-from-file-at-size" role="function" condition="since:2.4">
<title>gdk_pixbuf_new_from_file_at_size ()</title>
<indexterm zone="gdk-pixbuf-new-from-file-at-size" role="2.4"><primary sortas="new_from_file_at_size">gdk_pixbuf_new_from_file_at_size</primary></indexterm><programlisting><link linkend="GdkPixbuf">GdkPixbuf</link> *         gdk_pixbuf_new_from_file_at_size    (const <link linkend="char">char</link> *filename,
                                                         <link linkend="int">int</link> width,
                                                         <link linkend="int">int</link> height,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Creates a new pixbuf by loading an image from a file.  
The file format is detected automatically. If <link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned, then 
<parameter>error</parameter> will be set. Possible errors are in the <link linkend="GDK-PIXBUF-ERROR--CAPS"><type>GDK_PIXBUF_ERROR</type></link> and 
<link linkend="G-FILE-ERROR--CAPS"><type>G_FILE_ERROR</type></link> domains.
</para>
<para>
The image will be scaled to fit in the requested size, preserving
the image's aspect ratio. Note that the returned pixbuf may be smaller
than <parameter>width</parameter> x <parameter>height</parameter>, if the aspect ratio requires it. To load
and image at the requested size, regardless of aspect ratio, use
<link linkend="gdk-pixbuf-new-from-file-at-scale"><function>gdk_pixbuf_new_from_file_at_scale()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>filename</parameter>&#160;:</term>
<listitem><simpara> Name of file to load, in the GLib file name encoding
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>width</parameter>&#160;:</term>
<listitem><simpara> The width the image should have or -1 to not constrain the width
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>height</parameter>&#160;:</term>
<listitem><simpara> The height the image should have or -1 to not constrain the height
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> Return location for an error
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A newly-created pixbuf with a reference count of 1, or 
<link linkend="NULL--CAPS"><literal>NULL</literal></link> if any of several error conditions occurred:  the file could not 
be opened, there was no loader for the file's format, there was not 
enough memory to allocate the image buffer, or the image file contained 
invalid data.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="gdk-pixbuf-new-from-file-at-scale" role="function" condition="since:2.6">
<title>gdk_pixbuf_new_from_file_at_scale ()</title>
<indexterm zone="gdk-pixbuf-new-from-file-at-scale" role="2.6"><primary sortas="new_from_file_at_scale">gdk_pixbuf_new_from_file_at_scale</primary></indexterm><programlisting><link linkend="GdkPixbuf">GdkPixbuf</link> *         gdk_pixbuf_new_from_file_at_scale   (const <link linkend="char">char</link> *filename,
                                                         <link linkend="int">int</link> width,
                                                         <link linkend="int">int</link> height,
                                                         <link linkend="gboolean">gboolean</link> preserve_aspect_ratio,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Creates a new pixbuf by loading an image from a file.  The file format is
detected automatically. If <link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned, then <parameter>error</parameter> will be set.
Possible errors are in the <link linkend="GDK-PIXBUF-ERROR--CAPS"><type>GDK_PIXBUF_ERROR</type></link> and <link linkend="G-FILE-ERROR--CAPS"><type>G_FILE_ERROR</type></link> domains.
The image will be scaled to fit in the requested size, optionally preserving
the image's aspect ratio. 
</para>
<para>
When preserving the aspect ratio, a <parameter>width</parameter> of -1 will cause the image
to be scaled to the exact given height, and a <parameter>height</parameter> of -1 will cause
the image to be scaled to the exact given width. When not preserving
aspect ratio, a <parameter>width</parameter> or <parameter>height</parameter> of -1 means to not scale the image 
at all in that dimension. Negative values for <parameter>width</parameter> and <parameter>height</parameter> are 
allowed since 2.8.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>filename</parameter>&#160;:</term>
<listitem><simpara> Name of file to load, in the GLib file name encoding
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>width</parameter>&#160;:</term>
<listitem><simpara> The width the image should have or -1 to not constrain the width
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>height</parameter>&#160;:</term>
<listitem><simpara> The height the image should have or -1 to not constrain the height
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>preserve_aspect_ratio</parameter>&#160;:</term>
<listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> to preserve the image's aspect ratio
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> Return location for an error
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A newly-created pixbuf with a reference count of 1, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> 
if any of several error conditions occurred:  the file could not be opened,
there was no loader for the file's format, there was not enough memory to
allocate the image buffer, or the image file contained invalid data.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.6</para></refsect2>
<refsect2 id="gdk-pixbuf-get-file-info" role="function" condition="since:2.4">
<title>gdk_pixbuf_get_file_info ()</title>
<indexterm zone="gdk-pixbuf-get-file-info" role="2.4"><primary sortas="get_file_info">gdk_pixbuf_get_file_info</primary></indexterm><programlisting><link linkend="GdkPixbufFormat">GdkPixbufFormat</link> *   gdk_pixbuf_get_file_info            (const <link linkend="gchar">gchar</link> *filename,
                                                         <link linkend="gint">gint</link> *width,
                                                         <link linkend="gint">gint</link> *height);</programlisting>
<para>
Parses an image file far enough to determine its format and size.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>filename</parameter>&#160;:</term>
<listitem><simpara> The name of the file to identify.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>width</parameter>&#160;:</term>
<listitem><simpara> Return location for the width of the image, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>height</parameter>&#160;:</term>
<listitem><simpara> Return location for the height of the image, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A <link linkend="GdkPixbufFormat"><type>GdkPixbufFormat</type></link> describing the image format of the file 
   or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the image format wasn't recognized. The return value 
   is owned by GdkPixbuf and should not be freed.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="gdk-pixbuf-new-from-stream" role="function" condition="since:2.14">
<title>gdk_pixbuf_new_from_stream ()</title>
<indexterm zone="gdk-pixbuf-new-from-stream" role="2.14"><primary sortas="new_from_stream">gdk_pixbuf_new_from_stream</primary></indexterm><programlisting><link linkend="GdkPixbuf">GdkPixbuf</link> *         gdk_pixbuf_new_from_stream          (<link linkend="GInputStream">GInputStream</link> *stream,
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Creates a new pixbuf by loading an image from an input stream.  
</para>
<para>
The file format is detected automatically. If <link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned, then 
<parameter>error</parameter> will be set. The <parameter>cancellable</parameter> can be used to abort the operation
from another thread. If the operation was cancelled, the error 
<link linkend="GIO-ERROR-CANCELLED--CAPS"><literal>GIO_ERROR_CANCELLED</literal></link> will be returned. Other possible errors are in 
the <link linkend="GDK-PIXBUF-ERROR--CAPS"><type>GDK_PIXBUF_ERROR</type></link> and <link linkend="G-IO-ERROR--CAPS"><literal>G_IO_ERROR</literal></link> domains. 
</para>
<para>
The stream is not closed.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>stream</parameter>&#160;:</term>
<listitem><simpara>  a <link linkend="GInputStream"><type>GInputStream</type></link> to load the pixbuf from
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellable</parameter>&#160;:</term>
<listitem><simpara> optional <link linkend="GCancellable"><type>GCancellable</type></link> object, <link linkend="NULL--CAPS"><literal>NULL</literal></link> to ignore
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> Return location for an error
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A newly-created pixbuf, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if any of several error 
conditions occurred: the file could not be opened, the image format is 
not supported, there was not enough memory to allocate the image buffer, 
the stream contained invalid data, or the operation was cancelled.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.14</para></refsect2>
<refsect2 id="gdk-pixbuf-new-from-stream-at-scale" role="function" condition="since:2.14">
<title>gdk_pixbuf_new_from_stream_at_scale ()</title>
<indexterm zone="gdk-pixbuf-new-from-stream-at-scale" role="2.14"><primary sortas="new_from_stream_at_scale">gdk_pixbuf_new_from_stream_at_scale</primary></indexterm><programlisting><link linkend="GdkPixbuf">GdkPixbuf</link> *         gdk_pixbuf_new_from_stream_at_scale (<link linkend="GInputStream">GInputStream</link> *stream,
                                                         <link linkend="gint">gint</link> width,
                                                         <link linkend="gint">gint</link> height,
                                                         <link linkend="gboolean">gboolean</link> preserve_aspect_ratio,
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Creates a new pixbuf by loading an image from an input stream.  
</para>
<para>
The file format is detected automatically. If <link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned, then 
<parameter>error</parameter> will be set. The <parameter>cancellable</parameter> can be used to abort the operation
from another thread. If the operation was cancelled, the error 
<link linkend="GIO-ERROR-CANCELLED--CAPS"><literal>GIO_ERROR_CANCELLED</literal></link> will be returned. Other possible errors are in 
the <link linkend="GDK-PIXBUF-ERROR--CAPS"><type>GDK_PIXBUF_ERROR</type></link> and <link linkend="G-IO-ERROR--CAPS"><literal>G_IO_ERROR</literal></link> domains. 
</para>
<para>
The image will be scaled to fit in the requested size, optionally 
preserving the image's aspect ratio. When preserving the aspect ratio, 
a <parameter>width</parameter> of -1 will cause the image to be scaled to the exact given 
height, and a <parameter>height</parameter> of -1 will cause the image to be scaled to the 
exact given width. When not preserving aspect ratio, a <parameter>width</parameter> or 
<parameter>height</parameter> of -1 means to not scale the image at all in that dimension.
</para>
<para>
The stream is not closed.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>stream</parameter>&#160;:</term>
<listitem><simpara>  a <link linkend="GInputStream"><type>GInputStream</type></link> to load the pixbuf from
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>width</parameter>&#160;:</term>
<listitem><simpara> The width the image should have or -1 to not constrain the width
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>height</parameter>&#160;:</term>
<listitem><simpara> The height the image should have or -1 to not constrain the height
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>preserve_aspect_ratio</parameter>&#160;:</term>
<listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> to preserve the image's aspect ratio
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellable</parameter>&#160;:</term>
<listitem><simpara> optional <link linkend="GCancellable"><type>GCancellable</type></link> object, <link linkend="NULL--CAPS"><literal>NULL</literal></link> to ignore
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> Return location for an error
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A newly-created pixbuf, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if any of several error 
conditions occurred: the file could not be opened, the image format is 
not supported, there was not enough memory to allocate the image buffer, 
the stream contained invalid data, or the operation was cancelled.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.14</para></refsect2>

</refsect1>



<refsect1 id="gdk-pixbuf-file-loading.see-also">
<title>See Also</title>
  <para>
    <link linkend="GdkPixbufLoader"><type>GdkPixbufLoader</type></link>.
  </para>
</refsect1>

</refentry>
