Merge branch 'animate-layout-manager' into ebassi-next

* animate-layout-manager:
  layout-manager: Document the animation support
  layout-manager: Rewind the timeline in begin_animation()
  box-layout: Remove the allocations hash table
  docs: Clean up the README file
  layout: Let begin_animation() return the Alpha
  box-layout: Add knobs for controlling animations
  box-layout: Animate layout properties
  layout: Add animation support to LayoutManager
  Add ActorBox animation methods

layout-manager: Document the animation support

Add a section inside the LayoutManager class API reference documenting,
with examples, how to implement animation support inside a layout
manager sub-class.

layout-manager: Rewind the timeline in begin_animation()

If the default implementation begin_animation() is called twice then we
should rewind the timeline, as well as updating its duration and the
easing mode of the alpha.

box-layout: Remove the allocations hash table

The BoxLayout uses a HashTable to map the latest stable allocation of
each child, in order to use that as the initial value during an
animation; this in spite of already having a perfectly valid per-child
storage as part of the layout manager: ClutterBoxChild.

The last stable allocation should be stored inside the ClutterBoxChild
instead of having it in the private data for ClutterBoxLayout. The
access remains O(1), since there is a 1:1 mapping between child and
BoxChild instances, but we save a little bit of memory and we avoid
keeping aroud allocations for old children.

docs: Clean up the README file

Merge branch 'stage-use-alpha' into ebassi-next

* stage-use-alpha:
  tests: Use accessor methods for :use-alpha
  stage: Add accessors for :use-alpha
  tests: Allow setting the stage opacity in test-paint-wrapper
  stage: Premultiply the stage color
  stage: Composite the opacity with the alpha channel
  glx: Always request an ARGB visual
  stage: Add :use-alpha property
  materials: Get the right blend function for alpha

Merge branch 'internal-flag' into ebassi-next

* internal-flag:
  conform: Add test unit for the destruction of Containers
  actor: Add internal child flag
  Clean up whitespace, indentation and comments

conform: Add test unit for the destruction of Containers

Verify that internal children do not go through the remove()
implementation, and that non-internal children do.

actor: Add internal child flag

ClutterActor checks, when destroying and reparenting, if the parent
actor implements the Container interface, and automatically calls the
remove() method to perform a clean removal.

