gtkmm  4.8.0
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Functions | List of all members
Gdk::Pixbuf Class Reference

#include <gdkmm/pixbuf.h>

Inherits Glib::Object, Gio::Icon, and Gio::LoadableIcon.

Public Types

enum class  Rotation {
  NONE = 0 ,
  COUNTERCLOCKWISE = 90 ,
  UPSIDEDOWN = 180 ,
  CLOCKWISE = 270
}
 The possible rotations which can be passed to Gdk::Pixbuf::rotate_simple(). More...
 
using SlotDestroyData = sigc::slot< void(const guint8 *)>
 

Public Member Functions

 Pixbuf (Pixbuf && src) noexcept
 
Pixbufoperator= (Pixbuf && src) noexcept
 
 ~Pixbuf () noexcept override
 
GdkPixbuf * gobj ()
 Provides access to the underlying C GObject. More...
 
const GdkPixbuf * gobj () const
 Provides access to the underlying C GObject. More...
 
GdkPixbuf * gobj_copy ()
 Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
 
Glib::RefPtr< Pixbufcopy () const
 Creates a new Gdk::Pixbuf with a copy of the information in the specified pixbuf. More...
 
Colorspace get_colorspace () const
 Queries the color space of a pixbuf. More...
 
int get_n_channels () const
 Queries the number of channels of a pixbuf. More...
 
bool get_has_alpha () const
 Queries whether a pixbuf has an alpha channel (opacity information). More...
 
int get_bits_per_sample () const
 Queries the number of bits per color sample in a pixbuf. More...
 
guint8 * get_pixels ()
 Queries a pointer to the pixel data of a pixbuf. More...
 
const guint8 * get_pixels () const
 Provides a read-only pointer to the raw pixel data. More...
 
guint8 * get_pixels (guint & length)
 Queries a pointer to the pixel data of a pixbuf. More...
 
const guint8 * get_pixels (guint & length) const
 
int get_width () const
 Queries the width of a pixbuf. More...
 
int get_height () const
 Queries the height of a pixbuf. More...
 
int get_rowstride () const
 Queries the rowstride of a pixbuf, which is the number of bytes between the start of a row and the start of the next row. More...
 
gsize get_byte_length () const
 Returns the length of the pixel data, in bytes. More...
 
void fill (guint32 pixel)
 Clears a pixbuf to the given RGBA value, converting the RGBA value into the pixbuf's pixel format. More...
 
void save (const std::string & filename, const Glib::ustring & type) const
 Saves pixbuf to a file in format type. More...
 
void save (const std::string & filename, const Glib::ustring & type, const std::vector< Glib::ustring > & option_keys, const std::vector< Glib::ustring > & option_values) const
 Saves pixbuf to a file in format type. More...
 
void save_to_buffer (gchar *& buffer, gsize & buffer_size, const Glib::ustring & type="png") const
 Saves the pixbuf to a new buffer in format type. More...
 
void save_to_buffer (gchar *& buffer, gsize & buffer_size, const Glib::ustring & type, const std::vector< Glib::ustring > & option_keys, const std::vector< Glib::ustring > & option_values) const
 Saves the pixbuf to a new buffer in format type. More...
 
Glib::RefPtr< Gdk::Pixbufadd_alpha (bool substitute_color, guint8 r, guint8 g, guint8 b) const
 Takes an existing pixbuf and adds an alpha channel to it. More...
 
void copy_area (int src_x, int src_y, int width, int height, const Glib::RefPtr< Gdk::Pixbuf > & dest_pixbuf, int dest_x, int dest_y) const
 Copies a rectangular area from src_pixbuf to dest_pixbuf. More...
 
void saturate_and_pixelate (const Glib::RefPtr< Gdk::Pixbuf > & dest, float saturation, bool pixelate) const
 Modifies saturation and optionally pixelates src, placing the result in dest. More...
 
void scale (const Glib::RefPtr< Gdk::Pixbuf > & dest, int dest_x, int dest_y, int dest_width, int dest_height, double offset_x, double offset_y, double scale_x, double scale_y, InterpType interp_type) const
 Creates a transformation of the source image src by scaling by scale_x and scale_y then translating by offset_x and offset_y, then renders the rectangle ( dest_x, dest_y, dest_width, dest_height) of the resulting image onto the destination image replacing the previous contents. More...
 
void composite (const Glib::RefPtr< Gdk::Pixbuf > & dest, int dest_x, int dest_y, int dest_width, int dest_height, double offset_x, double offset_y, double scale_x, double scale_y, InterpType interp_type, int overall_alpha) const
 Creates a transformation of the source image src by scaling by scale_x and scale_y then translating by offset_x and offset_y. More...
 
void composite_color (const Glib::RefPtr< Gdk::Pixbuf > & dest, int dest_x, int dest_y, int dest_width, int dest_height, double offset_x, double offset_y, double scale_x, double scale_y, InterpType interp_type, int overall_alpha, int check_x, int check_y, int check_size, guint32 color1, guint32 color2) const
 Creates a transformation of the source image src by scaling by scale_x and scale_y then translating by offset_x and offset_y, then alpha blends the rectangle ( dest_x , dest_y, dest_width, dest_height) of the resulting image with a checkboard of the colors color1 and color2 and renders it onto the destination image. More...
 
Glib::RefPtr< Gdk::Pixbufscale_simple (int dest_width, int dest_height, InterpType interp_type) const
 Create a new pixbuf containing a copy of src scaled to dest_width x dest_height. More...
 
