File saving

File saving — Saving a pixbuf to a file.

Functions

Includes

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

Description

These functions allow to save a GdkPixbuf in a number of file formats. The formatted data can be written to a file or to a memory buffer. GdkPixBuf can also call a user-defined callback on the data, which allows to e.g. write the image to a socket or store it in a database.

Functions

gdk_pixbuf_savev ()

gboolean
gdk_pixbuf_savev (GdkPixbuf *pixbuf,
                  const char *filename,
                  const char *type,
                  char **option_keys,
                  char **option_values,
                  GError **error);

Saves pixbuf to a file in type , which is currently "jpeg", "png", "tiff", "ico" or "bmp". If error is set, FALSE will be returned. See gdk_pixbuf_save() for more details.

Parameters

pixbuf

a GdkPixbuf.

 

filename

name of file to save.

 

type

name of file format.

 

option_keys

name of options to set, NULL-terminated.

[array zero-terminated=1]

option_values

values for named options.

[array zero-terminated=1]

error

return location for error, or NULL.

[allow-none]

Returns

whether an error was set


gdk_pixbuf_save ()

gboolean
gdk_pixbuf_save (GdkPixbuf *pixbuf,
                 const char *filename,
                 const char *type,
                 GError **error,
                 ...);

Saves pixbuf to a file in format type . By default, "jpeg", "png", "ico" and "bmp" are possible file formats to save in, but more formats may be installed. The list of all writable formats can be determined in the following way:

1
2
3
4
5
6
7
8
9
10
void add_if_writable (GdkPixbufFormat *data, GSList **list)
{
  if (gdk_pixbuf_format_is_writable (data))
    *list = g_slist_prepend (*list, data);
}

GSList *formats = gdk_pixbuf_get_formats ();
GSList *writable_formats = NULL;
g_slist_foreach (formats, add_if_writable, &writable_formats);
g_slist_free (formats);

If error is set, FALSE will be returned. Possible errors include those in the GDK_PIXBUF_ERROR domain and those in the G_FILE_ERROR domain.

The variable argument list should be NULL-terminated; if not empty, it should contain pairs of strings that modify the save parameters. For example:

1
gdk_pixbuf_save (pixbuf, handle, "jpeg", &error, "quality", "100", NULL);

Currently only few parameters exist. JPEG images can be saved with a "quality" parameter; its value should be in the range [0,100]. JPEG and PNG density can be set by setting the "x-dpi" and "y-dpi" parameters to the appropriate values in dots per inch.

Text chunks can be attached to PNG images by specifying parameters of the form "tEXt::key", where key is an ASCII string of length 1-79. The values are UTF-8 encoded strings. The PNG compression level can be specified using the "compression" parameter; it's value is in an integer in the range of [0,9].

ICC color profiles can also be embedded into PNG, JPEG and TIFF images. The "icc-profile" value should be the complete ICC profile encoded into base64.

1
2
3
4
5
6
gchar *contents;
gchar *contents_encode;
gsize length;
g_file_get_contents ("/home/hughsie/.color/icc/L225W.icm", &contents, &length, NULL);
contents_encode = g_base64_encode ((const guchar *) contents, length);
gdk_pixbuf_save (pixbuf, handle, "png", &error, "icc-profile", contents_encode, NULL);

TIFF images recognize: (1) a "bits-per-sample" option (integer) which can be either 1 for saving bi-level CCITTFAX4 images, or 8 for saving 8-bits per sample; (2) a "compression" option (integer) which can be 1 for no compression, 2 for Huffman, 5 for LZW, 7 for JPEG and 8 for DEFLATE (see the libtiff documentation and tiff.h for all supported codec values); (3) an "icc-profile" option (zero-terminated string) containing a base64 encoded ICC color profile.

ICO images can be saved in depth 16, 24, or 32, by using the "depth" parameter. When the ICO saver is given "x_hot" and "y_hot" parameters, it produces a CUR instead of an ICO.

Parameters

pixbuf

a GdkPixbuf.

 

filename

name of file to save.

 

type

name of file format.

 

error

return location for error, or NULL.

[allow-none]

...

list of key-value save options, followed by NULL

 

Returns

whether an error was set


GdkPixbufSaveFunc ()

gboolean
(*GdkPixbufSaveFunc) (const gchar *buf,
                      gsize count,
                      GError **error,
                      gpointer data);

