clutter-texture: Remove confusing comments about realization

In 125bded81 some comments were introduced to ClutterTexture
complaining that it can have a Cogl texture before being
realized. Clutter always assumes that the single GL context is current
so there is no need to wait until the actor is realized before setting
a texture. This patch replaces the comments with clarification that
this should not be a problem.

The patch also changes the documentation about the realized state in
various places to clarify that it is acceptable to create any Cogl
resources before the actor is realized.

http://bugzilla.openedhand.com/show_bug.cgi?id=2075

clutter/clutter-actor.c

@@ -180,14 +180,18 @@
  *
  * Evaluates to %TRUE if the %CLUTTER_ACTOR_REALIZED flag is set.
  *
- * Whether GL resources such as textures are allocated;
+ * The realized state has an actor-dependant interpretation. If an
- * if an actor is mapped it must also be realized, but an actor
+ * actor wants to delay allocating resources until it is attached to a
- * can be realized and unmapped (this is so hiding an actor temporarily
+ * stage, it may use the realize state to do so. However it is
- * doesn't do an expensive unrealize/realize).
+ * perfectly acceptable for an actor to allocate Cogl resources before
+ * being realized because there is only one GL context used by Clutter
+ * so any resources will work on any stage.  If an actor is mapped it
+ * must also be realized, but an actor can be realized and unmapped
+ * (this is so hiding an actor temporarily doesn't do an expensive
+ * unrealize/realize).
  *
  * To be realized an actor must be inside a stage, and all its parents
- * must be realized. The stage is required so the actor knows the
+ * must be realized.
- * correct GL context and window system resources to use.
  *
  * Since: 0.2
  */
@@ -1232,11 +1236,12 @@ clutter_actor_hide_all (ClutterActor *self)
  * clutter_actor_realize:
  * @self: A #ClutterActor
  *
- * Creates any underlying graphics resources needed by the actor to be
+ * Realization informs the actor that it is attached to a stage. It
- * displayed.
+ * can use this to allocate resources if it wanted to delay allocation
- *
+ * until it would be rendered. However it is perfectly acceptable for
- * Realization means the actor is now tied to a specific rendering context
+ * an actor to create resources before being realized because Clutter
- * (that is, a specific toplevel stage).
+ * only ever has a single rendering context so that actor is free to
+ * be moved from one stage to another.
  *
  * This function does nothing if the actor is already realized.
  *
@@ -1321,11 +1326,12 @@ clutter_actor_real_unrealize (ClutterActor *self)
  * clutter_actor_unrealize:
  * @self: A #ClutterActor
  *
- * Frees up any underlying graphics resources needed by the actor to
+ * Unrealization informs the actor that it may be being destroyed or
- * be displayed.
+ * moved to another stage. The actor may want to destroy any
- *
+ * underlying graphics resources at this point. However it is
- * Unrealization means the actor is now independent of any specific
+ * perfectly acceptable for it to retain the resources until the actor
- * rendering context (is not attached to a specific toplevel stage).
+ * is destroyed because Clutter only ever uses a single rendering
+ * context and all of the graphics resources are valid on any stage.
  *
  * Because mapped actors must be realized, actors may not be
  * unrealized if they are mapped. This function hides the actor to be
@@ -1368,11 +1374,12 @@ clutter_actor_unrealize (ClutterActor *self)
  * clutter_actor_unrealize_not_hiding:
  * @self: A #ClutterActor
  *
- * Frees up any underlying graphics resources needed by the actor to
+ * Unrealization informs the actor that it may be being destroyed or
- * be displayed.
+ * moved to another stage. The actor may want to destroy any
- *
+ * underlying graphics resources at this point. However it is
- * Unrealization means the actor is now independent of any specific
+ * perfectly acceptable for it to retain the resources until the actor
- * rendering context (is not attached to a specific toplevel stage).
+ * is destroyed because Clutter only ever uses a single rendering
+ * context and all of the graphics resources are valid on any stage.
  *
  * Because mapped actors must be realized, actors may not be
  * unrealized if they are mapped. You must hide the actor or one of

clutter/clutter-texture.c

@@ -282,13 +282,14 @@ clutter_texture_realize (ClutterActor *actor)
       return;
     }
 
-  /* If the texture is not a FBO, then realization is a no-op but
+  /* If the texture is not a FBO, then realization is a no-op but we
-   * we still want to be in REALIZED state to maintain invariants.
+   * still want to be in REALIZED state to maintain invariants.
-   * We may have already created the texture if someone set some
+   * ClutterTexture doesn't need to be realized to have a Cogl texture
-   * data earlier, or we may create it later if someone sets some
+   * because Clutter assumes that a GL context is always current so
-   * data later. The fact that we may have created it earlier is
+   * there is no need to wait to realization time to create the
-   * really a bug, since it means ClutterTexture can have GL
+   * texture. Although this is slightly odd it would be wasteful to
-   * resources without being realized.
+   * redundantly store a copy of the texture data in local memory just
+   * so that we can make a texture during realize.
    */
 
   CLUTTER_NOTE (TEXTURE, "Texture realized");
@@ -1210,12 +1211,6 @@ clutter_texture_get_cogl_texture (ClutterTexture *texture)
  * @cogl_tex. A reference to the texture is taken so if the handle is
  * no longer needed it should be deref'd with cogl_handle_unref.
  *
- * This should not be called on an unrealizable texture (one that
- * isn't inside a stage). (Currently the ClutterTexture
- * implementation relies on being able to have a GL texture while
- * unrealized, which means you can get away with it, but it's
- * not correct and may change in the future.)
- *
  * Since: 0.8
  */
 void
@@ -1229,11 +1224,10 @@ clutter_texture_set_cogl_texture (ClutterTexture  *texture,
   g_return_if_fail (CLUTTER_IS_TEXTURE (texture));
   g_return_if_fail (cogl_is_texture (cogl_tex));
 
-  /* FIXME this implementation should realize the actor if it's in a
+  /* This function can set the texture without the actor being
-   * stage, and warn and return if not in a stage yet. However, right
+     realized. This is ok because Clutter requires that the GL context
-   * now everything would break if we did that, so we just fudge it
+     always be current so there is no point in waiting to realization
-   * and we're broken: we can have a texture without being realized.
+     to set the texture. */
-   */
 
   priv = texture->priv;
 

doc/clutter-actor-invariants.txt

@@ -29,7 +29,10 @@ ClutterActor.
 
 CLUTTER_ACTOR_REALIZED
         Means: the actor has GPU resources associated to its paint
-        cycle.
+        cycle. Note however that an actor is allowed to allocate Cogl
+        resources before being realized because Clutter only ever uses
+        one rendering context which is always current. An actor is
+        free to create resources at any time.
 
         Set by clutter_actor_realize(), unset by
         clutter_actor_unrealize(). Generally set implicitly when the