Glib::RefPtr< Gdk::Pixbufcomposite_color_simple (int dest_width, int dest_height, InterpType interp_type, int overall_alpha, int check_size, guint32 color1, guint32 color2) const
 Creates a new pixbuf by scaling src to dest_width x dest_height and alpha blending the result with a checkboard of colors color1 and color2. More...
 
Glib::RefPtr< Gdk::Pixbufrotate_simple (Rotation angle) const
 Rotates a pixbuf by a multiple of 90 degrees, and returns the result in a new pixbuf. More...
 
Glib::RefPtr< Gdk::Pixbufflip (bool horizontal=true) const
 Flips a pixbuf horizontally or vertically and returns the result in a new pixbuf. More...
 
Glib::ustring get_option (const Glib::ustring & key) const
 Looks up key in the list of options that may have been attached to the pixbuf when it was loaded, or that may have been attached by another function using set_option(). More...
 
bool set_option (const Glib::ustring & key, const Glib::ustring & value)
 Attaches a key/value pair as an option to a Gdk::Pixbuf. More...
 
bool remove_option (const Glib::ustring & key)
 Removes the key/value pair option attached to a Gdk::Pixbuf. More...
 
bool copy_options (const Glib::RefPtr< Pixbuf > & dest_pixbuf) const
 Copies the key/value pair options attached to a Gdk::Pixbuf to another Gdk::Pixbuf. More...
 
Glib::RefPtr< Pixbufapply_embedded_orientation ()
 Takes an existing pixbuf and checks for the presence of an associated "orientation" option. More...
 
Glib::PropertyProxy_ReadOnly< Colorspaceproperty_colorspace () const
 The color space of the pixbuf. More...
 
Glib::PropertyProxy_ReadOnly< int > property_n_channels () const
 The number of samples per pixel. More...
 
Glib::PropertyProxy_ReadOnly< bool > property_has_alpha () const
 Whether the pixbuf has an alpha channel. More...
 
Glib::PropertyProxy_ReadOnly< int > property_bits_per_sample () const
 The number of bits per sample. More...
 
Glib::PropertyProxy_ReadOnly< int > property_width () const
 The number of columns of the pixbuf. More...
 
Glib::PropertyProxy_ReadOnly< int > property_height () const
 The number of rows of the pixbuf. More...
 
Glib::PropertyProxy_ReadOnly< int > property_rowstride () const
 The number of bytes between the start of a row and the start of the next row. More...
 
Glib::PropertyProxy_ReadOnly< void * > property_pixels () const
 A pointer to the pixel data of the pixbuf. More...
 

Static Public Member Functions

static GType get_type ()
 Get the GType for this class, for use with the underlying GObject type system. More...
 
static Glib::RefPtr< Pixbufcreate (const ::Cairo::RefPtr< ::Cairo::Surface > & src, int src_x, int src_y, int width, int height)
 Transfers image data from a Cairo::Surface and converts it to an RGB(A) representation inside a Gdk::Pixbuf. More...
 
static Glib::RefPtr< Pixbufcreate (Colorspace colorspace, bool has_alpha, int bits_per_sample, int width, int height)
 Creates a new Gdk::Pixbuf structure and allocates a buffer for it. More...
 
static Glib::RefPtr< Pixbufcreate_subpixbuf (const Glib::RefPtr< Pixbuf > & src_pixbuf, int src_x, int src_y, int width, int height)
 Creates a new pixbuf which represents a sub-region of src_pixbuf. More...
 
static Glib::RefPtr< Pixbufcreate_from_file (const std::string & filename)
 Creates a new pixbuf by loading an image from a file. More...
 
static Glib::RefPtr< Pixbufcreate_from_file (const std::string & filename, int width, int height, bool preserve_aspect_ratio=true)
 Creates a new pixbuf by loading an image from a file. More...
 
static Glib::RefPtr< Pixbufcreate_from_resource (const std::string & resource_path)
 Creates a new pixbuf by loading an image from a resource. More...
 
static Glib::RefPtr< Pixbufcreate_from_resource (const std::string & resource_path, int width, int height, bool preserve_aspect_ratio=true)
 Creates a new pixbuf by loading an image from a resource. More...
 
static Glib::RefPtr< Pixbufcreate_from_data (const guint8 *data, Colorspace colorspace, bool has_alpha, int bits_per_sample, int width, int height, int rowstride)
 Creates a new Gdk::Pixbuf out of in-memory image data. More...
 
static Glib::RefPtr< Pixbufcreate_from_data (const guint8 *data, Colorspace colorspace, bool has_alpha, int bits_per_sample, int width, int height, int rowstride, const SlotDestroyData & destroy_slot)
 Creates a new Gdk::Pixbuf out of in-memory image data. More...
 
static Glib::RefPtr< Pixbufcreate_from_xpm_data (const char * const *data)
 Creates a new pixbuf by parsing XPM data in memory. More...
 
static Glib::RefPtr< Pixbufcreate_from_stream (const Glib::RefPtr< Gio::InputStream > & stream, const Glib::RefPtr< Gio::Cancellable > & cancellable)
 Creates a new pixbuf by loading an image from an input stream. More...
 
static Glib::RefPtr< Pixbufcreate_from_stream (const Glib::RefPtr< Gio::InputStream > & stream)
 
static Glib::RefPtr< Pixbufcreate_from_stream_at_scale (const Glib::RefPtr< Gio::InputStream > & stream, int width, int height, bool preserve_aspect_ratio, const Glib::RefPtr< Gio::Cancellable > & cancellable)
 Creates a new pixbuf by loading an image from an input stream. More...
 
