*
* Evaluates to %TRUE if the %CLUTTER_ACTOR_REALIZED flag is set.
*
- * Whether GL resources such as textures are allocated;
- * 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).
+ * The realized state has an actor-dependant interpretation. If an
+ * actor wants to delay allocating resources until it is attached to a
+ * stage, it may use the realize state to do so. However it is
+ * 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
- * correct GL context and window system resources to use.
+ * must be realized.
*
* Since: 0.2
*/
* clutter_actor_realize:
* @self: A #ClutterActor
*
- * Creates any underlying graphics resources needed by the actor to be
- * displayed.
- *
- * Realization means the actor is now tied to a specific rendering context
- * (that is, a specific toplevel stage).
+ * Realization informs the actor that it is attached to a stage. It
+ * can use this to allocate resources if it wanted to delay allocation
+ * until it would be rendered. However it is perfectly acceptable for
+ * an actor to create resources before being realized because Clutter
+ * 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.
*
* clutter_actor_unrealize:
* @self: A #ClutterActor
*
- * Frees up any underlying graphics resources needed by the actor to
- * be displayed.
- *
- * Unrealization means the actor is now independent of any specific
- * rendering context (is not attached to a specific toplevel stage).
+ * Unrealization informs the actor that it may be being destroyed or
+ * moved to another stage. The actor may want to destroy any
+ * underlying graphics resources at this point. However it is
+ * perfectly acceptable for it to retain the resources until the actor
+ * 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
* clutter_actor_unrealize_not_hiding:
* @self: A #ClutterActor
*
- * Frees up any underlying graphics resources needed by the actor to
- * be displayed.
- *
- * Unrealization means the actor is now independent of any specific
- * rendering context (is not attached to a specific toplevel stage).
+ * Unrealization informs the actor that it may be being destroyed or
+ * moved to another stage. The actor may want to destroy any
+ * underlying graphics resources at this point. However it is
+ * perfectly acceptable for it to retain the resources until the actor
+ * 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
return;
}
- /* If the texture is not a FBO, then realization is a no-op but
- * we still want to be in REALIZED state to maintain invariants.
- * We may have already created the texture if someone set some
- * data earlier, or we may create it later if someone sets some
- * data later. The fact that we may have created it earlier is
- * really a bug, since it means ClutterTexture can have GL
- * resources without being realized.
+ /* If the texture is not a FBO, then realization is a no-op but we
+ * still want to be in REALIZED state to maintain invariants.
+ * ClutterTexture doesn't need to be realized to have a Cogl texture
+ * because Clutter assumes that a GL context is always current so
+ * there is no need to wait to realization time to create the
+ * texture. Although this is slightly odd it would be wasteful to
+ * 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");
* @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
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
- * stage, and warn and return if not in a stage yet. However, right
- * now everything would break if we did that, so we just fudge it
- * and we're broken: we can have a texture without being realized.
- */
+ /* This function can set the texture without the actor being
+ realized. This is ok because Clutter requires that the GL context
+ always be current so there is no point in waiting to realization
+ to set the texture. */
priv = texture->priv;
projects / profile / ivi / clutter.git / commitdiff