Gdk.Texture¶

class — extends GObject.Object, Paintable, Gio.Icon, Gio.LoadableIcon

Refers to pixel data in various forms.

It is primarily meant for pixel data that will not change over multiple frames, and will be used for a long time.

There are various ways to create GdkTexture objects from a GdkPixbuf.Pixbuf, or from bytes stored in memory, a file, or a Gio.Resource.

The ownership of the pixel data is transferred to the GdkTexture instance; you can only make a copy of it, via Texture.download.

GdkTexture is an immutable object: That means you cannot change anything about it other than increasing the reference count via GObject.Object.ref, and consequently, it is a threadsafe object.

GDK provides a number of threadsafe texture loading functions: Texture.new_from_resource, Texture.new_from_bytes, Texture.new_from_file, Texture.new_from_filename, Texture.new_for_pixbuf. Note that these are meant for loading icons and resources that are shipped with the toolkit or application. It is recommended that you use a dedicated image loading framework such as glycin, if you need to load untrusted image data.

Constructors¶

new_for_pixbuf¶

@classmethod
def new_for_pixbuf(cls, pixbuf: GdkPixbuf.Pixbuf) -> Texture

:::warning Deprecated since 4.20 This API is deprecated. :::

Creates a new texture object representing the GdkPixbuf.

This function is threadsafe, so that you can e.g. use GTask and Gio.Task.run_in_thread to avoid blocking the main thread while loading a big image.

Parameters:

pixbuf — a GdkPixbuf

new_from_bytes¶

@classmethod
def new_from_bytes(cls, bytes: bytes) -> Texture

Creates a new texture by loading an image from memory,

The file format is detected automatically. The supported formats are PNG, JPEG and TIFF, though more formats might be available.

If NULL is returned, then error will be set.

This function is threadsafe, so that you can e.g. use GTask and Gio.Task.run_in_thread to avoid blocking the main thread while loading a big image.

::: warning Note that this function should not be used with untrusted data. Use a proper image loading framework such as libglycin, which can load many image formats into a GdkTexture.

Parameters:

bytes — a GBytes containing the data to load

new_from_file¶

@classmethod
def new_from_file(cls, file: Gio.File) -> Texture

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

The file format is detected automatically. The supported formats are PNG, JPEG and TIFF, though more formats might be available.

If NULL is returned, then error will be set.

This function is threadsafe, so that you can e.g. use GTask and Gio.Task.run_in_thread to avoid blocking the main thread while loading a big image.

::: warning Note that this function should not be used with untrusted data. Use a proper image loading framework such as libglycin, which can load many image formats into a GdkTexture.

Parameters:

file — GFile to load

new_from_filename¶

@classmethod
def new_from_filename(cls, path: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> Texture

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

The file format is detected automatically. The supported formats are PNG, JPEG and TIFF, though more formats might be available.

If NULL is returned, then error will be set.

This function is threadsafe, so that you can e.g. use GTask and Gio.Task.run_in_thread to avoid blocking the main thread while loading a big image.

::: warning Note that this function should not be used with untrusted data. Use a proper image loading framework such as libglycin, which can load many image formats into a GdkTexture.

Parameters:

path — the filename to load

new_from_resource¶

@classmethod
def new_from_resource(cls, resource_path: str) -> Texture

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

The file format is detected automatically. The supported formats are PNG, JPEG and TIFF, though more formats might be available.

It is a fatal error if resource_path does not specify a valid image resource and the program will abort if that happens. If you are unsure about the validity of a resource, use Texture.new_from_file to load it.

This function is threadsafe, so that you can e.g. use GTask and Gio.Task.run_in_thread to avoid blocking the main thread while loading a big image.

Parameters:

resource_path — the path of the resource file

Methods¶

download¶

def download(self, data: list[int], stride: int) -> None

Downloads the texture into local memory.

This may be an expensive operation, as the actual texture data may reside on a GPU or on a remote display server.

The data format of the downloaded data is equivalent to CAIRO_FORMAT_ARGB32, so every downloaded pixel requires 4 bytes of memory.

Downloading a texture into a Cairo image surface:

surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
                                      gdk_texture_get_width (texture),
                                      gdk_texture_get_height (texture));
gdk_texture_download (texture,
                      cairo_image_surface_get_data (surface),
                      cairo_image_surface_get_stride (surface));
cairo_surface_mark_dirty (surface);

For more flexible download capabilities, see TextureDownloader.

Parameters:

data — pointer to enough memory to be filled with the downloaded data of texture
stride — rowstride in bytes

get_color_state¶

def get_color_state(self) -> ColorState

Returns the color state associated with the texture.

get_format¶

def get_format(self) -> MemoryFormat

Gets the memory format most closely associated with the data of the texture.

Note that it may not be an exact match for texture data stored on the GPU or with compression.

The format can give an indication about the bit depth and opacity of the texture and is useful to determine the best format for downloading the texture.

get_height¶

def get_height(self) -> int

Returns the height of the texture, in pixels.

get_width¶

def get_width(self) -> int

Returns the width of texture, in pixels.

save_to_png¶

def save_to_png(self, filename: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> bool

Store the given texture to the filename as a PNG file.

This is a utility function intended for debugging and testing. If you want more control over formats, proper error handling or want to store to a Gio.File or other location, you might want to use Texture.save_to_png_bytes or look into the libglycin library.

Parameters:

filename — the filename to store to

save_to_png_bytes¶

def save_to_png_bytes(self) -> bytes

Store the given texture in memory as a PNG file.

Use Texture.new_from_bytes to read it back.

If you want to serialize a texture, this is a convenient and portable way to do that.

If you need more control over the generated image, such as attaching metadata, you should look into an image handling library such as the libglycin library.

If you are dealing with high dynamic range float data, you might also want to consider Texture.save_to_tiff_bytes instead.

save_to_tiff¶

def save_to_tiff(self, filename: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> bool

Store the given texture to the filename as a TIFF file.

GTK will attempt to store data without loss.

Parameters:

filename — the filename to store to

save_to_tiff_bytes¶

def save_to_tiff_bytes(self) -> bytes

Store the given texture in memory as a TIFF file.

Use Texture.new_from_bytes to read it back.

This function is intended to store a representation of the texture's data that is as accurate as possible. This is particularly relevant when working with high dynamic range images and floating-point texture data.

If that is not your concern and you are interested in a smaller size and a more portable format, you might want to use Texture.save_to_png_bytes.

Properties¶

color_state¶

color_state: ColorState  # read/write

The color state of the texture.

height¶

height: int  # read/write

The height of the texture, in pixels.

width¶

width: int  # read/write

The width of the texture, in pixels.