static Glib::RefPtr< Pixbufcreate_from_stream_at_scale (const Glib::RefPtr< Gio::InputStream > & stream, int width, int height, bool preserve_aspect_ratio)
 
static std::vector< PixbufFormatget_formats ()
 Obtains the available information about the image formats supported by GdkPixbuf. More...
 

Protected Member Functions

 Pixbuf (const ::Cairo::RefPtr< ::Cairo::Surface > & src, int src_x, int src_y, int width, int height)
 Transfers image data from a Cairo::Surface and converts it to an RGB(A) representation inside a Gdk::Pixbuf. More...
 

Related Functions

(Note that these are not member functions.)

Glib::RefPtr< Gdk::Pixbufwrap (GdkPixbuf * object, bool take_copy=false)
 A Glib::wrap() method for this object. More...
 

Member Typedef Documentation

◆ SlotDestroyData

using Gdk::Pixbuf::SlotDestroyData = sigc::slot<void(const guint8*)>

Constructor & Destructor Documentation

◆ Pixbuf() [1/2]

Gdk::Pixbuf::Pixbuf ( Pixbuf &&  src)
noexcept

◆ ~Pixbuf()

Gdk::Pixbuf::~Pixbuf ( )
overridenoexcept

◆ Pixbuf() [2/2]

Gdk::Pixbuf::Pixbuf ( const ::Cairo::RefPtr< ::Cairo::Surface > &  src,
int  src_x,
int  src_y,
int  width,
int  height 
)
protected

Transfers image data from a Cairo::Surface and converts it to an RGB(A) representation inside a Gdk::Pixbuf.

This allows you to efficiently read individual pixels from cairo surfaces.

This will create an RGB pixbuf with 8 bits per channel. The pixbuf will contain an alpha channel if the surface contains one.

Parameters
srcSurface to copy from.
src_xSource X coordinate within the surface.
src_ySource Y coordinate within the surface.
widthWidth in pixels of region to get.
heightHeight in pixels of region to get.
Exceptions
Gdk::PixbufError
Since gtkmm 2.30:

Member Function Documentation

◆ add_alpha()

Glib::RefPtr<Gdk::Pixbuf> Gdk::Pixbuf::add_alpha ( bool  substitute_color,
guint8  r,
guint8  g,
guint8  b 
) const

Takes an existing pixbuf and adds an alpha channel to it.

If the existing pixbuf already had an alpha channel, the channel values are copied from the original; otherwise, the alpha channel is initialized to 255 (full opacity).

If substitute_color is true, then the color specified by the (r, g, b) arguments will be assigned zero opacity. That is, if you pass (255, 255, 255) for the substitute color, all white pixels will become fully transparent.

If substitute_color is false, then the (r, g, b) arguments will be ignored.

Parameters
substitute_colorWhether to set a color to zero opacity.
rRed value to substitute.
gGreen value to substitute.
bBlue value to substitute.
Returns
A newly-created pixbuf.

◆ apply_embedded_orientation()

Glib::RefPtr<Pixbuf> Gdk::Pixbuf::apply_embedded_orientation ( )

Takes an existing pixbuf and checks for the presence of an associated "orientation" option.

The orientation option may be provided by the JPEG loader (which reads the exif orientation tag) or the TIFF loader (which reads the TIFF orientation tag, and compensates it for the partial transforms performed by libtiff).

If an orientation option/tag is present, the appropriate transform will be performed so that the pixbuf is oriented correctly.

Since gtkmm 2.12:
Returns
A newly-created pixbuf.

◆ composite()

void Gdk::Pixbuf::composite ( const Glib::RefPtr< Gdk::Pixbuf > &  dest,
int  dest_x,
int  dest_y,
int  dest_width,
int  dest_height,
double  offset_x,
double  offset_y,
double  scale_x,
double  scale_y,
InterpType  interp_type,
int  overall_alpha 
) const

Creates a transformation of the source image src by scaling by scale_x and scale_y then translating by offset_x and offset_y.

This gives an image in the coordinates of the destination pixbuf. The rectangle ( dest_x, dest_y, dest_width, dest_height) is then alpha blended onto the corresponding rectangle of the original destination image.

When the destination rectangle contains parts not in the source image, the data at the edges of the source image is replicated to infinity.

Parameters
destThe Gdk::Pixbuf into which to render the results.
dest_xThe left coordinate for region to render.
dest_yThe top coordinate for region to render.
dest_widthThe width of the region to render.
dest_heightThe height of the region to render.
offset_xThe offset in the X direction (currently rounded to an integer).
offset_yThe offset in the Y direction (currently rounded to an integer).
scale_xThe scale factor in the X direction.
scale_yThe scale factor in the Y direction.
interp_typeThe interpolation type for the transformation.
overall_alphaOverall alpha for source image (0..255).

◆ composite_color()

void Gdk::Pixbuf::composite_color ( const Glib::RefPtr< Gdk::Pixbuf > &  dest,
int  dest_x,
int  dest_y,
int  dest_width,
int  dest_height,
double  offset_x,
double  offset_y,
double  scale_x,
double  scale_y,
InterpType  interp_type,
int  overall_alpha,
int  check_x,
int  check_y,
int  check_size,
guint32  color1,
guint32  color2 
) const

Creates a transformation of the source image src by scaling by scale_x and scale_y then translating by offset_x and offset_y, then alpha blends the rectangle ( dest_x , dest_y, dest_width, dest_height) of the resulting image with a checkboard of the colors color1 and color2 and renders it onto the destination image.

