This extends visualization for CLUTTER_PAINT=redraws so it now also
draws outlines for actors to show how they are being culled. Actors get
a green outline if they are fully inside the clip region, blue if fully
outside and greeny-blue if only partially inside.
This adds an internal _clutter_stage_get_active_framebuffer function
that can be used to get a pointer to the current CoglFramebuffer pointer
that is in use, in association with a given stage.
The "active" infix in the function name is there because we shouldn't
assume that a stage will always correspond to only a single framebuffer
so we aren't getting a pointer to a sole framebuffer, we are getting
a pointer to the framebuffer that is currently in use/being painted.
This API is now used for culling purposes where we need to check if we
are currently painting an actor to a framebuffer that is offscreen, that
doesn't correspond to the stage.
This renames the two internal functions _cogl_get_draw/read_buffer
as cogl_get_draw_framebuffer and _cogl_get_read_framebuffer. The
former is now also exposed as experimental API.
Previously we were applying the culling optimization to any actor
painted without considering that we may be painting to an offscreen
framebuffer where the stage clip isn't applicable.
For now we simply expose a getter for the current draw framebuffer
and we can assume that a return value of NULL corresponds to the
stage.
Note: This will need to be updated as stages start to be backed by real
CoglFramebuffer objects and so we won't get NULL in those cases.
To give quick visibility to the things going on relating to clipping and
culling this adds some more CLIPPING debug notes to clutter-actor.c and
clutter-stage.c
There's an optimisation in clutter-actor.c to avoid calculating the
last known paint volume whenever culling and clipped redraws are both
disabled. However there was a small thinko in the logic so that it
would also avoid calculating the paint volume whenever only one of the
debug flags is enabled. This fixes it to explicitly check that the two
flags are not both enabled before skipping the paint volume
calculation.
Previously each time we needed to retrieve the model transform for a
given actor we would call the apply_transform vfunc which would build up
a transformation matrix based on the actor's current anchor point, its
scale, its allocation and rotation. The apply_transform implementation
would repeatedly call API like cogl_matrix_rotate, cogl_matrix_translate
and cogl_matrix_scale.
All this micro matrix manipulation APIs were starting to show up in the
profiles of dynamic applications so this adds priv->transform matrix
cache which maintains the combined result of the actors scale, rotation
and anchor point etc. Whenever something like the rotation changes then
then the matrix is marked as dirty, but so long as the matrix isn't
dirty then the apply_transform vfunc now just calls cogl_matrix_multiply
with the cached transform matrix.
This implements a variation of frustum culling whereby we convert screen
space clip rectangles into eye space mini-frustums so that we don't have
to repeatedly transform actor paint-volumes all the way into screen
coordinates to perform culling, we just have to apply the modelview
transform and then determine each points distance from the planes that
make up the clip frustum.
By avoiding the projective transform, perspective divide and viewport
scale for each point culled this makes culling much cheaper.
OpenGL < 4.0 only supports integer based viewports and internally we
have a mixture of code using floats and integers for viewports. This
patch switches all viewports throughout clutter and cogl to be
represented using floats considering that in the future we may want to
take advantage of floating point viewports with modern hardware/drivers.
This is needed if an effect wants to temporarily override the paint
opacity. It needs to be able to restore the old opacity override in
the post_paint handler otherwise it would replace the effect of the
opacity override from any outer effects.
http://bugzilla.clutter-project.org/show_bug.cgi?id=2541
The shader stack held by ClutterMainContext should only be accessed
using functions, and not directly.
Since it's a stack, we can use stack-like operations: push, pop and
peek.
Let's try and start reducing the size of ClutterActorPrivate by moving
some optional, out-of-band data from it to GObject data.
The ShaderData structure is a prime candidate for this migration: it
does not need to be inspected by the actor, and its relationship with an
actor is transient and optional.
By attaching it to the actor's instance through g_object_set_data() we
neatly tie its lifetime to the instance, and we don't have to care
cleaning it up in the finalize()/dispose() implementation of
ClutterActor itself.
In _clutter_actor_queue_redraw_with_clip it has a local variable to
mark when a new paint volume for the clip is created so that it can be
freed when the function returns. However the actual code to free the
paint volume went missing in 3b789490d2 so the variable did
nothing. This patch just adds the free back in.
This time, in Clutter core.
The ObjC standard library provides a type called 'id', which obviously
requires any library to either drop the useful shadowed variable warning
or stop using 'id' as a variable name.
Yes, it's almost unbearably stupid. Well, at least it's not 'index' in
string.h, or 'y2' in math.h.
The 'in_clone_paint' parameter of the private function
_clutter_actor_set_in_clone_paint() shadowed the private function
in_clone_paint(). Rename this parameter to 'is_in_clone_paint' to remove
a compiler warning.
Replace the opacity_parent with an opacity_override variable, to allow
direct overriding of the paint opacity and simplify this mechanism
somewhat.
This also required a new private flag, in_clone_paint, to maintain the
functionality of the public function clutter_actor_is_in_clone_paint()
Don't use ugly "#undef CLUTTER_DISABLE_DEPRECATED" inside source code
using deprecated symbols; we have the handy CLUTTER_COMPILATION define
that we can use as part of the "disable deprecated" conditional.
Use the internal child list for the default map/unmap vfuncs. This removes
the requirement for non-container composite actors to implement their own
map/unmap functions.
Unrealizing an actor is a recursive process that needs to traverse the
children of an actor to ensure they are also unrealized. This maintains
the invariant that if any given actor is marked as unrealized then you
know that all its children have also been unrealized.
The previous implementation would use the container interface's
foreach_with_internals vfunc to explicitly traverse the children of
container actors but this didn't consider composite actors that aren't
containers.
Since clutter-actor now maintains an explicit list of children we can
also handle composite actors that aren't containers using
_clutter_actor_traverse.
This makes it possible to choose the traversal order; either depth first
or breadth first and when visiting actors in a depth first order there
is now a callback called before children are traversed and one called
after. Some tasks such as unrealizing actors need to explicitly control
the traversal order to maintain the invariable that all children of an
actor are unrealized before we actually mark the parent as unrealized.
The callbacks are now passed the relative depth in the graph of the
actor being visited and instead of only being able to return a boolean
to bail out of further traversal it can now do one of: continue,
skip_children or break. To implement something like unrealize it's
desirable to skip children that you find have already been unrealized.
The last_paint_box for an actor represents its "normal" position - we
shouldn't update it or use it to cull drawing if we are painting
a clone of the actor. Tracking whether we are painting a clone is
done by adding _clutter_actor_push/pop_clone_paint() and a global
"clone paint level".
http://bugzilla.clutter-project.org/show_bug.cgi?id=2396
When transforming a paint-volume or transforming allocation vertices we
are transforming more than one point at a time so we can batch those
together with cogl_matrix_transform_points instead of
cogl_matrix_transform_point. Also in both of these cases we don't need
to do a projective transform so using cogl_matrix_transform_points also
lets us reduce the per-vertex computation.
The Behaviour class and its implementations have been replaced by the
new animation framework API and by the constraints for layout-related
animations.
Currently, we need to make tests build, so we undef DISABLE_DEPRECATED
in specific test cases while they get ported.
The paint volume structure is cached in the Actor it references, and
this causes a reference cycle.
The paint volume is going to be used when painting, so the actor must
still be valid - otherwise Clutter will bail out far before than
accessing the actor pointer in ClutterPaintVolume.
Otherwise, we could have used dispose() to check for a valid actor and
remove a reference if the actor field is !NULL; it feels less clean,
though, since we're effectively managing an extra reference on
ourselves.
http://bugzilla.clutter-project.org/show_bug.cgi?id=2431
For internal usage, writing:
clutter_actor_get_name (actor) != NULL
? clutter_actor_get_name (actor)
: G_OBJECT_TYPE_NAME (actor)
is overly verbose and does two type checks. A simple, internal method
for getting the same result without type checks would be much more
appreciated.
Instead of waiting until clutter_actor_paint to check if there are any
handlers connected to the "paint" signal, we now do the check whenever
the paint-volume is requested in _actor_get_paint_volume_mutable().
Previously we checked in clutter_actor_paint(), but at that time we may
already be using a stage clip that could be derived from an invalid
paint-volume. We used to try and handle that by queuing a follow up,
unclipped, redraw but anyway there was an additional problem with the
previous approach because the checking wasn't enough to always catch
invalid volumes involved in culling (considering that containers may
derive their volume from children that haven't yet been painted)
By moving the check to _get_paint_volume time not only do we now
correctly check children in cases where a container derives its volume
from its children's volumes but we no longer need to queue follow up
redraws to cover up artefacts.
Since we now never queue follow up redraws, this in turn means we should
no longer clobber redraws queued with an explicit clip which was
something affecting gnome-shell since it connects a handler to the paint
signal of the stage.
http://bugzilla.clutter-project.org/show_bug.cgi?id=2388
Once an actor had _clutter_stage_queue_redraw_entry_invalidate()
called on it once, then priv->queue_redraw_entry would point to
an entry with entry->actor NULL. _clutter_stage_queue_actor_redraw()
doesn't handle this case and no further redraws would be queued.
To fix this, NULL out priv->queue_redraw_entry() and then make sure
we free the invalidated entry in
_clutter_stage_maybe_finish_queue_redraws() just as we do for
still valid entries.
http://bugzilla.clutter-project.org/show_bug.cgi?id=2389
We need to make sure that redraws queued for actors on a stage are for
actors actually in the stage. So in clutter_actor_unparent() descend
through the children and remove redraws. Just removing the actor itself
isn't good enough since an entire hierarchy can be removed from the
stage without breaking it up into individual actors.
http://bugzilla.clutter-project.org/show_bug.cgi?id=2359
This is based on an original patch from Owen Taylor who debugged the
root cause of this bug; thanks.
Instead of delegating the check for the ActorMeta:enabled property to
the sub-classes of ClutterActorMeta, ClutterActor can do the check prior
to using the ClutterActorMeta instances.
In all the changes made recently to how we handle redraws and adding
support for paint-volumes we stopped looking at explicit clip regions
passed to _clutter_actor_queue_redraw_with_clip.
In _clutter_actor_finish_queue_redraw we had started always trying to
clip the redraw to the paint-volume of the actor, but forgot to consider
that the user may have already determined the clip region for us!
Now we first check if the given clip != NUll and if so we don't need to
calculate the paint-volume of the actor.
http://bugzilla.clutter-project.org/show_bug.cgi?id=2349
Since re-working how redraws are queued it is no longer necessary to
dirty the pick buffer in _clutter_actor_real_queue_redraw since this
should now reliably be handled in _clutter_stage_queue_actor_redraw.
This adds two internal functions relating to explicit traversal of the
scenegraph:
_clutter_actor_foreach_child
_clutter_actor_traverse
_clutter_actor_foreach_child just iterates the immediate children of an
actor, and with a new ClutterForeachCallback type it allows the
callbacks to break iteration early.
_clutter_actor_traverse traverses the given actor and all of its
decendants. Again traversal can be stopped early if a callback returns
FALSE.
The first intended use for _clutter_actor_traverse is to maintain a
cache pointer to the stage for all actors. In this case we will need to
update the pointer for all descendants of an actor when an actor is
reparented in any way.
This adds a private getter to query the number of children an actor has.
One use planned for this API is to avoid calling get_paint_volume on
such actors. (It's not clear what the best semantics for
get_paint_volume are for actors with children, so we are considering
leaving the semantics undefined for the initial clutter 1.4 release)
We now explicitly track the list of children each actor has in a private
GList. This gives us a reliable way to know how many children an actor
has - even for composite actors that don't implement the container
interface. This also will allow us to directly traverse the scenegraph
in a more generalized fashion. Previously the scenegraph was
more-or-less represented implicitly according the implementation of
paint methods.
When using the CLUTTER_PAINT=paint-volumes debug option we try and show
when a paint volume couldn't be determined by drawing a blue outline of
the allocation instead. There was a typo though and instead we were
drawing an outline the size of the stage instead of for the given actor.
This fixes that and removes a FIXME comment relating to the blue outline
that is now implemented.
This reverts commit ca44c6a7d8abe9f2c548bee817559ea8adaa7a80.
In reality there are probably lots of actors that depend on the exact
semantics as they are documented so this change isn't really acceptable.
For example when the font changes in ClutterText we only queue a
relayout, and since it's possible that the font will have the same size
and the actor won't get a new allocation it wouldn't otherwise queue a
redraw.
Since queue_redraw requests now get deferred until just before a paint
run it is actually no longer a problem to queue the redraw here.
Instead of immediately, recursively emitting the "queue-redraw" signal
when clutter_actor_queue_redraw is called we now defer this process
until all stage updates are complete. This allows us to aggregate
repeated _queue_redraw requests for the same actor avoiding redundant
paint volume transformations. By deferring we also increase the
likelihood that the actor will have a valid paint volume since it will
have an up to date allocation; this in turn means we will more often be
able to automatically queue clipped redraws which can have a big impact
on performance.
Here's an outline of the actor queue redraw mechanism:
The process starts in clutter_actor_queue_redraw or
_clutter_actor_queue_redraw_with_clip.
These functions queue an entry in a list associated with the stage which
is a list of actors that queued a redraw while updating the timelines,
performing layouting and processing other mainloop sources before the
next paint starts.
We aim to minimize the processing done at this point because there is a
good chance other events will happen while updating the scenegraph that
would invalidate any expensive work we might otherwise try to do here.
For example we don't try and resolve the screen space bounding box of an
actor at this stage so as to minimize how much of the screen redraw
because it's possible something else will happen which will force a full
redraw anyway.
When all updates are complete and we come to paint the stage (see
_clutter_stage_do_update) then we iterate this list and actually emit
the "queue-redraw" signals for each of the listed actors which will
bubble up to the stage for each actor and at that point we will
transform the actors paint volume into screen coordinates to determine
the clip region for what needs to be redrawn in the next paint.
Note: actors are allowed to queue a redraw in reseponse to a
queue-redraw signal so we repeat the processing of the list until it
remains empty. An example of when this happens is for Clone actors or
clutter_texture_new_from_actor actors which need to queue a redraw if
their source queues a redraw.
This makes clutter_actor_queue_redraw simply bail out early if the actor
isn't a descendant of a ClutterStage since the request isn't meaningful
and it avoids a crash when trying to queue a clipped redraw against the
stage to clear the actors old location.
This splits out all the clutter_paint_volume code from clutter-actor.c
into clutter-paint-volume.c. Since clutter-actor.c and
clutter-paint-volume.c both needed the functionality of
_fully_transform_vertices, this function has now been moved to
clutter-utils.c as _clutter_util_fully_transform_vertices.
There are too many examples where the default assumption that an actor
paints inside its allocation isn't true, so we now return FALSE in the
base implementation instead. This means that by default we are saying
"we don't know the paint volume of the actor", so developers need to
implement the get_paint_volume virtual to take advantage of culling and
clipped redraws with their actors.
This patch provides very conservative get_paint_volume implementations
for ClutterTexture, ClutterCairoTexture, ClutterRectangle and
ClutterText which all explicitly check the actor's object type to avoid
making any assumptions about subclasses.
We were always explicitly checking priv->needs_allocation in
_clutter_actor_queue_redraw_with_clip, but we only need to do that if
the CLUTTER_REDRAW_CLIPPED_TO_ALLOCATION flag is used.
This initializes priv->last_paint_box with a degenerate box, so a newly
allocated actor added to the scenegraph and made visible only needs to
trigger a redraw of its initial position. If we don't have a valid
last_paint_box though we would instead trigger a full stage redraw.
To make comparing the performance with culling/clipped redraws
enabled/disabled fairer we now avoid querying the paint box when they
are disabled, so that results should reflect how the cost of
transforming paint volumes into screen space etc gets offset against the
benefit of culling.
We have bent the originally documented semantics a bit so now where we
say "Queueing a new layout automatically queues a redraw as well" it
might be clearer to say "Queuing a new layout implicitly queues a redraw
as well if anything in the layout changes".
This should be close enough to the original semantics to not cause any
problems.
Without this change then we we fail to take advantage of clipped redraws
in a lot of cases because queuing a redraw with priv->needs_allocation
== TRUE will automatically be promoted to a full stage redraw since it's
not possible to determine a valid paint-volume.
Also queuing a redraw here will end up registering a redundant clipped
redraw for the current location, doing quite a lot of redundant
transforms, and then later when re-allocated during layouting another
queue redraw would happen with the correct paint-volume.
This uses actor paint volumes to perform culling during
clutter_actor_paint.
When performing a clipped redraw (because only a few localized actors
changed) then as we traverse the scenegraph painting the actors we can
now ignore actors that don't intersect the clip region. Early testing
shows this can have a big performance benefit; e.g. 100% fps improvement
for test-state with culling enabled and we hope that there are even much
more compelling examples than that in the real world,
Most Clutter applications are 2Dish interfaces and have quite a lot of
actors that get continuously painted when anything is animated. The
dynamic actors are often localized to an area of user focus though so
with culling we can completely avoid painting any of the static actors
outside the current clip region.
Obviously the cost of culling has to be offset against the cost of
painting to determine if it's a win, but our (limited) testing suggests
it should be a win for most applications.
Note: we hope we will be able to also bring another performance bump
from culling with another iteration - hopefully in the 1.6 cycle - to
avoid doing the culling in screen space and instead do it in the stage's
model space. This will hopefully let us minimize the cost of
transforming the actor volumes for culling.
This makes clutter_actor_queue_redraw transparently use an actor's paint
volume to queue a clipped redraw.
We save the actors paint box each time it is painted so that when
clutter_actor_queue_redraw is called we can determine the old and new
location of the actor so we know the full bounds of what must be redrawn
to clear its old view and show the new.
This makes _clutter_actor_transform_and_project_box a static function
and removes the prototype from clutter-private.h since it is no longer
used outside clutter-actor.c
The base implementation for the actor queue_relayout method was queuing
an implicit redraw, but there shouldn't be anything implied from the
mere process of queuing a redraw that should force us to queue a redraw.
If actors are moved as a part of relayouting later then they will queue
a redraw. Also clutter_actor_queue_relayout() still also explicitly
queues a redraw so I think this may have been doubly redundant.
If clutter_actor_allocate finds it necessary to update an actors
allocation then it now also queue a redraw of that actor. Currently we
queue redraws for actors very early on when queuing a relayout instead
of waiting to determine the final outcome of relayouting to determine if
a redraw is really required. With this in place we can move away from
preemptive queuing of redraws.
clutter_actor_queue_relayout currently queues a relayout and a redraw,
but the plan is to change it to only queue a relayout and honour the
documentation by assuming that the process of relayouting will
result queuing redraws for any actors whos allocation changes.
This doesn't make that change it just adds an internal
_clutter_actor_queue_only_relayout function which
clutter_actor_queue_relayout now uses as well as calling
clutter_actor_queue_redraw.
There is an internal _clutter_actor_queue_redraw_with_clip API that gets
used for texture-from-pixmap to minimize what we redraw in response to
Damage events. It was previously working in terms of a ClutterActorBox
but it has now been changed so an actor can queue a redraw of volume
instead.
The plan is that clutter_actor_queue_redraw will start to transparently
use _clutter_actor_queue_redraw_with_clip when it can determine a paint
volume for the actor.
This adds a debug option to visualize the paint volumes of all actors.
When CLUTTER_PAINT=paint-volumes is exported in the environment before
running a Clutter application then all actors will have their bounding
volume drawn in green with a label corresponding to the actors type.
This is a fairly extensive second pass at exposing paint volumes for
actors.
The API has changed to allow clutter_actor_get_paint_volume to fail
since there are times - such as when an actor isn't a descendent of the
stage - when the volume can't be determined. Another example is when
something has connected to the "paint" signal of the actor and we simply
have no way of knowing what might be drawn in that handler.
The API has also be changed to return a const ClutterPaintVolume pointer
(transfer none) so we can avoid having to dynamically allocate the
volumes in the most common/performance critical code paths. Profiling was
showing the slice allocation of volumes taking about 1% of an apps time,
for some fairly basic tests. Most volumes can now simply be allocated on
the stack; for clutter_actor_get_paint_volume we return a pointer to
&priv->paint_volume and if we need a more dynamic allocation there is
now a _clutter_stage_paint_volume_stack_allocate() mechanism which lets
us allocate data which expires at the start of the next frame.
The API has been extended to make it easier to implement
get_paint_volume for containers by using
clutter_actor_get_transformed_paint_volume and
clutter_paint_volume_union. The first allows you to query the paint
volume of a child but transformed into parent actor coordinates. The
second lets you combine volumes together so you can union all the
volumes for a container's children and report that as the container's
own volume.
The representation of paint volumes has been updated to consider that
2D actors are the most common.
The effect apis, clutter-texture and clutter-group have been update
accordingly.
An Effect implementation might override the paint volume of the actor to
which it is applied to. The get_paint_volume() virtual function should
be added to the Effect class vtable so that any effect can get the
current paint volume and update it.
The clutter_actor_get_paint_volume() function becomes context aware, and
does the right thing if called from within a ClutterEffect pre_paint()
or post_paint() implementation, by allowing all effects in the chain up
to the caller to modify the paint volume.
An actor has an implicit "paint volume", that is the volume in 3D space
occupied when painting itself.
The paint volume is defined as a cuboid with the origin placed at the
top-left corner of the actor; the size of the cuboid is given by three
vectors: width, height and depth.
ClutterActor provides API to convert the paint volume into a 2D box in
screen coordinates, to compute the on-screen area that an actor will
occupy when painted.
Actors can override the default implementation of the get_paint_volume()
virtual function to provide a different volume.
This reorganizes the loop for clutter_actor_contains so that it is a
for loop rather than a while loop. Although this is mostly just
nitpicking, I think this change could make the loop slightly faster if
not optimized because it doesn't perform the self == descendant check
twice and it is clearer.
The documentation for clutter_actor_contains didn't specify what
happens when self==descendant. A strict reading of it might lead you
to think that it would return FALSE because in that case the
descendant isn't an immediate child or a deeper descendant. The code
actually would return TRUE. I think this is more useful so this patch
fixes the docs rather than the code.
This adds a check in clutter_actor_real_queue_redraw after calling
_clutter_actor_get_stage_internal to check in case the actor doesn't yet
have an associated stage so we can avoid passing a NULL stage pointer to
_clutter_stage_set_pick_buffer_valid which could cause a crash.
We have an optimization to track when there are multiple picks per
frame so we can do a full render of the pick buffer to reduce the
number of pick renders for a static scene.
There was a problem though in that we were tracking this information in
the ClutterMainContext, but conceptually this doesn't really make sense
because the pick buffer is associated with a stage framebuffer and there
can be multiple stages for one context.
This patch moves the state tracking to ClutterStage.
This reverts commit d7e86e2696.
This was a half baked patch that was pushed a bit early since it broke
test-texture-pick-with-alpha + the commit message refers to a change on
the wip/paint-box branch that hasn't happened yet.
We have an optimization to track when there are multiple picks per
frames so we can do a full render of the pick buffer to reduce the
number of pick renders for a static scene.
There were two problems with how we were tracking this state though.
Firstly we were tracking this information in the ClutterMainContext, but
conceptually this doesn't really make sense because the pick buffer is
associated with a stage framebuffer and there can be multiple stages for
one context. Secondly - since the change to how redraws are queued - we
weren't marking the pick buffer as invalid when a queuing a redraw, we
were only marking the buffer invalid when signaling/finishing the
queue-redraw process, which is now deferred until just before a paint.
This meant using clutter_stage_get_actor_at_pos after a scenegraph
change could give a wrong result if it just read from an existing (but
technically invalid) pick buffer.
This patch moves the state tracking to ClutterStage, and ensures the
buffer is invalidated in _clutter_stage_queue_actor_redraw.
http://bugzilla.clutter-project.org/show_bug.cgi?id=2283
Signed-off-by: Emmanuele Bassi <ebassi@linux.intel.com>
The Constraint should plug directly into the allocation mechanism, and
modify the allocation of the actor to which they are applied to. This is
similar to the mechanism used by the Effect class to modify the paint
sequence of an actor.
This adds a verbose warning that will be displayed if
clutter_actor_allocate is passed an actor that isn't a descendent of a
ClutterStage. Layouting should always bubble up from a stage so this
condition is likely to indicate a buggy container that allocating a
child that it has already unparented.
When building actor relative transforms, instead of using the matrix
stack to combine transformations and making assumptions about what is
currently on the stack we now just explicitly initialize an identity
matrix and apply transforms to that.
This removes the full_vertex_t typedef for internal transformation code
and we just use ClutterVertex.
ClutterStage now implements apply_transform like any other actor now
and the code we had in _cogl_setup_viewport has been moved to the
stage's apply_transform instead.
ClutterStage now tracks an explicit projection matrix and viewport
geometry. The projection matrix is derived from the perspective whenever
that changes, and the viewport is updated when the stage gets a new
allocation. The SYNC_MATRICES mechanism has been removed in favour of
_clutter_stage_dirty_viewport/projection() APIs that get used when
switching between multiple stages to ensure cogl has the latest
information about the onscreen framebuffer.
This adds _clutter_actor_get_stage_internal to clutter-private.h since
we plan to use it in clutter-offscreen-effect when preparing to
redirect an actor offscreen.
Comprehensively add (out) annotations to functions parameters
returning int/float/double.
Not handled here: structure out returns like ClutterColor or
ClutterPerspective or GValue that should get (out caller-allocates).
Not handled here: Cogl
http://bugzilla.clutter-project.org/show_bug.cgi?id=2302