Specifies the type of the function passed to gdk_pixbuf_save_to_callback(). It is called once for each block of bytes that is "written" by gdk_pixbuf_save_to_callback(). If successful it should return TRUE. If an error occurs it should set error and return FALSE, in which case gdk_pixbuf_save_to_callback() will fail with the same error.

Parameters

buf

bytes to be written.

[array length=count][element-type guint8]

count

number of bytes in buf .

 

error

A location to return an error.

[out]

data

user data passed to gdk_pixbuf_save_to_callback().

[closure]

Returns

TRUE if successful, FALSE (with error set) if failed.

Since: 2.4


gdk_pixbuf_save_to_callback ()

gboolean
gdk_pixbuf_save_to_callback (GdkPixbuf *pixbuf,
                             GdkPixbufSaveFunc save_func,
                             gpointer user_data,
                             const char *type,
                             GError **error,
                             ...);

Saves pixbuf in format type by feeding the produced data to a callback. Can be used when you want to store the image to something other than a file, such as an in-memory buffer or a socket. If error is set, FALSE will be returned. Possible errors include those in the GDK_PIXBUF_ERROR domain and whatever the save function generates.

See gdk_pixbuf_save() for more details.

Parameters

pixbuf

a GdkPixbuf.

 

save_func

a function that is called to save each block of data that the save routine generates.

[scope call]

user_data

user data to pass to the save function.

 

type

name of file format.

 

error

return location for error, or NULL.

[allow-none]

...

list of key-value save options

 

Returns

whether an error was set

Since: 2.4


gdk_pixbuf_save_to_callbackv ()

gboolean
gdk_pixbuf_save_to_callbackv (GdkPixbuf *pixbuf,
                              GdkPixbufSaveFunc save_func,
                              gpointer user_data,
                              const char *type,
                              char **option_keys,
                              char **option_values,
                              GError **error);

Saves pixbuf to a callback in format type , which is currently "jpeg", "png", "tiff", "ico" or "bmp". If error is set, FALSE will be returned. See gdk_pixbuf_save_to_callback() for more details.

Parameters

pixbuf

a GdkPixbuf.

 

save_func

a function that is called to save each block of data that the save routine generates.

[scope call]

user_data

user data to pass to the save function.

[closure]

type

name of file format.

 

option_keys

name of options to set, NULL-terminated.

[array zero-terminated=1][element-type utf8]

option_values

values for named options.

[array zero-terminated=1][element-type utf8]

error

return location for error, or NULL.

[allow-none]

Returns

whether an error was set

Since: 2.4


gdk_pixbuf_save_to_buffer ()

gboolean
gdk_pixbuf_save_to_buffer (GdkPixbuf *pixbuf,
                           gchar **buffer,
                           gsize *buffer_size,
                           const char *type,
                           GError **error,
                           ...);

Saves pixbuf to a new buffer in format type , which is currently "jpeg", "png", "tiff", "ico" or "bmp". This is a convenience function that uses gdk_pixbuf_save_to_callback() to do the real work. Note that the buffer is not nul-terminated and may contain embedded nuls. If error is set, FALSE will be returned and buffer will be set to NULL. Possible errors include those in the GDK_PIXBUF_ERROR domain.

See gdk_pixbuf_save() for more details.

Parameters

pixbuf

a GdkPixbuf.

 

buffer

location to receive a pointer to the new buffer.

[array length=buffer_size][out][element-type guint8]

buffer_size

location to receive the size of the new buffer.

 

type

name of file format.

 

error

return location for error, or NULL.

[allow-none]

...

list of key-value save options

 

Returns

whether an error was set

Since: 2.4


gdk_pixbuf_save_to_bufferv ()

gboolean
gdk_pixbuf_save_to_bufferv (GdkPixbuf *pixbuf,
                            gchar **buffer,
                            gsize *buffer_size,
                            const char *type,
                            char **option_keys,
                            char **option_values,
                            GError **error);

Saves pixbuf to a new buffer in format type , which is currently "jpeg", "tiff", "png", "ico" or "bmp". See gdk_pixbuf_save_to_buffer() for more details.

Parameters

pixbuf

a GdkPixbuf.

 

buffer

location to receive a pointer to the new buffer.

[array length=buffer_size][out][element-type guint8]

buffer_size

location to receive the size of the new buffer.

 

type

name of file format.

 

option_keys

name of options to set, NULL-terminated.

[array zero-terminated=1]

option_values

values for named options.

[array zero-terminated=1]

error

return location for error, or NULL.

[allow-none]

Returns

whether an error was set

Since: 2.4


gdk_pixbuf_save_to_stream ()