If the source image has no alpha channel, and overall_alpha is 255, a fast path is used which omits the alpha blending and just performs the scaling.

See composite_color_simple() for a simpler variant of this function suitable for many tasks.

Parameters
destThe Gdk::Pixbuf into which to render the results.
dest_xThe left coordinate for region to render.
dest_yThe top coordinate for region to render.
dest_widthThe width of the region to render.
dest_heightThe height of the region to render.
offset_xThe offset in the X direction (currently rounded to an integer).
offset_yThe offset in the Y direction (currently rounded to an integer).
scale_xThe scale factor in the X direction.
scale_yThe scale factor in the Y direction.
interp_typeThe interpolation type for the transformation.
overall_alphaOverall alpha for source image (0..255).
check_xThe X offset for the checkboard (origin of checkboard is at - check_x, - check_y).
check_yThe Y offset for the checkboard.
check_sizeThe size of checks in the checkboard (must be a power of two).
color1The color of check at upper left.
color2The color of the other check.

◆ composite_color_simple()

Glib::RefPtr<Gdk::Pixbuf> Gdk::Pixbuf::composite_color_simple ( int  dest_width,
int  dest_height,
InterpType  interp_type,
int  overall_alpha,
int  check_size,
guint32  color1,
guint32  color2 
) const

Creates a new pixbuf by scaling src to dest_width x dest_height and alpha blending the result with a checkboard of colors color1 and color2.

Parameters
dest_widthThe width of destination image.
dest_heightThe height of destination image.
interp_typeThe interpolation type for the transformation.
overall_alphaOverall alpha for source image (0..255).
check_sizeThe size of checks in the checkboard (must be a power of two).
color1The color of check at upper left.
color2The color of the other check.
Returns
The new pixbuf.

◆ copy()

Glib::RefPtr<Pixbuf> Gdk::Pixbuf::copy ( ) const

Creates a new Gdk::Pixbuf with a copy of the information in the specified pixbuf.

Note that this does not copy the options set on the original Gdk::Pixbuf, use copy_options() for this.

Returns
A newly-created pixbuf.

◆ copy_area()

void Gdk::Pixbuf::copy_area ( int  src_x,
int  src_y,
int  width,
int  height,
const Glib::RefPtr< Gdk::Pixbuf > &  dest_pixbuf,
int  dest_x,
int  dest_y 
) const

Copies a rectangular area from src_pixbuf to dest_pixbuf.

Conversion of pixbuf formats is done automatically.

If the source rectangle overlaps the destination rectangle on the same pixbuf, it will be overwritten during the copy operation. Therefore, you can not use this function to scroll a pixbuf.

Parameters
src_xSource X coordinate within src_pixbuf.
src_ySource Y coordinate within src_pixbuf.
widthWidth of the area to copy.
heightHeight of the area to copy.
dest_pixbufDestination pixbuf.
dest_xX coordinate within dest_pixbuf.
dest_yY coordinate within dest_pixbuf.

◆ copy_options()

bool Gdk::Pixbuf::copy_options ( const Glib::RefPtr< Pixbuf > &  dest_pixbuf) const

Copies the key/value pair options attached to a Gdk::Pixbuf to another Gdk::Pixbuf.

This is useful to keep original metadata after having manipulated a file. However be careful to remove metadata which you've already applied, such as the "orientation" option after rotating the image.

Since gtkmm 2.36:
Parameters
dest_pixbufThe destination pixbuf.
Returns
true on success.

◆ create() [1/2]

static Glib::RefPtr<Pixbuf> Gdk::Pixbuf::create ( Colorspace  colorspace,
bool  has_alpha,
int  bits_per_sample,
int  width,
int  height 
)
static

Creates a new Gdk::Pixbuf structure and allocates a buffer for it.

If the allocation of the buffer failed, this function will return nullptr.

The buffer has an optimal rowstride. Note that the buffer is not cleared; you will have to fill it completely yourself.

Parameters
colorspaceColor space for image.
has_alphaWhether the image should have transparency information.
bits_per_sampleNumber of bits per color sample.
widthWidth of image in pixels, must be > 0.
heightHeight of image in pixels, must be > 0.
Returns
A newly-created pixel buffer.

◆ create() [2/2]

static Glib::RefPtr<Pixbuf> Gdk::Pixbuf::create ( const ::Cairo::RefPtr< ::Cairo::Surface > &  src,
int  src_x,
int  src_y,
int  width,
int  height 
)
static

Transfers image data from a Cairo::Surface and converts it to an RGB(A) representation inside a Gdk::Pixbuf.

This allows you to efficiently read individual pixels from cairo surfaces.

This will create an RGB pixbuf with 8 bits per channel. The pixbuf will contain an alpha channel if the surface contains one.

Parameters
srcSurface to copy from.
src_xSource X coordinate within the surface.
src_ySource Y coordinate within the surface.
widthWidth in pixels of region to get.
heightHeight in pixels of region to get.
Exceptions
Gdk::PixbufError
Since gtkmm 2.30:

◆ create_from_data() [1/2]

static Glib::RefPtr<Pixbuf> Gdk::Pixbuf::create_from_data ( const guint8 *  data,
Colorspace  colorspace,
bool  has_alpha,
int  bits_per_sample,
int  width,
int  height,
int  rowstride 
)
static

Creates a new Gdk::Pixbuf out of in-memory image data.

