Commit Graph

175 Commits

Author SHA1 Message Date
Emmanuele Bassi
67eeea6b62 actor: Maintain behaviour of old allocate() implementations
The usual way to implement a container actor is to override the
allocate() virtual function, chain up, and then allocate the actor's
children.

Clutter now has the ability to delegate layout management to
ClutterLayoutManager directly; in the allocation, this is done by
checking whether the actor has children, and then call
clutter_layout_manager_allocate() from within the default implementation
of the ClutterActor::allocate() vfunc. The same vfunc that everyone, has
been chaining up to.

Whoopsie.

Well, we can check if there's a layout manager, and if it's NULL, we
bail out. Except that there's a default layout manager, and it's the
fixed layout manager, so that classes like Group and Stage work by
default.

Double whoopsie.

The fix for this scenario is a bit nasty; we have to check if the actor
class has overridden the allocate() vfunc or not, before actually
looking at the layout manager. This means that classes that override the
allocate() vfunc are expected to do everything that ClutterActor's
default implementation does - which I think it's a fair requirement to
have.

For newly written code, though, it would probably be best if we just
provided a function that does the right thing by default, and that
you're supposed to be calling from within the allocate() vfunc
implementation, if you ever chose to override it. This new function,
clutter_actor_set_allocation(), should come with a warning the size of
Texas, to avoid people thinking it's a way to override the whole "call
allocate() on each child" mechanism. Plus, it should check if we're
inside an allocation sequence, and bail out if not.
2012-01-19 12:40:32 +00:00
Emmanuele Bassi
0f39f20db6 actor: Deprecate show_all()/hide_all()
The hide_all() method is pretty much pointless, as hiding an actor will
automatically prevent its children from being painted. The show_all()
method would only be marginally useful, if actors weren't set to be
visible by default when added to another actor - which was the case when
we introduced show_all() and hide_all().
2012-01-17 16:21:54 +00:00
Emmanuele Bassi
f41061b8df actor: Deprecated push/pop internal methods
The concept of "internal child" only meant anything when we had a
separate API for containers and actors. Now that we plugged that
particular hole, we can drop all the hacks we used to have in place
to work around its design limitations.
2012-01-16 23:37:14 +00:00
Emmanuele Bassi
ea6ddd1534 actor: Add boxed margin accessors
It can be convenient to be able to set, or get, all the components of an
actor's margin at the same time; since we already have a boxed type for
storing a margin, an accessors pair based on it is not a complicated
addition to the API.
2012-01-16 23:37:14 +00:00
Emmanuele Bassi
b835e1f8c4 Deprecate the old raise/lower API
We have a replacement in ClutterActor, now.

The old ClutterContainer API needs to be deprecated, and the raise() and
lower() virtual functions need a default implementation, so we can check
for implementations overriding them, by using the diagnostic mode like
we do for add(), remove(), and foreach().

The sort_depth_order() virtual function just doesn't do anything, as it
should have been made ages ago.

The Actor wrappers for the Container methods also need to be deprecated.
2012-01-16 23:37:13 +00:00
Emmanuele Bassi
9a66392d49 actor: Add new methods for changing the paint sequence
ClutterActor provides four methods for changing the paint sequence order
of its children:

  raise_top()
  raise()
  lower()
  lower_bottom()

The first and last one being just wrappers around raise() and lower(),
respectively. These methods have various issues: they omit the parent,
preferring to retrieve it from the actor passed as the first argument;
this does not match the new style of API introduced to operate on the
list of children of an actor.

Additionally, the raise() and lower() methods of ClutterActor call into
the Container interface, and are not really aptly named (raise() in
particular collides with the completely unrelated 'raise' keyword in
Python, and usually needs to be wrapped in order to be used at all).

Furthermore, we need public methods that Container can call from its
default implementation, as well as methods to port current Container
implementations.

