:right-sidebar: True

Renderer
===================================================================

.. currentmodule:: gi.repository.Gsk





.. class:: Renderer(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.GObject.Object`


Subclasses: :class:`~gi.repository.Gsk.BroadwayRenderer`, :class:`~gi.repository.Gsk.CairoRenderer`, :class:`~gi.repository.Gsk.GLRenderer`, :class:`~gi.repository.Gsk.NglRenderer`, :class:`~gi.repository.Gsk.VulkanRenderer`




``GskRenderer`` is a class that renders a scene graph defined via a
tree of :obj:`~gi.repository.Gsk.RenderNode` instances.

Typically you will use a ``GskRenderer`` instance to repeatedly call
:obj:`~gi.repository.Gsk.Renderer.render` to update the contents of its associated
:obj:`~gi.repository.Gdk.Surface`\.

It is necessary to realize a ``GskRenderer`` instance using
:obj:`~gi.repository.Gsk.Renderer.realize` before calling :obj:`~gi.repository.Gsk.Renderer.render`\,
in order to create the appropriate windowing system resources needed
to render the scene.


Constructors
------------

.. rst-class:: interim-class

.. class:: Renderer
   :no-index:


   .. classmethod:: new_for_surface(surface: ~gi.repository.Gdk.Surface) -> ~gi.repository.Gsk.Renderer | None

      Creates an appropriate ``GskRenderer`` instance for the given ``surface``\.

      If the ``GSK_RENDERER`` environment variable is set, GSK will
      try that renderer first, before trying the backend-specific
      default. The ultimate fallback is the cairo renderer.

      The renderer will be realized before it is returned.






      :param surface: a ``GdkSurface``








Methods
-------

.. rst-class:: interim-class

.. class:: Renderer
   :no-index:


   .. method:: get_surface() -> ~gi.repository.Gdk.Surface | None

      Retrieves the ``GdkSurface`` set using gsk_enderer_realize().

      If the renderer has not been realized yet, :const:`None` will be returned.









   .. method:: is_realized() -> bool

      Checks whether the ``renderer`` is realized or not.









   .. method:: realize(surface: ~gi.repository.Gdk.Surface | None = None) -> bool

      Creates the resources needed by the ``renderer`` to render the scene
      graph.

      Since GTK 4.6, the surface may be ``NULL``\, which allows using
      renderers without having to create a surface.
      Since GTK 4.14, it is recommended to use :obj:`~gi.repository.Gsk.Renderer.realize_for_display`
      instead.

      Note that it is mandatory to call :obj:`~gi.repository.Gsk.Renderer.unrealize` before
      destroying the renderer.






      :param surface: the ``GdkSurface`` renderer will be used on




   .. method:: realize_for_display(display: ~gi.repository.Gdk.Display) -> bool

      Creates the resources needed by the ``renderer`` to render the scene
      graph.

      Note that it is mandatory to call :obj:`~gi.repository.Gsk.Renderer.unrealize` before
      destroying the renderer.


      .. versionadded:: 4.14





      :param display: the ``GdkDisplay`` renderer will be used on




   .. method:: render(root: ~gi.repository.Gsk.RenderNode, region: ~gi.repository.cairo.Region | None = None) -> None

      Renders the scene graph, described by a tree of ``GskRenderNode`` instances
      to the renderer's surface,  ensuring that the given ``region`` gets redrawn.

      If the renderer has no associated surface, this function does nothing.

      Renderers must ensure that changes of the contents given by the ``root``
      node as well as the area given by ``region`` are redrawn. They are however
      free to not redraw any pixel outside of ``region`` if they can guarantee that
      it didn't change.

      The ``renderer`` will acquire a reference on the ``GskRenderNode`` tree while
      the rendering is in progress.






      :param root: a ``GskRenderNode``

      :param region: the ``cairo_region_t`` that must be redrawn or :const:`None`
           for the whole window




   .. method:: render_texture(root: ~gi.repository.Gsk.RenderNode, viewport: ~gi.repository.Graphene.Rect | None = None) -> ~gi.repository.Gdk.Texture

      Renders the scene graph, described by a tree of ``GskRenderNode`` instances,
      to a ``GdkTexture``\.

      The ``renderer`` will acquire a reference on the ``GskRenderNode`` tree while
      the rendering is in progress.

      If you want to apply any transformations to ``root``\, you should put it into a
      transform node and pass that node instead.






      :param root: a ``GskRenderNode``

      :param viewport: the section to draw or :const:`None` to use ``root``\'s bounds




   .. method:: unrealize() -> None

      Releases all the resources created by :func:`~gi.repository.Gsk.Renderer.realize`.













Properties
----------

.. rst-class:: interim-class

.. class:: Renderer
   :no-index:
   

   .. attribute:: props.realized
      :type: bool

      The type of the None singleton.







   .. attribute:: props.surface
      :type: ~gi.repository.Gdk.Surface

      The type of the None singleton.