Currently only RGB images with 8 bits per sample are supported.

Parameters
dataImage data in 8-bit/sample packed format.
colorspaceColorspace for the image data.
has_alphaWhether the data has an opacity channel.
bits_per_sampleNumber of bits per sample.
widthWidth of the image in pixels.
heightHeight of the image in pixels.
rowstrideDistance in bytes between rows.
Returns
A newly-created Gdk::Pixbuf object.

◆ create_from_data() [2/2]

static Glib::RefPtr<Pixbuf> Gdk::Pixbuf::create_from_data ( const guint8 *  data,
Colorspace  colorspace,
bool  has_alpha,
int  bits_per_sample,
int  width,
int  height,
int  rowstride,
const SlotDestroyData destroy_slot 
)
static

Creates a new Gdk::Pixbuf out of in-memory image data.

Currently only RGB images with 8 bits per sample are supported.

Parameters
dataImage data in 8-bit/sample packed format.
colorspaceColorspace for the image data.
has_alphaWhether the data has an opacity channel.
bits_per_sampleNumber of bits per sample.
widthWidth of the image in pixels.
heightHeight of the image in pixels.
rowstrideDistance in bytes between rows.
destroy_slotSlot used to free the data when the pixbuf's reference count drops to zero.
Returns
A newly-created Gdk::Pixbuf object.

◆ create_from_file() [1/2]

static Glib::RefPtr<Pixbuf> Gdk::Pixbuf::create_from_file ( const std::string filename)
static

Creates a new pixbuf by loading an image from a file.

The file format is detected automatically.

Parameters
filenameThe path to the pixbuf file.
Exceptions
Glib::FileError
Gdk::PixbufError

◆ create_from_file() [2/2]

static Glib::RefPtr<Pixbuf> Gdk::Pixbuf::create_from_file ( const std::string filename,
int  width,
int  height,
bool  preserve_aspect_ratio = true 
)
static

Creates a new pixbuf by loading an image from a file.

The file format is detected automatically. The image will be scaled to fit in the requested size.

Parameters
filenameThe path to the pixbuf file.
widthThe desired width
heightThe desired height
preserve_aspect_ratioWhether the image's aspect ratio will be preserved when scaling.
Exceptions
Glib::FileError
Gdk::PixbufError

◆ create_from_resource() [1/2]

static Glib::RefPtr<Pixbuf> Gdk::Pixbuf::create_from_resource ( const std::string resource_path)
static

Creates a new pixbuf by loading an image from a resource.

The file format is detected automatically.

Parameters
resource_pathThe path of the resource file.
Exceptions
Gio::ResourceError
Gdk::PixbufError
Since gtkmm 3.12:

◆ create_from_resource() [2/2]

static Glib::RefPtr<Pixbuf> Gdk::Pixbuf::create_from_resource ( const std::string resource_path,
int  width,
int  height,
bool  preserve_aspect_ratio = true 
)
static

Creates a new pixbuf by loading an image from a resource.

The file format is detected automatically. The image will be scaled to fit in the requested size, optionally preserving the image's aspect ratio. When preserving the aspect ratio, a width of -1 will cause the image to be scaled to the exact given height, and a height of -1 will cause the image to be scaled to the exact given width. When not preserving aspect ratio, a width or height of -1 means to not scale the image at all in that dimension.

Parameters
resource_pathThe path of the resource file.
widthThe desired width
heightThe desired height
preserve_aspect_ratioWhether the image's aspect ratio will be preserved when scaling.
Exceptions
Gio::ResourceError
Gdk::PixbufError
Since gtkmm 3.12:

◆ create_from_stream() [1/2]

static Glib::RefPtr<Pixbuf> Gdk::Pixbuf::create_from_stream ( const Glib::RefPtr< Gio::InputStream > &  stream)
static

◆ create_from_stream() [2/2]

static Glib::RefPtr<Pixbuf> Gdk::Pixbuf::create_from_stream ( const Glib::RefPtr< Gio::InputStream > &  stream,
const Glib::RefPtr< Gio::Cancellable > &  cancellable 
)
static

Creates a new pixbuf by loading an image from an input stream.


The file format is detected automatically.

If nullptr is returned, then error will be set.

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

The stream is not closed.

Since gtkmm 2.14:
Parameters
streamA Gio::InputStream to load the pixbuf from.
cancellableOptional Gio::Cancellable object, nullptr to ignore.
Returns
A newly-created pixbuf.
Exceptions
Glib::Error

◆ create_from_stream_at_scale() [1/2]

static Glib::RefPtr<Pixbuf> Gdk::Pixbuf::create_from_stream_at_scale ( const Glib::RefPtr< Gio::InputStream > &  stream,
int  width,
int  height,
bool  preserve_aspect_ratio 
)
static

◆ create_from_stream_at_scale() [2/2]

static Glib::RefPtr<Pixbuf> Gdk::Pixbuf::create_from_stream_at_scale ( const Glib::RefPtr< Gio::InputStream > &  stream,
int  width,
int  height,
bool  preserve_aspect_ratio,
const Glib::RefPtr< Gio::Cancellable > &  cancellable 
)
static

Creates a new pixbuf by loading an image from an input stream.


The file format is detected automatically. If nullptr is returned, then error will be set. The cancellable can be used to abort the operation from another thread. If the operation was cancelled, the error Gio::Error::CANCELLED will be returned. Other possible errors are in the GDK_PIXBUF_ERROR and G_IO_ERROR domains.

