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$