class Gdk::Texture

Overview

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 Gdk::Texture objects from a Gdk::Pixbuf::Pixbuf, or from bytes stored in memory, a file, or a Gio::Resource.

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

Gdk::Texture 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: Gdk::Texture#new_from_resource, Gdk::Texture#new_from_bytes, Gdk::Texture#new_from_file, Gdk::Texture#new_from_filename, Gdk::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.

Included Modules

Direct Known Subclasses

Defined in:

lib/gi-crystal/src/auto/gdk-4.0/texture.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from module Gio::LoadableIcon

load(size : Int32, cancellable : Gio::Cancellable | Nil) : Gio::InputStream load, load_async(size : Int32, cancellable : Gio::Cancellable | Nil, &callback : Gio::AsyncReadyCallback) : Nil load_async, load_finish(res : Gio::AsyncResult) : Gio::InputStream load_finish, to_unsafe to_unsafe

Constructor methods inherited from module Gio::LoadableIcon

cast(obj : GObject::Object) : self cast

Class methods inherited from module Gio::LoadableIcon

cast?(obj : GObject::Object) : self | Nil cast?, g_type : UInt64 g_type

Instance methods inherited from module Gio::Icon

equal(icon2 : Gio::Icon | Nil) : Bool equal, hash : UInt32 hash, new_for_string(str : String) : Gio::Icon new_for_string, serialize : GLib::Variant | Nil serialize, to_string : String | Nil to_string, to_unsafe to_unsafe

Constructor methods inherited from module Gio::Icon

cast(obj : GObject::Object) : self cast

Class methods inherited from module Gio::Icon

cast?(obj : GObject::Object) : self | Nil cast?, deserialize(value : _) : Gio::Icon | Nil deserialize, g_type : UInt64 g_type

Instance methods inherited from module Gdk::Paintable

compute_concrete_size(specified_width : Float64, specified_height : Float64, default_width : Float64, default_height : Float64, concrete_width : Float64, concrete_height : Float64) : Nil compute_concrete_size, current_image : Gdk::Paintable current_image, flags : Gdk::PaintableFlags flags, intrinsic_aspect_ratio : Float64 intrinsic_aspect_ratio, intrinsic_height : Int32 intrinsic_height, intrinsic_width : Int32 intrinsic_width, invalidate_contents : Nil invalidate_contents, invalidate_contents_signal invalidate_contents_signal, invalidate_size : Nil invalidate_size, invalidate_size_signal invalidate_size_signal, snapshot(snapshot : Gdk::Snapshot, width : Float64, height : Float64) : Nil snapshot, to_unsafe to_unsafe

Constructor methods inherited from module Gdk::Paintable

cast(obj : GObject::Object) : self cast

Class methods inherited from module Gdk::Paintable

cast?(obj : GObject::Object) : self | Nil cast?, g_type : UInt64 g_type, new_empty(intrinsic_width : Int32, intrinsic_height : Int32) : Gdk::Paintable new_empty

Instance methods inherited from class GObject::Object

==(other : self) ==, bind_property(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags) : GObject::Binding bind_property, bind_property_full(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags, transform_to : GObject::Closure, transform_from : GObject::Closure) : GObject::Binding bind_property_full, data(key : String) : Pointer(Void) | Nil data, finalize finalize, freeze_notify : Nil freeze_notify, getv(names : Enumerable(String), values : Enumerable(_)) : Nil getv, hash(hasher) hash, notify(property_name : String) : Nil notify, notify_by_pspec(pspec : GObject::ParamSpec) : Nil notify_by_pspec, notify_signal notify_signal, property(property_name : String, value : _) : Nil property, qdata(quark : UInt32) : Pointer(Void) | Nil qdata, ref_count : UInt32 ref_count, run_dispose : Nil run_dispose, set_data(key : String, data : Pointer(Void) | Nil) : Nil set_data, set_property(property_name : String, value : _) : Nil set_property, steal_data(key : String) : Pointer(Void) | Nil steal_data, steal_qdata(quark : UInt32) : Pointer(Void) | Nil steal_qdata, thaw_notify : Nil thaw_notify, to_unsafe : Pointer(Void) to_unsafe, watch_closure(closure : GObject::Closure) : Nil watch_closure

Constructor methods inherited from class GObject::Object

cast(obj : GObject::Object) : self cast, new(pointer : Pointer(Void), transfer : GICrystal::Transfer)
new new, newv(object_type : UInt64, parameters : Enumerable(GObject::Parameter)) : self newv

Class methods inherited from class GObject::Object

cast?(obj : GObject::Object) : self | Nil cast?, compat_control(what : UInt64, data : Pointer(Void) | Nil) : UInt64 compat_control, g_type : UInt64 g_type, interface_find_property(g_iface : GObject::TypeInterface, property_name : String) : GObject::ParamSpec interface_find_property, interface_list_properties(g_iface : GObject::TypeInterface) : Enumerable(GObject::ParamSpec) interface_list_properties

Macros inherited from class GObject::Object

previous_vfunc(*args) previous_vfunc, previous_vfunc!(*args) previous_vfunc!, signal(signature) signal

Constructor Detail

def self.new #

Initialize a new Texture.


def self.new(*, color_state : Gdk::ColorState | Nil = nil, height : Int32 | Nil = nil, width : Int32 | Nil = nil) #

def self.new_for_pixbuf(pixbuf : GdkPixbuf::Pixbuf) : self #

Creates a new texture object representing the Gdk::Pixbuf.

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.


def self.new_from_bytes(bytes : GLib::Bytes) : self #

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 nil 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.


def self.new_from_file(file : Gio::File) : self #

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 nil 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.


def self.new_from_filename(path : String) : self #

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 nil 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.


def self.new_from_resource(resource_path : String) : self #

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

The file format is detected automatically. The supported formats are PNG and JPEG, 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 Gdk::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.


Class Method Detail

def self.g_type : UInt64 #

Returns the type id (GType) registered in GLib type system.


Instance Method Detail

def ==(other : self) #
Description copied from class Reference

Returns true if this reference is the same as other. Invokes same?.


def color_state : Gdk::ColorState #

Returns the color state associated with the texture.


def color_state=(value : Gdk::ColorState | Nil) : Gdk::ColorState | Nil #

def download(data : Bytes, stride : UInt64) : Nil #

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:

WARNING ⚠️ The following code is in c ⚠️

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 Gdk::TextureDownloader.


def format : Gdk::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.


def hash(hasher) #
Description copied from class Reference

See Object#hash(hasher)


def height : Int32 #

Returns the height of the texture, in pixels.


def height=(value : Int32) : Int32 #

def save_to_png(filename : String) : 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 Gdk::Texture#save_to_png_bytes or look into the gdk-pixbuf library.


def save_to_png_bytes : GLib::Bytes #

Store the given texture in memory as a PNG file.

Use Gdk::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 gdk-pixbuf library.

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


def save_to_tiff(filename : String) : Bool #

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

GTK will attempt to store data without loss.


def save_to_tiff_bytes : GLib::Bytes #

Store the given texture in memory as a TIFF file.

Use Gdk::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 Gdk::Texture#save_to_png_bytes.


def width : Int32 #

Returns the width of texture, in pixels.


def width=(value : Int32) : Int32 #