The image will be scaled to fit in the requested size, optionally preserving the image's aspect ratio.

When preserving the aspect ratio, a width of -1 will cause the image to be scaled to the exact given height, and a height of -1 will cause the image to be scaled to the exact given width. If both width and height are given, this function will behave as if the smaller of the two values is passed as -1.

When not preserving aspect ratio, a width or height of -1 means to not scale the image at all in that dimension.

The stream is not closed.

Since gtkmm 2.14:
Parameters
streamA Gio::InputStream to load the pixbuf from.
widthThe width the image should have or -1 to not constrain the width.
heightThe height the image should have or -1 to not constrain the height.
preserve_aspect_ratiotrue to preserve the image's aspect ratio.
cancellableOptional Gio::Cancellable object, nullptr to ignore.
Returns
A newly-created pixbuf.
Exceptions
Glib::Error

◆ create_from_xpm_data()

static Glib::RefPtr<Pixbuf> Gdk::Pixbuf::create_from_xpm_data ( const char *const *  data)
static

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.

Parameters
dataPointer to inline XPM data.
Returns
A newly-created pixbuf.

◆ create_subpixbuf()

static Glib::RefPtr<Pixbuf> Gdk::Pixbuf::create_subpixbuf ( const Glib::RefPtr< Pixbuf > &  src_pixbuf,
int  src_x,
int  src_y,
int  width,
int  height 
)
static

Creates a new pixbuf which represents a sub-region of src_pixbuf.

The new pixbuf shares its pixels with the original pixbuf, so writing to one affects both. The new pixbuf holds a reference to src_pixbuf, so src_pixbuf will not be finalized until the new pixbuf is finalized.

Note that if src_pixbuf is read-only, this function will force it to be mutable.

Parameters
src_pixbufA Gdk::Pixbuf.
src_xX coord in src_pixbuf.
src_yY coord in src_pixbuf.
widthWidth of region in src_pixbuf.
heightHeight of region in src_pixbuf.
Returns
A new pixbuf.

◆ fill()

void Gdk::Pixbuf::fill ( guint32  pixel)

Clears a pixbuf to the given RGBA value, converting the RGBA value into the pixbuf's pixel format.

The alpha component will be ignored if the pixbuf doesn't have an alpha channel.

Parameters
pixelRGBA pixel to used to clear (0xffffffff is opaque white, 0x00000000 transparent black).

◆ flip()

Glib::RefPtr<Gdk::Pixbuf> Gdk::Pixbuf::flip ( bool  horizontal = true) const

Flips a pixbuf horizontally or vertically and returns the result in a new pixbuf.

Since gtkmm 2.6:
Parameters
horizontaltrue to flip horizontally, false to flip vertically.
Returns
The new pixbuf.

◆ get_bits_per_sample()

int Gdk::Pixbuf::get_bits_per_sample ( ) const

Queries the number of bits per color sample in a pixbuf.

Returns
Number of bits per color sample.

◆ get_byte_length()

gsize Gdk::Pixbuf::get_byte_length ( ) const

Returns the length of the pixel data, in bytes.

Since gtkmm 2.26:
Returns
The length of the pixel data.

◆ get_colorspace()

Colorspace Gdk::Pixbuf::get_colorspace ( ) const

Queries the color space of a pixbuf.

Returns
Color space.

◆ get_formats()

static std::vector<PixbufFormat> Gdk::Pixbuf::get_formats ( )
static

Obtains the available information about the image formats supported by GdkPixbuf.

Returns
A list of PixbufFormats describing the supported image formats.

◆ get_has_alpha()

bool Gdk::Pixbuf::get_has_alpha ( ) const

Queries whether a pixbuf has an alpha channel (opacity information).

Returns
true if it has an alpha channel, false otherwise.

◆ get_height()

int Gdk::Pixbuf::get_height ( ) const

Queries the height of a pixbuf.

Returns
Height in pixels.

◆ get_n_channels()

int Gdk::Pixbuf::get_n_channels ( ) const

Queries the number of channels of a pixbuf.

Returns
Number of channels.

◆ get_option()

Glib::ustring Gdk::Pixbuf::get_option ( const Glib::ustring &  key) const

Looks up key in the list of options that may have been attached to the pixbuf when it was loaded, or that may have been attached by another function using set_option().

For instance, the ANI loader provides "Title" and "Artist" options. The ICO, XBM, and XPM loaders provide "x_hot" and "y_hot" hot-spot options for cursor definitions. The PNG loader provides the tEXt ancillary chunk key/value pairs as options. Since 2.12, the TIFF and JPEG loaders return an "orientation" option string that corresponds to the embedded TIFF/Exif orientation tag (if present). Since 2.32, the TIFF loader sets the "multipage" option string to "yes" when a multi-page TIFF is loaded. Since 2.32 the JPEG and PNG loaders set "x-dpi" and "y-dpi" if the file contains image density information in dots per inch. Since 2.36.6, the JPEG loader sets the "comment" option with the comment EXIF tag.

Parameters
keyA nul-terminated string.
Returns
The value associated with key.

◆ get_pixels() [1/4]

guint8* Gdk::Pixbuf::get_pixels ( )

Queries a pointer to the pixel data of a pixbuf.

This function will cause an implicit copy of the pixbuf data if the pixbuf was created from read-only data.

Please see the section on image data for information about how the pixel data is stored in memory.

Returns
A pointer to the pixbuf's pixel data.

◆ get_pixels() [2/4]

const guint8* Gdk::Pixbuf::get_pixels ( ) const

