:right-sidebar: True GLTextureBuilder =================================================================== .. currentmodule:: gi.repository.Gdk .. versionadded:: 4.12 .. class:: GLTextureBuilder(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` ``GdkGLTextureBuilder`` is a builder used to construct :obj:`~gi.repository.Gdk.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 :obj:`~gi.repository.Gdk.GLTextureBuilder.props.context`\, :obj:`~gi.repository.Gdk.GLTextureBuilder.props.id`\, :obj:`~gi.repository.Gdk.GLTextureBuilder.props.width`\, and :obj:`~gi.repository.Gdk.GLTextureBuilder.props.height` are mandatory - and then call :obj:`~gi.repository.Gdk.GLTextureBuilder.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 ------------ .. rst-class:: interim-class .. class:: GLTextureBuilder :no-index: .. classmethod:: new() -> ~gi.repository.Gdk.GLTextureBuilder Creates a new texture builder. .. versionadded:: 4.12 Methods ------- .. rst-class:: interim-class .. class:: GLTextureBuilder :no-index: .. method:: build(destroy: ~typing.Callable[[~typing.Any], None] | None = None, data: ~typing.Any = None) -> ~gi.repository.Gdk.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 :obj:`~gi.repository.Gdk.GLTexture.release`\. It should release all GL resources associated with the texture, such as the :obj:`~gi.repository.Gdk.GLTextureBuilder.props.id` and the :obj:`~gi.repository.Gdk.GLTextureBuilder.props.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. .. versionadded:: 4.12 :param destroy: destroy function to be called when the texture is released :param data: user data to pass to the destroy function .. method:: get_color_state() -> ~gi.repository.Gdk.ColorState Gets the color state previously set via :func:`~gi.repository.Gdk.GLTextureBuilder.set_color_state`. .. versionadded:: 4.16 .. method:: get_context() -> ~gi.repository.Gdk.GLContext | None Gets the context previously set via :func:`~gi.repository.Gdk.GLTextureBuilder.set_context` or :const:`None` if none was set. .. versionadded:: 4.12 .. method:: get_format() -> ~gi.repository.Gdk.MemoryFormat Gets the format previously set via :func:`~gi.repository.Gdk.GLTextureBuilder.set_format`. .. versionadded:: 4.12 .. method:: get_has_mipmap() -> bool Gets whether the texture has a mipmap. .. versionadded:: 4.12 .. method:: get_height() -> int Gets the height previously set via :func:`~gi.repository.Gdk.GLTextureBuilder.set_height` or 0 if the height wasn't set. .. versionadded:: 4.12 .. method:: get_id() -> int Gets the texture id previously set via :func:`~gi.repository.Gdk.GLTextureBuilder.set_id` or 0 if the id wasn't set. .. versionadded:: 4.12 .. method:: get_sync() -> ~typing.Any | None Gets the ``GLsync`` previously set via :func:`~gi.repository.Gdk.GLTextureBuilder.set_sync`. .. versionadded:: 4.12 .. method:: get_update_region() -> ~gi.repository.cairo.Region | None Gets the region previously set via :func:`~gi.repository.Gdk.GLTextureBuilder.set_update_region` or :const:`None` if none was set. .. versionadded:: 4.12 .. method:: get_update_texture() -> ~gi.repository.Gdk.Texture | None Gets the texture previously set via :func:`~gi.repository.Gdk.GLTextureBuilder.set_update_texture` or :const:`None` if none was set. .. versionadded:: 4.12 .. method:: get_width() -> int Gets the width previously set via :func:`~gi.repository.Gdk.GLTextureBuilder.set_width` or 0 if the width wasn't set. .. versionadded:: 4.12 .. method:: set_color_state(color_state: ~gi.repository.Gdk.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. .. versionadded:: 4.16 :param color_state: a ``GdkColorState`` .. method:: set_context(context: ~gi.repository.Gdk.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 :obj:`~gi.repository.Gdk.GLTextureBuilder.build`\. .. versionadded:: 4.12 :param context: The context the texture belongs to or :const:`None` to unset .. method:: set_format(format: ~gi.repository.Gdk.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 :obj:`~gi.repository.Gdk.GLTextureBuilder.props.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. .. versionadded:: 4.12 :param format: The texture's format .. method:: 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. .. versionadded:: 4.12 :param has_mipmap: Whether the texture has a mipmap .. method:: set_height(height: int) -> None Sets the height of the texture. The height must be set before calling :obj:`~gi.repository.Gdk.GLTextureBuilder.build`\. .. versionadded:: 4.12 :param height: The texture's height or 0 to unset .. method:: set_id(id: int) -> None Sets the texture id of the texture. The texture id must remain unmodified until the texture was finalized. See :obj:`~gi.repository.Gdk.GLTextureBuilder.build` for a longer discussion. The id must be set before calling :obj:`~gi.repository.Gdk.GLTextureBuilder.build`\. .. versionadded:: 4.12 :param id: The texture id to be used for creating the texture .. method:: set_sync(sync: ~typing.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 to :obj:`~gi.repository.Gdk.GLTextureBuilder.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. .. versionadded:: 4.12 :param sync: the GLSync object .. method:: set_update_region(region: ~gi.repository.cairo.Region | None = None) -> None Sets the region to be updated by this texture. Together with :obj:`~gi.repository.Gdk.GLTextureBuilder.props.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. .. versionadded:: 4.12 :param region: the region to update .. method:: set_update_texture(texture: ~gi.repository.Gdk.Texture | None = None) -> None Sets the texture to be updated by this texture. See :obj:`~gi.repository.Gdk.GLTextureBuilder.set_update_region` for an explanation. .. versionadded:: 4.12 :param texture: the texture to update .. method:: set_width(width: int) -> None Sets the width of the texture. The width must be set before calling :obj:`~gi.repository.Gdk.GLTextureBuilder.build`\. .. versionadded:: 4.12 :param width: The texture's width or 0 to unset Properties ---------- .. rst-class:: interim-class .. class:: GLTextureBuilder :no-index: .. attribute:: props.color_state :type: ~gi.repository.Gdk.ColorState The type of the None singleton. .. versionadded:: 4.16 .. attribute:: props.context :type: ~gi.repository.Gdk.GLContext The type of the None singleton. .. versionadded:: 4.12 .. attribute:: props.format :type: ~gi.repository.Gdk.MemoryFormat The type of the None singleton. .. versionadded:: 4.12 .. attribute:: props.has_mipmap :type: bool The type of the None singleton. .. versionadded:: 4.12 .. attribute:: props.height :type: int The type of the None singleton. .. versionadded:: 4.12 .. attribute:: props.id :type: int The type of the None singleton. .. versionadded:: 4.12 .. attribute:: props.sync :type: ~typing.Any The type of the None singleton. .. versionadded:: 4.12 .. attribute:: props.update_region :type: ~gi.repository.cairo.Region The type of the None singleton. .. versionadded:: 4.12 .. attribute:: props.update_texture :type: ~gi.repository.Gdk.Texture The type of the None singleton. .. versionadded:: 4.12 .. attribute:: props.width :type: int The type of the None singleton. .. versionadded:: 4.12