ClutterActor: expose setter for the opacity override

Toolkits may need to paint actors internally outside the normal tree
(for example to create a shadow shape), in which case they need to
control the opacity directly.

https://bugzilla.gnome.org/show_bug.cgi?id=677412

Signed-off-by: Emmanuele Bassi <ebassi@gnome.org>

clutter/clutter-actor-private.h

@@ -263,9 +263,6 @@ void                            _clutter_actor_rerealize
                                                                                          ClutterCallback  callback,
                                                                                          gpointer         data);
 
-void                            _clutter_actor_set_opacity_override                     (ClutterActor *self,
-                                                                                         gint          opacity);
-gint                            _clutter_actor_get_opacity_override                     (ClutterActor *self);
 void                            _clutter_actor_set_in_clone_paint                       (ClutterActor *self,
                                                                                          gboolean      is_in_clone_paint);
 

clutter/clutter-actor.c

@@ -15753,20 +15753,50 @@ clutter_actor_create_pango_layout (ClutterActor *self,
   return layout;
 }
 
-/* Allows overriding the calculated paint opacity. Used by ClutterClone and
+/**
- * ClutterOffscreenEffect.
+ * clutter_actor_set_opacity_override:
+ * @self: a #ClutterActor
+ * @opacity: the override opacity value, or -1 to reset
+ *
+ * Allows overriding the calculated paint opacity (as returned by
+ * clutter_actor_get_paint_opacity()). This is used internally by
+ * ClutterClone and ClutterOffscreenEffect, and should be used by
+ * actors that need to mimick those.
+ *
+ * In almost all cases this should not used by applications.
+ *
+ * Stability: unstable
  */
 void
-_clutter_actor_set_opacity_override (ClutterActor *self,
+clutter_actor_set_opacity_override (ClutterActor *self,
                                      gint          opacity)
 {
   g_return_if_fail (CLUTTER_IS_ACTOR (self));
 
+  /* ensure bounds */
+  if (opacity >= 0)
+    opacity = CLAMP (opacity, 0, 255);
+  else
+    opacity = -1;
+
   self->priv->opacity_override = opacity;
 }
 
+/**
+ * clutter_actor_get_opacity_override:
+ * @self: a #ClutterActor
+ *
+ * See clutter_actor_set_opacity_override()
+ *
+ * Returns: the override value for the actor's opacity, or -1 if no override
+ *   is set.
+ *
+ * Since: 1.22
+ *
+ * Stability: unstable
+ */
 gint
-_clutter_actor_get_opacity_override (ClutterActor *self)
+clutter_actor_get_opacity_override (ClutterActor *self)
 {
   g_return_val_if_fail (CLUTTER_IS_ACTOR (self), -1);
 

clutter/clutter-actor.h

@@ -829,6 +829,11 @@ void                            clutter_actor_remove_all_transitions
 #ifdef CLUTTER_ENABLE_EXPERIMENTAL_API
 CLUTTER_AVAILABLE_IN_1_16
 gboolean                        clutter_actor_has_mapped_clones                 (ClutterActor *self);
+CLUTTER_AVAILABLE_IN_1_22
+void                            clutter_actor_set_opacity_override              (ClutterActor               *self,
+                                                                                 gint                        opacity);
+CLUTTER_AVAILABLE_IN_1_22
+gint                            clutter_actor_get_opacity_override              (ClutterActor               *self);
 #endif
 
 G_END_DECLS

clutter/clutter-clone.c

@@ -41,6 +41,7 @@
 #include "config.h"
 #endif
 
+#define CLUTTER_ENABLE_EXPERIMENTAL_API
 #include "clutter-actor-private.h"
 #include "clutter-clone.h"
 #include "clutter-debug.h"
@@ -173,7 +174,7 @@ clutter_clone_paint (ClutterActor *actor)
    *   the clone source actor.
    */
   _clutter_actor_set_in_clone_paint (priv->clone_source, TRUE);
-  _clutter_actor_set_opacity_override (priv->clone_source,
+  clutter_actor_set_opacity_override (priv->clone_source,
                                        clutter_actor_get_paint_opacity (actor));
   _clutter_actor_set_enable_model_view_transform (priv->clone_source, FALSE);
 
@@ -191,7 +192,7 @@ clutter_clone_paint (ClutterActor *actor)
     _clutter_actor_set_enable_paint_unmapped (priv->clone_source, FALSE);
 
   _clutter_actor_set_enable_model_view_transform (priv->clone_source, TRUE);
-  _clutter_actor_set_opacity_override (priv->clone_source, -1);
+  clutter_actor_set_opacity_override (priv->clone_source, -1);
   _clutter_actor_set_in_clone_paint (priv->clone_source, FALSE);
 }
 

clutter/clutter-offscreen-effect.c

@@ -343,8 +343,8 @@ clutter_offscreen_effect_pre_paint (ClutterEffect *effect)
    * multiplying the opacity twice.
    */
   priv->old_opacity_override =
-    _clutter_actor_get_opacity_override (priv->actor);
+    clutter_actor_get_opacity_override (priv->actor);
-  _clutter_actor_set_opacity_override (priv->actor, 0xff);
+  clutter_actor_set_opacity_override (priv->actor, 0xff);
 
   return TRUE;
 }
@@ -413,7 +413,7 @@ clutter_offscreen_effect_post_paint (ClutterEffect *effect)
     return;
 
   /* Restore the previous opacity override */
-  _clutter_actor_set_opacity_override (priv->actor, priv->old_opacity_override);
+  clutter_actor_set_opacity_override (priv->actor, priv->old_opacity_override);
 
   cogl_pop_matrix ();
   cogl_pop_framebuffer ();

doc/reference/clutter/clutter-sections.txt

@@ -426,6 +426,8 @@ clutter_actor_set_clip_to_allocation
 clutter_actor_get_clip_to_allocation
 clutter_actor_set_opacity
 clutter_actor_get_opacity
+clutter_actor_set_opacity_override
+clutter_actor_get_opacity_override
 ClutterOffscreenRedirect
 clutter_actor_set_offscreen_redirect
 clutter_actor_get_offscreen_redirect