From 7be6ed3334a55b7ba89d116905a603c625866c41 Mon Sep 17 00:00:00 2001
From: Elliot Smith <elliot.smith@intel.com>
Date: Thu, 15 Jul 2010 19:47:53 +0100
Subject: [PATCH] cookbook: Added a recipe about making an actor transparent

Explains how to make an actor transparent so that other actors
are visible through it.

Also explains a bit more generally about opacity and how
it's computed from the actor, container, and color; and how actor
visibility is affected by depth (fog) and depth order.
---
 doc/cookbook/Makefile.am                      |   5 +-
 doc/cookbook/actors.xml                       | 229 ++++++++++++++++++
 ...tors-opacity-container-affects-opacity.png | Bin 0 -> 5150 bytes
 doc/cookbook/images/actors-opacity.png        | Bin 0 -> 5029 bytes
 4 files changed, 233 insertions(+), 1 deletion(-)
 create mode 100644 doc/cookbook/images/actors-opacity-container-affects-opacity.png
 create mode 100644 doc/cookbook/images/actors-opacity.png

diff --git a/doc/cookbook/Makefile.am b/doc/cookbook/Makefile.am
index 30f98d635..205d64b55 100644
--- a/doc/cookbook/Makefile.am
+++ b/doc/cookbook/Makefile.am
@@ -27,7 +27,10 @@ XSL_XHTML_URI = $(XSL_BASE_URI)/xhtml/docbook.xsl
 
 HTML_FILES = html/*.html
 CSS_FILES = html/*.css
-IMAGE_FILES = images/clutter-logo.png
+IMAGE_FILES = \
+	images/clutter-logo.png \
+	images/actors-opacity.png \
+	images/actors-opacity-container-affects-opacity.png
 
 EXTRA_DIST = clutter-cookbook.xml.in $(IMAGE_FILES) $(XML_FILES)
 
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)
 
   </section>
 
+  <section id="actors-opacity">
+      <title>Making an actor transparent by changing its opacity</title>
+
+      <section>
+        <title>Problem</title>
+
+        <para>You want an actor to be transparent so that other
+        actors are visible through it.</para>
+      </section>
+
+      <section>
+        <title>Solution</title>
+
+        <para>Change the actor's <emphasis>opacity</emphasis> so that
+        it is partially (or even fully) transparent:</para>
+
+        <informalexample>
+          <programlisting>
+/* 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);
+          </programlisting>
+        </informalexample>
+
+        <para>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.</para>
+
+      </section>
+
+      <section>
+        <title>Discussion</title>
+
+        <para>Opacity is a property of every <type>ClutterActor</type>.
+        It is a float on a scale from 0 (invisible) to 255 (completely
+        opaque). Actors with <code>0 &lt; opacity &lt; 255</code> will
+        have a varying amount of solidity on the stage, so other actors
+        may be visible through them.</para>
+
+        <para>For example, below are 4 yellow rectangles overlapping
+        a white rectangle on a blue stage:</para>
+
+        <screenshot>
+          <mediaobject>
+            <imageobject>
+              <imagedata format="PNG"
+                         fileref="images/actors-opacity.png" />
+            </imageobject>
+            <alt>
+              <para>The effect of different opacities levels on
+              an actor's appearance</para>
+            </alt>
+          </mediaobject>
+        </screenshot>
+
+        <para>The rectangles have the following opacities:</para>
+
+        <itemizedlist>
+          <listitem>
+            <para>top-left: <code>255</code> (0% transparency)</para>
+          </listitem>
+          <listitem>
+            <para>top-right: <code>191.25</code> (25% transparency)</para>
+          </listitem>
+          <listitem>
+            <para>bottom-right: <code>122.5</code> (50% transparency)</para>
+          </listitem>
+          <listitem>
+            <para>bottom-left: <code>61.25</code> (75% transparency)</para>
+          </listitem>
+        </itemizedlist>
+
+        <para>Notice how both the stage and the white rectangle are
+        visible through the yellow rectangles.</para>
+
+        <para>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.</para>
+
+        <para>The following sections cover some other considerations
+        when working with actor opacity.</para>
+
+        <section>
+          <title>Container and color opacity</title>
+
+          <para>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 <code>122.5</code>
+          (50% transparent) and the child also has an opacity of
+          <code>122.5</code>, the child's <emphasis>effective</emphasis>
+          opacity is 25% (<code>opacity = 61.25</code>, and it is
+          75% transparent).</para>
+
+          <para>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:</para>
+
+          <screenshot>
+            <mediaobject>
+              <imageobject>
+                <imagedata format="PNG"
+                           fileref="images/actors-opacity-container-affects-opacity.png" />
+              </imageobject>
+              <alt>
+                <para>How a container's opacity affects the opacity of
+                its children</para>
+              </alt>
+            </mediaobject>
+          </screenshot>
+
+          <itemizedlist>
+            <listitem>
+              <para>The left-hand rectangle has <code>opacity = 255</code>
+              and is in a <type>ClutterGroup</type> with
+              <code>opacity = 255</code>. This means it is fully opaque.</para>
+            </listitem>
+            <listitem>
+              <para>The middle rectangle has <code>opacity = 255</code>
+              and is in a <type>ClutterGroup</type> with
+              <code>opacity = 122.5</code>. Notice that the parent opacity
+              makes the rectangle appear darker, as the stage colour is showing
+              through from behind.</para>
+            </listitem>
+            <listitem>
+              <para>The right-hand rectangle has <code>opacity = 122.5</code>
+              and is in a <type>ClutterGroup</type> with
+              <code>opacity = 122.5</code>. Notice that the rectangle appears
+              to be even darker, as the stage colour is showing
+              through both the rectangle and its parent.</para>
+            </listitem>
+          </itemizedlist>
+
+          <para>Similarly, <type>ClutterColor</type> also contains an
+          <varname>alpha</varname> property which governs the transparency
+          of the color. Where an actor can have a color set (e.g.
+          <type>ClutterRectangle</type>) the alpha value of the color also
+          affects the transparency of the actor, for example:</para>
+
+          <informalexample>
+            <programlisting>
+<![CDATA[
+/* color with 50% transparency */
+ClutterColor half_transparent_color = { 255, 0, 0, 122.5 };
+
+ClutterRectangle *actor = clutter_rectangle_new ();
+
+/* set actor's transparency to 50% */
+clutter_actor_set_opacity (actor, 122.5);
+
+/* rectangle will be 25% opaque/75% transparent */
+clutter_rectangle_set_color (CLUTTER_RECTANGLE (actor),
+                             &half_transparent_color);
+]]>
+            </programlisting>
+          </informalexample>
+
+        </section>
+
+        <section>
+          <title>Depth and depth order</title>
+
+          <para>Each actor has two more aspects which affect its
+          apparent opacity:</para>
+
+          <itemizedlist>
+            <listitem>
+              <para>An actor's <emphasis>depth</emphasis> 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 <type>ClutterStage</type> documentation for
+              more details about fog.</para>
+
+              <para>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.</para>
+            </listitem>
+            <listitem>
+              <para>The <emphasis>depth order</emphasis> governs how
+              actors within a <type>ClutterContainer</type> implementation
+              are placed with respect to each other.</para>
+
+              <note>
+                <para>Depth ordering is not the same thing as depth: depth
+                ordering records relationships between actors at the same
+                depth.</para>
+              </note>
+
+              <para>If you have two overlapping actors <code>actorA</code> and
+              <code>actorB</code> in a container, and you want <code>actorA</code>
+              (opaque) to be visible through <code>actorB</code> (transparent),
+              you should ensure that <code>actorB</code> is "above" <code>actorA</code>
+              in the depth ordering. You could do this as follows:</para>
+
+              <informalexample>
+                <programlisting>
+/*
+ * 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);
+                </programlisting>
+              </informalexample>
+
+              <para><function>clutter_actor_raise()</function>,
+              <function>clutter_actor_lower()</function> and related
+              <type>ClutterActor</type> functions set
+              depth ordering on actors; see also <type>ClutterContainer</type>'s
+              <function>clutter_container_raise_child()</function> and
+              <function>clutter_container_lower_child()</function>
+              functions.</para>
+            </listitem>
+          </itemizedlist>
+
+        </section>
+
+      </section>
+
+    </section>
+
 </chapter>
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 0000000000000000000000000000000000000000..46be2e17838fffadd6bdd9fa531c0b84de28cea5
GIT binary patch
literal 5150
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
HPhS5I;I8mm

literal 0
HcmV?d00001

diff --git a/doc/cookbook/images/actors-opacity.png b/doc/cookbook/images/actors-opacity.png
new file mode 100644
index 0000000000000000000000000000000000000000..1080c99047ad76c7b27aca0ca1f28d8794a3722f
GIT binary patch
literal 5029
zcmd^D*IN_Vw?!F7EQkn700Ac;3`!k(A1Ts77^D|Lst}NbY9?fq-VH>MuAqQ)iGZ{q
zAWcYugx(@Z2rZ$8014rjxli{G@ONMC!}<1i_QO8kT5Ioh&UcdTTN-g)5WK*~#>Qo0
zY+%F2c1DS{j5*J;GS=)b!K}az(KE5-<m8-PwEE843WORug#H!m6B^+G_Ga@93I=)0
zKpug;y@Mcr!J%91ojPo6ylN%}cWomJ$n)?gNNVBd9UN+!G2^wTIc*V+5|8~w?=UUV
z=5Cx#4bl@deo(vMFzdO&RhX~-@_kS0c+1mwz1T1(&6tR$2=Wm<6gg4J$+vy(xeXu3
znWPtga-KgrdBmGJ52IvAO6OxF94{&qf2R{ugNjJg!Dw6-j1(1)N{YYK#ApgT`%tU>
zpdX&X7!g5-ovas^FI#o|2(X8({B`ywFmuIu1iG?)Cu1Q1rgnuyt%65Su5Tq9!&2aL
zWxuYD%u%?1(GLj<w5liiXvlu$Y_4$;Z!k8f)**vyhg-`iYW-(rJuqZub~+_yD=-a0
zU%Qwcr|08U45x9XfwX}Qeru*YQN(XhGB7h!_kn>qo?%O8b9w5d@icFy^)h+BX>&-`
zLIx`mM(>eyYDO~{ACJro#U;h4C8;+_nM&D&CW>?O=?J{(R4;tZrXh+x3;d&|{R=51
zgXUs;=py_gKD#y|oasHd`+!ogueQ~2>UZ*{WA?gqOV`V+XzP1d5XWU$?K*Ak?E=WE
z<KCiCQ7U8=enJZFZFv`6M~<ZTQk#<pO68a}$IEL=Y9i^ZoU=ihg;df^<R>Dp*)TiU
zf78i4{x{$f)`UBLspEz8K#0gyh16$>vVX_cKPgc7wRLS}!$_ER<m=vITbF=QlchFq
z&Iw0viqvSjx-1JuMKSc=yukR-_fhD9KML239_JgrZBu=LMEd2e#BJsIs8q=y?$7zh
zZTV?C#iwtNPN*7s^)|@Gs*1FVgJbKTsp<D<U5G%3J&Zjs<7lhg4WkBZt!mjpD@###
z0GHmCiRZlJGpbd#Q1r^1bt8xYuX$&+8_Mz|9m|g{miBXtYNJDUh+@**aeDoa*9G&O
zutj7uQ`1oX<!sAcCwI$$Wt-x1)GT3iM#np|ykbDvrC6qh+#g^S79N%l#D*HZ$7N*|
z`qwn{<+?0U=}@dvvxK;~`R?_2s}QoVt5L@I@kz(Chw{I5WiOh`-H{3}(~Q@=xkobZ
zBq3ygHmle=X}PpxC+D_s48JV&5e@z4O$X)1;Ri470Lz8)xkYL%%|E&~KB*0%bZPt+
z>r3|+9gp{Lh)5D#B!YrZjwyA?19@Ee==M<S;ak>Xv0P9`dQ5;`KyWc+wbDTUi~J?L
z5?9Za9{Dfzg>4EgZ`;2QyG!`xOIj&U>Cfx7`eSX~gTR>`Z{BU}U}Dg`xj+_2ygFt#
z)W^3&!Yqcl4ZWz9QC0RBUc`fd;_HZ4Lv?PU)990P!7f_fJDW!>0`Ebt9kaCY_QSp|
zbyV3_<eu<`tQAQ8zLTv+^V|s|UBB(}WX`dczONf(*Vf18Az9bWZDml!pmM{hc;V^y
z!z7ByLP;lDL4NTRMr99vMoYeJg`55inbmzt+LnBIEo)Y@?K!iFj)uia5^}RMr)K%p
zTxJ>l_Bx!u%sJ++DR2)wF}ew!405Bv;SSBWWt4XoB?&t7Q_^L8Z#kH-lbS*%dh2BK
z-5uF{?PtgB^@=28F$Rmb+UfeiRvtG%i$!E?y*0K#rAH#3n&F@50buvOTrIeR&TDLp
zkTAo=M95my3v|Gq{h)#<1);@v#K8F#^Mc17@rq<)5F}2{-ayc~ZB_$nDBhDR0aVC2
z1)X+5(NRa6VEdZ@jc-%dND|{%`DN|q$9^{*fXIQ+q}@RQSHa_TJ_YfK4<Jwg&iuk0
zy#H#CeBKNLXycd}aVl&kayXA&nP}SfX_l>eytPi=rxAVC(aqqX4c<0EtWttGo@{=b
z<};}pq1<?+&4F#XMv+=55M?eAGc%VWFB=cLs`NJf==h=P;uuYCH|cyz(S|+;5s43g
zyM4@=g3aN`BH>jYrpoRbt^iCKR`-h~+Pi=7>5;fIFd#h{IQ5aSeg~*)#-avM1W8WB
z_y9Z;0l>1vFuV`SvcNO-Z+A@k<V4L$0>^okQi?fgh7fe#MDOO6SJn!v4dG)Nq~Ypz
zR)bIEF2@xnG;h|Jn3@)7qHGM}W#y<*n1zXHqAVT>6`i(mopf?~MHM{-&p$xHtU%f$
z;GnViYzj0Q)vI*Xg+pB@cyZ(rwEbWVMsV{3^dV+e=qf?Hhy;p@)8bHvx8pcYgdn`I
zIrV;ml~**3Zatpy&)T(feX#RgH2i@@;pocN;X#btegW63vNfy;;Zt}V9%1_+ukCbd
zFzhsxSaD8#MHZLmhK{01vdGdYp93k<H8trZi?Eb|beJ;7Q55gSqQZ5YdX9`6fP!!E
z=_&J0;lBq<_9%uNP|ua><|ZZr*e4s}{gXWa@g71B03Ol^eSLCz+?9giL3A?7k@xJv
zKa>wBVNkwwVDtG{Jux_-@kboxY{XsWNU4X6ZdhvwbNL33!lff(2AZ$sZi_0(KtCZ2
zN`fjoPEYqP00mY)hlkOJw5EX#^oNDB#D*Z-LvVRygJv7Hvu(&J0MJKa55r3kU-J2c
zMbHY!7nPJ$>W=!JR}OLrq`%!B_i0jWEH76rV!sN>F?{=`hW3M3hS;l~;!C$w4l5I%
z7IJE>+L$3>q>3E4Gqx4hC}g3ip*Im950tPx@wHqTS5!8=$t`LicB#BFg(pMDIbnin
zFv9sSN)~wJ3;&bJ8|~{1P>=lct`}mr6u_XdbZ*zHEptj18<BB(E8ntY5JJCT_N)dq
zPGARLzNm4paSCzhmjUjL{VHlN+ID(icnv-Ga6l`%wWCwl&-L|8AW2ew_l!VLj%zK$
zo@SfFPjb<$TlRBJN!<LqPC`!3w_97~D(|mF)g1c2@kIG<(ZvGWA2I`ZOzNi%zW68}
z$GmwX<`830q(YqAv)Z8O8*vIz8^XT}s;DuniyS6pvXzY1`z4(#P50^w?RURY*12aj
z&UXDtT<)qvzw*)3d*0bhKxD3d4IkTLE+<!(3^Y!pcy+zVeW+-YMW#}@EHE<o@|P*s
z_P!I{tQNmz)c`$F0-dKrbW!2pKQ4)NN$izhpJ@EGL}!aLVQkU3rZ%8PdeB*Iey<zb
zQ#Q~oRAs;dQ`Li*8CTvG86GN!s&s@H7+kNe=0mVd=KXuAd8WulHJx#gAwpny<Vw;P
zm4|A`Sy`D&>Nk7HV9W4{d^$Ibb_ZgX(r{sK)X<BL&MRO5a)@6A^kq#;TQ4}HJhB?o
zu9b#RN|YYQcF+$Jj1vF8JFpI6&N=?e#x1OTKGpOEAf9>^5yH$T$I{Ox8e6~FNWzHf
z9G(QUa|mRdM0(HXTH1%tn6;&&;j0XlvP4B~^5+kV7jLK7N#CZmD3)7%O>qgx^LcCv
z2I)inJtkB;)gFBtUV13MpLH5t1ztzK8oK2beScmJRsH>qW=@e`Aa~qwiI%U8XE%r&
zeMP+);eJ;N%&*l!{d^K3{eGJm)E*Hhm03)bx7f?AIhQ=gVU#X{QptBgHtsB3EAzkZ
zRh~3Zyr8vodq5L*Y!1>l^0%HyGb?jdsrh{<_lAgy7+wH(M!+LS*dJTCHSW?}FMVs!
z&2@5S?i=Yq!s=81y+aRS90c1{*Z8%CRPe#b0p)?8n^vq5T6B4o&g$_D8|hoU-ldiy
zCBkqX#Qy$%pJK;`N>CfiWmwmwiHDuOnLP{YvPzj$??OpGlYzz~TqqdqP-tMJ=Va?F
zf5K#5*<o^rkoy#rl(q+}HQ#tUHcu7}I%1tNq02m&%tpE^50M6Os~g-RRl&2+iiKRn
z^tXAyQIwI|Tg&pjP<<SG=WNtaL#0$vAdk8&et#^RJ<W9~T)ih>8%2FBNjQpg>}6fK
zIFRnX2grBr?Gkbs>8{=8i&4Ff{G`aGAAQiTI!T}!2GEz^E+6PX#@PSpmL-vhK?{3>
zVHbxCy!z33b90+Xho1q*5X+5Fe*E`Ir!>gc6+xx$O-IFQ9v@tu!dzwrPxn0yNbPB_
z{>~;YmQL{-#0`<xDNLdwwC#j>f56<-beFGn1(WN4^15Nl8Cjfj2iU?9$IZk!N5iea
z;LP$7;g$&{iv+R8StWRTh*9vC<A&OBz9Qrk5olwlax~sSWx4$rfe@^iiX1~;D#w#=
zKWTBX7E2je6dTts*KRCfJ%R||rm1+{cJkI54`OT#sTc9A>a)O6+$#B^*1>2(XB1`r
zmwXKItK3eM1>W4mMCDfSJiKE8kI&D{+}wLw5+43P@QZ`|v}QNB<IVM#sk8v?-YkhF
zb}@!i6*V=aFLg~U@J4E6+LP6)#>K{on+PFpS77nFuwFE-@-W=jvq;0x;LG9@^CFk4
zE#h8z5FZ>T;W`i0)AI;9xX4v9k!)Nk7WTLoIlyzzDF_f3SKHlvcT2WGmcR6#&Ta^m
zoglD(AUkx@2}hN*OKWR`z9L5}a*aT_g@ukqs_KtHU@+M5=&0&Vg_R)gOj1jLa-(D?
z1m^8;ZTB1#xe>#A=7Z!EnU^wtQ$1oqbAI&NX@-rUvxfJ8W~{7NY<*-gWJz&_MstvR
zciB~h#J_=Jtib~UX2&6tEayEpo|e(^v2$u8_jN|a0`vRsHFr4q9jP5(JN)&=$)xGb
zOq-?1Oyl3ZlTdohgsl4^rw4oI9|wc)vll6;I}N8XfZ)I)Wz_8=XjJkA2n5pS<<tXr
z>yaP5ak&^5&^&9@8Dp1@d}{#hp2#WAfY80&(eHJy>>DxWcDs$_EvENo@a!RWlgj<N
z(C?$!S-IH-fGt`M>f~AW!D=TE+$9D;bmG*1lhga>!^qr(GFr^R%7u(Cu#js%KIX9G
z_}r_EnfBsG@J|wEM(4zV?yZ#CouaGTElo$`gk<CSLEh7&)q|Z=S16kTkK}8<kh7*g
zEsQywaQjZwMu(@~L+@9^_g8j`^ez#cT43$v@*Y}8<pF)34%mW!Y`&cT-SB4yWjna7
z;0}~F@7o8xpb&Vv*Z4y_?n7h5*0Y_W?%&lQKM~?j<?H{f7!sD+=X$z|;SZ>YAi!2U
zx#A98_g;3U)A;%(=5<@VS^8Y~ZwT{KRsLVa4ip5NKh>{!a*c-`Q&W_YmQj>mmgE4P
z8QMssl}DhfI;}KCd8`)pl7-l~K>f_SMBe+!YX5)3SDgi3z&x!Je)=yxg%voVEvYY0
zh;tdNfhmsoZxHmjnpyD?tBXuMB+uBZFZ^}b{$uzjkNv+55yPz5U$KX4y6v%DiBpt(
yJ@z>lMOjYTDLnVj?|pe~(eeurwktiS?AutSy_jaRCe}wAn~9;NL9O1y=l=ngEwhjS

literal 0
HcmV?d00001