gboolean
gdk_pixbuf_save_to_stream (GdkPixbuf *pixbuf,
                           GOutputStream *stream,
                           const char *type,
                           GCancellable *cancellable,
                           GError **error,
                           ...);

Saves pixbuf to an output stream.

Supported file formats are currently "jpeg", "tiff", "png", "ico" or "bmp". See gdk_pixbuf_save_to_buffer() for more details.

The cancellable can be used to abort the operation from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned. Other possible errors are in the GDK_PIXBUF_ERROR and G_IO_ERROR domains.

The stream is not closed.

Parameters

pixbuf

a GdkPixbuf

 

stream

a GOutputStream to save the pixbuf to

 

type

name of file format

 

cancellable

optional GCancellable object, NULL to ignore.

[allow-none]

error

return location for error, or NULL.

[allow-none]

...

list of key-value save options

 

Returns

TRUE if the pixbuf was saved successfully, FALSE if an error was set.

Since: 2.14


gdk_pixbuf_save_to_streamv ()

gboolean
gdk_pixbuf_save_to_streamv (GdkPixbuf *pixbuf,
                            GOutputStream *stream,
                            const char *type,
                            char **option_keys,
                            char **option_values,
                            GCancellable *cancellable,
                            GError **error);

Saves pixbuf to an output stream.

Supported file formats are currently "jpeg", "tiff", "png", "ico" or "bmp". See gdk_pixbuf_save_to_stream() for more details.

Parameters

pixbuf

a GdkPixbuf

 

stream

a GOutputStream to save the pixbuf to

 

type

name of file format

 

option_keys

name of options to set, NULL-terminated.

[array zero-terminated=1]

option_values

values for named options.

[array zero-terminated=1]

cancellable

optional GCancellable object, NULL to ignore.

[allow-none]

error

return location for error, or NULL.

[allow-none]

Returns

TRUE if the pixbuf was saved successfully, FALSE if an error was set.

Since: 2.36


gdk_pixbuf_save_to_stream_async ()

void
gdk_pixbuf_save_to_stream_async (GdkPixbuf *pixbuf,
                                 GOutputStream *stream,
                                 const gchar *type,
                                 GCancellable *cancellable,
                                 GAsyncReadyCallback callback,
                                 gpointer user_data,
                                 ...);

Saves pixbuf to an output stream asynchronously.

For more details see gdk_pixbuf_save_to_stream(), which is the synchronous version of this function.

When the operation is finished, callback will be called in the main thread. You can then call gdk_pixbuf_save_to_stream_finish() to get the result of the operation.

Parameters

pixbuf

a GdkPixbuf

 

stream

a GOutputStream to which to save the pixbuf

 

type

name of file format

 

cancellable

optional GCancellable object, NULL to ignore.

[allow-none]

callback

a GAsyncReadyCallback to call when the pixbuf is saved

 

user_data

the data to pass to the callback function

 

...

list of key-value save options

 

Since: 2.24


gdk_pixbuf_save_to_streamv_async ()

void
gdk_pixbuf_save_to_streamv_async (GdkPixbuf *pixbuf,
                                  GOutputStream *stream,
                                  const gchar *type,
                                  gchar **option_keys,
                                  gchar **option_values,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

Saves pixbuf to an output stream asynchronously.

For more details see gdk_pixbuf_save_to_streamv(), which is the synchronous version of this function.

When the operation is finished, callback will be called in the main thread. You can then call gdk_pixbuf_save_to_stream_finish() to get the result of the operation.

Parameters

pixbuf

a GdkPixbuf

 

stream

a GOutputStream to which to save the pixbuf

 

type

name of file format

 

option_keys

name of options to set, NULL-terminated.

[array zero-terminated=1]

option_values

values for named options.

[array zero-terminated=1]

cancellable

optional GCancellable object, NULL to ignore.

[allow-none]

callback

a GAsyncReadyCallback to call when the pixbuf is saved

 

user_data

the data to pass to the callback function

 

Since: 2.36


gdk_pixbuf_save_to_stream_finish ()

gboolean
gdk_pixbuf_save_to_stream_finish (GAsyncResult *async_result,
                                  GError **error);

Finishes an asynchronous pixbuf save operation started with gdk_pixbuf_save_to_stream_async().

Parameters

async_result

a GAsyncResult

 

error

a GError, or NULL

 

Returns

TRUE if the pixbuf was saved successfully, FALSE if an error was set.

Since: 2.24

Types and Values