ClutterStage: Clutter Reference Manual

## ClutterStage ClutterStage — Top level visual element to which actors are placed. |

## Functions

ClutterActor * | clutter_stage_new ()
ClutterActor * | clutter_stage_get_actor_at_pos ()
void | clutter_stage_ensure_current ()
void | clutter_stage_ensure_viewport ()
void | clutter_stage_ensure_redraw ()
gboolean | clutter_stage_event ()
void | clutter_stage_set_key_focus ()
ClutterActor * | clutter_stage_get_key_focus ()
guchar * | clutter_stage_read_pixels ()
void | clutter_stage_set_throttle_motion_events ()
gboolean | clutter_stage_get_throttle_motion_events ()
void | clutter_stage_set_use_alpha ()
gboolean | clutter_stage_get_use_alpha ()
void | clutter_stage_set_minimum_size ()
void | clutter_stage_get_minimum_size ()
void | clutter_stage_set_no_clear_hint ()
gboolean | clutter_stage_get_no_clear_hint ()
void | clutter_stage_get_redraw_clip_bounds ()
gboolean | clutter_stage_get_motion_events_enabled ()
void | clutter_stage_set_motion_events_enabled ()
void | clutter_stage_set_perspective ()
void | clutter_stage_get_perspective ()
void | clutter_stage_set_title ()
const gchar * | clutter_stage_get_title ()
void | clutter_stage_set_user_resizable ()
gboolean | clutter_stage_get_user_resizable ()
void | clutter_stage_set_fullscreen ()
gboolean | clutter_stage_get_fullscreen ()
void | clutter_stage_show_cursor ()
void | clutter_stage_hide_cursor ()
void | clutter_stage_set_accept_focus ()
gboolean | clutter_stage_get_accept_focus ()
void | clutter_stage_set_sync_delay ()
void | clutter_stage_skip_sync_delay ()
#define | CLUTTER_STAGE_WIDTH
#define | CLUTTER_STAGE_HEIGHT
ClutterActor * | clutter_stage_get_default ()
gboolean | clutter_stage_is_default ()
void | clutter_stage_set_color ()
void | clutter_stage_get_color ()
void | clutter_stage_queue_redraw ()
void | clutter_stage_set_use_fog ()
gboolean | clutter_stage_get_use_fog ()
void | clutter_stage_set_fog ()
void | clutter_stage_get_fog ()

## Properties

gboolean | accept-focus | Read / Write
ClutterColor * | color | Read / Write
gboolean | cursor-visible | Read / Write
ClutterFog * | fog | Read / Write
gboolean | fullscreen-set | Read
ClutterActor * | key-focus | Read / Write
gboolean | no-clear-hint | Read / Write
gboolean | offscreen | Read / Write
ClutterPerspective * | perspective | Read / Write
gchar * | title | Read / Write
gboolean | use-alpha | Read / Write
gboolean | use-fog | Read / Write
gboolean | user-resizable | Read / Write

## Signals

void | activate | Run Last
void | after-paint | Run Last
void | deactivate | Run Last
gboolean | delete-event | Run Last
void | fullscreen | Run First
void | unfullscreen | Run Last

## Types and Values

| ClutterStage
struct | ClutterStageClass
enum | ClutterPickMode
| ClutterPerspective
| ClutterFog

## Object Hierarchy

        GBoxed
        ├── ClutterFog
        ╰── ClutterPerspective
        GObject
        ╰── GInitiallyUnowned
            ╰── ClutterActor
                ╰── ClutterGroup
                    ╰── ClutterStage

## Implemented Interfaces

ClutterStage implements ClutterContainer, ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

## 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_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.

#### Returns

a new stage, or `NULL` if the default backend does not support multiple stages. Use `clutter_actor_destroy()` to programmatically close the returned stage.

Since: 0.8

### 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.

#### Parameters

stage | a ClutterStage |
pick_mode | how the scene graph should be painted |
x | X coordinate to check |
y | Y coordinate to check |

#### Returns

the actor at the specified coordinates, if any.

[transfer none]

### 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.

#### Parameters

stage | the ClutterStage |

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+.

#### Parameters

stage | a ClutterStage |

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+.

#### Parameters

stage | a ClutterStage |

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.

#### Parameters

stage | a ClutterStage |
event | a ClutterEvent |

#### Returns

the return value from the signal emission

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.

#### Parameters

stage | the ClutterStage |
actor | the actor to set key focus to, or `NULL`. | [allow-none]

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.

#### Parameters

stage | the ClutterStage |

#### Returns

the actor with key focus, or the stage.

[transfer none]

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.

#### Parameters

stage | A ClutterStage |
x | x coordinate of the first pixel that is read from stage |
y | y coordinate of the first pixel that is read from stage |
width | Width dimention of pixels to be read, or -1 for the entire stage width |
height | Height dimention of pixels to be read, or -1 for the entire stage height |

