## GdkTexture GdkTexture — Pixel data |

## Functions

GdkTexture * | gdk_texture_new_for_pixbuf ()
GdkTexture * | gdk_texture_new_from_resource ()
GdkTexture * | gdk_texture_new_from_file ()
int | gdk_texture_get_width ()
int | gdk_texture_get_height ()
void | gdk_texture_download ()
gboolean | gdk_texture_save_to_png ()
GdkTexture * | gdk_memory_texture_new ()
GdkTexture * | gdk_gl_texture_new ()
void | gdk_gl_texture_release ()

## Properties

int | height | Read / Write / Construct Only
int | width | Read / Write / Construct Only

## Types and Values

| GdkTexture
| GdkMemoryTexture
| GdkGLTexture
enum | GdkMemoryFormat
#define | GDK_MEMORY_DEFAULT

## Object Hierarchy

        GObject
        ╰── GdkTexture
            ├── GdkGLTexture
            ╰── GdkMemoryTexture

## Implemented Interfaces

GdkTexture implements GdkPaintable.

GdkMemoryTexture implements GdkPaintable.

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

There are various ways to create GdkTexture objects from a GdkPixbuf, or a Cairo surface, or other pixel data.

The ownership of the pixel data is transferred to the GdkTexture instance; you can only make a copy of it, via `gdk_texture_download()`.

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

### 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:

    1
    2
    3
    4
    5
    6
    7
    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_gl_texture_release()`.

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

### GdkMemoryTexture

    typedef struct _GdkMemoryTexture GdkMemoryTexture;

### GdkGLTexture

    typedef struct _GdkGLTexture GdkGLTexture;

### 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_R8G8B8A8_PREMULTIPLIED | 4 bytes; for red, green, blue, alpha 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”                   int

The height of the texture.

Owner: GdkTexture

Flags: Read / Write / Construct Only

Allowed values: >= 1

Default value: 1

### The `“width”` property

      “width”                    int

The width of the texture.

Owner: GdkTexture

Flags: Read / Write / Construct Only

Allowed values: >= 1

Default value: 1