GdkTexture

GdkTexture — Pixel data

Properties

gint height Read / Write / Construct Only
gint width Read / Write / Construct Only

Types and Values

Object Hierarchy

    GObject
    ╰── GdkTexture

Implemented Interfaces

GdkTexture implements GdkPaintable.

Includes

#include <gdk/gdk.h>

Description

GdkTexture is the basic element used to refer to pixel data. It is primarily mean for pixel data that will not change over multiple frames, and will be used for a long time.

You cannot get your pixel data back once you've uploaded it.

GdkTexture is an immutable object: That means you cannot change anything about it other than increasing the reference count via g_object_ref().

Functions

gdk_texture_new_for_pixbuf ()

GdkTexture *
gdk_texture_new_for_pixbuf (GdkPixbuf *pixbuf);

Creates a new texture object representing the GdkPixbuf.

Parameters

pixbuf

a GdkPixbuf

 

Returns

a new GdkTexture


gdk_texture_new_from_resource ()

GdkTexture *
gdk_texture_new_from_resource (const char *resource_path);

Creates a new texture by loading an image from a resource. The file format is detected automatically.

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.

Parameters

resource_path

the path of the resource file

 

Returns

A newly-created texture


gdk_texture_new_from_file ()

GdkTexture *
gdk_texture_new_from_file (GFile *file,
                           GError **error);

Creates a new texture by loading an image from a file. The file format is detected automatically. If NULL is returned, then error will be set.

Parameters

file

GFile to load

 

error

Return location for an error

 

Returns

A newly-created GdkTexture or NULL if an error occured.


gdk_texture_get_width ()

int
gdk_texture_get_width (GdkTexture *texture);

Returns the width of texture .

Parameters

texture

a GdkTexture

 

Returns

the width of the GdkTexture


gdk_texture_get_height ()

int
gdk_texture_get_height (GdkTexture *texture);

Returns the height of the texture .

Parameters

texture

a GdkTexture

 

Returns

the height of the GdkTexture


gdk_texture_download ()

void
gdk_texture_download (GdkTexture *texture,
                      guchar *data,
                      gsize stride);

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);

Parameters

texture

a GdkTexture

 

data

pointer to enough memory to be filled with the downloaded data of texture .

[array]

stride

rowstride in bytes

 

gdk_texture_save_to_png ()

gboolean
gdk_texture_save_to_png (GdkTexture *texture,
                         const char *filename);

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 GFile or other location, you might want to look into using the gdk-pixbuf library.

Parameters

texture

a GdkTexture

 

filename

the filename to store to

 

Returns

TRUE if saving succeeded, FALSE on failure.


gdk_memory_texture_new ()

GdkTexture *
gdk_memory_texture_new (int width,
                        int height,
                        GdkMemoryFormat format,
                        GBytes *bytes,
                        gsize stride);

Creates a new texture for a blob of image data. The GBytes must contain stride x height pixels in the given format.

Parameters

width

the width of the texture

 

height

the height of the texture

 

format

the format of the data

 

bytes

the GBytes containing the pixel data

 

stride

rowstride for the data

 

Returns

A newly-created GdkTexture


gdk_gl_texture_new ()

GdkTexture *
gdk_gl_texture_new (GdkGLContext *context,
                    guint id,
                    int width,
                    int height,
                    GDestroyNotify destroy,
                    gpointer data);

Creates a new texture for an existing GL texture.

Note that the GL texture must not be modified until destroy is called, which will happen when the GdkTexture object is finalized, or due to an explicit call of gdk_texture_release_gl().

Parameters

context

a GdkGLContext

 

id

the ID of a texture that was created with context

 

width

the nominal width of the texture

 

height

the nominal height of the texture

 

destroy

a destroy notify that will be called when the GL resources are released

 

data

data that gets passed to destroy

 

Returns

A newly-created GdkTexture.

[transfer full]


gdk_gl_texture_release ()

void
gdk_gl_texture_release (GdkGLTexture *self);

Releases the GL resources held by a GdkGLTexture that was created with gdk_gl_texture_new().

The texture contents are still available via the gdk_texture_download() function, after this function has been called.

Parameters

self

a GdkTexture wrapping a GL texture

 

Types and Values

GdkTexture

typedef struct _GdkTexture GdkTexture;

The GdkTexture structure contains only private data.


enum GdkMemoryFormat

GdkMemoryFormat describes a format that bytes can have in memory.

It describes formats by listing the contents of the memory passed to it. So GDK_MEMORY_A8R8G8B8 will be 1 byte (8 bits) of alpha, followed by a byte each of red, green and blue. It is not endian-dependent, so CAIRO_FORMAT_ARGB32 is represented by different GdkMemoryFormats on architectures with different endiannesses.

Its naming is modelled after VkFormat (see https://www.khronos.org/registry/vulkan/specs/1.0/html/vkspec.htmlVkFormat for details).

Members

GDK_MEMORY_B8G8R8A8_PREMULTIPLIED

4 bytes; for blue, green, red, alpha. The color values are premultiplied with the alpha value.

 

GDK_MEMORY_A8R8G8B8_PREMULTIPLIED

4 bytes; for alpha, red, green, blue. The color values are premultiplied with the alpha value.

 

GDK_MEMORY_B8G8R8A8

4 bytes; for blue, green, red, alpha.

 

GDK_MEMORY_A8R8G8B8

4 bytes; for alpha, red, green, blue.

 

GDK_MEMORY_R8G8B8A8

4 bytes; for red, green, blue, alpha.

 

GDK_MEMORY_A8B8G8R8

4 bytes; for alpha, blue, green, red.

 

GDK_MEMORY_R8G8B8

3 bytes; for red, green, blue. The data is opaque.

 

GDK_MEMORY_B8G8R8

3 bytes; for blue, green, red. The data is opaque.

 

GDK_MEMORY_N_FORMATS

The number of formats. This value will change as more formats get added, so do not rely on its concrete integer.

 

GDK_MEMORY_DEFAULT

#define GDK_MEMORY_DEFAULT GDK_MEMORY_B8G8R8A8_PREMULTIPLIED

This is the default memory format used by GTK and is the format provided by gdk_texture_download(). It is equal to CAIRO_FORMAT_ARGB32.

Be aware that unlike the GdkMemoryFormat values, this format is different for different endianness.

Property Details

The “height” property

  “height”                   gint

The height of the texture.

Flags: Read / Write / Construct Only

Allowed values: >= 1

Default value: 1


The “width” property

  “width”                    gint

The width of the texture.

Flags: Read / Write / Construct Only

Allowed values: >= 1

Default value: 1