GLTextureBuilder#
Added in version 4.12.
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[[Any], None] | None = None, data: Any = 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 torelease
. It should release all GL resources associated with the texture, such as theid
and thesync
.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_color_state() ColorState #
Gets the color state previously set via
set_color_state()
.Added in version 4.16.
- get_context() GLContext | None #
Gets the context previously set via
set_context()
orNone
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_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() Any | None #
Gets the
GLsync
previously set viaset_sync()
.Added in version 4.12.
- get_update_region() Region | None #
Gets the region previously set via
set_update_region()
orNone
if none was set.Added in version 4.12.
- get_update_texture() Texture | None #
Gets the texture previously set via
set_update_texture()
orNone
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_color_state(color_state: ColorState) None #
Sets the color state for the texture.
By default, the sRGB colorstate is used. If you don’t know what colorstates are, this is probably the right thing.
Added in version 4.16.
- Parameters:
color_state – a
GdkColorState
- 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 belongs 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 asGL_RGBA16
texture, andGDK_MEMORY_G8A8
is expected to be stored asGL_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: Any = 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 tobuild
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
Properties#
- class GLTextureBuilder
- props.color_state: ColorState#
The type of the None singleton.
Added in version 4.16.
- props.format: MemoryFormat#
The type of the None singleton.
Added in version 4.12.
- props.update_region: Region#
The type of the None singleton.
Added in version 4.12.