242de47c03
• Clear up what's deprecated. • Remove mentions of set_parent/unparent, and use add_child/remove_child instead. • Clarify that reparent may not touch the MAPPED state.
278 lines
9.9 KiB
Text
278 lines
9.9 KiB
Text
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.
|
|
|
|
Reparent may not change the MAPPED flag if the old and the
|
|
new parent are both MAPPED.
|
|
|
|
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 [DEPRECATED]
|
|
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_IN_PAINT:
|
|
Set internally by clutter_actor_paint()
|
|
|
|
CLUTTER_ACTOR_IN_RELAYOUT
|
|
Set internally by clutter_actor_allocate()
|
|
|
|
c. 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_add_child (parent, actor):
|
|
((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_add_child() on an actor and a mapped
|
|
parent will map the actor if it has been shown.
|
|
|
|
4) if clutter_actor_remove_child (parent, actor):
|
|
CLUTTER_ACTOR_IS_MAPPED (actor) <=> CLUTTER_ACTOR_IN_REPARENT
|
|
|
|
calling clutter_actor_remove_child() 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. [DEPRECATED]
|
|
|
|
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_add_child:
|
|
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_remove_child:
|
|
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: [DEPRECATED]
|
|
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_add_child (container, actor)
|
|
|
|
b. Removing from a container
|
|
|
|
When removing an actor from a container, the container must:
|
|
|
|
1. call clutter_actor_remove_child (container, actor)
|
|
|
|
c. Initial state
|
|
|
|
When creating an actor, the initial state is:
|
|
|
|
1. !CLUTTER_ACTOR_REALIZED
|
|
2. !CLUTTER_ACTOR_MAPPED
|