Drop mentions of deprecated classes and API, and update the inline
example code.
Still some way to go, and the cookbook would probably benefit from
having a recipe on how to use ClutterActor to build a scene.
Given the size and scope of the changes in ClutterActor, we ought to
rewrite the overall description of what an actor is, what it does, and
how are you supposed to use it and subclass it.
This adds a --enable-wayland-compositor configure option which will add
support for a ClutterWaylandSurface actor which can be used to aid in
writing Wayland compositors using Clutter by providing a ClutterActor to
represent Wayland client surfaces.
Notably this configure option isn't tied into any particular backend
since conceptually the compositor support can be used in conjunction
with any clutter backend that has corresponding Cogl support.
Reviewed-by: Emmanuele Bassi <ebassi@linux.intel.com>
This updates Wayland support in line with upstream changes to the Wayland
API and protocol.
This update means we no longer use the Cogl stub winsys so a lot of code
that had to manually interact with EGL and implement a swap_buffers
mechanism could be removed and instead we now depend on Cogl to handle
those things for us.
This update also adds an input device manager consistent with other
clutter backends.
Note: to use the client side "wayland" clutter backend you need to have
built Cogl with --enable-wayland-egl-platform. If Cogl has been built
with support for multiple winsys backends then you should run
applications with COGL_RENDERER=EGL in the environment.
Reviewed-by: Emmanuele Bassi <ebassi@linux.intel.com>
* deprecate-default-stage:
evdev: do not associate device with stage
evdev: don't even process events without a default stage
docs: Note default stage deprecation in README
docs: Remove clutter_stage_get_default()
stage: Deprecate the default stage
script: Do not use clutter_stage_get_default()
cally/actor: Do not use the default stage as a fallback
Try to mop up the default stage mess
performance/*: Do not use clutter_stage_get_default()
interactive/*: Do not use clutter_stage_get_default()
Merge with a11y
micro-bench/*: Do not use clutter_stage_get_default()
accessibility/*: Do not use clutter_stage_get_default()
conform/*: Do not use clutter_stage_get_default()
A lot of the example code in the cookbook and the API reference still
uses the default stage — sometimes as if it were a non-default one,
which once again demonstrates how the default stage was a flawed concept
that just confused people.
The Clutter backend split is opaque enough that should allow us to just
build all possible backends inside the same shared object, and select
the wanted backend at initialization time.
This requires some work in the build system, as well as the
initialization code, to remove duplicate functions that might cause
conflicts at build and link time. We also need to defer all the checks
of the internal state of the platform-specific API to run-time type
checks.
The deprecated sections should be much more prominently separated from
the current API; we can use a new part inside the main reference index
for this.
The disconnect_matched() function is a bit too complicated, and its
simpler wrapper disconnect_by_func() is functionally equivalent in the
cases used by the cookbook examples.
Keeping the backing Cairo surface of a CairoTexture canvas in sync with
the actor's allocation is tedious and prone to mistakes. We can
definitely do better by simply exposing a property that does the surface
resize and invalidation automagically on ::allocate.
The current "create context/draw/destroy context" pattern presents
various problems. The first issue is that it defers memory management to
the caller of the create() or create_region() methods, which makes
bookkeeping of the cairo_t* harder for language bindings and third party
libraries. The second issue is that, while it's easier for
draw-and-forget texturs, this API is needlessly complicated for contents
that have to change programmatically - and it introduces constraints
like calling the drawing code explicitly after a surface resize (e.g.
inside an allocate() implementation).
By using a signal-based approach we can make the CairoTexture actor
behave like other actors, and like other libraries using Cairo as their
2D drawing API.
The semantics of the newly-introduced ::draw signal are the same as the
one used by GTK+:
- the signal is emitted on invalidation;
- the cairo_t* context is owned by the actor;
- it is safe to have multiple callbacks attached to the same
signal, to allow composition;
- the cairo_t* is already clipped to the invalidated area, so
that Cairo can discard geometry immediately before we upload
the texture data.
There are possible future improvements, like coalescing multiple
invalidations inside regions, and performing clipped draws during
the paint cycle; we could even perform clipped redraws if we know the
extent of the invalidated area.
This adds a public function to get the bounds of the current clipped
redraw on a stage. This should only be called while the stage is being
painted. The function diverts to a virtual function on the
ClutterStageWindow implementation. If the function isn't implemented
or it returns FALSE then the entire stage is reported. The clip bounds
are in integer pixel coordinates in the stage's coordinate space.
http://bugzilla.clutter-project.org/show_bug.cgi?id=2421
The recommended command to check for differences from master to the
remote master was using git log with a range from the local master to
the remote master but this wouldn't work if the local master is ahead
of the remote master because the range is backwards. This patch
changes it to recommend git diff --stat instead because then the
command would work even if the two branches have diverged.
* swipe-action:
test-swipe-action: Clean up the test code
docs: Add the new actions to the API reference
gesture-action: Remove the multi-device entry points
swipe-action: Remove the required devices call
swipe-action: Clean up
gesture-action: Clean up
Add ClutterSwipeAction and ClutterGestureAction
ChangeLog.pre-git-import is useless since the Git log contains the
pre-Git history anyway.
AUTHORS is not really useful, as many more people have been committing
to Clutter for a while now.
The G_CONST_RETURN define in GLib is, and has always been, a bit fuzzy.
We always used it to conform to the platform, at least for public-facing
API.
At first I assumed it has something to do with brain-damaged compilers
or with weird platforms where const was not really supported; sadly,
it's something much, much worse: it's a define that can be toggled at
compile-time to remove const from the signature of public API. This is a
truly terrifying feature that I assume was added in the past century,
and whose inception clearly had something to do with massive doses of
absynthe and opium — because any other explanation would make the
existence of such a feature even worse than assuming drugs had anything
to do with it.
Anyway, and pleasing the gods, this dubious feature is being
removed/deprecated in GLib; see bug:
https://bugzilla.gnome.org/show_bug.cgi?id=644611
Before deprecation, though, we should just remove its usage from the
whole API. We should especially remove its usage from Cally's internals,
since there it never made sense in the first place.
In Cogl, cogl-pango.h has moved to <cogl-pango/cogl-pango.h>. When
using the experimental 2.0 API (which Clutter does) it is no longer
possible to include it under the old name of <cogl/cogl-pango.h> so we
need to update the include location.
This adds a virtual to ClutterActor so that an actor subclass can
report whether it has overlapping primitives. ClutterActor uses this
to determine whether it needs to use ClutterFlattenEffect to implement
the opacity property. The default implementation of the virtual
returns TRUE which means that most actors will end up being redirected
offscreen when the opacity != 255. ClutterTexture and ClutterRectangle
override this to return FALSE because they should never need to be
redirected. ClutterClone overrides it to divert to the source.
The values for the ClutterOffscreenRedirect enum have changed to:
AUTOMATIC_FOR_OPACITY
The actor will only be redirected if has_overlaps returns TRUE and
the opacity is < 255
ALWAYS_FOR_OPACITY
The actor will always be redirected if the opacity < 255 regardless
of the return value of has_overlaps
ALWAYS
The actor will always be redirected offscreen.
This means that the property can't be used to prevent the actor from
being redirected but only to increase the likelihood that it will be
redirected.
ClutterActor now adds and removes the flatten effect depending on
whether flattening is needed directly in clutter_actor_paint(). There
are new internal versions of add/remove_effect that don't queue a
redraw. This means that ClutterFlattenEffect is now just a no-op
subclass of ClutterOffscreen. It is only needed because
ClutterOffscreen is abstract. Removing the effect also makes it so
that the cached image will be freed as soon as an actor is repainted
without being flattened.
This adds a property which can be used to redirect the actor through
an FBO before painting so that it becomes flattened in an image. The
image can be used as a cache to avoid having to repaint the actor if
something unrelated in the scene changes. It can also be used to
implement correct opacity even if the actor has overlapping
primitives. The property is an enum that takes three values:
CLUTTER_OFFSCREEN_REDIRECT_NEVER: The default behaviour which is to
never flatten the actor.
CLUTTER_OFFSCREEN_REDIRECT_ALWAYS: The actor is always redirected
through an FBO.
CLUTTER_OFFSCREEN_REDIRECT_ONLY_FOR_OPACITY: The actor is only
redirected through an FBO if the paint opacity is not 255. This
value would be used if the actor wants correct opacity. It will
avoid the overhead of using an FBO whenever the actor is fully
opaque.
The property is implemented by installing a ClutterFlattenEffect.
ClutterFlattenEffect is a new internal class which subclasses
ClutterOffscreen to redirect the painting to an FBO. When
ClutterOffscreen paints, the effect sets an opacity override on the
actor so that the image will always contain the actor at full
opacity. The opacity is then applied to the resulting image before
painting it to the stage. This means the actor does not need to be
redrawn while the opacity is being animated.
The effect has a high internal priority so that it will always occur
before any other effects and it gets hidden from the application.
This adds a new public function to queue a rerun of an effect. If
nothing else queues a redraw then when the effect's actor is painted
the effect will be run without the CLUTTER_EFFECT_RUN_ACTOR_DIRTY
flag. This allows parametrised offscreen effects to report that they
need to redraw the image without having to redraw the underlying
actor. This will be used to implement the 'transparency' effect of
ClutterActor.
If multiple redraws are queued with different effects then redrawing
is started from the one that occurs last in the list of effects.
Internally the function is a wrapper around the new function
_clutter_actor_queue_redraw_full. This is intended to be the sole
point of code for queuing redraws on an actor. It has parameters for
the clip and the effect. The other two existing functions to queue a
redraw (one with a clip and one without) now wrap around this function
by passing a NULL effect.
This adds a new virtual to ClutterEffect which is intended to be a
more flexible replacement for the pre and post_paint functions. The
implementation of a run virtual would look something like this:
void
effect_run (ClutterEffect *effect,
ClutterEffectRunFlags flags)
{
/* Set up state */
/* ... */
/* Chain to the next item in the paint sequence */
clutter_actor_continue_paint (priv->actor);
/* Clean up state */
/* ... */
}
ClutterActor now just calls this virtual instead of the pre_paint and
post_paint functions. It keeps track of the next effect in the list so
that it knows what to do when clutter_actor_continue_paint is
called. clutter_actor_continue_paint is a new function added just for
implementing effects.
The default implementation of the run virtual just calls pre_paint and
post_paint so that existing effects will continue to work.
An effect is allowed to conditionally skip calling
clutter_actor_continue_paint(). This is useful to implement effects
that cache the image of an actor. The flags parameter can be used to
determine if the actor is dirty since the last paint. ClutterActor
sets this flag whenever propagated_one_redraw is TRUE which means that
a redraw for this actor or one of its children was queued.
Cogl has now been split out into a standalone project with a separate
repository at git://git.gnome.org/cogl. From now on the Clutter build
will now simply look for a cogl-1.0 pkg-config file to find a suitable
Cogl library to link against at build time.
This backend hasn't been used for years now and so because it is
untested code and almost certainly doesn't work any more it would be a
burdon to continue trying to maintain it. Considering that we are now
looking at moving OpenGL window system integration code down from
Clutter backends into Cogl that will be easier if we don't have to
consider this backend.
pre_paint() and post_paint() implementations don't need
to check whether an effect is disabled: Clutter will
not apply an effect unless it is enabled.
So remove code which checks whether the effect is
enabled or disabled from the example applications and the
documentation.
Add a recipe showing how to implement two simple
effects, based on ClutterEffect: an always gray background,
and a border with configurable width and color.
Also explains the necessity to queue a redraw on
the associated actor if the effect's properties change,
and shows how to implement that.
The example gives the GObject code for both effects,
as well as an example application showing how to use them.
The example also demonstrates how to disable/enable an effect,
making the border round an actor togglable.
Add example of a simple background color effect applied via
pre_paint() implementation in a ClutterEffect subclass.
This is a simple effect with an incomplete GObject
implementation (no properties, setters or getters)
to make it as easy to follow as possible.
The OffscreenEffect class needs to expose a way for sub-classes to
track the size of FBO it creates, in case it has to do some geometry
deformations like the DeformEffect sub-classes.
Let's move the private symbol we used internally in 1.6 to fix
DeformEffect to the list of public symbols of OffscreenEffect.
http://bugzilla.clutter-project.org/show_bug.cgi?id=2570
Creating a synthetic event requires direct access to the ClutterEvent
union members; this access does not map in bindings to high-level
languages, especially run-time bindings using GObject-Introspection.
It's also midly annoying from C, as it unnecessarily exposes the guts of
ClutterEvent - something we might want to fix in the future.
http://bugzilla.clutter-project.org/show_bug.cgi?id=2575
Make sure users get the idea that clutter_init()
has a return value that needs to be checked.
These were fixed via sed magic:
sed -i -s -e "s/clutter_init (.*)/\
if (& != CLUTTER_INIT_SUCCESS)\n return 1/"\
doc/*/*/*.{c,xml} doc/*/*.xml
http://bugzilla.clutter-project.org/show_bug.cgi?id=2574
Add an effects chapter which gives a broad overview of
the abstract classes in the effects API, plus a short
example of how to apply one of the stock Clutter
effects (ClutterColorizeEffect).
The recipe explains how to create a custom ClutterDeformEffect
to produce a page fold (code based on ClutterPageTurnEffect).
The example code includes the effect class plus a small
application to apply it to a texture.
Show how to animate an actor using a ClutterPathConstraint.
This demonstrates how to get effects similar to
ClutterPathBehaviour with the modern animation APIs.
Includes 3 examples:
1) Simple ClutterPathConstraint used with implicit animations
2) ClutterPathConstraint used to simulate circular animation,
using ClutterAnimator
3) Creating simple curved path animations with non-linear
easing
Try to make the cookbook pass the distcheck phase, so that we can run
distcheck with --enable-docs, and make sure that a tarballed clutter
release can actually build the cookbook.
Remove the dispose() implementation and replace
with destroy().
This should be promoted as the standard approach
for implementing a composite actor, as it emits a
signal when instances of the actor subclass are destroyed.
Add some extra detail to the Discussion section of the
composite actor recipe, concentrating on the pros and
cons of this approach.
Also explain more about the Clutter parts of the implementation.
Also general tidy up of language and style.
Add some extra description to the allocate() function,
explaining how the allocation has to be adjusted to
coordinates relative to the actor as a whole, before
applying to the single child actor it is composed from.
Include all the code examples inline as part of the recipe.
Remove sections around each code example, as these are
unnecessary; leave full discussion for the Discussion section
instead of trying to cram it in around the code example.
As most actor subclasses will probably want to implement
size requisition, give a simple example of how to do this
on the basis of the composed actor's size, plus some padding.
When synthesizing events coming from input devices it should be
possible to just call a setter function, to avoid a huge switch
on the type of the event.
Clutter should also store the device pointer inside the private
data, for faster access of the pointer in allocated events.
Finally, the get_device_id() and get_device_type() accessors should
just be wrappers around clutter_event_get_device(), to reduce the
amount of code duplication.
* xi2: (41 commits)
test-devices: Actually print the axis data
device-manager/xi2: Sync the stage of source devices
event: Clean up clutter_event_copy()
device: unset the axes array pointer when resetting
device-manager/xi2: Fix device hotplugging
glx: Clean up GLX implementation
device/x11: Store min/max keycode in the XI device class
x11: Hide all private symbols
docs: More documentation fixes for InputDevice
*/event: Never manipulate the event queue directly
win32: Update DeviceManager device creation
device: Allow enabling/disabling non-master devices
backend/eglx: Add newly created stages to the translators
device: Add more doc annotations
device: Use a double for translate_axis() argument
test-devices: Clean up and show axes data
event: Fix up clutter_event_copy()
device/xi2: Translate the axis data after setting devices
device: Add more accessors for properties
docs: Update API reference
...
This is part of a broader cleanup of some of the experimental Cogl API.
One of the reasons for this particular rename is to reduce the verbosity
of using the API. Another reason is that CoglVertexArray is going to be
renamed CoglAttributeBuffer and we want to help emphasize the
relationship between CoglAttributes and CoglAttributeBuffers.
Allow the developer to set whether the Stage should receive key focus
when mapped. The implementation is fully backend-dependent. The default
value is TRUE because that's what we've been expecting so far.
http://bugzilla.clutter-project.org/show_bug.cgi?id=2500
Keeping the Cogl 2.0 API reference in the build is getting far more
troublesome than it's worth.
It's breaking distcheck far too often, and it makes it impossible to
rebuild the build environment from tarballs - which is something that
some distributions (namely: the Debian-based ones, but not limited to
them) do in order to change build scripts using their own rules.
Added 3 examples for the box layout recipe:
1) Simple box layout demonstrating how to set actor properties
2) Trivial menu implementation using box layout
3) Demonstration app which enables tweaking and testing
of layout property interactions
Also inlined example 1 in the solution section and added
more explanatory text in the discussion.
Other frameworks expose the same functionality as "auto-reverse",
probably to match the cassette tape player. It actually makes sense
for Clutter to follow suit.
If an <emphasis> element is placed inside a <programlisting> in a cookbook
recipe, the result is bold italic text in the HTML output. This isn't
particularly readable.
Fix is to style emphasis elements inside programlistings
so the font weight is not bold but is still italicised.
http://bugzilla.clutter-project.org/show_bug.cgi?id=2475
If not configured with --enable-cogl2-reference then don't try and dist
the doc/references/cogl-2.0 manual. Although this means a tarball built
this way will not be able to build the experimental cogl-2.0 manual this
isn't considered a big problem since anyone interested in this would
hopefully be tracking git for now or we can simply be careful to
configure with --enable-cogl2-reference for our tarball releases.
To allow us to have gobject properties that accept a CoglMatrix value we
need to register a GType. This adds a cogl_gtype_matrix_get_type function
that will register a static boxed type called "CoglMatrix".
This adds a new section to the reference manual for GType integration
functions.
clutter_timeline_set_reverse() can be used to
automatically reverse a timeline's direction each time
it completes, so use that in looping animation recipe and
examples.
* elliot/cookbook-animations-scaling:
cookbook: Add recipe for animated scaling of an actor
cookbook: Add example of scaling a texture
cookbook: Added "animated scaling" recipe skeleton
cookbook: Added animated scaling example
Recipe explains how to animate scaling a single actor.
Also covers scaling vs. resizing, scale center, and
scaling within layouts and containers.
The first example shows how animations around each scale
gravity look, as well as tracking the transformed position
and size of the actor and displaying those.
The second example is a simple image viewer with zoom in/out
using scaling.
Added an example showing scaling of an actor on
each of the scaling gravity settings (NORTH_WEST, NORTH etc.),
with a mark indicating the center being used.
Displays the transformed size and position, updated
on each paint of the actor.
This add two new function that allows us to transform or project an
array of points instead of only transforming one point at a time. Recent
benchmarking has shown cogl_matrix_transform_point to be a bottleneck
sometimes, so this should allow us to reduce the overhead when
transforming lots of vertices at the same time, and also reduce the cost
of 3 component, non-projective transforms.
For now they are marked as experimental (you have to define
COGL_ENABLE_EXPERIMENTAL_API) because there is some concern that it
introduces some inconsistent naming. cogl_matrix_transform_point would
have to be renamed cogl_matrix_project_point to be consistent, but that
would be an API break.
Building the API reference for Cogl 2.0 is fairly confusing: the API
itself is experimental and for internal use only -- though we want
feedback for it.
Let's build the API reference only when Clutter is configured with a
specific configure switch, so that people that wish to give feedback on
the API and its documentation can do it.
* elliot/cookbook-animations-looping:
cookbook: Recipe for "looping animations"
cookbook: Clarify how signals are emitted during looped animation
cookbook: First draft for looping animations recipe
cookbook: Recipe skeleton for "looping animations"
cookbook: Looping animation examples
Added a recipe giving examples of how to loop
animations for each part of the animation API (implicit,
animator, state).
The discussion covers looping a fixed number of times
and inverting a single implicit animation to create
a loop which goes back to its start on each iteration.
So we can keep track of the experimental progress of Cogl 2.0 features
this adds a standalone Cogl 2.0 Reference Manual which doesn't cover
the deprecated 1.x symbols and removes the need for a "Cogl
experimental API" chapter since those sections now make up the main
table of contents.
Since EGA colors are apparently all the rage in other toolkits, Clutter
should not be left out. On top of the usual CGA/EGA palette the static
colors also include the Tango Icon palette, which at least is more
pleasant to the eye.
Static colors are accessed through an enumeration by using
clutter_color_get_static(), or using the short-hand pre-processor
macros.
http://bugzilla.clutter-project.org/show_bug.cgi?id=2066
This exposes the idea of a stack of source materials instead of just
having a single current material. This allows the writing of orthogonal
code that can change the current source material and restore it to its
previous state. It also allows the implementation of new composite
primitives that may want to validate the current source material and
possibly make override changes in a derived material.
* wip/path-constraint:
docs: Add PathConstraint
tests: Add a PathConstraint interactive test
Add ClutterPathConstraint
actor-box: Add setters for origin and size
This function handles a single windows message. The idea is that it
could be used by clutter-gtk to forward on events from a
GdkEventFilter. The function replaces the old message_translate()
function. That function didn't translate the event anymore anyway and
instead it could generate multiple events so
clutter_win32_handle_event seems like a more appropriate name. The
function returns TRUE or FALSE depending on whether the event was
completely handled instead of setting call_window_proc.
The interpolate() method does what it says on the tin: it interpolates
between two colors using the given factor.
ClutterColor uses it to register a progress function for Intervals.
Recipe covers adding handlers for button-press-event and
button-release-event signals on actors, and how to
examine the content of a ClutterButtonEvent via API functions.
The discussion section explains about click count
(the criteria for how clicks get counted, including
distance and time settings); how button numbers are reported;
and how to use ClutterClickAction as an alternative
for press + release in certain scenarios.
The internal copy of JSON-GLib was meant to go away right after the 1.0
release, given that JSON-GLib was still young and relatively unknown.
Nowadays, many projects started depending on this little library, and
distributions ship it and keep it up to date.
Keeping a copy of JSON-GLib means keeping it up to date; unfortunately,
this would also imply updating the code not just for the API but for the
internal implementations.
Starting with the 1.2 release, Clutter preferably dependend on the
system copy; with the 1.4 release we stopped falling back automatically.
The 1.6 cycle finally removes the internal copy and requires a copy of
JSON-GLib installed on the target system in order to compile Clutter.
This recipe explains how to use the three animation
approaches (implicit, State, Animator) to animate movement
of actors.
Includes some guidelines about which approach to use when, with
a full code example for each approach.
The discussion section covers some subtleties around animated
movement; namely: moving actors out of their containers; anchor
points and movement; moving in the depth axis; interactions
between animated movement and constraints.
Added an example showing how to move two actors between
two states (one minimised, one maximised) using ClutterState
to do the movement. Also shows how movement can be mixed
with other animation (in this case, scaling).
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.
