ClutterStage

typedef struct _ClutterStage ClutterStage;

The ClutterStage structure contains only private data and should be accessed using the provided API

Since 0.1

struct ClutterStageClass

struct ClutterStageClass {
  /* signals */
  void (* fullscreen)   (ClutterStage *stage);
  void (* unfullscreen) (ClutterStage *stage);
  void (* activate)     (ClutterStage *stage);
  void (* deactivate)   (ClutterStage *stage);

  gboolean (* delete_event) (ClutterStage *stage,
                             ClutterEvent *event);
};

The ClutterStageClass structure contains only private data

Since 0.1

clutter_stage_new ()

ClutterActor *      clutter_stage_new                   (void);

Creates a new, non-default stage. A non-default stage is a new top-level actor which can be used as another container. It works exactly like the default stage, but while clutter_stage_get_default() will always return the same instance, you will have to keep a pointer to any ClutterStage returned by clutter_stage_new().

The ability to support multiple stages depends on the current backend. Use clutter_feature_available() and CLUTTER_FEATURE_STAGE_MULTIPLE to check at runtime whether a backend supports multiple stages.

Since 0.8

enum ClutterPickMode

typedef enum {
  CLUTTER_PICK_NONE = 0,
  CLUTTER_PICK_REACTIVE,
  CLUTTER_PICK_ALL
} ClutterPickMode;

Controls the paint cycle of the scene graph when in pick mode

Since 1.0

clutter_stage_get_actor_at_pos ()

ClutterActor *      clutter_stage_get_actor_at_pos      (ClutterStage *stage,
                                                         ClutterPickMode pick_mode,
                                                         gint x,
                                                         gint y);

Checks the scene at the coordinates x and y and returns a pointer to the ClutterActor at those coordinates.

By using pick_mode it is possible to control which actors will be painted and thus available.

clutter_stage_ensure_current ()

void                clutter_stage_ensure_current        (ClutterStage *stage);

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

Since 0.8

clutter_stage_ensure_viewport ()

void                clutter_stage_ensure_viewport       (ClutterStage *stage);

Ensures that the GL viewport is updated with the current stage window size.

This function will queue a redraw of stage.

This function should not be called by applications; it is used when embedding a ClutterStage into a toolkit with another windowing system, like GTK+.

Since 1.0

clutter_stage_ensure_redraw ()

void                clutter_stage_ensure_redraw         (ClutterStage *stage);

Ensures that stage is redrawn

This function should not be called by applications: it is used when embedding a ClutterStage into a toolkit with another windowing system, like GTK+.

Since 1.0

clutter_stage_event ()

gboolean            clutter_stage_event                 (ClutterStage *stage,
                                                         ClutterEvent *event);

This function is used to emit an event on the main stage.

You should rarely need to use this function, except for synthetised events.

Since 0.4

clutter_stage_set_key_focus ()

void                clutter_stage_set_key_focus         (ClutterStage *stage,
                                                         ClutterActor *actor);

Sets the key focus on actor. An actor with key focus will receive all the key events. If actor is NULL, the stage will receive focus.

Since 0.6

clutter_stage_get_key_focus ()

ClutterActor *      clutter_stage_get_key_focus         (ClutterStage *stage);

Retrieves the actor that is currently under key focus.

Since 0.6

clutter_stage_read_pixels ()

guchar *            clutter_stage_read_pixels           (ClutterStage *stage,
                                                         gint x,
                                                         gint y,
                                                         gint width,
                                                         gint height);

Makes a screenshot of the stage in RGBA 8bit data, returns a linear buffer with width * 4 as rowstride.

The alpha data contained in the returned buffer is driver-dependent, and not guaranteed to hold any sensible value.

clutter_stage_set_throttle_motion_events ()

void                clutter_stage_set_throttle_motion_events
                                                        (ClutterStage *stage,
                                                         gboolean throttle);

Sets whether motion events received between redraws should be throttled or not. If motion events are throttled, those events received by the windowing system between redraws will be compressed so that only the last event will be propagated to the stage and its actors.

This function should only be used if you want to have all the motion events delivered to your application code.

Since 1.0

clutter_stage_get_throttle_motion_events ()

gboolean            clutter_stage_get_throttle_motion_events
                                                        (ClutterStage *stage);

Retrieves the value set with clutter_stage_set_throttle_motion_events()

Since 1.0

