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("org.javagi.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(String), fromBytes(byte[]), fromFile(File), fromFilename(String), forPixbuf(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.

  • Constructor Details

    • Texture

      public Texture(MemorySegment address)
      Create a Texture instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • Texture

      public Texture()
      Create a new Texture.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the Texture class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected Texture asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class GObject
      Returns:
      the instance as if it were its parent type

    • 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 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 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 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 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(File) to load it.

      This function is threadsafe, so that you can e.g. use GTask and Task#runInThread 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(@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