Finally, since we have insert_child_at_index(), we should also have an
equivalent set_child_at_index() as well.
2012-01-16 23:37:13 +00:00
Emmanuele Bassi
72fa75c034 actor: Remove automagic "expand" flag
I don't feel comfortable with this feature, and its implementation
still has too many rough edges. We can safely punt it for now, and
introduce it at a later point, as it doesn't block existing features
or API.
2012-01-16 23:37:13 +00:00
Emmanuele Bassi
f61916fc5e actor: Add remove_all_children()
A simple method for removing all children of an actor in one fell swoop.
2012-01-16 23:37:11 +00:00
Emmanuele Bassi
bd58694678 actor: Add replace_child() method
A simple method that atomically replaces a child actor with another one.
2012-01-16 23:37:10 +00:00
Emmanuele Bassi
238a6eb03d actor: Deprecate the old parent modifiers
The old API should not be used in newly written code; we have better
methods for setting up and modifying the scene graph, now.
2012-01-16 23:37:10 +00:00
Emmanuele Bassi
8b430507b5 actor: Add children iteration methods
Instead of requiring every consumer of the ClutterActor API that wishes
to iterate over the children of an actor to use the get_children()
method, we should provide an iteration API directly inside ClutterActor
itself.
2012-01-16 23:37:09 +00:00
Emmanuele Bassi
7fd35edd3f actor: Make Actor instantiatable
ClutterActor now has all the API and capabilities for being a concrete
class:

  - layout management, through delegation
  - container implementation and API
  - background color

This means that a simple scene can be built straight out of actors
without using subclasses except for the Stage.

This is the first step towards the deprecation of most of the Actor
subclasses provided by Clutter.
2012-01-16 23:35:16 +00:00
Emmanuele Bassi
4acf8de8b4 actor: Provide more children methods
Add a getter for the number of children, as well as a method to retrieve
the child at a given index.
2012-01-16 23:35:16 +00:00
Emmanuele Bassi
98a8feae64 actor: Background color
Each actor should have a background color property, disabled by default.

This property allows us to cover 99% of the use cases for
ClutterRectangle, and brings us one step closer to being able to
instantiate ClutterActor directly.
2012-01-16 23:35:15 +00:00
Emmanuele Bassi
798a2e5297 actor: Minor cosmetic fixes to the header 2012-01-16 23:35:15 +00:00
Emmanuele Bassi
86ec629776 actor: Add child insertion methods
We should allow inserting children at given indices, and at given
stacking positions (relative or not to other children).
2012-01-16 23:35:14 +00:00
Emmanuele Bassi
37d46649ce actor: Adjust the preferred size too
Don't adjust just the allocation: we need to adjust the preferred size
of the actor to account for the margin.
2012-01-16 23:35:14 +00:00
Emmanuele Bassi
bf27575187 actor: Maintain invariants in add_child/remove_child
We need to queue a relayout when removing a visible child from a visible
parent.

We also need to insert the child at the right position (depending on the
depth) so that newly added actors will be painted on top.
2012-01-16 23:35:14 +00:00
Emmanuele Bassi
a2a38ee797 actor: Add margin properties
The actor class should be able to hold the margin offsets like it does
for expand and alignment flags.

Instead of filling the private data structure with data, we should be
able to use an ancillary data structure, given that all this data is
optional and might never be set in the first place.
2012-01-16 23:35:13 +00:00
Emmanuele Bassi
c8659b6ca5 actor: Add [xy]-align
Allow an actor to define how it should occupy the extra space given to
by its parent during the allocation.
2012-01-16 23:35:13 +00:00
Emmanuele Bassi
f2609dcca4 actor: Add [xy]-expand properties 2012-01-16 23:35:13 +00:00
Emmanuele Bassi
11e876c86b actor: Add :layout-manager
Now that ClutterActor implements the Container contract we can actually
defer the size negotiation to a ClutterLayoutManager directly from the
default implementation of the Actor's virtual functions.
2012-01-16 23:35:13 +00:00
Emmanuele Bassi
53aa64aeb9 actor: Provide add/remove child and get children methods
Let's try and move away from the reverse implicit scene graph build API,
which we mutuated from GTK+, towards a more traditional node/child API.