#### Returns

a pointer to newly allocated memory with the buffer or `NULL` if the read failed. Use `g_free()` on the returned data to release the resources it has allocated.

[transfer full][array]

### 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.

#### Parameters

stage | a ClutterStage |
throttle | `TRUE` to throttle motion events |

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

#### Parameters

stage | a ClutterStage |

#### Returns

`TRUE` if the motion events are being throttled, and `FALSE` otherwise

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”

#### Parameters

stage | a ClutterStage |
use_alpha | whether the stage should honour the opacity or the alpha channel of the stage 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()`

#### Parameters

stage | a ClutterStage |

#### Returns

`TRUE` if the stage should honour the opacity and the alpha channel of the stage color

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

#### Parameters

stage | a ClutterStage |
width | width, in pixels |
height | height, in pixels |

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

#### Parameters

stage | a ClutterStage |
width | return location for the minimum width, in pixels, or `NULL`. | [out]
height | return location for the minimum height, in pixels, or `NULL`. | [out]

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.

This setting is a hint; Clutter might discard this hint depending on its internal state.

If parts of the stage are visible and you disable clearing you might end up with visual artifacts while painting the contents of the stage.

#### Parameters

stage | a ClutterStage |
no_clear | `TRUE` if the `stage` should not clear itself on every repaint cycle |

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

#### Parameters

stage | a ClutterStage |

#### Returns

`TRUE` if the stage should not clear itself on every paint cycle, and `FALSE` otherwise

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.

#### Parameters

stage | A ClutterStage |
clip | Return location for the clip bounds. | [out caller-allocates]

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

#### Parameters

stage | a ClutterStage |

#### Returns

`TRUE` if the per-actor motion event delivery is enabled and `FALSE` otherwise

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 signals will not be emitted by the actors children of `stage` :

- “motion-event”

- “enter-event”

- “leave-event”

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.

#### Parameters

stage | a ClutterStage |
enabled | `TRUE` to enable the motion events delivery, and `FALSE` otherwise |

Since: 1.8

### 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.

#### Parameters

stage | A ClutterStage |
perspective | A ClutterPerspective |

### clutter_stage_get_perspective ()

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

Retrieves the stage perspective.

#### Parameters

stage | A ClutterStage |
perspective | return location for a ClutterPerspective. | [out caller-allocates][allow-none]

### clutter_stage_set_title ()

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

Sets the stage title.

#### Parameters

stage | A ClutterStage |
title | A utf8 string for the stage windows title. |

Since: 0.4

### clutter_stage_get_title ()

    const gchar *
    clutter_stage_get_title (ClutterStage *stage);

Gets the stage title.

#### Parameters

stage | A ClutterStage |

#### Returns

pointer to the title string for the stage. The returned string is owned by the actor and should not be modified or freed.

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)

#### Parameters

stage | a ClutterStage |
resizable | whether the stage should be user resizable. |

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

#### Parameters

stage | a ClutterStage |

#### Returns

`TRUE` if the stage is resizable by the user.

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

#### Parameters

stage | a ClutterStage |
fullscreen | `TRUE` to to set the stage fullscreen |

Since: 1.0

### clutter_stage_get_fullscreen ()

    gboolean
    clutter_stage_get_fullscreen (ClutterStage *stage);

Retrieves whether the stage is full screen or not

#### Parameters

stage | a ClutterStage |

#### Returns

`TRUE` if the stage is full screen

Since: 1.0

### clutter_stage_show_cursor ()

    void
    clutter_stage_show_cursor (ClutterStage *stage);

Shows the cursor on the stage window

#### Parameters

stage | a ClutterStage |

### clutter_stage_hide_cursor ()

    void
    clutter_stage_hide_cursor (ClutterStage *stage);

Makes the cursor invisible on the stage window

#### Parameters

stage | a ClutterStage |

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

#### Parameters

stage | a ClutterStage |
accept_focus | `TRUE` to accept focus on 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()`.

#### Parameters

stage | a ClutterStage |

#### Returns

`TRUE` if the ClutterStage should accept focus, and `FALSE` otherwise

Since: 1.6

### 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.

#### Parameters

stage | a ClutterStage |
sync_delay | number of milliseconds after frame presentation to wait before painting the next frame. If less than zero, restores the default behavior where redraw is throttled to the refresh rate but not synchronized to it. |

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.

#### Parameters

stage | a ClutterStage |

Since: 1.14

Stability Level: Unstable

### 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_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_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_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

## Types and Values

### ClutterStage

    typedef struct _ClutterStage ClutterStage;

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

Since: 0.2

### 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

#### Members

`fullscreen` () | handler for the “fullscreen” signal |
`unfullscreen` () | handler for the “unfullscreen” signal |
`activate` () | handler for the “activate” signal |
`deactivate` () | handler for the “deactivate” signal |
`delete_event` () | handler for the “delete-event” signal |

Since: 0.2

