ClutterStage

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

Synopsis

                    ClutterStage;
                    ClutterStageClass;
#define             CLUTTER_STAGE_WIDTH                 ()
#define             CLUTTER_STAGE_HEIGHT                ()
ClutterActor*       clutter_stage_get_default           (void);
void                clutter_stage_set_color             (ClutterStage *stage,
                                                         const ClutterColor *color);
void                clutter_stage_get_color             (ClutterStage *stage,
                                                         ClutterColor *color);
void                clutter_stage_fullscreen            (ClutterStage *stage);
void                clutter_stage_unfullscreen          (ClutterStage *stage);
void                clutter_stage_show_cursor           (ClutterStage *stage);
void                clutter_stage_hide_cursor           (ClutterStage *stage);
ClutterActor*       clutter_stage_get_actor_at_pos      (ClutterStage *stage,
                                                         gint x,
                                                         gint y);
GdkPixbuf*          clutter_stage_snapshot              (ClutterStage *stage,
                                                         gint x,
                                                         gint y,
                                                         gint width,
                                                         gint height);
gboolean            clutter_stage_event                 (ClutterStage *stage,
                                                         ClutterEvent *event);
void                clutter_stage_set_key_focus         (ClutterStage *stage,
                                                         ClutterActor *actor);
ClutterActor*       clutter_stage_get_key_focus         (ClutterStage *stage);
gdouble             clutter_stage_get_resolution        (ClutterStage *stage);
ClutterFixed        clutter_stage_get_resolutionx       (ClutterStage *stage);

                    ClutterPerspective;
void                clutter_stage_set_perspective       (ClutterStage *stage,
                                                         gfloat fovy,
                                                         gfloat aspect,
                                                         gfloat z_near,
                                                         gfloat z_far);
void                clutter_stage_set_perspectivex      (ClutterStage *stage,
                                                         ClutterPerspective *perspective);
void                clutter_stage_get_perspective       (ClutterStage *stage,
                                                         gfloat *fovy,
                                                         gfloat *aspect,
                                                         gfloat *z_near,
                                                         gfloat *z_far);
void                clutter_stage_get_perspectivex      (ClutterStage *stage,
                                                         ClutterPerspective *perspective);

void                clutter_stage_set_title             (ClutterStage *stage,
                                                         const gchar *title);
const gchar*        clutter_stage_get_title             (ClutterStage *stage);
void                clutter_stage_set_user_resizable    (ClutterStage *stage,
                                                         gboolean resizable);
gboolean            clutter_stage_get_user_resizable    (ClutterStage *stage);

                    ClutterFog;
void                clutter_stage_set_use_fog           (ClutterStage *stage,
                                                         gboolean fog);
gboolean            clutter_stage_get_use_fog           (ClutterStage *stage);
void                clutter_stage_set_fog               (ClutterStage *stage,
                                                         gdouble density,
                                                         gdouble z_near,
                                                         gdouble z_far);
void                clutter_stage_get_fog               (ClutterStage *stage,
                                                         gdouble *density,
                                                         gdouble *z_near,
                                                         gdouble *z_far);
void                clutter_stage_set_fogx              (ClutterStage *stage,
                                                         ClutterFog *fog);
void                clutter_stage_get_fogx              (ClutterStage *stage,
                                                         ClutterFog *fog);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----ClutterActor
               +----ClutterGroup
                     +----ClutterStage

Implemented Interfaces

ClutterStage implements ClutterContainer.

Properties

  "color"                    ClutterColor*         : Read / Write
  "cursor-visible"           gboolean              : Read / Write / Construct
  "fullscreen"               gboolean              : Read / Write / Construct
  "offscreen"                gboolean              : Read / Write / Construct
  "title"                    gchar*                : Read / Write
  "use-fog"                  gboolean              : Read / Write
  "user-resizable"           gboolean              : Read / Write / Construct

Signals

  "activate"                                       : Run Last
  "deactivate"                                     : Run Last
  "fullscreen"                                     : Run Last
  "unfullscreen"                                   : Run Last

Description

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

Details

ClutterStage

typedef struct _ClutterStage ClutterStage;

ClutterStageClass