Provides a read-only pointer to the raw pixel data.

This function allows skipping the implicit copy that must be made if get_pixels() is called on a read-only pixbuf.

Since gtkmm 2.32:
Returns
A read-only pointer to the raw pixel data.

◆ get_pixels() [3/4]

guint8* Gdk::Pixbuf::get_pixels ( guint &  length)

Queries a pointer to the pixel data of a pixbuf.

This function will cause an implicit copy of the pixbuf data if the pixbuf was created from read-only data.

Please see the section on image data for information about how the pixel data is stored in memory.

Since gtkmm 2.26:
Parameters
lengthThe length of the binary data.
Returns
A pointer to the pixbuf's pixel data.

◆ get_pixels() [4/4]

const guint8* Gdk::Pixbuf::get_pixels ( guint &  length) const

◆ get_rowstride()

int Gdk::Pixbuf::get_rowstride ( ) const

Queries the rowstride of a pixbuf, which is the number of bytes between the start of a row and the start of the next row.

Returns
Distance between row starts.

◆ get_type()

static GType Gdk::Pixbuf::get_type ( )
static

Get the GType for this class, for use with the underlying GObject type system.

◆ get_width()

int Gdk::Pixbuf::get_width ( ) const

Queries the width of a pixbuf.

Returns
Width in pixels.

◆ gobj() [1/2]

GdkPixbuf* Gdk::Pixbuf::gobj ( )
inline

Provides access to the underlying C GObject.

◆ gobj() [2/2]

const GdkPixbuf* Gdk::Pixbuf::gobj ( ) const
inline

Provides access to the underlying C GObject.

◆ gobj_copy()

GdkPixbuf* Gdk::Pixbuf::gobj_copy ( )

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

◆ operator=()

Pixbuf& Gdk::Pixbuf::operator= ( Pixbuf &&  src)
noexcept

◆ property_bits_per_sample()

Glib::PropertyProxy_ReadOnly< int > Gdk::Pixbuf::property_bits_per_sample ( ) const

The number of bits per sample.

Currently only 8 bit per sample are supported.

Default value: 8

Returns
A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

◆ property_colorspace()

Glib::PropertyProxy_ReadOnly< Colorspace > Gdk::Pixbuf::property_colorspace ( ) const

The color space of the pixbuf.

Currently, only Gdk::Colorspace::RGB is supported.

Default value: Gdk::Colorspace::RGB

Returns
A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

◆ property_has_alpha()

Glib::PropertyProxy_ReadOnly< bool > Gdk::Pixbuf::property_has_alpha ( ) const

Whether the pixbuf has an alpha channel.

Default value: false

Returns
A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

◆ property_height()

Glib::PropertyProxy_ReadOnly< int > Gdk::Pixbuf::property_height ( ) const

The number of rows of the pixbuf.

Default value: 1

Returns
A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

◆ property_n_channels()

Glib::PropertyProxy_ReadOnly< int > Gdk::Pixbuf::property_n_channels ( ) const

The number of samples per pixel.

Currently, only 3 or 4 samples per pixel are supported.

Default value: 3

Returns
A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

◆ property_pixels()

Glib::PropertyProxy_ReadOnly< void* > Gdk::Pixbuf::property_pixels ( ) const

A pointer to the pixel data of the pixbuf.

Returns
A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

◆ property_rowstride()

Glib::PropertyProxy_ReadOnly< int > Gdk::Pixbuf::property_rowstride ( ) const

The number of bytes between the start of a row and the start of the next row.

This number must (obviously) be at least as large as the width of the pixbuf.

Default value: 1

Returns
A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

◆ property_width()

Glib::PropertyProxy_ReadOnly< int > Gdk::Pixbuf::property_width ( ) const

The number of columns of the pixbuf.

Default value: 1

Returns
A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

◆ remove_option()

bool Gdk::Pixbuf::remove_option ( const Glib::ustring &  key)

Removes the key/value pair option attached to a Gdk::Pixbuf.

Since gtkmm 2.36:
Parameters
keyA nul-terminated string representing the key to remove.
Returns
true if an option was removed, false if not.

◆ rotate_simple()

Glib::RefPtr<Gdk::Pixbuf> Gdk::Pixbuf::rotate_simple ( Rotation  angle) const

Rotates a pixbuf by a multiple of 90 degrees, and returns the result in a new pixbuf.

If angle is 0, this function will return a copy of src.

Since gtkmm 2.6:
Parameters
angleThe angle to rotate by.
Returns
The new pixbuf.

◆ saturate_and_pixelate()

void Gdk::Pixbuf::saturate_and_pixelate ( const Glib::RefPtr< Gdk::Pixbuf > &  dest,
float  saturation,
bool  pixelate 
) const

Modifies saturation and optionally pixelates src, placing the result in dest.

The src and dest pixbufs must have the same image format, size, and rowstride.

The src and dest arguments may be the same pixbuf with no ill effects.

If saturation is 1.0 then saturation is not changed. If it's less than 1.0, saturation is reduced (the image turns toward grayscale); if greater than 1.0, saturation is increased (the image gets more vivid colors).

If pixelate is true, then pixels are faded in a checkerboard pattern to create a pixelated image.

Parameters
destPlace to write modified version of src.
saturationSaturation factor.
pixelateWhether to pixelate.

◆ save() [1/2]

void Gdk::Pixbuf::save ( const std::string filename,
const Glib::ustring &  type 
) const

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 by using get_formats() with is_writable().