### enum ClutterPickMode

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

#### Members

CLUTTER_PICK_NONE | Do not paint any actor |
CLUTTER_PICK_REACTIVE | Paint only the reactive actors |
CLUTTER_PICK_ALL | Paint all actors |

Since: 1.0

### 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()`.

#### Members

gfloat `fovy`; | the field of view angle, in degrees, in the y direction |
gfloat `aspect`; | the aspect ratio that determines the field of view in the x direction. The aspect ratio is the ratio of x (width) to y (height) |
gfloat `z_near`; | the distance from the viewer to the near clipping plane (always positive) |
gfloat `z_far`; | the distance from the viewer to the far clipping plane (always positive) |

Since: 0.4

### ClutterFog

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

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

The fog-related API in ClutterStage has been deprecated as well.

Fog settings used to create the depth cueing effect.

#### Members

gfloat `z_near`; | starting distance from the viewer to the near clipping plane (always positive) |
gfloat `z_far`; | final distance from the viewer to the far clipping plane (always positive) |

Since: 0.6

## Property Details

### The `“accept-focus”` property

      “accept-focus”             gboolean

Whether the ClutterStage should accept key focus when shown.

Flags: Read / Write

Default value: TRUE

Since: 1.6

### The `“color”` property

      “color”                    ClutterColor *

The background color of the main stage.

`ClutterStage:color` has been deprecated since version 1.10 and should not be used in newly-written code.

Use the “background-color” property of ClutterActor instead.

Flags: Read / Write

### The `“cursor-visible”` property

      “cursor-visible”           gboolean

Whether the mouse pointer should be visible

Flags: Read / Write

Default value: TRUE

### The `“fog”` property

      “fog”                      ClutterFog *

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

`ClutterStage:fog` has been deprecated since version 1.10 and should not be used in newly-written code.

This property does not do anything.

Flags: Read / Write

Since: 1.0

### The `“fullscreen-set”` property

      “fullscreen-set”           gboolean

Whether the main stage is fullscreen.

Flags: Read

Default value: FALSE

### The `“key-focus”` property

      “key-focus”                ClutterActor *

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

If `NULL`, the ClutterStage will receive the events.

Flags: Read / Write

Since: 1.2

### The `“no-clear-hint”` property

      “no-clear-hint”            gboolean

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

See `clutter_stage_set_no_clear_hint()` for further information.

Flags: Read / Write

Default value: FALSE

Since: 1.4

### The `“offscreen”` property

      “offscreen”                gboolean

Whether the stage should be rendered in an offscreen buffer.

`ClutterStage:offscreen` has been deprecated since version 1.10 and should not be used in newly-written code.

This property does not do anything.

Flags: Read / Write

Default value: FALSE

### The `“perspective”` property

      “perspective”              ClutterPerspective *

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

Flags: Read / Write

Since: 0.8

### The `“title”` property

      “title”                    gchar *

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

Flags: Read / Write

Default value: NULL

Since: 0.4

### The `“use-alpha”` property

      “use-alpha”                gboolean

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)

Flags: Read / Write

Default value: FALSE

Since: 1.2

### The `“use-fog”` property

      “use-fog”                  gboolean

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.

`ClutterStage:use-fog` has been deprecated since version 1.10 and should not be used in newly-written code.

This property does not do anything.

Flags: Read / Write

Default value: FALSE

Since: 0.6

### The `“user-resizable”` property

      “user-resizable”           gboolean

Whether the stage is resizable via user interaction.

Flags: Read / Write

Default value: FALSE

Since: 0.4

## Signal Details

### The `“activate”` signal

    void
    user_function (ClutterStage *stage,
                   gpointer      user_data)

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

#### Parameters

stage | the stage which was activated |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.6

### The `“after-paint”` signal

    void
    user_function (ClutterStage *stage,
                   gpointer      user_data)

The ::after-paint signal is emitted after the stage is painted, but before the results are displayed on the screen.

#### Parameters

stage | the stage that received the event |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.20

### The `“deactivate”` signal

    void
    user_function (ClutterStage *stage,
                   gpointer      user_data)

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

#### Parameters

stage | the stage which was deactivated |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.6

### The `“delete-event”` signal

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

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.

This signal is emitted only on Clutter backends that embed ClutterStage in native windows. It is not emitted for backends that use a static frame buffer.

#### Parameters

stage | the stage that received the event |
event | a ClutterEvent of type `CLUTTER_DELETE` |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.2

### The `“fullscreen”` signal

    void
    user_function (ClutterStage *stage,
                   gpointer      user_data)

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

#### Parameters

stage | the stage which was fullscreened |
user_data | user data set when the signal handler was connected. |

Flags: Run First

Since: 0.6

### The `“unfullscreen”` signal

    void
    user_function (ClutterStage *stage,
                   gpointer      user_data)

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

#### Parameters

stage | the stage which has left a fullscreen state. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.6