typedef struct {
  /* vfuncs, not signals */
  void          (* set_fullscreen)     (ClutterStage *stage,
                                        gboolean      fullscreen);
  void          (* set_cursor_visible) (ClutterStage *stage,
                                        gboolean      visible);
  GdkPixbuf*    (* draw_to_pixbuf)     (ClutterStage *stage,
                                        gint          x,
                                        gint          y,
                                        gint          width,
                                        gint          height);
  void          (* set_title)          (ClutterStage *stage,
                                        const gchar  *title);
  void          (* set_user_resize)    (ClutterStage *stage,
                                        gboolean      value);

  /* events */
  void     (* fullscreen)      (ClutterStage           *stage);
  void     (* unfullscreen)    (ClutterStage           *stage);
  void     (* activate)        (ClutterStage           *stage);
  void     (* deactivate)      (ClutterStage           *stage);
} ClutterStageClass;

CLUTTER_STAGE_WIDTH()

#define             CLUTTER_STAGE_WIDTH()

Macro that evaluates to the current stage width

Since 0.2

CLUTTER_STAGE_HEIGHT()

#define             CLUTTER_STAGE_HEIGHT()

Macro that evaluates to the current stage height

Since 0.2

clutter_stage_get_default ()

ClutterActor*       clutter_stage_get_default           (void);

Returns the main stage. ClutterStage is a singleton, so the stage will be created the first time this function is called (typically, inside clutter_init()); all the subsequent calls to clutter_stage_get_default() will return the same instance.

Returns :

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

clutter_stage_set_color ()

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

Set the stage color.

stage :

 A ClutterStage

color :

 A ClutterColor

clutter_stage_get_color ()

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

Retrieves the stage color.

stage :

 A ClutterStage

color :

 return location for a ClutterColor

clutter_stage_fullscreen ()

void                clutter_stage_fullscreen            (ClutterStage *stage);

Asks to place the stage window in the fullscreen state. 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.

stage :

 a ClutterStage

clutter_stage_unfullscreen ()

void                clutter_stage_unfullscreen          (ClutterStage *stage);

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

stage :

 a ClutterStage

clutter_stage_show_cursor ()

void                clutter_stage_show_cursor           (ClutterStage *stage);

Shows the cursor on the stage window

stage :

 a ClutterStage

clutter_stage_hide_cursor ()

void                clutter_stage_hide_cursor           (ClutterStage *stage);

Makes the cursor invisible on the stage window

stage :

 a ClutterStage

Since 0.4

clutter_stage_get_actor_at_pos ()

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

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

stage :

 a ClutterStage

x :

 X coordinate to check

y :

 Y coordinate to check

Returns :

 the actor at the specified coordinates, if any

clutter_stage_snapshot ()

GdkPixbuf*          clutter_stage_snapshot              (ClutterStage *stage,
                                                         gint x,
                                                         gint y,
                                                         gint width,
                                                         gint height);

Gets a pixel based representation of the current rendered stage.

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 :

 pixel representation as a GdkPixbuf

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 synthetising events.

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.

stage :

 the ClutterStage

actor :

 the actor to set key focus to, or NULL

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.

stage :

 the ClutterStage

Returns :

 the actor with key focus, or the stage

Since 0.6

clutter_stage_get_resolution ()

gdouble             clutter_stage_get_resolution        (ClutterStage *stage);

Retrieves the resolution (in DPI) of the stage from the default backend.

stage :

 the ClutterStage

Returns :

 the resolution of the stage

Since 0.6

clutter_stage_get_resolutionx ()

ClutterFixed        clutter_stage_get_resolutionx       (ClutterStage *stage);

Fixed point version of clutter_stage_get_resolution().

stage :

 the ClutterStage

Returns :

 the resolution of the stage

Since 0.6

ClutterPerspective

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

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

ClutterFixed fovy;

 the field of view angle, in degrees, in the y direction

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

ClutterFixed z_near;

 the distance from the viewer to the near clipping plane (always positive)

ClutterFixed z_far;

 the distance from the viewer to the far clipping plane (always positive)

Since 0.4

clutter_stage_set_perspective ()

void                clutter_stage_set_perspective       (ClutterStage *stage,
                                                         gfloat fovy,
                                                         gfloat aspect,
                                                         gfloat z_near,
                                                         gfloat z_far);

Set the stage perspective.

stage :

 A ClutterStage

fovy :

 the field of view angle, in degrees, in the y direction

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)

z_near :

 the distance from the viewer to the near clipping plane (always positive)

z_far :

 the distance from the viewer to the far clipping plane (always positive)

Since 0.4

clutter_stage_set_perspectivex ()

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

Set the stage perspective. This is the fixed point version of clutter_stage_set_perspective().

stage :

 A ClutterStage

perspective :

 A ClutterPerspective

clutter_stage_get_perspective ()

