clutter-stage

clutter-stage — Top level visual element to which actors are placed.

Functions

Description

ClutterStage is a top level 'window' on which child actors are placed and manipulated.

Backends might provide support for multiple stages. The support for this feature can be checked at run-time using the clutter_feature_available() function and the CLUTTER_FEATURE_STAGE_MULTIPLE flag. If the backend used supports multiple stages, new ClutterStage instances can be created using clutter_stage_new(). These stages must be managed by the developer using clutter_actor_destroy(), which will take care of destroying all the actors contained inside them.

ClutterStage is a proxy actor, wrapping the backend-specific implementation of the windowing system. It is possible to subclass ClutterStage, as long as every overridden virtual function chains up to the parent class corresponding function.

Functions

CLUTTER_STAGE_WIDTH

#define CLUTTER_STAGE_WIDTH()           (clutter_actor_get_width (clutter_stage_get_default ()))

CLUTTER_STAGE_WIDTH has been deprecated since version 1.2 and should not be used in newly-written code.

Use clutter_actor_get_width() instead

Macro that evaluates to the width of the default stage

Since: 0.2


CLUTTER_STAGE_HEIGHT

#define CLUTTER_STAGE_HEIGHT()          (clutter_actor_get_height (clutter_stage_get_default ()))

CLUTTER_STAGE_HEIGHT has been deprecated since version 1.2 and should not be used in newly-written code.

use clutter_actor_get_height() instead

Macro that evaluates to the height of the default stage

Since: 0.2


clutter_stage_add()

#define             clutter_stage_add(stage,actor)

clutter_stage_get_default ()

ClutterActor *
clutter_stage_get_default (void);

clutter_stage_get_default has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_stage_new() instead.

Retrieves a ClutterStage singleton.

This function is not as useful as it sounds, and will most likely by deprecated in the future. Application code should only create a ClutterStage instance using clutter_stage_new(), and manage the lifetime of the stage manually.

The default stage singleton has a platform-specific behaviour: on platforms without the CLUTTER_FEATURE_STAGE_MULTIPLE feature flag set, the first ClutterStage instance will also be set to be the default stage instance, and this function will always return a pointer to it.

On platforms with the CLUTTER_FEATURE_STAGE_MULTIPLE feature flag set, the default stage will be created by the first call to this function, and every following call will return the same pointer to it.

Returns

the main ClutterStage. You should never destroy or unref the returned actor.

[transfer none][type Clutter.Stage]


clutter_stage_is_default ()

gboolean
clutter_stage_is_default (ClutterStage *stage);

clutter_stage_is_default has been deprecated since version 1.10 and should not be used in newly-written code.

Track the stage pointer inside your application code, or use clutter_actor_get_stage() to retrieve the stage for a given actor.

Checks if stage is the default stage, or an instance created using clutter_stage_new() but internally using the same implementation.

Parameters

stage

a ClutterStage

 

Returns

TRUE if the passed stage is the default one

Since: 0.8


clutter_stage_queue_redraw ()

void
clutter_stage_queue_redraw (ClutterStage *stage);

clutter_stage_queue_redraw has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_queue_redraw() instead.

Queues a redraw for the passed stage.

Applications should call clutter_actor_queue_redraw() and not this function.

Parameters

stage

the ClutterStage

 

Since: 0.8


clutter_stage_set_use_fog ()

void
clutter_stage_set_use_fog (ClutterStage *stage,
                           gboolean fog);

clutter_stage_set_use_fog has been deprecated since version 1.10 and should not be used in newly-written code.

Calling this function produces no visible effect

Sets whether the depth cueing effect on the stage should be enabled or not.

Depth cueing is a 3D effect that makes actors farther away from the viewing point less opaque, by fading them with the stage color.

The parameters of the GL fog used can be changed using the clutter_stage_set_fog() function.

Parameters

stage

the ClutterStage

 

fog

TRUE for enabling the depth cueing effect

 

Since: 0.6


clutter_stage_get_use_fog ()

gboolean
clutter_stage_get_use_fog (ClutterStage *stage);

clutter_stage_get_use_fog has been deprecated since version 1.10 and should not be used in newly-written code.

This function will always return FALSE

Gets whether the depth cueing effect is enabled on stage .

Parameters

stage

the ClutterStage

 

Returns

TRUE if the depth cueing effect is enabled

Since: 0.6


clutter_stage_set_fog ()

void
clutter_stage_set_fog (ClutterStage *stage,
                       ClutterFog *fog);

clutter_stage_set_fog has been deprecated since version 1.10 and should not be used in newly-written code.

Fog settings are ignored.

Sets the fog (also known as "depth cueing") settings for the stage .

A ClutterStage will only use a linear fog progression, which depends solely on the distance from the viewer. The cogl_set_fog() function in COGL exposes more of the underlying implementation, and allows changing the for progression function. It can be directly used by disabling the “use-fog” property and connecting a signal handler to the “paint” signal on the stage , like:

1
2
clutter_stage_set_use_fog (stage, FALSE);
g_signal_connect (stage, "paint", G_CALLBACK (on_stage_paint), NULL);

The paint signal handler will call cogl_set_fog() with the desired settings:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
static void
on_stage_paint (ClutterActor *actor)
{
  ClutterColor stage_color = { 0, };
  CoglColor fog_color = { 0, };

  // set the fog color to the stage background color
  clutter_stage_get_color (CLUTTER_STAGE (actor), &stage_color);
  cogl_color_init_from_4ub (&fog_color,
                            stage_color.red,
                            stage_color.green,
                            stage_color.blue,
                            stage_color.alpha);

  // enable fog //
  cogl_set_fog (&fog_color,
                COGL_FOG_MODE_EXPONENTIAL, // mode
                0.5,                       // density
                5.0, 30.0);                // z_near and z_far
}

The fogging functions only work correctly when the visible actors use unmultiplied alpha colors. By default Cogl will premultiply textures and cogl_set_source_color() will premultiply colors, so unless you explicitly load your textures requesting an unmultiplied internal format and use cogl_material_set_color() you can only use fogging with fully opaque actors. Support for premultiplied colors will improve in the future when we can depend on fragment shaders.

Parameters

stage

the ClutterStage

 

fog

a ClutterFog structure

 

Since: 0.6


clutter_stage_get_fog ()

void
clutter_stage_get_fog (ClutterStage *stage,
                       ClutterFog *fog);

clutter_stage_get_fog has been deprecated since version 1.10 and should not be used in newly-written code.

This function will always return the default values of ClutterFog

Retrieves the current depth cueing settings from the stage.

Parameters

stage

the ClutterStage

 

fog

return location for a ClutterFog structure.

[out]

Since: 0.6


clutter_stage_set_color ()

void
clutter_stage_set_color (ClutterStage *stage,
                         const ClutterColor *color);

clutter_stage_set_color has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_set_background_color() instead.

Sets the stage color.

Parameters

stage

A ClutterStage

 

color

A ClutterColor

 

clutter_stage_get_color ()

void
clutter_stage_get_color (ClutterStage *stage,
                         ClutterColor *color);

clutter_stage_get_color has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_get_background_color() instead.

Retrieves the stage color.

Parameters

stage

A ClutterStage

 

color

return location for a ClutterColor.

[out caller-allocates]

clutter_stage_ensure_current ()

void
clutter_stage_ensure_current (ClutterStage *stage);

clutter_stage_ensure_current is deprecated and should not be used in newly-written code.

muffin: This function does not do anything.

This function essentially makes sure the right GL context is current for the passed stage. It is not intended to be used by applications.

Parameters

stage

the ClutterStage

 

Since: 0.8