clutter_stage_set_use_alpha ()

void                clutter_stage_set_use_alpha         (ClutterStage *stage,
                                                         gboolean use_alpha);

Sets whether the stage should honour the "opacity" and the alpha channel of the "color"

Since 1.2

clutter_stage_get_use_alpha ()

gboolean            clutter_stage_get_use_alpha         (ClutterStage *stage);

Retrieves the value set using clutter_stage_set_use_alpha()

Since 1.2

clutter_stage_set_minimum_size ()

void                clutter_stage_set_minimum_size      (ClutterStage *stage,
                                                         guint width,
                                                         guint height);

Sets the minimum size for a stage window, if the default backend uses ClutterStage inside a window

This is a convenience function, and it is equivalent to setting the "min-width" and "min-height" on stage

If the current size of stage is smaller than the minimum size, the stage will be resized to the new width and height

This function has no effect if stage is fullscreen

Since 1.2

clutter_stage_get_minimum_size ()

void                clutter_stage_get_minimum_size      (ClutterStage *stage,
                                                         guint *width,
                                                         guint *height);

Retrieves the minimum size for a stage window as set using clutter_stage_set_minimum_size().

The returned size may not correspond to the actual minimum size and it is specific to the ClutterStage implementation inside the Clutter backend

Since 1.2

clutter_stage_set_no_clear_hint ()

void                clutter_stage_set_no_clear_hint     (ClutterStage *stage,
                                                         gboolean no_clear);

Sets whether the stage should clear itself at the beginning of each paint cycle or not.

Clearing the ClutterStage can be a costly operation, especially if the stage is always covered - for instance, in a full-screen video player or in a game with a background texture.

Since 1.4

clutter_stage_get_no_clear_hint ()

gboolean            clutter_stage_get_no_clear_hint     (ClutterStage *stage);

Retrieves the hint set with clutter_stage_set_no_clear_hint()

Since 1.4

clutter_stage_get_redraw_clip_bounds ()

void                clutter_stage_get_redraw_clip_bounds
                                                        (ClutterStage *stage,
                                                         cairo_rectangle_int_t *clip);

Gets the bounds of the current redraw for stage in stage pixel coordinates. E.g., if only a single actor has queued a redraw then Clutter may redraw the stage with a clip so that it doesn't have to paint every pixel in the stage. This function would then return the bounds of that clip. An application can use this information to avoid some extra work if it knows that some regions of the stage aren't going to be painted. This should only be called while the stage is being painted. If there is no current redraw clip then this function will set clip to the full extents of the stage.

Since 1.8

clutter_stage_get_motion_events_enabled ()

gboolean            clutter_stage_get_motion_events_enabled
                                                        (ClutterStage *stage);

Retrieves the value set using clutter_stage_set_motion_events_enabled().

Since 1.8

clutter_stage_set_motion_events_enabled ()

void                clutter_stage_set_motion_events_enabled
                                                        (ClutterStage *stage,
                                                         gboolean enabled);

Sets whether per-actor motion events (and relative crossing events) should be disabled or not.

The default is TRUE.

If enable is FALSE the following events will not be delivered to the actors children of stage.

The events will still be delivered to the ClutterStage.

The main side effect of this function is that disabling the motion events will disable picking to detect the ClutterActor underneath the pointer for each motion event. This is useful, for instance, when dragging a ClutterActor across the stage: the actor underneath the pointer is not going to change, so it's meaningless to perform a pick.

Since 1.8

ClutterPerspective

typedef struct {
  gfloat fovy;
  gfloat aspect;
  gfloat z_near;
  gfloat z_far;
} ClutterPerspective;

Stage perspective definition. ClutterPerspective is only used by the fixed point version of clutter_stage_set_perspective().

Since 0.4

clutter_stage_set_perspective ()

void                clutter_stage_set_perspective       (ClutterStage *stage,
                                                         ClutterPerspective *perspective);

Sets the stage perspective. Using this function is not recommended because it will disable Clutter's attempts to generate an appropriate perspective based on the size of the stage.

clutter_stage_get_perspective ()

void                clutter_stage_get_perspective       (ClutterStage *stage,
                                                         ClutterPerspective *perspective);

Retrieves the stage perspective.

clutter_stage_set_title ()

void                clutter_stage_set_title             (ClutterStage *stage,
                                                         const gchar *title);