void                clutter_stage_get_perspective       (ClutterStage *stage,
                                                         gfloat *fovy,
                                                         gfloat *aspect,
                                                         gfloat *z_near,
                                                         gfloat *z_far);

Retrieves the stage perspective.

stage :

 A ClutterStage

fovy :

 return location for the field of view, in degrees, or NULL

aspect :

 return location for the aspect ratio, or NULL

z_near :

 return location for the distance of the viewer from the near clipping plane, or NULL

z_far :

 return location for the distance of the viewer from the far clipping plane, or NULL

Since 0.4

clutter_stage_get_perspectivex ()

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

Retrieves the stage perspective. This is the fixed point version of clutter_stage_get_perspective().

stage :

 A ClutterStage

perspective :

 return location for a ClutterPerspective

clutter_stage_set_title ()

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

Sets the stage title.

Since 0.4

stage :

 A ClutterStage

title :

 A utf8 string for the stage windows title.

clutter_stage_get_title ()

const gchar*        clutter_stage_get_title             (ClutterStage *stage);

Gets the stage title.

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)

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

stage :

 a ClutterStage

Returns :

 TRUE if the stage is resizable by the user.

Since 0.4

ClutterFog

typedef struct {
  ClutterFixed density;
  ClutterFixed z_near;
  ClutterFixed z_far;
} ClutterFog;

Fog settings used to create the depth cueing effect. ClutterFog is useful only when using the fixed point API.

ClutterFixed density;

 density of the fog

ClutterFixed z_near;

 starting distance from the viewer to the near clipping plane (always positive)

ClutterFixed z_far;

 final distance from the viewer to the far clipping plane (always positive)

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.

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

Gets whether the depth cueing effect is enabled on stage.

stage :

 the ClutterStage

Returns :

 TRUE if the the depth cueing effect is enabled

Since 0.6

clutter_stage_set_fog ()

void                clutter_stage_set_fog               (ClutterStage *stage,
                                                         gdouble density,
                                                         gdouble z_near,
                                                         gdouble z_far);

Sets the GL fog settings used to create the depth cueing effect on the stage.

If the actors are all near the view point you will need a higher density and a smaller interval between z_near and z_far. On the other hand, if actors are placed far away from the view point you will need a lower density but a bigger interval between z_near and z_far.

stage :

 the ClutterStage

density :

 density of the intensity dampening

z_near :

 starting point of the depth cueing

z_far :

 ending point of the depth cueing

Since 0.6

clutter_stage_get_fog ()

void                clutter_stage_get_fog               (ClutterStage *stage,
                                                         gdouble *density,
                                                         gdouble *z_near,
                                                         gdouble *z_far);

Retrieves the settings used by the GL fog to create the depth cueing effect on the stage.

stage :

 a ClutterStage

density :

 return location for the intensity dampening

z_near :

 return location for the starting point of the depth cueing

z_far :

 return location for the ending point of the depth cueing

Since 0.6

clutter_stage_set_fogx ()

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

Sets the depth cueing settings for the stage. This is the fixed point version of clutter_stage_set_fog().

stage :

 the ClutterStage

fog :

 a ClutterFog structure

Since 0.6

clutter_stage_get_fogx ()

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

Retrieves the current depth cueing settings from the stage. This is the fixed point version of clutter_stage_get_fog().

stage :

 the ClutterStage

fog :

 return location for a ClutterFog structure

Since 0.6

Property Details

The "color" property

  "color"                    ClutterColor*         : Read / Write

The color of the main stage.

The "cursor-visible" property

  "cursor-visible"           gboolean              : Read / Write / Construct

Whether the mouse pointer should be visible

Default value: TRUE

The "fullscreen" property

  "fullscreen"               gboolean              : Read / Write / Construct

Whether the stage should be fullscreen or not.

Default value: FALSE

The "offscreen" property

  "offscreen"                gboolean              : Read / Write / Construct

Whether the stage should be rendered in an offscreen buffer.

Default value: FALSE

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-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 / Construct

Whether the stage is resizable via user interaction.

Default value: FALSE

Since 0.4

Signal Details

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.

stage :

 the stage which was activated

user_data :

 user data set when the signal handler was connected.

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.

stage :

 the stage which was deactivated

user_data :

 user data set when the signal handler was connected.

Since 0.6

The "fullscreen" signal

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

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

stage :

 the stage which was fullscreened

user_data :

 user data set when the signal handler was connected.

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.

stage :

 the stage which has left a fullscreen state.

user_data :

 user data set when the signal handler was connected.

Since 0.6

Generated by GTK-Doc V1.10