The set_parent()/unparent() API is confusing, unless you know the
history; having a add_child()/remove_child() methods pair makes it more
explicit.

We can easily implement the old set_parent()/unparent() pair in terms of
the newly add_child()/remove_child() one.
2012-01-16 23:35:13 +00:00
Emmanuele Bassi
f0a246cdc6 actor: Add queue_redraw_with_clip()
Add a public version of the clipped queue redraw, using a 2D clip. This
allows implementing actors with trackable 2D clipped regions, like the
ClutterX11TexturePixmap, outside of Clutter itself.

https://bugzilla.gnome.org/show_bug.cgi?id=660997
2011-12-12 17:29:58 +00:00
Emmanuele Bassi
ba8d682c09 actor: Deprecate [sg]et_geometry()
These methods are short-hands for accessing the position and size,
which are already shorthands for accessing the various dimensional
and positional attributes. Plus, they use ClutterGeometry, which is a
fairly bad data type for a rectangle.
2011-11-08 14:46:55 +00:00
Emmanuele Bassi
b19c919645 actor: Move deprecated symbols into separate headers
The clutter-actor.h header is already pretty big, so let's try to keep
the deprecated symbols out of it.
2011-11-02 13:00:46 +00:00
Emmanuele Bassi
af7afc29a7 Add a Clutter-specific deprecation macro for symbols
Just like GLIB_DEPRECATED and GLIB_DEPRECATED_FOR, Clutter should have
its own wrappers for G_DEPRECATED and G_DEPRECATED_FOR, to allow opting
out of deprecation warnings.

Deprecation warnings are enabled by default, now, even when building
Clutter.
2011-10-11 23:03:09 +01:00
Emmanuele Bassi
d28e04be72 Move all enumerations to a separate file
This should allow sharing types, and we can avoid glib-mkenums thrawling
the whole repository for enumerations.
2011-10-11 17:59:46 +01:00
Robert Bragg
0aacbd47b7 actor: make offscreen_redirect prop take flags + default off
Because we have had several reports about significant performance
regressions since we enabled offscreen redirection by default for
handling correct opacity we are now turning this feature off by default.

We feel that clutter should prioritize performance over correctness in
this case. Correct opacity is still possible if required but the
overhead of the numerous offscreen allocations as well as the cost of
many render target switches per-frame seems too high relative the
improvement in quality for many cases.

On reviewing the offscreen_redirect property so we have a way to
disable redirection by default we realized that it makes more sense for
it to take a set of flags instead of an enum so we can potentially
extend the number of things that might result in offscreen redirection.

We removed the ability to say REDIRECT_ALWAYS_FOR_OPACITY, since it
seems that implies you don't trust the implementation of an actor's
has_overlaps() vfunc which doesn't seem right.

The default value if actor::redirect_offscreen is now 0 which
effectively means don't ever redirect the actor offscreen.
2011-08-30 16:20:16 +01:00
Evan Nemerson
a6bd11ac62 introspection: add missing introspection data from Vala bindings
https://bugzilla.gnome.org/show_bug.cgi?id=655387
2011-07-29 13:06:51 +01:00
Emmanuele Bassi
9a3b97b55e Revert "build: Detect the appropriate default flavour"
Ouch, butterfingers and git commit -a.

This reverts commit 81e8c8dec9.
2011-07-13 14:26:05 +01:00
Emmanuele Bassi
81e8c8dec9 build: Detect the appropriate default flavour
If we're building on/for Windows, set 'win32' as the default flavour; if
we're building on OS X, set 'osx' as the default flavour. For everything
else, use 'glx'.
2011-07-13 14:20:47 +01:00
Emmanuele Bassi
2b81d90dd7 Eliminate G_CONST_RETURN
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.
2011-06-07 16:06:24 +01:00
Emmanuele Bassi
835fc2381c Deprecate ClutterShader
With the instantiatable ClutterShaderEffect, the only reason for
ClutterShader to exist is to make the ClutterActor::paint implementation
miserable.