Since gtkmm 3.6:
Parameters
filenameThe path of the file to be created.
typeThe file type.
Exceptions
Glib::FileError
Gdk::PixbufError

◆ save() [2/2]

void Gdk::Pixbuf::save ( const std::string filename,
const Glib::ustring &  type,
const std::vector< Glib::ustring > &  option_keys,
const std::vector< Glib::ustring > &  option_values 
) const

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. TThe list of all writable formats can be determined by using get_formats() with Gdk::PixbufFormat::is_writable().

The option_keys and option_values, if not empty, should contain pairs of strings that modify the save parameters. For example, "quality", "100".

Currently only a few parameters exist. JPEG images can be saved with a "quality" parameter; its value should be in the range [0,100]. 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. 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.

Since gtkmm 3.6:
Parameters
filenameThe path of the file to be created.
typeThe file type.
option_keys
option_values
Exceptions
Glib::FileError
Gdk::PixbufError

◆ save_to_buffer() [1/2]

void Gdk::Pixbuf::save_to_buffer ( gchar *&  buffer,
gsize &  buffer_size,
const Glib::ustring &  type,
const std::vector< Glib::ustring > &  option_keys,
const std::vector< Glib::ustring > &  option_values 
) const

Saves the pixbuf to a new buffer in format type.

Note that the buffer is not nul-terminated and may contain embedded nulls.

See also
save().
Since gtkmm 3.6:
Parameters
bufferThis will be set to the address of a new buffer.
buffer_sizeThis will be set to the size of the buffer.
typeCurrently "jpeg", "png", "ico" or "bmp".
option_keysNames of options to set.
option_valuesValues for named options.
Exceptions
Glib::FileError
Gdk::PixbufError

◆ save_to_buffer() [2/2]

void Gdk::Pixbuf::save_to_buffer ( gchar *&  buffer,
gsize &  buffer_size,
const Glib::ustring &  type = "png" 
) const

Saves the pixbuf to a new buffer in format type.

Note that the buffer is not nul-terminated and may contain embedded nulls.

See also
save().
Since gtkmm 3.6:
Parameters
bufferThis will be set to the address of a new buffer.
buffer_sizeThis will be set to the size of the buffer.
typeCurrently "jpeg", "png", "ico" or "bmp".
Exceptions
Glib::FileError
Gdk::PixbufError

◆ scale()

void Gdk::Pixbuf::scale ( const Glib::RefPtr< Gdk::Pixbuf > &  dest,
int  dest_x,
int  dest_y,
int  dest_width,
int  dest_height,
double  offset_x,
double  offset_y,
double  scale_x,
double  scale_y,
InterpType  interp_type 
) const

Creates a transformation of the source image src by scaling by scale_x and scale_y then translating by offset_x and offset_y, then renders the rectangle ( dest_x, dest_y, dest_width, dest_height) of the resulting image onto the destination image replacing the previous contents.

Try to use scale_simple() first; this function is the industrial-strength power tool you can fall back to, if scale_simple() isn't powerful enough.

If the source rectangle overlaps the destination rectangle on the same pixbuf, it will be overwritten during the scaling which results in rendering artifacts.

Parameters
destThe Gdk::Pixbuf into which to render the results.
dest_xThe left coordinate for region to render.
dest_yThe top coordinate for region to render.
dest_widthThe width of the region to render.
dest_heightThe height of the region to render.
offset_xThe offset in the X direction (currently rounded to an integer).
offset_yThe offset in the Y direction (currently rounded to an integer).
scale_xThe scale factor in the X direction.
scale_yThe scale factor in the Y direction.
interp_typeThe interpolation type for the transformation.

◆ scale_simple()

Glib::RefPtr<Gdk::Pixbuf> Gdk::Pixbuf::scale_simple ( int  dest_width,
int  dest_height,
InterpType  interp_type 
) const

Create a new pixbuf containing a copy of src scaled to dest_width x dest_height.

This function leaves src unaffected.

The interp_type should be Gdk::InterpType::NEAREST if you want maximum speed (but when scaling down Gdk::InterpType::NEAREST is usually unusably ugly). The default interp_type should be Gdk::InterpType::BILINEAR which offers reasonable quality and speed.

You can scale a sub-portion of src by creating a sub-pixbuf pointing into src; see GdkPixbuf::Pixbuf::new_subpixbuf().

If dest_width and dest_height are equal to the width and height of src, this function will return an unscaled copy of src.

For more complicated scaling/alpha blending see GdkPixbuf::Pixbuf::scale() and GdkPixbuf::Pixbuf::composite().

Parameters
dest_widthThe width of destination image.
dest_heightThe height of destination image.
interp_typeThe interpolation type for the transformation.
Returns
The new pixbuf.

◆ set_option()

bool Gdk::Pixbuf::set_option ( const Glib::ustring &  key,
const Glib::ustring &  value 
)

Attaches a key/value pair as an option to a Gdk::Pixbuf.

If key already exists in the list of options attached to the pixbuf, the new value is ignored and false is returned.

Since gtkmm 2.2:
Parameters
keyA nul-terminated string.
valueA nul-terminated string.
Returns
true on success.

Friends And Related Function Documentation

◆ wrap()

Glib::RefPtr< Gdk::Pixbuf > wrap ( GdkPixbuf *  object,
bool  take_copy = false 
)
related

A Glib::wrap() method for this object.

Parameters
objectThe C instance.
take_copyFalse if the result should take ownership of the C instance. True if it should take a new copy or ref.
Returns
A C++ instance that wraps this C instance.