Sets the stage title.

Since 0.4

clutter_stage_get_title ()

const gchar *       clutter_stage_get_title             (ClutterStage *stage);

Gets the stage title.

Since 0.4

clutter_stage_set_user_resizable ()

void                clutter_stage_set_user_resizable    (ClutterStage *stage,
                                                         gboolean resizable);

Sets if the stage is resizable by user interaction (e.g. via window manager controls)

Since 0.4

clutter_stage_get_user_resizable ()

gboolean            clutter_stage_get_user_resizable    (ClutterStage *stage);

Retrieves the value set with clutter_stage_set_user_resizable().

Since 0.4

clutter_stage_set_fullscreen ()

void                clutter_stage_set_fullscreen        (ClutterStage *stage,
                                                         gboolean fullscreen);

Asks to place the stage window in the fullscreen or unfullscreen states.

( Note that you shouldn't assume the window is definitely full screen afterward, because other entities (e.g. the user or window manager) could unfullscreen it again, and not all window managers honor requests to fullscreen windows.

If you want to receive notification of the fullscreen state you should either use the "fullscreen" and "unfullscreen" signals, or use the notify signal for the "fullscreen-set" property

Since 1.0

clutter_stage_get_fullscreen ()

gboolean            clutter_stage_get_fullscreen        (ClutterStage *stage);

Retrieves whether the stage is full screen or not

Since 1.0

clutter_stage_show_cursor ()

void                clutter_stage_show_cursor           (ClutterStage *stage);

Shows the cursor on the stage window

clutter_stage_hide_cursor ()

void                clutter_stage_hide_cursor           (ClutterStage *stage);

Makes the cursor invisible on the stage window

Since 0.4

clutter_stage_set_accept_focus ()

void                clutter_stage_set_accept_focus      (ClutterStage *stage,
                                                         gboolean accept_focus);

Sets whether the stage should accept the key focus when shown.

This function should be called before showing stage using clutter_actor_show().

Since 1.6

clutter_stage_get_accept_focus ()

gboolean            clutter_stage_get_accept_focus      (ClutterStage *stage);

Retrieves the value set with clutter_stage_set_accept_focus().

Since 1.6

ClutterStagePaintFunc ()

void                (*ClutterStagePaintFunc)            (ClutterStage *stage,
                                                         gpointer data);

clutter_stage_set_paint_callback ()

void                clutter_stage_set_paint_callback    (ClutterStage *stage,
                                                         ClutterStagePaintFunc callback,
                                                         gpointer data,
                                                         GDestroyNotify notify);

Sets a callback function to be invoked after the stage has been painted.

Since 1.14

clutter_stage_set_sync_delay ()

void                clutter_stage_set_sync_delay        (ClutterStage *stage,
                                                         gint sync_delay);

This function enables an alternate behavior where Clutter draws at a fixed point in time after the frame presentation time (also known as the VBlank time). This is most useful when the application wants to show incoming data with predictable latency. (The primary example of this would be a window system compositor.) By synchronizing to provide new data before Clutter redraws, an external source of updates (in the compositor, an application) can get a reliable latency.

The appropriate value of sync_delay depends on the complexity of drawing the stage's scene graph - in general a value of between 0 and 8 ms (up to one-half of a typical 60hz frame rate) is appropriate. using a larger value will reduce latency but risks skipping a frame if drawing the stage takes too long.

Since 1.14

Stability Level: Unstable

clutter_stage_skip_sync_delay ()

void                clutter_stage_skip_sync_delay       (ClutterStage *stage);

Causes the next frame for the stage to be drawn as quickly as possible, ignoring any delay that clutter_stage_set_sync_delay() would normally cause.

Since 1.14

Stability Level: Unstable

CLUTTER_STAGE_WIDTH

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

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 ()))

Macro that evaluates to the height of the default stage

Since 0.2

clutter_stage_get_default ()

ClutterActor *      clutter_stage_get_default           (void);

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.

clutter_stage_is_default ()

gboolean            clutter_stage_is_default            (ClutterStage *stage);

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

Since 0.8

clutter_stage_set_color ()

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

Sets the stage color.

clutter_stage_get_color ()

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

Retrieves the stage color.

clutter_stage_queue_redraw ()

void                clutter_stage_queue_redraw          (ClutterStage *stage);

Queues a redraw for the passed stage.

Since 0.8

ClutterFog

