PixbufRef
public struct PixbufRef : PixbufProtocol, GWeakCapturing
A pixel buffer.
GdkPixbuf
contains information about an image’s pixel data,
its color space, bits per sample, width and height, and the
rowstride (the number of bytes between the start of one row
and the start of the next).
Creating new GdkPixbuf
The most basic way to create a pixbuf is to wrap an existing pixel
buffer with a [classGdkPixbuf.Pixbuf
] instance. You can use the
[ctor
GdkPixbuf.Pixbuf.new_from_data``] function to do this.
Every time you create a new GdkPixbuf
instance for some data, you
will need to specify the destroy notification function that will be
called when the data buffer needs to be freed; this will happen when
a GdkPixbuf
is finalized by the reference counting functions. If
you have a chunk of static data compiled into your application, you
can pass in NULL
as the destroy notification function so that the
data will not be freed.
The [ctor
GdkPixbuf.Pixbuf.new] constructor function can be used
as a convenience to create a pixbuf with an empty buffer; this is
equivalent to allocating a data buffer using
malloc()and then
wrapping it with
gdk_pixbuf_new_from_data(). The
gdk_pixbuf_new()“
function will compute an optimal rowstride so that rendering can be
performed with an efficient algorithm.
As a special case, you can use the [ctor
GdkPixbuf.Pixbuf.new_from_xpm_data”]
function to create a pixbuf from inline XPM image data.
You can also copy an existing pixbuf with the [methodPixbuf.copy
]
function. This is not the same as just acquiring a reference to
the old pixbuf instance: the copy function will actually duplicate
the pixel data in memory and create a new [classPixbuf
] instance
for it.
Reference counting
GdkPixbuf
structures are reference counted. This means that an
application can share a single pixbuf among many parts of the
code. When a piece of the program needs to use a pixbuf, it should
acquire a reference to it by calling g_object_ref()
; when it no
longer needs the pixbuf, it should release the reference it acquired
by calling g_object_unref()
. The resources associated with a
GdkPixbuf
will be freed when its reference count drops to zero.
Newly-created GdkPixbuf
instances start with a reference count
of one.
Image Data
Image data in a pixbuf is stored in memory in an uncompressed, packed format. Rows in the image are stored top to bottom, and in each row pixels are stored from left to right.
There may be padding at the end of a row.
The “rowstride” value of a pixbuf, as returned by [method
GdkPixbuf.Pixbuf.get_rowstride``],
indicates the number of bytes between rows.
NOTE: If you are copying raw pixbuf data with memcpy()
note that the
last row in the pixbuf may not be as wide as the full rowstride, but rather
just as wide as the pixel data needs to be; that is: it is unsafe to do
memcpy (dest, pixels, rowstride * height)
to copy a whole pixbuf. Use
[methodGdkPixbuf.Pixbuf.copy
] instead, or compute the width in bytes of the
last row as:
last_row = width * ((n_channels * bits_per_sample + 7) / 8);
The same rule applies when iterating over each row of a GdkPixbuf
pixels
array.
The following code illustrates a simple put_pixel()
function for RGB pixbufs with 8 bits per channel with an alpha
channel.
static void
put_pixel (GdkPixbuf *pixbuf,
int x,
int y,
guchar red,
guchar green,
guchar blue,
guchar alpha)
{
int n_channels = gdk_pixbuf_get_n_channels (pixbuf);
// Ensure that the pixbuf is valid
g_assert (gdk_pixbuf_get_colorspace (pixbuf) == GDK_COLORSPACE_RGB);
g_assert (gdk_pixbuf_get_bits_per_sample (pixbuf) == 8);
g_assert (gdk_pixbuf_get_has_alpha (pixbuf));
g_assert (n_channels == 4);
int width = gdk_pixbuf_get_width (pixbuf);
int height = gdk_pixbuf_get_height (pixbuf);
// Ensure that the coordinates are in a valid range
g_assert (x >= 0 && x < width);
g_assert (y >= 0 && y < height);
int rowstride = gdk_pixbuf_get_rowstride (pixbuf);
// The pixel buffer in the GdkPixbuf instance
guchar *pixels = gdk_pixbuf_get_pixels (pixbuf);
// The pixel we wish to modify
guchar *p = pixels + y * rowstride + x * n_channels;
p[0] = red;
p[1] = green;
p[2] = blue;
p[3] = alpha;
}
Loading images
The GdkPixBuf
class provides a simple mechanism for loading
an image from a file in synchronous and asynchronous fashion.
For GUI applications, it is recommended to use the asynchronous stream API to avoid blocking the control flow of the application.
Additionally, GdkPixbuf
provides the [classGdkPixbuf.PixbufLoader
`]
API for progressive image loading.
Saving images
The GdkPixbuf
class provides methods for saving image data 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.
The PixbufRef
type acts as a lightweight Swift reference to an underlying GdkPixbuf
instance.
It exposes methods that can operate on this data type through PixbufProtocol
conformance.
Use PixbufRef
only as an unowned
reference to an existing GdkPixbuf
instance.
-
Untyped pointer to the underlying `GdkPixbuf` instance.
For type-safe access, use the generated, typed pointer
pixbuf_ptr
property instead.Declaration
Swift
public let ptr: UnsafeMutableRawPointer!
-
Designated initialiser from the underlying
C
data typeDeclaration
Swift
@inlinable init(_ p: UnsafeMutablePointer<GdkPixbuf>)
-
Designated initialiser from a constant pointer to the underlying
C
data typeDeclaration
Swift
@inlinable init(_ p: UnsafePointer<GdkPixbuf>)
-
Conditional initialiser from an optional pointer to the underlying
C
data typeDeclaration
Swift
@inlinable init!(_ maybePointer: UnsafeMutablePointer<GdkPixbuf>?)
-
Conditional initialiser from an optional, non-mutable pointer to the underlying
C
data typeDeclaration
Swift
@inlinable init!(_ maybePointer: UnsafePointer<GdkPixbuf>?)
-
Conditional initialiser from an optional
gpointer
Declaration
Swift
@inlinable init!(gpointer g: gpointer?)
-
Conditional initialiser from an optional, non-mutable
gconstpointer
Declaration
Swift
@inlinable init!(gconstpointer g: gconstpointer?)
-
Reference intialiser for a related type that implements
PixbufProtocol
Declaration
Swift
@inlinable init<T>(_ other: T) where T : PixbufProtocol
-
This factory is syntactic sugar for setting weak pointers wrapped in
GWeak<T>
Declaration
Swift
@inlinable static func unowned<T>(_ other: T) -> PixbufRef where T : PixbufProtocol
-
Unsafe typed initialiser. Do not use unless you know the underlying data type the pointer points to conforms to
PixbufProtocol
.Declaration
Swift
@inlinable init<T>(cPointer: UnsafeMutablePointer<T>)
-
Unsafe typed initialiser. Do not use unless you know the underlying data type the pointer points to conforms to
PixbufProtocol
.Declaration
Swift
@inlinable init<T>(constPointer: UnsafePointer<T>)
-
Unsafe untyped initialiser. Do not use unless you know the underlying data type the pointer points to conforms to
PixbufProtocol
.Declaration
Swift
@inlinable init(mutating raw: UnsafeRawPointer)
-
Unsafe untyped initialiser. Do not use unless you know the underlying data type the pointer points to conforms to
PixbufProtocol
.Declaration
Swift
@inlinable init(raw: UnsafeMutableRawPointer)
-
Unsafe untyped initialiser. Do not use unless you know the underlying data type the pointer points to conforms to
PixbufProtocol
.Declaration
Swift
@inlinable init(opaquePointer: OpaquePointer)
-
Creates a new `GdkPixbuf` structure and allocates a buffer for it.
If the allocation of the buffer failed, this function will return
NULL
.The buffer has an optimal rowstride. Note that the buffer is not cleared; you will have to fill it completely yourself.
Declaration
Swift
@inlinable init(colorspace: GdkColorspace, hasAlpha: Bool, bitsPerSample: Int, width: Int, height: Int)
-
Creates a new
GdkPixbuf
out of in-memory readonly image data.Currently only RGB images with 8 bits per sample are supported.
This is the
GBytes
variant ofgdk_pixbuf_new_from_data()
, useful for language bindings.Declaration
Swift
@inlinable init<GLibBytesT>(bytes data: GLibBytesT, colorspace: GdkColorspace, hasAlpha: Bool, bitsPerSample: Int, width: Int, height: Int, rowstride: Int) where GLibBytesT : BytesProtocol
-
Creates a new
GdkPixbuf
out of in-memory image data.Currently only RGB images with 8 bits per sample are supported.
Since you are providing a pre-allocated pixel buffer, you must also specify a way to free that data. This is done with a function of type
GdkPixbufDestroyNotify
. When a pixbuf created with is finalized, your destroy notification function will be called, and it is its responsibility to free the pixel array.See also: [ctor
GdkPixbuf.Pixbuf.new_from_bytes
]Declaration
Swift
@inlinable init(data: UnsafePointer<guchar>!, colorspace: GdkColorspace, hasAlpha: Bool, bitsPerSample: Int, width: Int, height: Int, rowstride: Int, destroyFn: GdkPixbufDestroyNotify? = nil, destroyFnData: gpointer? = nil)
-
Creates a new pixbuf by loading an image from a file.
The file format is detected automatically.
If
NULL
is returned, thenerror
will be set. Possible errors are:- the file could not be opened
- there is no loader for the file’s format
- there is not enough memory to allocate the image buffer
- the image buffer contains invalid data
The error domains are
GDK_PIXBUF_ERROR
andG_FILE_ERROR
.Declaration
Swift
@inlinable init(file filename: UnsafePointer<CChar>!) throws
-
Creates a new pixbuf by loading an image from a file.
The file format is detected automatically.
If
NULL
is returned, thenerror
will be set. Possible errors are:- the file could not be opened
- there is no loader for the file’s format
- there is not enough memory to allocate the image buffer
- the image buffer contains invalid data
The error domains are
GDK_PIXBUF_ERROR
andG_FILE_ERROR
.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 aheight
of -1 will cause the image to be scaled to the exact given width. When not preserving aspect ratio, awidth
orheight
of -1 means to not scale the image at all in that dimension. Negative values forwidth
andheight
are allowed since 2.8.Declaration
Swift
@inlinable init(fileAtScale filename: UnsafePointer<CChar>!, width: Int, height: Int, preserveAspectRatio: Bool) throws
-
Creates a new pixbuf by loading an image from a file.
The file format is detected automatically.
If
NULL
is returned, thenerror
will be set. Possible errors are:- the file could not be opened
- there is no loader for the file’s format
- there is not enough memory to allocate the image buffer
- the image buffer contains invalid data
The error domains are
GDK_PIXBUF_ERROR
andG_FILE_ERROR
.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
width
xheight
, if the aspect ratio requires it. To load and image at the requested size, regardless of aspect ratio, use [ctorGdkPixbuf.Pixbuf.new_from_file_at_scale
].Declaration
Swift
@inlinable init(fileAtSize filename: UnsafePointer<CChar>!, width: Int, height: Int) throws
-
Creates a
GdkPixbuf
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.
GdkPixbuf ships with a program called
gdk-pixbuf-csource
, which allows for conversion ofGdkPixbuf
s into such a inline representation.In almost all cases, you should pass the
--raw
option togdk-pixbuf-csource
. A sample invocation would be:gdk-pixbuf-csource --raw --name=myimage_inline myimage.png
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
FALSE
forcopy_pixels
. If you pass--rle
togdk-pixbuf-csource
, a copy will be made even ifcopy_pixels
isFALSE
, so using this option is generally a bad idea.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:
pixbuf = gdk_pixbuf_new_from_inline (-1, myimage_inline, FALSE, NULL);
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.
new_from_inline is deprecated: Use
GResource
instead.Declaration
Swift
@available(*, deprecated) @inlinable init(inline dataLength: Int, data: UnsafePointer<guint8>!, copyPixels: Bool) throws
-
Creates a new pixbuf by loading an image from an resource.
The file format is detected automatically. If
NULL
is returned, thenerror
will be set.Declaration
Swift
@inlinable init(resource resourcePath: UnsafePointer<CChar>!) throws
-
Creates a new pixbuf by loading an image from an resource.
The file format is detected automatically. If
NULL
is returned, thenerror
will be set.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 aheight
of -1 will cause the image to be scaled to the exact given width. When not preserving aspect ratio, awidth
orheight
of -1 means to not scale the image at all in that dimension.The stream is not closed.
Declaration
Swift
@inlinable init(resourceAtScale resourcePath: UnsafePointer<CChar>!, width: Int, height: Int, preserveAspectRatio: Bool) throws
-
Creates a new pixbuf by loading an image from an input stream.
The file format is detected automatically.
If
NULL
is returned, thenerror
will be set.The
cancellable
can be used to abort the operation from another thread. If the operation was cancelled, the errorG_IO_ERROR_CANCELLED
will be returned. Other possible errors are in theGDK_PIXBUF_ERROR
andG_IO_ERROR
domains.The stream is not closed.
Declaration
Swift
@inlinable init<GioCancellableT, GioInputStreamT>(stream: GioInputStreamT, cancellable: GioCancellableT?) throws where GioCancellableT : CancellableProtocol, GioInputStreamT : InputStreamProtocol
-
Creates a new pixbuf by loading an image from an input stream.
The file format is detected automatically. If
NULL
is returned, thenerror
will be set. Thecancellable
can be used to abort the operation from another thread. If the operation was cancelled, the errorG_IO_ERROR_CANCELLED
will be returned. Other possible errors are in theGDK_PIXBUF_ERROR
andG_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 aheight
of -1 will cause the image to be scaled to the exact given width. If bothwidth
andheight
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
orheight
of -1 means to not scale the image at all in that dimension.The stream is not closed.
Declaration
Swift
@inlinable init<GioCancellableT, GioInputStreamT>(streamAtScale stream: GioInputStreamT, width: Int, height: Int, preserveAspectRatio: Bool, cancellable: GioCancellableT?) throws where GioCancellableT : CancellableProtocol, GioInputStreamT : InputStreamProtocol
-
Finishes an asynchronous pixbuf creation operation started with
gdk_pixbuf_new_from_stream_async()
.Declaration
Swift
@inlinable init<GioAsyncResultT>(streamFinish asyncResult: GioAsyncResultT) throws where GioAsyncResultT : AsyncResultProtocol
-
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.
Declaration
Swift
@inlinable init(xpmData data: UnsafeMutablePointer<UnsafePointer<CChar>?>!)
-
Creates a new
GdkPixbuf
out of in-memory readonly image data.Currently only RGB images with 8 bits per sample are supported.
This is the
GBytes
variant ofgdk_pixbuf_new_from_data()
, useful for language bindings.Declaration
Swift
@inlinable static func newFrom<GLibBytesT>(bytes data: GLibBytesT, colorspace: GdkColorspace, hasAlpha: Bool, bitsPerSample: Int, width: Int, height: Int, rowstride: Int) -> GdkPixBuf.PixbufRef! where GLibBytesT : BytesProtocol
-
Creates a new
GdkPixbuf
out of in-memory image data.Currently only RGB images with 8 bits per sample are supported.
Since you are providing a pre-allocated pixel buffer, you must also specify a way to free that data. This is done with a function of type
GdkPixbufDestroyNotify
. When a pixbuf created with is finalized, your destroy notification function will be called, and it is its responsibility to free the pixel array.See also: [ctor
GdkPixbuf.Pixbuf.new_from_bytes
]Declaration
Swift
@inlinable static func newFrom(data: UnsafePointer<guchar>!, colorspace: GdkColorspace, hasAlpha: Bool, bitsPerSample: Int, width: Int, height: Int, rowstride: Int, destroyFn: GdkPixbufDestroyNotify? = nil, destroyFnData: gpointer? = nil) -> GdkPixBuf.PixbufRef!
-
Creates a new pixbuf by loading an image from a file.
The file format is detected automatically.
If
NULL
is returned, thenerror
will be set. Possible errors are:- the file could not be opened
- there is no loader for the file’s format
- there is not enough memory to allocate the image buffer
- the image buffer contains invalid data
The error domains are
GDK_PIXBUF_ERROR
andG_FILE_ERROR
.Declaration
Swift
@inlinable static func newFrom(file filename: UnsafePointer<CChar>!) throws -> GdkPixBuf.PixbufRef!
-
Creates a new pixbuf by loading an image from a file.
The file format is detected automatically.
If
NULL
is returned, thenerror
will be set. Possible errors are:- the file could not be opened
- there is no loader for the file’s format
- there is not enough memory to allocate the image buffer
- the image buffer contains invalid data
The error domains are
GDK_PIXBUF_ERROR
andG_FILE_ERROR
.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 aheight
of -1 will cause the image to be scaled to the exact given width. When not preserving aspect ratio, awidth
orheight
of -1 means to not scale the image at all in that dimension. Negative values forwidth
andheight
are allowed since 2.8.Declaration
Swift
@inlinable static func newFrom(fileAtScale filename: UnsafePointer<CChar>!, width: Int, height: Int, preserveAspectRatio: Bool) throws -> GdkPixBuf.PixbufRef!
-
Creates a new pixbuf by loading an image from a file.
The file format is detected automatically.
If
NULL
is returned, thenerror
will be set. Possible errors are:- the file could not be opened
- there is no loader for the file’s format
- there is not enough memory to allocate the image buffer
- the image buffer contains invalid data
The error domains are
GDK_PIXBUF_ERROR
andG_FILE_ERROR
.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
width
xheight
, if the aspect ratio requires it. To load and image at the requested size, regardless of aspect ratio, use [ctorGdkPixbuf.Pixbuf.new_from_file_at_scale
].Declaration
Swift
@inlinable static func newFrom(fileAtSize filename: UnsafePointer<CChar>!, width: Int, height: Int) throws -> GdkPixBuf.PixbufRef!
-
Creates a
GdkPixbuf
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.
GdkPixbuf ships with a program called
gdk-pixbuf-csource
, which allows for conversion ofGdkPixbuf
s into such a inline representation.In almost all cases, you should pass the
--raw
option togdk-pixbuf-csource
. A sample invocation would be:gdk-pixbuf-csource --raw --name=myimage_inline myimage.png
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
FALSE
forcopy_pixels
. If you pass--rle
togdk-pixbuf-csource
, a copy will be made even ifcopy_pixels
isFALSE
, so using this option is generally a bad idea.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:
pixbuf = gdk_pixbuf_new_from_inline (-1, myimage_inline, FALSE, NULL);
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.
new_from_inline is deprecated: Use
GResource
instead.Declaration
Swift
@available(*, deprecated) @inlinable static func newFrom(inline dataLength: Int, data: UnsafePointer<guint8>!, copyPixels: Bool) throws -> GdkPixBuf.PixbufRef!
-
Creates a new pixbuf by loading an image from an resource.
The file format is detected automatically. If
NULL
is returned, thenerror
will be set.Declaration
Swift
@inlinable static func newFrom(resource resourcePath: UnsafePointer<CChar>!) throws -> GdkPixBuf.PixbufRef!
-
Creates a new pixbuf by loading an image from an resource.
The file format is detected automatically. If
NULL
is returned, thenerror
will be set.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 aheight
of -1 will cause the image to be scaled to the exact given width. When not preserving aspect ratio, awidth
orheight
of -1 means to not scale the image at all in that dimension.The stream is not closed.
Declaration
Swift
@inlinable static func newFrom(resourceAtScale resourcePath: UnsafePointer<CChar>!, width: Int, height: Int, preserveAspectRatio: Bool) throws -> GdkPixBuf.PixbufRef!
-
Creates a new pixbuf by loading an image from an input stream.
The file format is detected automatically.
If
NULL
is returned, thenerror
will be set.The
cancellable
can be used to abort the operation from another thread. If the operation was cancelled, the errorG_IO_ERROR_CANCELLED
will be returned. Other possible errors are in theGDK_PIXBUF_ERROR
andG_IO_ERROR
domains.The stream is not closed.
Declaration
Swift
@inlinable static func newFrom<GioCancellableT, GioInputStreamT>(stream: GioInputStreamT, cancellable: GioCancellableT?) throws -> GdkPixBuf.PixbufRef! where GioCancellableT : CancellableProtocol, GioInputStreamT : InputStreamProtocol
-
Creates a new pixbuf by loading an image from an input stream.
The file format is detected automatically. If
NULL
is returned, thenerror
will be set. Thecancellable
can be used to abort the operation from another thread. If the operation was cancelled, the errorG_IO_ERROR_CANCELLED
will be returned. Other possible errors are in theGDK_PIXBUF_ERROR
andG_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 aheight
of -1 will cause the image to be scaled to the exact given width. If bothwidth
andheight
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
orheight
of -1 means to not scale the image at all in that dimension.The stream is not closed.
Declaration
Swift
@inlinable static func newFrom<GioCancellableT, GioInputStreamT>(streamAtScale stream: GioInputStreamT, width: Int, height: Int, preserveAspectRatio: Bool, cancellable: GioCancellableT?) throws -> GdkPixBuf.PixbufRef! where GioCancellableT : CancellableProtocol, GioInputStreamT : InputStreamProtocol
-
Finishes an asynchronous pixbuf creation operation started with
gdk_pixbuf_new_from_stream_async()
.Declaration
Swift
@inlinable static func newFrom<GioAsyncResultT>(streamFinish asyncResult: GioAsyncResultT) throws -> GdkPixBuf.PixbufRef! where GioAsyncResultT : AsyncResultProtocol
-
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.
Declaration
Swift
@inlinable static func newFromXpm(xpmData data: UnsafeMutablePointer<UnsafePointer<CChar>?>!) -> GdkPixBuf.PixbufRef!