Package org.gnome.gdk

Class Texture

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.gdk.Texture

All Implemented Interfaces:

Paintable, Icon, LoadableIcon, Proxy

Direct Known Subclasses:

DmabufTexture, GLTexture, MemoryTexture, Texture.Texture$Impl

@Generated("io.github.jwharm.JavaGI")
public abstract class Texture
extends GObject
implements Paintable, Icon, 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 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 download(byte[], long).

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

GDK provides a number of threadsafe texture loading functions: fromResource(java.lang.String), fromBytes(byte[]), fromFile(org.gnome.gio.File), fromFilename(java.lang.String), forPixbuf(org.gnome.gdkpixbuf.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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Texture.Builder<B extends Texture.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static class	Texture.Texture$Impl	The Texture$Impl type represents a native instance of the abstract Texture class.
static class	Texture.TextureClass

Nested classes/interfaces inherited from class org.gnome.gobject.GObject

GObject.NotifyCallback, GObject.ObjectClass

Nested classes/interfaces inherited from interface org.gnome.gio.Icon

Icon.Icon$Impl, Icon.IconIface

Nested classes/interfaces inherited from interface org.gnome.gio.LoadableIcon

LoadableIcon.LoadableIcon$Impl, LoadableIcon.LoadableIconIface

Nested classes/interfaces inherited from interface org.gnome.gdk.Paintable

Paintable.InvalidateContentsCallback, Paintable.InvalidateSizeCallback, Paintable.Paintable$Impl, Paintable.PaintableInterface

Constructor Summary

Constructors

Constructor	Description
Texture()	Creates a new Texture.
Texture(MemorySegment address)	Create a Texture proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
protected Texture	asParent()	Returns this instance as if it were its parent type.
void	download(@org.jspecify.annotations.Nullable byte @Nullable [] data, long stride)	Downloads the this Texture into local memory.
static Texture	forPixbuf(Pixbuf pixbuf)	Deprecated. Use e.g.
static Texture	fromBytes(byte[] bytes)	Creates a new texture by loading an image from memory,
static Texture	fromFile(File file)	Creates a new texture by loading an image from a file.
static Texture	fromFilename(String path)	Creates a new texture by loading an image from a file.
static Texture	fromResource(String resourcePath)	Creates a new texture by loading an image from a resource.
ColorState	getColorState()	Returns the color state associated with the texture.
MemoryFormat	getFormat()	Gets the memory format most closely associated with the data of the texture.
int	getHeight()	Returns the height of the texture, in pixels.
static @Nullable Type	getType()	Get the GType of the Texture class
int	getWidth()	Returns the width of texture, in pixels.
boolean	saveToPng(String filename)	Store the given this Texture to the filename as a PNG file.
byte[]	saveToPngBytes()	Store the given this Texture in memory as a PNG file.
boolean	saveToTiff(String filename)	Store the given this Texture to the filename as a TIFF file.
byte[]	saveToTiffBytes()	Store the given this Texture in memory as a TIFF file.

Methods inherited from class org.gnome.gobject.GObject

addToggleRef, addWeakPointer, bindProperty, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, builder, compatControl, connect, connect, connect, constructed, disconnect, dispatchPropertiesChanged, dispose, dupData, dupQdata, emit, emitNotify, finalize_, forceFloating, freezeNotify, get, getData, getMemoryLayout, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, newv, notify, notify, notifyByPspec, onNotify, ref, refSink, removeToggleRef, removeWeakPointer, replaceData, replaceQdata, runDispose, set, setData, setDataFull, setProperty, setProperty, setProperty, setQdata, setQdataFull, setv, stealData, stealQdata, takeRef, thawNotify, unref, watchClosure, weakRef, weakUnref, withProperties

Methods inherited from class org.gnome.gobject.TypeInstance

callParent, callParent, cast, getPrivate, readGClass, writeGClass

Methods inherited from class org.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.gnome.gio.Icon

equal, hash, serialize, serializeToString

Methods inherited from interface org.gnome.gio.LoadableIcon

load, loadAsync, loadFinish

Methods inherited from interface org.gnome.gdk.Paintable

computeConcreteSize, emitInvalidateContents, emitInvalidateSize, getCurrentImage, getFlags, getIntrinsicAspectRatio, getIntrinsicHeight, getIntrinsicWidth, invalidateContents, invalidateSize, onInvalidateContents, onInvalidateSize, snapshot

Methods inherited from interface org.javagi.base.Proxy

handle

Constructor Details

Texture

public Texture(MemorySegment address)

Create a Texture proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Texture

public Texture()

Creates a new Texture.

Method Details

getType

public static @Nullable Type getType()

Get the GType of the Texture class

Returns:

the GType

asParent

protected Texture asParent()

Returns this instance as if it were its parent type. This is mostly synonymous to the Java super keyword, but will set the native typeclass function pointers to the parent type. When overriding a native virtual method in Java, "chaining up" with super.methodName() doesn't work, because it invokes the overridden function pointer again. To chain up, call asParent().methodName(). This will call the native function pointer of this virtual method in the typeclass of the parent type.

Overrides:

asParent in class GObject

forPixbuf

@Deprecated
public static Texture forPixbuf(Pixbuf pixbuf)

Deprecated.

Use e.g. libglycin, which can load many image formats into a GdkTexture

Creates a new texture object representing the GdkPixbuf.

This function is threadsafe, so that you can e.g. use GTask and Task.runInThread(org.gnome.gio.TaskThreadFunc) to avoid blocking the main thread while loading a big image.

Parameters:

pixbuf - a GdkPixbuf

Returns:

a new GdkTexture

fromBytes

public static Texture fromBytes(byte[] bytes)
                         throws GErrorException

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 Task.runInThread(org.gnome.gio.TaskThreadFunc) 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

Returns:

A newly-created GdkTexture

Throws:

GErrorException - see GError

Since:

4.6

fromFile

public static Texture fromFile(File file)
                        throws GErrorException

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 Task.runInThread(org.gnome.gio.TaskThreadFunc) 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

Returns:

A newly-created GdkTexture

Throws:

GErrorException - see GError

fromFilename

public static Texture fromFilename(String path)
                            throws GErrorException

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 Task.runInThread(org.gnome.gio.TaskThreadFunc) 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

Returns:

A newly-created GdkTexture

Throws:

GErrorException - see GError

Since:

4.6

fromResource

public static Texture fromResource(String resourcePath)

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 resourcePath 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 fromFile(org.gnome.gio.File) to load it.

This function is threadsafe, so that you can e.g. use GTask and Task.runInThread(org.gnome.gio.TaskThreadFunc) to avoid blocking the main thread while loading a big image.

Parameters:

resourcePath - the path of the resource file

Returns:

A newly-created GdkTexture

download

public void download(@org.jspecify.annotations.Nullable byte @Nullable [] data,
 long stride)

Downloads the this 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 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 Gdk.TextureDownloader.

Parameters:

data - pointer to enough memory to be filled with the downloaded data of this Texture

stride - rowstride in bytes

getColorState

public ColorState getColorState()

Returns the color state associated with the texture.

Returns:

the color state of the GdkTexture

Since:

4.16

getFormat

public MemoryFormat getFormat()

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.

Returns:

the preferred format for the texture's data

Since:

4.10

getHeight

public int getHeight()

Returns the height of the texture, in pixels.

Returns:

the height of the GdkTexture

getWidth

public int getWidth()

Returns the width of texture, in pixels.

Returns:

the width of the GdkTexture

saveToPng

public boolean saveToPng(String filename)

Store the given this 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 File or other location, you might want to use saveToPngBytes() or look into the libglycin library.

Parameters:

filename - the filename to store to

Returns:

true if saving succeeded, false on failure.

saveToPngBytes

public byte[] saveToPngBytes()

Store the given this Texture in memory as a PNG file.

Use fromBytes(byte[]) 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 saveToTiffBytes() instead.

Returns:

a newly allocated GBytes containing PNG data

Since:

4.6

saveToTiff

public boolean saveToTiff(String filename)

Store the given this Texture to the filename as a TIFF file.

GTK will attempt to store data without loss.

Parameters:

filename - the filename to store to

Returns:

true if saving succeeded, false on failure.

Since:

4.6

saveToTiffBytes

public byte[] saveToTiffBytes()

Store the given this Texture in memory as a TIFF file.

Use fromBytes(byte[]) 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 saveToPngBytes().

Returns:

a newly allocated GBytes containing TIFF data

Since:

4.6