This adds a "Cogl deprecated API" chapter to the Cogl reference manual
so we can group all the documentation for deprecated symbols together
instead of having them clutter up the documentation of symbols we would
rather developers used.
The CoglTexture3D API is only available when defining
COGL_ENABLE_EXPERIMENTAL_API so it should be listed in the experimental
section of the API reference.
* cookbook-layouts-bind-constraint:
cookbook: Add recipe about sync'ing actor sizes
cookbook: Example using allocation-changed to sync actor size
cookbook: Simple example to demonstrate bind constraint
cookbook: Example of using a bind constraint for an overlay
The recipe covers how to use ClutterBindConstraint
to bind actor sizes together.
It gives some examples of where this approach is appropriate,
as well as explaining an alternative using allocation-changed
or notify::* signals.
Three examples are given:
1. Resizing a texture to the stage.
2. Resizing a rectangle to act as a transparent overlay on
top of a texture (using constraints).
3. Resizing a rectangle to act as a transparent overlay on
top of a texture, but with a size proportional to the texture
(using a handler connected to allocation-changed signals
emitted by the texture).
An alternative method (not using constraints) to bind
one actor's size and position to another. Used as
an example in the recipe about resizing one actor in
sync with a source actor.
A simple example showing how to scale an actor to the stage.
Demonstrates ClutterBindConstraint and ClutterAlignConstraint
in a fashion suitable for a short recipe.
Example code which loads an image into a texture, and resizes
the image in response to +/- key presses. The overlay is
a transparent rectangle which is bound to the height and
width of the texture; on clicking the texture, the overlay
is made visible by increasing its opacity.
This demonstrates how to use constraints to simplify code
for resizing an actor which is "dependent" on another actor.
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 recipe explains how to "reuse" the same animation
definition for different actors, by creating a new
instance of a "rig" (empty container) and animation
for the rig each time the animation is required.
An actor is then re-parented to the rig and animated
using it, rather than being animated directly.
JSON is used to define the rig + animator, to make
creating new instances of them simpler. The recipe
also discusses various caveats around using this
approach, rather than directly animating an actor.
Modified the "animation reuse" sample code to provide
a simpler example to explain in the recipe.
Also modified variable names to mirror the names used
for the previous "complex animation" example and added
some more comments, to further simplify and support the
recipe.
With some help from pippin, moved variable declarations
into more sensible positions within their functions,
changed a function name, and found a better way
to unref a script once its associated actor has
been destroyed.
Extracted the animation into its own JSON definition,
then create a new script and get the animation each
time a rectangle is clicked.
Removes the need to reparent onto the background and
copy property values to the rectangle after the animation,
and generally much cleaner.
Added an example showing how to reuse a ClutterAnimator
instance to animate multiple actors at different times
using an animatable rig, combined with reparenting.
The keysyms defines in clutter-keysyms.h are generated from the X11 key
symbols headers by doing the equivalent of a pass of sed from XK_* to
CLUTTER_*. This might lead to namespace collisions, down the road.
Instead, we should use the CLUTTER_KEY_* namespace.
This commit includes the script, taken from GDK, that parses the X11
key symbols and generates two headers:
- clutter-keysyms.h: the default included header, with CLUTTER_KEY_*
- clutter-keysyms-compat.h: the compatibility header, with CLUTTER_*
The compat.h header file is included if CLUTTER_DISABLE_DEPRECATED is
not defined - essentially deprecating all the old key symbols.
This does not change any ABI and, assuming that an application or
library is not compiling with CLUTTER_DISABLE_DEPRECATED, the source
compatibility is still guaranteed.
When animating an actor through clutter_actor_animate() and friends we
might want forcibly detach the animation instance from the actor in
order to start a new one - for instance, in response to user
interaction.
Currently, there is no way to do that except in a very convoluted way,
by emitting the ::completed signal and adding a special case in the
signal handlers; this is due to the fact that clutter_actor_animate()
adds more logic than the one added by clutter_animation_set_object(),
so calling set_object(NULL) or unreferencing the animation instance
itself won't be enough.
The right way to approach this is to add a new method to Clutter.Actor
that detaches any eventual Animation currently referencing it.
http://bugzilla.clutter-project.org/show_bug.cgi?id=2051
Uses ClutterAnimator to implement a reasonably complex
animation of a single actor (movement along a path with
simultaneous scaling).
Provides a metaphor for thinking about ClutterAnimator
animations (stage directions) and explains keys and key
frames in some depth. Also compares ClutterAnimator
with other possible approaches to this type of animation
(implicit animations, ClutterState).
Added another JSON example to show how transitions can
be easily overlapped when using ClutterAnimator (two
sequences of 5 transitions, simultaneous with two
sequences of 1 transition).
Modified the C JSON loader program so it can be used with
this example as well.
Intel CE3100 and CE4100 have several planes (framebuffers) and a
hardware blender to blend the planes togeteher to produce the final
image.
clutter_cex100_set_plane() lets you configure which framebuffer clutter
will use for its rendering.
*** This is an API change ***
The create_target() virtual function should return a CoglHandle to a
texture; clutter_offscreen_effect_get_target(), instead, returns a
CoglMaterial to be painted in the implementation of the paint_target()
virtual function.
Instead of equating textures with materials, and confusing the user of
the API, we should mark the difference more prominently.
First of all, we should return a CoglMaterial* (now that we have that
as a public type) in get_target(); having handles all over the place
does not make it easier to distinguish the semantics of the virtual
functions.
Then we should rename create_target() to create_texture(), to make it
clear that what should be returned is a texture that is used as the
backing for the offscreen framebuffer.
Added a recipe explaining how to connect signals to handlers
in the JSON definition used by ClutterScript; also shows
how to connect the signals in code once the JSON has been
loaded.
Includes guidelines on writing handlers (i.e. need to use
-export-dynamic and non-static functions) and example
which connects a handler for motion events on a rectangle.
GEnum nicknames can be used to set properties in JSON
definitions, so added a callout to the JSON example explaining
this, and showing how to derive the nickname for an enumeration
value.
Modified the example code to use nicknames as well.
As JSON can make use of nicknames for GEnum properties,
mentioned this in the table mapping C property values
to their JSON equivalents (as the nick name is a much
shorter and cleaner way of setting a property in JSON).
Wrote an introduction to using ClutterScript with JSON. Focus
is on explaining why you might want to use it, basic principles
of operation (with annotated JSON sample), and how to map
data types from C to JSON.
Written simultaneously with a short recipe (uses the same sample
code) showing how to load a JSON file and retrieve objects
from it in code.
Commented the ClutterScript example so it can be used
inline as part of the recipe, rather than as an
example in the appendix (it's too simple to warrant
a separate appendix).
New script chapter needs an introduction.
While writing the introduction, also slightly changed the
emphasis of the recipe (towards refactoring an existing
application to use ClutterScript) and incorporated example
code into documentation.
Set a parameter on the XSLT transform so that callout elements
are rendered as text rather than graphics (removes the need
to add callout graphics to the build).