Yes, ClutterShader doesn't use a FBO, so it's "more efficient" on
ClutterTextures. It's also generally wrong unless you know *exactly* how
the actor's pipeline is set up — something we cannot even guarantee
internally unless we start doing lame type checks.
2011-06-07 14:09:53 +01:00
Neil Roberts
701440efd8 clutter-actor: Add a 'has_overlaps' virtual
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.
2011-05-13 01:46:32 +01:00
Neil Roberts
7f78237ee5 clutter-actor: Add an 'offscreen-redirect' property
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.
2011-05-13 01:46:32 +01:00
Neil Roberts
c3aa4d24bf clutter-effect: Add a 'run' virtual
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.
2011-05-13 01:46:31 +01:00
Emmanuele Bassi
f6e6c803d9 Deprecate actor id
The actor's id, which is currently used to generate the pick color,
should not be part of the public API: it's an internal detail of the
pick implementation, and having it exposed is like punching a hole
through the abstraction.

http://bugzilla.clutter-project.org/show_bug.cgi?id=2633

https://bugzilla.gnome.org/show_bug.cgi?id=647876
2011-05-06 17:47:41 +01:00
Emmanuele Bassi
5c398c18ad More ISO C90 warning fixes in Clutter
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.
2011-02-15 12:40:11 +00:00
Emmanuele Bassi
2f8d22ef89 Unify the vfunc parameters names with their callers
Otherwise g-ir-scanner will get fairly angry.
2011-02-08 15:30:48 +00:00
Emmanuele Bassi
d229036441 Reduce the amount of g-ir-scanner warnings
As much as we can; the remaining warnings are mostly valid things that
the introspection scanner still flags as potential issues.
2010-12-09 12:36:50 +00:00
Chris Lord
f687ec6a22 docs: Update documentation to reflect automatic map/unmap/etc.
Update the ClutterActor documentation to reflect the new automatic
map/unmap/realize/unrealize implementations.
2010-11-24 16:51:59 +00:00
Emmanuele Bassi
694632ce95 build: Re-arrange headers
Try to minimize the included headers, especially in clutter-actor.h.
2010-11-18 18:23:49 +00:00
Emmanuele Bassi
45b6d7d47a docs: Fix the annotations of ActorClass 2010-10-04 11:26:46 +01:00
Robert Bragg
1ea7145efc Queue clipped redraws work in terms of paint volumes
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.
2010-09-29 15:12:57 +01:00
Robert Bragg
3540d222e1 paint volumes: another pass at the design
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.
2010-09-29 15:12:57 +01:00
Emmanuele Bassi
94ce747f83 actor: Allow querying 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.
2010-09-29 15:12:56 +01:00
Emmanuele Bassi
01362effca actor: Add a method for querying key focus
A simple convenience method on Clutter.Actor for checking whether
it has key focus assigned on the Stage to which it belongs.
2010-09-10 11:42:11 +01:00
Emmanuele Bassi
ad0c36e1a1 docs: Fixes to avoid gtk-doc warnings 2010-08-17 14:54:20 +01:00
Emmanuele Bassi
07b01888ba actor: Add allocate_align_fill()
Layout managers are using the same code to allocate a child while taking
into consideration:

  • horizontal and vertical alignment
  • horizontal and vertical fill
  • the preferred minimum and natural size, depending
    on the :request-mode property
  • the text direction for the horizontal alignment
  • an offset given by the fixed position properties

Given the amount of code involved, and the amount of details that can go
horribly wrong while copy and pasting such code in various classes - let
alone various projects - Clutter should provide an allocate() variant
that does the right thing in the right way. This way, we have a single
point of failure.
2010-08-10 22:25:11 +01:00