GLTextureBuilder

Added in version 4.12.

class GLTextureBuilder(**properties: Any)

Superclasses: Object

GdkGLTextureBuilder is a builder used to construct Texture objects from GL textures.

The operation is quite simple: Create a texture builder, set all the necessary properties - keep in mind that the properties context, id, width, and height are mandatory - and then call build to create the new texture.

GdkGLTextureBuilder can be used for quick one-shot construction of textures as well as kept around and reused to construct multiple textures.

Constructors

class GLTextureBuilder

classmethod new() → GLTextureBuilder

Creates a new texture builder.

Added in version 4.12.

Methods

class GLTextureBuilder

build(destroy: Callable[[None], None] | None, data: None) → Texture

Builds a new GdkTexture with the values set up in the builder.

The destroy function gets called when the returned texture gets released; either when the texture is finalized or by an explicit call to release. It should release all GL resources associated with the texture, such as the id and the sync.

Note that it is a programming error to call this function if any mandatory property has not been set.

It is possible to call this function multiple times to create multiple textures, possibly with changing properties in between.

Added in version 4.12.

Parameters:

• destroy – destroy function to be called when the texture is released

• data – user data to pass to the destroy function

get_context() → GLContext | None

Gets the context previously set via set_context() or None if none was set.

Added in version 4.12.

get_format() → MemoryFormat

Gets the format previously set via set_format().

Added in version 4.12.

get_has_mipmap() → bool

Gets whether the texture has a mipmap.

Added in version 4.12.

get_height() → int

Gets the height previously set via set_height() or 0 if the height wasn’t set.

Added in version 4.12.

get_id() → int

Gets the texture id previously set via set_id() or 0 if the id wasn’t set.

Added in version 4.12.

get_sync() → None

Gets the GLsync previously set via set_sync().

Added in version 4.12.

get_update_region() → Region | None

Gets the region previously set via set_update_region() or None if none was set.

Added in version 4.12.

get_update_texture() → Texture | None

Gets the texture previously set via set_update_texture() or None if none was set.

Added in version 4.12.

get_width() → int

Gets the width previously set via set_width() or 0 if the width wasn’t set.

Added in version 4.12.

set_context(context: GLContext | None = None) → None

Sets the context to be used for the texture. This is the context that owns the texture.

The context must be set before calling build.

Added in version 4.12.

Parameters:

context – The context the texture beongs to or None to unset

set_format(format: MemoryFormat) → None

Sets the format of the texture. The default is GDK_MEMORY_R8G8B8A8_PREMULTIPLIED.

The format is the preferred format the texture data should be downloaded to. The format must be supported by the GL version of context.

GDK’s texture download code assumes that the format corresponds to the storage parameters of the GL texture in an obvious way. For example, a format of GDK_MEMORY_R16G16B16A16_PREMULTIPLIED is expected to be stored as GL_RGBA16 texture, and GDK_MEMORY_G8A8 is expected to be stored as GL_RG8 texture.

Setting the right format is particularly useful when using high bit depth textures to preserve the bit depth, to set the correct value for unpremultiplied textures and to make sure opaque textures are treated as such.

Non-RGBA textures need to have swizzling parameters set up properly to be usable in GSK’s shaders.

Added in version 4.12.

Parameters:

format – The texture’s format

set_has_mipmap(has_mipmap: bool) → None

Sets whether the texture has a mipmap. This allows the renderer and other users of the generated texture to use a higher quality downscaling.

Typically, the glGenerateMipmap function is used to generate a mimap.

Added in version 4.12.

Parameters:

has_mipmap – Whether the texture has a mipmap

set_height(height: int) → None

Sets the height of the texture.

The height must be set before calling build.

Added in version 4.12.

Parameters:

height – The texture’s height or 0 to unset

set_id(id: int) → None

Sets the texture id of the texture. The texture id must remain unmodified until the texture was finalized. See build for a longer discussion.

The id must be set before calling build.

Added in version 4.12.

Parameters:

id – The texture id to be used for creating the texture

set_sync(sync: None) → None

Sets the GLSync object to use for the texture.

GTK will wait on this object before using the created GdkTexture.

The destroy function that is passed to build is responsible for freeing the sync object when it is no longer needed. The texture builder does not destroy it and it is the callers responsibility to make sure it doesn’t leak.

Added in version 4.12.

Parameters:

sync – the GLSync object

set_update_region(region: Region | None = None) → None

Sets the region to be updated by this texture. Together with update_texture this describes an update of a previous texture.

When rendering animations of large textures, it is possible that consecutive textures are only updating contents in parts of the texture. It is then possible to describe this update via these two properties, so that GTK can avoid rerendering parts that did not change.

An example would be a screen recording where only the mouse pointer moves.

Added in version 4.12.

Parameters:

region – the region to update

set_update_texture(texture: Texture | None = None) → None

Sets the texture to be updated by this texture. See set_update_region for an explanation.

Added in version 4.12.

Parameters:

texture – the texture to update

set_width(width: int) → None

Sets the width of the texture.

The width must be set before calling build.

Added in version 4.12.

Parameters:

width – The texture’s width or 0 to unset

Properties

class GLTextureBuilder

props.context: GLContext

The context owning the texture.

Added in version 4.12.

props.format: MemoryFormat

The format when downloading the texture.

Added in version 4.12.

props.has_mipmap: bool

If the texture has a mipmap.

Added in version 4.12.

props.height: int

The height of the texture.

Added in version 4.12.

props.id: int

The texture ID to use.

Added in version 4.12.

props.sync: None

An optional GLSync object.

If this is set, GTK will wait on it before using the texture.

Added in version 4.12.

props.update_region: Region

The update region for update_texture.

Added in version 4.12.

props.update_texture: Texture

The texture update_region is an update for.

Added in version 4.12.

props.width: int

The width of the texture.

Added in version 4.12.