mutter/doc/clutter-actor-invariants.txt

ClutterActor Invariants
===============================================================================

ClutterActor behaviour has invariants that will be kept with the same API and
ABI guarantees as the whole Clutter library.

This document refers to the 0.8 release of Clutter.

Sections:

   i. Flags
        a. Public ClutterActor Flags
        b. Private ClutterActor Flags
        c. Private Pick Modes
  ii. Invariants
 iii. State changes
  iv. Responsibilities of a ClutterActor
        a. Adding to a container
        b. Removing from a container
        c. Initial state

 i. Flags
-------------------------------------------------------------------------------

This section describes the various flags and enumerations used by
ClutterActor.

 a. Public ClutterActor Flags

CLUTTER_ACTOR_REALIZED
        Means: the actor has GPU resources associated to its paint
        cycle. Note however that an actor is allowed to allocate Cogl
        resources before being realized because Clutter only ever uses
        one rendering context which is always current. An actor is
        free to create resources at any time.

        Set by clutter_actor_realize(), unset by
        clutter_actor_unrealize(). Generally set implicitly when the
        actor becomes MAPPED (see below).

        May only be set if one of the actor's ancestors is a toplevel.
        May only be set if all of the actor's ancestors are realized.

        Once realized an actor remains realized until removed from the
        toplevel. Hide, reparent will not unrealize; but unparent or
        destroy will unrealize since they remove the actor from the
        toplevel.

CLUTTER_ACTOR_MAPPED
        Means: the actor will be painted if the stage is mapped.

        On non-toplevels, will be set if all of the following are
        true, and unset otherwise:
        * the actor's VISIBLE flag is set
        * all of the actor's non-toplevel ancestors have the MAPPED
          flag set
        * the actor has a toplevel ancestor
        * the toplevel ancestor's VISIBLE flag is set
        * the toplevel ancestor's REALIZED flag is set

        On toplevels, MAPPED is set asynchronously when the window
        system notifies Clutter that the toplevel has been made
        visible on the screen.

        The MAPPED flag requires that an actor is REALIZED. When
        Clutter sets the MAPPED flag, it forces realization; this is
        the "normal" way for realization to occur, though explicit
        realization with clutter_actor_realize() is permitted.

CLUTTER_ACTOR_VISIBLE
        Means: the actor's "visible" property was set to true by
        the application programmer.

        Set by clutter_actor_show(), unset by clutter_actor_hide().

        This is an application-controlled property, while MAPPED and
        REALIZED are usually managed by Clutter (with the exception
        that applications can "realize early" with
        clutter_actor_realize()).

        If VISIBLE is unset, the actor (and any children) must
        be immediately unmapped, to maintain the invariants for
        the MAPPED flag.

CLUTTER_ACTOR_REACTIVE
        Set and unset by clutter_actor_set_reactive()
        Means: the actor is now reactive to events.
        Notes:
          * If parents need to be reactive for child its up to the
            parent implementation. In the case of ClutterGroup it
            being marked unreactive does not mark all children unreactive.
          * Clutter stage is always reactive.


 b. Private ClutterActor flags

CLUTTER_ACTOR_IN_DESTRUCTION
        Set internally by clutter_actor_destroy().
        Used to avoid uneeded overhead when freeing GPU resources on unrealize

CLUTTER_ACTOR_IS_TOPLEVEL
        Set internally by the initialization of ClutterStage

CLUTTER_ACTOR_IN_REPARENT
        Set internally by clutter_actor_reparent(). This flag
        optimizes the reparent process by avoiding the need
        to pass through an unrealized state when the actor is
        removed from the old parent.

CLUTTER_ACTOR_ABOUT_TO_UNPARENT
        Set internally during part of clutter_actor_unparent().
        Causes the actor to pretend it has no parent, then
        update invariants; which effectively forces the actor
        to unrealize. The purpose of this is to unrealize _before_ the
        actor is removed from the stage, so unrealize implementations
        can use clutter_actor_get_stage().

CLUTTER_ACTOR_SYNC_MATRICES
        Set internally by ClutterStage implementations
        Means: the size of the stage changed and the viewport must be
        synchronized to the new size

CLUTTER_ACTOR_IN_PAINT:
        Set internally by clutter_actor_paint()

CLUTTER_ACTOR_IN_RELAYOUT
        Set internally by clutter_relayout()

 c. Private Pick Modes

CLUTTER_PICK_NONE
        No pick operation is performed during the paint

CLUTTER_PICK_REACTIVE
        Only reactive actors will be picked

CLUTTER_PICK_ALL
        All visible actors will be picked

 ii. Invariants
-------------------------------------------------------------------------------

This section describes the various constraints and invariants on ClutterActor.

In the following

        A  => B         means   if A is true then B is true
        A <=> B         means   A is true if and only if B is true
                                (equivalent to A => B && A <= B)

1) CLUTTER_ACTOR_IN_DESTRUCTION => !CLUTTER_ACTOR_IS_MAPPED (actor) &&
                                   !CLUTTER_ACTOR_IS_REALIZED (actor)

        clutter_actor_destroy() will cause an actor to be unparented,
        which means the actor must be unmapped and unrealized as
        well.

2) CLUTTER_ACTOR_IS_MAPPED (actor) => CLUTTER_ACTOR_IS_REALIZED (actor)

        when an actor is mapped, it must first be realized.

        This is the most common way an actor becomes realized.

