diff --git a/doc/cookbook/Makefile.am b/doc/cookbook/Makefile.am index 14cee2554..59a5977f0 100644 --- a/doc/cookbook/Makefile.am +++ b/doc/cookbook/Makefile.am @@ -30,6 +30,8 @@ CSS_FILES = html/*.css IMAGE_FILES = \ images/clutter-logo.png \ images/textures-reflection.png \ + images/actors-opacity.png \ + images/actors-opacity-container-affects-opacity.png \ $(NULL) VIDEO_FILES = \ videos/animations-fading-out.ogv \ diff --git a/doc/cookbook/actors.xml b/doc/cookbook/actors.xml index 02f28d9a0..4d3dcfd31 100644 --- a/doc/cookbook/actors.xml +++ b/doc/cookbook/actors.xml @@ -257,4 +257,233 @@ on_paint (ClutterActor *actor) +
+ Making an actor transparent by changing its opacity + +
+ Problem + + You want an actor to be transparent so that other + actors are visible through it. +
+ +
+ Solution + + Change the actor's opacity so that + it is partially (or even fully) transparent: + + + +/* 25% transparency */ +clutter_actor_set_opacity (actor, 191.25); + +/* 50% transparency */ +clutter_actor_set_opacity (actor, 122.5); + +/* completely transparent */ +clutter_actor_set_opacity (actor, 0); + + + + Any actor covered or overlapped by the transparent actor + should be visible through it; the Discussion section gives + some examples of how visible you can expect the covered or + overlapped actor to be. + +
+ +
+ Discussion + + Opacity is a property of every ClutterActor. + It is a float on a scale from 0 (invisible) to 255 (completely + opaque). Actors with 0 < opacity < 255 will + have a varying amount of solidity on the stage, so other actors + may be visible through them. + + For example, below are 4 yellow rectangles overlapping + a white rectangle on a blue stage: + + + + + + + + The effect of different opacities levels on + an actor's appearance + + + + + The rectangles have the following opacities: + + + + top-left: 255 (0% transparency) + + + top-right: 191.25 (25% transparency) + + + bottom-right: 122.5 (50% transparency) + + + bottom-left: 61.25 (75% transparency) + + + + Notice how both the stage and the white rectangle are + visible through the yellow rectangles. + + As opacity is a property of every actor, it can + be animated like any other GObject property, using any of + the approaches in the animation API. + + The following sections cover some other considerations + when working with actor opacity. + +
+ Container and color opacity + + If a container has its opacity set, any children of the + container have their opacity combined with their parent's opacity. + For example, if a parent has an opacity of 122.5 + (50% transparent) and the child also has an opacity of + 122.5, the child's effective + opacity is 25% (opacity = 61.25, and it is + 75% transparent). + + To demonstrate the visual effect of this, here are + three rectangles with the same color but different opacity settings, + inside parents which also have different opacity settings: + + + + + + + + How a container's opacity affects the opacity of + its children + + + + + + + The left-hand rectangle has opacity = 255 + and is in a ClutterGroup with + opacity = 255. This means it is fully opaque. + + + The middle rectangle has opacity = 255 + and is in a ClutterGroup with + opacity = 122.5. Notice that the parent opacity + makes the rectangle appear darker, as the stage colour is showing + through from behind. + + + The right-hand rectangle has opacity = 122.5 + and is in a ClutterGroup with + opacity = 122.5. Notice that the rectangle appears + to be even darker, as the stage colour is showing + through both the rectangle and its parent. + + + + Similarly, ClutterColor also contains an + alpha property which governs the transparency + of the color. Where an actor can have a color set (e.g. + ClutterRectangle) the alpha value of the color also + affects the transparency of the actor, for example: + + + + + + + +
+ +
+ Depth and depth order + + Each actor has two more aspects which affect its + apparent opacity: + + + + An actor's depth can have an + effect if the stage has fog (a depth cueing effect) turned on. + As an actor's depth increases, the actor apparently "recedes" from + view and gradually blends into the colour of the stage. This + produces an effect similar to making the actor transparent. + See the ClutterStage documentation for + more details about fog. + + Depth also needs to be considered if you want + one actor to be visible through another: the actor you want + to see through a transparent actor must be "deeper" than (or at + the same depth as) the transparent actor. + + + The depth order governs how + actors within a ClutterContainer implementation + are placed with respect to each other. + + + Depth ordering is not the same thing as depth: depth + ordering records relationships between actors at the same + depth. + + + If you have two overlapping actors actorA and + actorB in a container, and you want actorA + (opaque) to be visible through actorB (transparent), + you should ensure that actorB is "above" actorA + in the depth ordering. You could do this as follows: + + + +/* + * raise actorB so it is above actorA in the depth order; + * NB actorA and actorB both need to be in the same container + * for this to work + */ +clutter_actor_raise (actorB, actorA); + + + + clutter_actor_raise(), + clutter_actor_lower() and related + ClutterActor functions set + depth ordering on actors; see also ClutterContainer's + clutter_container_raise_child() and + clutter_container_lower_child() + functions. + + + +
+ +
+ +
+ diff --git a/doc/cookbook/images/actors-opacity-container-affects-opacity.png b/doc/cookbook/images/actors-opacity-container-affects-opacity.png new file mode 100644 index 000000000..46be2e178 Binary files /dev/null and b/doc/cookbook/images/actors-opacity-container-affects-opacity.png differ diff --git a/doc/cookbook/images/actors-opacity.png b/doc/cookbook/images/actors-opacity.png new file mode 100644 index 000000000..1080c9904 Binary files /dev/null and b/doc/cookbook/images/actors-opacity.png differ