<chapter id="drawing-overview">
  <title>Overview of the drawing model</title>
  <para>
    This chapter describes the GTK drawing model in detail. If you are
    interested in the procedure which GTK follows to draw its widgets
    and windows, you should read this chapter; this will be useful to
    know if you decide to implement your own widgets. This chapter will
    also clarify the reasons behind the ways certain things are done in
    GTK.
  </para>
  <sect1 id="drawing-windows">
    <title>Windows and events</title>
    <para>
      Applications that use a windowing system generally create
      rectangular regions in the screen called
      <emphasis>surfaces</emphasis> (GTK is following the Wayland
      terminology, other windowing systems such as X11 may call these
      <emphasis>windows</emphasis>). Traditional windowing systems do
      not automatically save the graphical content of surfaces, and
      instead ask applications to provide new content whenever it is
      needed. For example, if a window that is stacked below other
      windows gets raised to the top, then the application has to
      repaint it, so the previously obscured area can be shown. When the
      windowing system asks an application to redraw a window, it sends
      a <emphasis>frame event</emphasis> (<emphasis>expose
      event</emphasis> in X11 terminology) for that window.
    </para>
    <para>
      Each GTK toplevel window or dialog is associated with a windowing
      system surface. Child widgets such as buttons or entries don’t
      have their own surface; they use the surface of their toplevel.
    </para>
    <para>
      Generally, the drawing cycle begins when GTK receives a frame
      event from the underlying windowing system: if the user drags a
      window over another one, the windowing system will tell the
      underlying surface that it needs to repaint itself. The drawing
      cycle can also be initiated when a widget itself decides that it
      needs to update its display. For example, when the user types a
      character in an entry widget, the entry asks GTK to queue a redraw
      operation for itself.
    </para>
    <para>
      The windowing system generates frame events for surfaces. The GDK
      interface to the windowing system translates such events into
      emissions of the ::render signal on the affected surfaces. The GTK
      toplevel window connects to that signal, and reacts appropriately.
    </para>
    <para>
      The following sections describe how GTK decides which widgets need
      to be repainted in response to such events, and how widgets work
      internally in terms of the resources they use from the windowing
      system.
    </para>
  </sect1>
  <sect1 id="frameclock">
    <title>The frame clock</title>
    <para>
      All GTK applications are mainloop-driven, which means that most of
      the time the app is idle inside a loop that just waits for
      something to happen and then calls out to the right place when it
      does. On top of this GTK has a frame clock that gives a
      <quote>pulse</quote> to the application. This clock beats at a
      steady rate, which is tied to the framerate of the output (this is
      synced to the monitor via the window manager/compositor). A
      typical refresh rate is 60 frames per second, so a new
      <quote>pulse</quote> happens roughly every 16 milliseconds.
    </para>
    <para>
      The clock has several phases:
    </para>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Events
        </para>
      </listitem>
      <listitem>
        <para>
          Update
        </para>
      </listitem>
      <listitem>
        <para>
          Layout
        </para>
      </listitem>
      <listitem>
        <para>
          Paint
        </para>
      </listitem>
    </itemizedlist>
    <para>
      The phases happens in this order and we will always run each phase
      through before going back to the start.
    </para>
    <para>
      The Events phase is a stretch of time between each redraw where
      GTK processes input events from the user and other events (like
      e.g. network I/O). Some events, like mouse motion are compressed
      so that only a single mouse motion event per clock cycle needs to
      be handled.
    </para>
    <para>
      Once the Events phase is over, external events are paused and the
      redraw loop is run. First is the Update phase, where all
      animations are run to calculate the new state based on the
      estimated time the next frame will be visible (available via the
      frame clock). This often involves geometry changes which drive the
      next phase, Layout. If there are any changes in widget size
      requirements the new layout is calculated for the widget hierarchy
      (i.e. sizes and positions for all widgets are determined). Then
      comes the Paint phase, where we redraw the regions of the window
      that need redrawing.
    </para>
    <para>
      If nothing requires the Update/Layout/Paint phases we will stay in
      the Events phase forever, as we don’t want to redraw if nothing
      changes. Each phase can request further processing in the
      following phases (e.g. the Update phase will cause there to be
      layout work, and layout changes cause repaints).
    </para>
    <para>
      There are multiple ways to drive the clock, at the lowest level
      you can request a particular phase with
      <link linkend="gdk-frame-clock-request-phase"><function>gdk_frame_clock_request_phase()</function></link> which will schedule a clock beat
      as needed so that it eventually reaches the requested phase.
      However, in practice most things happen at higher levels:
    </para>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          If you are doing an animation, you can use
          <link linkend="gtk-widget-add-tick-callback"><function>gtk_widget_add_tick_callback()</function></link> which will cause a regular
          beating of the clock with a callback in the Update phase until
          you stop the tick.
        </para>
      </listitem>
      <listitem>
        <para>
          If some state changes that causes the size of your widget to
          change you call <link linkend="gtk-widget-queue-resize"><function>gtk_widget_queue_resize()</function></link> which will request a
          Layout phase and mark your widget as needing relayout.
        </para>
      </listitem>
      <listitem>
        <para>
          If some state changes so you need to redraw some area of your
          widget you use the normal <link linkend="gtk-widget-queue-draw"><function>gtk_widget_queue_draw()</function></link> set of
          functions. These will request a Paint phase and mark the
          region as needing redraw.
        </para>
      </listitem>
    </itemizedlist>
    <para>
      There are also a lot of implicit triggers of these from the CSS
      layer (which does animations, resizes and repaints as needed).
    </para>
  </sect1>
  <sect1 id="scene-graph">
    <title>The scene graph</title>
    <para>
      The first step in <quote>drawing</quote> a window is that GTK
      creates <emphasis>render nodes</emphasis> for all the widgets in
      the window. The render nodes are combined into a tree that you can
      think of as a <emphasis>scene graph</emphasis> describing your
      window contents.
    </para>
    <para>
      Render nodes belong to the GSK layer, and there are various kinds
      of them, for the various kinds of drawing primitives you are
      likely to need when translating widget content and CSS styling.
      Typical examples are text nodes, gradient nodes, texture nodes or
      clip nodes.
    </para>
    <para>
      In the past, all drawing in GTK happened via cairo. It is still
      possible to use cairo for drawing your custom widget contents, by
      using a cairo render node.
    </para>
    <para>
      A GSK <emphasis>renderer</emphasis> takes these render nodes,
      transforms them into rendering commands for the drawing API it
      targets, and arranges for the resulting drawing to be associated
      with the right surface. GSK has renderers for OpenGL, Vulkan and
      cairo.
    </para>
  </sect1>
  <sect1 id="hierarchical-drawing">
    <title>Hierarchical drawing</title>
    <para>
      During the Paint phase GTK receives a single <link linkend="GdkSurface-render"><type>“render”</type></link>
      signal on the toplevel surface. The signal handler will create a
      snapshot object (which is a helper for creating a scene graph) and
      call the <link linkend="GtkWidget"><type>GtkWidget</type></link>::<link linkend="snapshot"><function>snapshot()</function></link> vfunc, which will propagate down
      the widget hierarchy. This lets each widget snapshot its content
      at the right place and time, correctly handling things like
      partial transparencies and overlapping widgets.
    </para>
    <para>
      During the snapshotting of each widget, GTK automatically handles
      the CSS rendering according to the CSS box model. It snapshots
      first the background, then the border, then the widget content
      itself, and finally the outline.
    </para>
    <para>
      To avoid excessive work when generating scene graphs, GTK caches
      render nodes. Each widget keeps a reference to its render node
      (which in turn, will refer to the render nodes of children, and
      grandchildren, and so on), and will reuse that node during the
      Paint phase. Invalidating a widget (by calling
      <link linkend="gtk-widget-queue-draw"><function>gtk_widget_queue_draw()</function></link>) discards the cached render node, forcing
      the widget to regenerate it the next time it needs to produce a
      snapshot.
    </para>
  </sect1>
</chapter>