typedef struct {
  gfloat z_near;
  gfloat z_far;
} ClutterFog;

Fog settings used to create the depth cueing effect.

Since 0.6

clutter_stage_set_use_fog ()

void                clutter_stage_set_use_fog           (ClutterStage *stage,
                                                         gboolean fog);

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.

Since 0.6

clutter_stage_get_use_fog ()

gboolean            clutter_stage_get_use_fog           (ClutterStage *stage);

Gets whether the depth cueing effect is enabled on stage.

Since 0.6

clutter_stage_set_fog ()

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

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 */
}

Since 0.6

clutter_stage_get_fog ()

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

Retrieves the current depth cueing settings from the stage.

Since 0.6

The "accept-focus" property

  "accept-focus"             gboolean              : Read / Write

Whether the ClutterStage should accept key focus when shown.

Default value: TRUE

Since 1.6

The "color" property

  "color"                    ClutterColor*         : Read / Write

The background color of the main stage.

The "cursor-visible" property

  "cursor-visible"           gboolean              : Read / Write

Whether the mouse pointer should be visible

Default value: TRUE

The "fog" property

  "fog"                      ClutterFog*           : Read / Write

The settings for the GL "fog", used only if "use-fog" is set to TRUE

Since 1.0

The "fullscreen-set" property

  "fullscreen-set"           gboolean              : Read

Whether the main stage is fullscreen.

Default value: FALSE

The "key-focus" property

  "key-focus"                ClutterActor*         : Read / Write

The ClutterActor that will receive key events from the underlying windowing system.

If NULL, the ClutterStage will receive the events.

Since 1.2

The "no-clear-hint" property

  "no-clear-hint"            gboolean              : Read / Write

Whether or not the ClutterStage should clear its contents before each paint cycle.

See clutter_stage_set_no_clear_hint() for further information.

Default value: FALSE

Since 1.4

The "offscreen" property

  "offscreen"                gboolean              : Read / Write

Whether the stage should be rendered in an offscreen buffer.

Default value: FALSE

The "perspective" property

  "perspective"              ClutterPerspective*   : Read / Write

The parameters used for the perspective projection from 3D coordinates to 2D

Since 0.8.2

The "title" property

  "title"                    gchar*                : Read / Write

The stage's title - usually displayed in stage windows title decorations.

Default value: NULL

Since 0.4

The "use-alpha" property

  "use-alpha"                gboolean              : Read / Write

Whether the ClutterStage should honour the alpha component of the "color" property when painting. If Clutter is run under a compositing manager this will result in the stage being blended with the underlying window(s)

Default value: FALSE

Since 1.2

The "use-fog" property

  "use-fog"                  gboolean              : Read / Write

Whether the stage should use a linear GL "fog" in creating the depth-cueing effect, to enhance the perception of depth by fading actors farther from the viewpoint.

Default value: FALSE

Since 0.6

The "user-resizable" property

  "user-resizable"           gboolean              : Read / Write

Whether the stage is resizable via user interaction.

Default value: FALSE

Since 0.4

The "activate" signal

void                user_function                      (ClutterStage *stage,
                                                        gpointer      user_data)      : Run Last

The ::activate signal is emitted when the stage receives key focus from the underlying window system.

Since 0.6

The "deactivate" signal

void                user_function                      (ClutterStage *stage,
                                                        gpointer      user_data)      : Run Last

The ::activate signal is emitted when the stage loses key focus from the underlying window system.

Since 0.6

The "delete-event" signal

gboolean            user_function                      (ClutterStage *stage,
                                                        ClutterEvent *event,
                                                        gpointer      user_data)      : Run Last

The ::delete-event signal is emitted when the user closes a ClutterStage window using the window controls.

Clutter by default will call clutter_main_quit() if stage is the default stage, and clutter_actor_destroy() for any other stage.

It is possible to override the default behaviour by connecting a new handler and returning TRUE there.

Since 1.2

The "fullscreen" signal

void                user_function                      (ClutterStage *stage,
                                                        gpointer      user_data)      : Run First

The ::fullscreen signal is emitted when the stage is made fullscreen.

Since 0.6

The "unfullscreen" signal

void                user_function                      (ClutterStage *stage,
                                                        gpointer      user_data)      : Run Last

The ::unfullscreen signal is emitted when the stage leaves a fullscreen state.

Since 0.6