3) if clutter_actor_set_parent (actor, parent):
     ((parent_is_not_toplevel && CLUTTER_ACTOR_IS_MAPPED (parent)) ||
      (parent_is_toplevel && CLUTTER_ACTOR_IS_VISIBLE(parent))) &&
     CLUTTER_ACTOR_IS_VISIBLE (actor)
                                  => CLUTTER_ACTOR_IS_MAPPED (actor)

        calling clutter_actor_set_parent() on an actor and a mapped
        parent will map the actor if it has been shown.

4) if clutter_actor_unparent (actor):
     CLUTTER_ACTOR_IS_MAPPED (actor) <=> CLUTTER_ACTOR_IN_REPARENT

        calling clutter_actor_unparent() on an actor will unmap and
        unrealize the actor since it no longer has a toplevel.

        calling clutter_actor_reparent() on an actor will leave the
        actor mapped and realized (if it was before) until it has a
        new parent, at which point the invariants implied by the new
        parent's state are applied.

5) CLUTTER_ACTOR_IS_REALIZED(actor) => CLUTTER_ACTOR_IS_REALIZED(parent)

        Actors may only be realized if their parent is realized.
        However, they may be unrealized even though their parent
        is realized.

        This implies that an actor may not be realized unless
        it has a parent, or is a toplevel.

        Since only toplevels can realize without a parent, no actor
        can be realized unless it either is a toplevel or has a
        toplevel ancestor.

        As long as they are unmapped, actors may be unrealized. This
        will force all children of the actor to be unrealized, since
        children may not be realized while parents are unrealized.

6) CLUTTER_ACTOR_IS_MAPPED(actor) <=>
      (  (  (CLUTTER_ACTOR_IS_VISIBLE(toplevel_parent) &&
             CLUTTER_ACTOR_IS_REALIZED(toplevel_parent)) ||
             CLUTTER_ACTOR_IS_MAPPED(non_toplevel_parent)  )  ) &&
       CLUTTER_ACTOR_IS_VISIBLE(actor)

       Actors _must_ be mapped if and only if they are visible and
       their parent is mapped, or they are visible and their
       parent is a toplevel that's realized and visible.

       This invariant enables us to track whether an actor will
       be painted (whether it's MAPPED) without ever traversing
       the actor graph.

 iii. State changes
-------------------------------------------------------------------------------

clutter_actor_show:
        1. sets VISIBLE
        2. sets MAPPED if invariants are met; mapping in turn sets
           REALIZED

clutter_actor_hide:
        1. sets !VISIBLE
        2. unsets MAPPED if actor was mapped previously
        3. does not affect REALIZED

clutter_actor_destroy:
        1. sets CLUTTER_ACTOR_IN_DESTRUCTION
        2. unparents the actor, which in turn implies unmap and unrealize

clutter_actor_realize:
        1. attempts to set REALIZED on all parents, failing if
           invariants are not met, e.g. not in a toplevel yet
        2. sets REALIZED on actor if parent was successfully realized

clutter_actor_unrealize:
        1. sets !VISIBLE which forces !MAPPED
        2. sets !REALIZED
        3. !MAPPED and !REALIZED forces unmap and unrealize of all
           children

clutter_actor_set_parent:
        1. sets actor->parent
        2. if actor->show_on_set_parent is TRUE calls clutter_actor_show
        3. sets MAPPED if all prerequisites are now met for map
        4. if !CLUTTER_ACTOR_IN_REPARENT emits ::parent-set with
           old_parent set to NULL

clutter_actor_unparent:
        1. unsets actor->parent
        2. if !CLUTTER_ACTOR_IN_REPARENT, sets !MAPPED and !REALIZED
           since the invariants for those flags are no longer met
        3. if !CLUTTER_ACTOR_IN_REPARENT emits ::parent-set with
           old_parent set to the previous parent

clutter_actor_reparent:
        1. sets CLUTTER_ACTOR_IN_REPARENT
        2. emits ::parent-set with old_parent set to the previous parent
           equivalent to:
                clutter_actor_unparent
                clutter_actor_set_parent
        3. updates state of the actor to match invariants
           (may change MAPPED or REALIZED in either direction,
           depending on state of the new parent)


 iv. Responsibilities of a ClutterActor
-------------------------------------------------------------------------------

 a. Adding to a container

When adding an actor to a container, the container must:

 1. call clutter_actor_set_parent (actor, container)
 2. call clutter_actor_queue_relayout (container) if
    adding the actor changes the container's preferred
    size

 b. Removing from a container

When removing an actor from a container, the container must:

 1. call clutter_actor_unparent (actor)
 2. call clutter_actor_queue_relayout (container) if removing
    the actor changes the container's preferred size

Notes:

* here a container actor is any actor that contains children actors; it
  does not imply the implementation of the ClutterContainer interface.

* clutter_actor_unparent() will unmap and unrealize the actor except
  in the special case when CLUTTER_ACTOR_IN_REPARENT is set.

* 'Composite' Clutter actors need to pass down any allocations to children.

 c. Initial state

When creating an actor, the initial state is:

 1. !CLUTTER_ACTOR_REALIZED
 2. !CLUTTER_ACTOR_MAPPED

===============================================================================
$LastChangedDate$