Actors implementing Container, though, might have internal children;
that is, children that are not added through the Container API. It is
already possible to iterate through them using the Container API to
avoid breaking invariants - but calling clutter_actor_destroy() on
these children (even from the Container implementation, and thus outside
of Clutter's control) will either lead to leaks or to segmentation
faults.

Clutter needs a way to distinguish a clutter_actor_set_parent() done on
an internal child from one done on a "public" child; for this reason, a
push/pop pair of functions should be available to Actor implementations
to mark the section where they wish to add internal children:

  ➔ clutter_actor_push_internal ();
    ...
    clutter_actor_set_parent (child1, parent);
    clutter_actor_set_parent (child2, parent);
    ...
  ➔ clutter_actor_pop_internal ();

The set_parent() call will automatically set the newly added
INTERNAL_CHILD private flag on each child, and both
clutter_actor_destroy() and clutter_actor_unparent() will check for the
flag before deciding whether to call the Container's remove method.

layout: Let begin_animation() return the Alpha

When beginning a new animation for a LayoutManager, the implementation
should return the ClutterAlpha used. This allows controlling the
timeline and/or modifying the animation parameters on the fly.

box-layout: Add knobs for controlling animations

ClutterLayoutManager does not have any state associated with it, and
defers all the state to its sub-classes.

The BoxLayout is thus in charge of controlling:

  • whether or not animations should be used
  • the duration of the animation
  • the easing mode of the animation

By adding three new properties:

  • ClutterBoxLayout:use-animations
  • ClutterBoxLayout:easing-duration
  • ClutterBoxLayout:easing-mode

And their relative accessors pairs we can make BoxLayout decide whether
or not, and with which parameters, call the begin_animation() method of
ClutterLayoutManager.

The test-box-layout has been modified to reflect this new functionality,
by checking the key-press event for the 'a' key symbol to toggle the use
of animations.

box-layout: Animate layout properties

Use the newly added animation support inside LayoutManager to animate
between state changes of the BoxLayout properties.

The implementation is based on equivalent code from Mx, written by:

  Thomas Wood <thomas.wood@intel.com>

layout: Add animation support to LayoutManager

In order to animate a fluid layout we cannot use the common animation
code paths as they will override the size request and allocation paths
that are handled by the layout manager itself.

One way to introduce animations in the allocation sequence is to use a
Timeline and an Alpha to compute a progress value and then use that
value to interpolate an ActorBox between the initial and final states of
the animation - with the initial state being the last allocation of the
child prior to the animation start, and the final state the allocation
of the child at the end; for every frame of the Timeline we then queue a
relayout on the layout manager's container, which will result in an
animation.

ClutterLayoutManager is the most likely place to add a generic API for
beginning and ending an animation, as well as the place to provide a
default code path to create the ancillary Timeline and Alpha instances
needed to drive the animation.

A LayoutManager sub-class will need to:

  • call clutter_layout_manager_begin_animation() whenever it should
    animate between two states, for instance: whenever a layout property
    changes value;
  • eventually override begin_animation() and end_animation() in case
    further state needs to be set up, and then chain up to the default
    implementation provided by LayoutManager;
  • if a completely different implementation is required, the layout
    manager sub-class should override begin_animation(), end_animation()
    and get_animation_progress().

Inside the allocate() implementation the sub-class should also
interpolate between the last known allocation of a child and the newly
computed allocation.

Add ActorBox animation methods

ClutterActorBox should have an interpolate() method that allows to
compute the intermediate values between two states, given a progress
value, e.g.:

        clutter_actor_box_interpolate (start, end, alpha, &result);

Another utility method, useful for layout managers, is a modifier
that clamps the members of the actor box to the nearest integer
value.

Clean up whitespace, indentation and comments

Merge branch 'get-current-event' into ebassi-next

* get-current-event:
  Add clutter_get_current_event

Add clutter_get_current_event

When getting signals from higher level toolkits, occasionally
one wants access to the underlying event; say for a Button
widget's "clicked" signal, to get the keyboard state.

Rather than having all of the highlevel widgets emit
ClutterEvent just for the more unusual use cases,
add a global function to access the event state.

http://bugzilla.openedhand.com/show_bug.cgi?id=1888

Signed-off-by: Emmanuele Bassi <ebassi@linux.intel.com>

Merge branch 'no-layout-flag' into ebassi-next

* no-layout-flag:
  actor: Add a NO_LAYOUT flag for actors

Merge branch 'size-cache' into ebassi-next

* size-cache:
  tests: Clean up the BoxLayout interactive test
  actor: Add debugging notes for size cache
  Add a cache of size requests

x11: Emulate XKB's detectable key auto-repeat

Old-style X11 terminals require that even modern X11 send KeyPress
and KeyRelease pairs when auto-repeating. For this reason modern(-ish)
API like XKB has a way to detect auto-repeat and do a single KeyRelease
at the end of a KeyPress sequence.

The newly added check emulates XKB's detectable auto-repeat by peeking
the next event after a KeyRelease and checking if it's a KeyPress for
the same key and timestamp - and then ignoring the KeyRelease if it
matches.

docs: Move RELEASING under docs/

stage: Deprecate default stage size macros

The macros for getting the size of the default stage are a relic of the
past and they should be deprecated.

tests: Use accessor methods for :use-alpha

Instead of using g_object_set().

stage: Add accessors for :use-alpha

Use real accessors for the :use-alpha property.

tests: Allow setting the stage opacity in test-paint-wrapper

This allows testing the Stage:use-alpha property and the blending done
by a compositor.

stage: Premultiply the stage color

In case we are using Stage:use-alpha then we need to premultiply the
stage color to get the correct blending from the compositor.

x11: Do not manage a foreign window

If a Stage has been set to use a foreign Window then Clutter should not
be managing it; calling XWithdrawWindow and XMapWindow should be
reserved to the windows we manage ourselves.

Remove clutter_set_default_text_direction()

Setting the default text direction programmatically is wrong: it is a
value dependent on the locale or by the environment.

Queue a relayout when the default text direction changes

We need a relayout cycle if the default direction for the text changes
while the main loop is running.

stage: Composite the opacity with the alpha channel

The Stage's opacity should be composited with the alpha component of the
Stage's background color.

actor: Add a NO_LAYOUT flag for actors

Some actor implementation might avoid imposing any layout on their
children. The Actor base class usually assumes some sort of layout
management is in place, so it will queue relayouts when, for instance,
an actor is shown or is hidden. If the parent of the actor does not
impose any layout, though, showing or hiding one of its children will
not affect the layout of the others.

An example of this kind of container is ClutterGroup.

By adding a new Actor flag, CLUTTER_ACTOR_NO_LAYOUT, and by making
the Group actor set it on itself, the Actor base class can now decide
whether or not to queue a relayout. The flag is not meant to be used
by application code, and should only be set when implementing a new
container.

http://bugzilla.openedhand.com/show_bug.cgi?id=1838

tests: Clean up the BoxLayout interactive test

actor: Add debugging notes for size cache

Add a note for cache hits, and another one for cache misses.

box: Add relative packing methods

ClutterBox should provide some convenience functions to pack a new child
at a given position, either an absolute index or relative to a sibling.

Add a cache of size requests

clutter_actor_get_preferred_width/height currently caches only one size
requests, for a given height / width.

It's common for a layout manager to call get_preferred_width with 2
different heights during the same allocation cycle. Typically once in
the size request, once in the allocation. If
clutter_actor_get_preferred_width is called
alternatively with 2 different for_height, the cache is totally
inefficient, and we end up always querying the actor size even
when the actor does not need a re-allocation.

http://bugzilla.openedhand.com/show_bug.cgi?id=1876

Signed-off-by: Emmanuele Bassi <ebassi@linux.intel.com>

flow-layout: Use the natural size

Fix a copy-and-paste thinko where the cell size was computed using the
minimum size instead of the natural size. For actors with a minimum size
of zero, like Textures, this implied always a zero allocation.

Signed-off-by: Emmanuele Bassi <ebassi@linux.intel.com>

cogl: Use #ifdef GL around GL_TEXTURE_RECTANGLE_ARB

Commit 558b17ee1e added support for rectangle textures to the
framebuffer code. Under GLES there is no GL_TEXTURE_RECTANGLE_ARB
definition so this was breaking the build. The rest of Cogl uses
ifdef's around that constant so we should do the same here.

build: Fix CPP and LD flags

• The debug flags are pre-processor ones, so they should be listed
  inside AM_CPPFLAGS.

• Clutter's publicly exported symbols match the following regular
  expression:

    ^(clutter|cogl|json)_*

  The old one also listed "pango" as a possible prefix, but the
  Pango API is now under the Cogl namespace.

docs: Document Clutter's threading model

Be explicit on how to deal with threads and Clutter.

docs: Fix docbook syntax

The <variablename> tag is really called <varname> in DocBook.

docs: Annotate StageManager

The ClutterStageManager instance structure is private, so we need a
"floating" annotation.

Remove a gtk-doc annotation

The Mesa matrix code still has a comment that looks like a gtk-doc
annotation.

layout: Add padding to LayoutMeta

Add some padding to the LayoutMeta and LayoutMetaClass structures.

Remove unused variable 'lang'

Fix a compiler warning.

flow-layout: Include the first line when calculating number of lines

This ensures that the preferred height / width height takes into consideration
the correct amount of padding

flow-layout: Respect row-spacing/col-spacine in horizontal/vertical flows

We need to add the row-spacing value when calculating the y position for lines
of actors in horizontal flowing layouts.

Similarly we need to add the col-spacing value when calculating the x posution
for actors in vertical flowing layouts.

glx: Always request an ARGB visual

When requesting the GLXFBConfig for creating the GLX context, we should
always request one that links to an ARGB visual instead of a plain RGB
one.

By using an ARGB visual we allow the ClutterStage:use-alpha property to
work as intended when running Clutter under a compositing manager.

The default behaviour of requesting an ARGB visual can be disabled by
using the:

  CLUTTER_DISABLE_ARGB_VISUAL

Environment variable.

stage: Add :use-alpha property

The ClutterStage:use-alpha property is used to let a stage know that it
should honour the alpha component of the ClutterStage:color property.

If :use-alpha is set to FALSE the stage always uses the full opacity
when clearing itself before a paint(); otherwise, the alpha value is
used.

materials: Get the right blend function for alpha

The correct blend function for the alpha channel is:

  GL_ONE, GL_ONE_MINUS_SRC_ALPHA

As per bug 1406. This fix was dropped when the switch to premultiplied
alpha was merged.

actor: Fix a pre-condition check in set_text_direction()

The check is failing because the condition should be:

  text_dir != CLUTTER_TEXT_DIRECTION_DEFAULT

build: More cleanups for the configure summary

Document each section, and add some more items to the summary like what
JSON-GLib are we using, and which version of the GLES API is COGL
wrapping.

build: Require a stable JSON-GLib version

The 0.7 version is the development cycle for JSON-GLib 0.8.

docs: Add missing symbols to clutter-sections.txt

Merge branch 'text-direction'

* text-direction:
  docs: Add text-direction accessors
  Set the default language on the Pango context
  actor: Set text direction on parenting
  tests: Display the index inside text-box-layout
  box-layout: Honour :text-direction
  text: Dirty layout cache on text direction changes
  actor: Add :text-direction property
  Use the newly added ClutterTextDirection enumeration
  Add ClutterTextDirection enumeration

docs: Add text-direction accessors

build: Fix the SUBDIRS ordering

Signed-off-by: Emmanuele Bassi <ebassi@linux.intel.com>

docs: Move documentation under doc/

Clean up the root directory of the project and try to keep the
documentation all together.

cookbook: Clean up the text

• Remove the empty sections.

• Add the description for the "overriding the paint sequence" recipe.

docs: Fix recursion into doc/ directory

We should always recurse into the doc/ directory; whether we should then
recurse into reference/, cookbook/ and manual/ is a matter of specific
configure-time flags.

docs: Clean up the additional documentation build

• Make the manual a DevHelp book

• Make the generation of PDFs of the cookbook and the manual optional

• Consequently, make the hard dependency on jw optional

• Clean up the checks and build for the additional documentation

[cookbook] Build the Cookbook as a devhelp document

Instead of creating stand-alone HTML files, use XSLT to transform the
DocBook into a DevHelp file, so that we can read the Cookbook inside
DevHelp -- just like the API reference.

[cookbook] Fix folds

Update the ignore file

Add the temporary and output files of the cookbook.

Add the secon recipe to the Actors chapter

The second recipe shows how to use the ::paint signal to override
the paint sequence of a pre-existing actor.

Add the first recipe to the Actors chapter

The first recipe shows how to be notified when the relative position
and size of an actor changes using the notify:: signal on the actor's
dimensional and positional properties.

Add a preface instead of an introduction

Make the Cookbook look more like a book than a tutorial.

Add the Clutter Cookbook to the build

The "Clutter Cookbook" is a document designed to contain solutions
to common problems applications developers might encounter when using
Clutter. It is meant as a companion to the API reference but it
requires knowledge of the Clutter API and framework.

layout-manager: Create LayoutMeta on demand

The ClutterLayoutMeta instances should be created on demand, whenever
the layout manager needs them - if the layout manager supports layout
properties.

This removes the requirement to call add_child_meta() and
remove_child_meta() on add and remove respectively; it also simplifies
the implementation of LayoutManager sub-classes since we can add
fallback code in the base abstract class.

Eventually, this will also lead to an easier to implement ClutterScript
parser for layout properties.

With the new scheme, the ClutterLayoutMeta instance is created whenever
the layout manager tries to access it; if there isn't an instance
already attached to the container's child, one is created -- assuming
that the LayoutManager sub-class has overridden the
get_child_meta_type() virtual function and it's returning a valid GType.

We can also provide a default implementation for create_child_meta(),
by getting the GType and instantiating a ClutterLayoutMeta with all the
fields already set. If the layout manager requires more work then it can
obviously override the default implementation (and even chain up to it).

The ClutterBox actor has been updated, as well as the ClutterBoxLayout
layout manager, to take advantage of the changes of LayoutManager.

conform: Add named object property unit for ClutterScript

We should exercise the resolution of the object properties containing a
string pointing to an object previously defined using ClutterScript.

Use the correct colour when clearing the stage for picking

The colour test for the stage in _clutter_do_pick checks for white to
determine whether the stage was picked but since 47db7af4d we were
setting the colur to black. This usually worked because the id of the
default stage ends up being 0 which equates to black. However if a
second stage is created then it will always end up picking the first
stage.

cogl: Enable blending if a lighting colour is semi-transparent

We currently enable blending if the material colour has
transparency. This patch makes it also enable blending if any of the
lighting colours have transparency. Arguably this isn't neccessary
because we don't expose any API to enable lighting so there is no
bug. However it is currently possible to enable lighting with a direct
call to glEnable and this otherwise works so it is a shame not to have
it.

http://bugzilla.openedhand.com/show_bug.cgi?id=1907

Set the default language on the Pango context

When creating the Pango context we should also set the language
to be the default Pango language.

actor: Set text direction on parenting

When setting the parent on an actor we should set the text direction to
be the same as the parent's.

gitignore: update gitignore files to match the latest cogl tests

Some cogl tests were renamed in c1247066 to have 'cogl' in their names.
It's a good excuse to merge .gitigore and tests/.gitignore.

tests: fix argument parsing of test-texture-quality

This test did not open redhand.png as argc/argv should be handled
normally (argv[0] being the name of the exectutable).

Reviewed-by: Emmanuele Bassi <ebassi@linux.intel.com>

tests: give all the arguments to the wrapper

Some tests can be given extra arguments. The test-interactive dispatch
mechanism handles that but the small shell scripts around the wrapper
do not forward the arguments to the wrapper.

Reviewed-by: Emmanuele Bassi <ebassi@linux.intel.com>

primitives: Don't use dynamic arrays since VS2008 can't cope with them :-(

This changes _cogl_path_fill_nodes_scanlines to use g_alloca instead of
using a variable to declare an array length.

picking: avoid redundant picking geometry for the stage.

The stage's pick id can be written to the framebuffer when we call
cogl_clear so there's no need for the stage to also chain up in it's pick
function resulting in clutter-actor.c also emitting a rectangle for the
stage.

tests: rename cogl conformance tests so they can be clearly identified

All Cogl conformance tests are now prefixed 'test-cogl-'

cogl: deprecate cogl_draw_buffer API and replace with a cogl_framebuffer API

cogl_push_draw_buffer, cogl_set_draw_buffer and cogl_pop_draw_buffer are now
deprecated and new code should use the new cogl_framebuffer_* API instead.

Code that previously did:
    cogl_push_draw_buffer ();
    cogl_set_draw_buffer (COGL_OFFSCREEN_BUFFER, buffer);
    /* draw */
    cogl_pop_draw_buffer ();
should now be re-written as:
    cogl_push_framebuffer (buffer);
    /* draw */
    cogl_pop_framebuffer ();

As can be seen from the example above the rename has been used as an
opportunity to remove the redundant target argument from
cogl_set_draw_buffer; it now only takes one call to redirect to an offscreen
buffer, and finally the term framebuffer may be a bit more familiar to
anyone coming from an OpenGL background.

cogl_offscreen: deprecate cogl_offscreen_ref/unref.

New code should use cogl_handle_ref/unref

cogl: Use a vtable for the texture backends instead of a type and switch

Instead of storing an enum with the backend type for each texture and
then using a switch statement to decide which function to call, we
should store pointers to all of the functions in a struct and have
each texture point to that struct. This is potentially slightly faster
when there are more backends and it makes implementing new backends
easier because it's more obvious which functions have to be
implemented.

offscreen: cogl_offscreen_new_to_texture now supports GL_TEXTURE_RECTANGLE_ARB

cogl_offscreen_new_to_texture previously bailed out if the given texture's
GL target was anything but GL_TEXTURE_2D, but it now also allows
foreign GL_TEXTURE_RECTANGLE_ARB textures.

Thanks to Owen for reporting this issue, ref:
https://bugzilla.gnome.org/show_bug.cgi?id=601032

debug: remove the COGL_DEBUG=client-side-matrices option

Cogl only supports client side matrices so this debug option is no longer
useful.

[cogl-material] Adds cogl_material_copy() API

cogl_material_copy can be used to create a new CoglHandle referencing a copy
of some given material.

From now on we will advise that developers always aim to use this function
instead of cogl_material_new() when creating a material that is in any way
derived from another.

By using cogl_material_copy, Cogl can maintain an ancestry for each material
and keep track of "similar" materials.  The plan is that Cogl will use this
information to minimize the cost of GPU state transitions.

[cogl] remove unused gles/cogl-utils.[c,h]

The only function in gles/cogl-utils.c was cogl_util_next_p2() and it's
redundant since we also have a cogl/cogl-utils.[c,h]

docs: Don't document cogl_flush_gl_state as public API

This function was #if 0'd before we released Clutter 1.0 so there's no
implementation of it.  At some point we thought it might assist with
developers breaking out into raw OpenGL.  Breaking out to raw GL is a
difficult problem though so we decided instead we will wait for a specific
use case to arrise before trying to support it.

animation: Keep a weak reference on actors

Actors, unlike objects, can effectively go away whilst being
animated - usually because of an explicit destoy().

The Animation created by clutter_actor_animate() and friends
should keep a weak reference on the actor and eventually
get rid of the animation itself in case the actor goes away
whilst being animated.

Minor fix to cogl material

_cogl_material_get_layer expects a CoglMaterial* pointer but it was
being called with a CoglHandle. This doesn't matter because the
CoglHandle is actually just the CoglMaterial* pointer anyway but it
breaks the ability to change the _cogl_material_pointer_from_handle
macro.

docs: Add indices to the Cogl API reference

The Clutter API reference has an index of the symbols for each minor
version, and a list of deprecated symbols. The Cogl API reference
should have the same layout.

docs: Increase consistency in Cogl documentation

docs: Documentation fixes for CoglMatrix

Clean up the references, the docbook tags, and the style to fit in
with the rest of the API references for Cogl and Clutter.

Whitespace fix for cogl-color.h

docs: Documentation fixes for CoglMaterial

Clean up the references, the docbook tags, and the style to fit in
with the rest of the API references for Cogl and Clutter.

docs: Documentation fixes for CoglBitmap

• Use the same style for the Cogl API reference as the one used for
  the Clutter API reference.

• Fix the introspection annotations for cogl_bitmap_get_size_from_file()

docs: Fix Cogl API reference build

• Ignore all the private header files

• Add all missing/unused symbols

• Remove deprecated symbols from 0.*

docs: Remove non-gtk-doc annotations

The imported Mesa matrix code has some documentation annotations
that make gtk-doc very angry. Since it's all private anyway we
can safely make gtk-doc ignore the offending stuff.

docs: Fix the 'Since' annotation for some functions

The 'Since' annotation needs to have a colon after it or gtk-doc won't
pick it up.

cogl: Use APIENTRY for GL function pointer declarations

This matters for platforms such as Windows that use a different
calling covention from the default for GL functions.

build: Fix out-of-tree builds for cogl-defines.h

$(COGL_DRIVER)/cogl-defines.h is generated in the configure script so
it ends up in the build directory. Therefore the build rule for
cogl/cogl-defines.h should depend on the file in $(builddir) not
$(srcdir).