![]() |
![]() |
![]() |
Clutter Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties | Signals |
ClutterStage; ClutterStageClass; #define CLUTTER_STAGE_WIDTH () #define CLUTTER_STAGE_HEIGHT () ClutterActor * clutter_stage_get_default (void); ClutterActor * clutter_stage_new (void); gboolean clutter_stage_is_default (ClutterStage *stage); void clutter_stage_set_color (ClutterStage *stage, const ClutterColor *color); void clutter_stage_get_color (ClutterStage *stage, ClutterColor *color); void clutter_stage_set_fullscreen (ClutterStage *stage, gboolean fullscreen); gboolean clutter_stage_get_fullscreen (ClutterStage *stage); void clutter_stage_show_cursor (ClutterStage *stage); void clutter_stage_hide_cursor (ClutterStage *stage); enum ClutterPickMode; ClutterActor * clutter_stage_get_actor_at_pos (ClutterStage *stage, ClutterPickMode pick_mode, gint x, gint y); void clutter_stage_ensure_current (ClutterStage *stage); void clutter_stage_ensure_viewport (ClutterStage *stage); void clutter_stage_ensure_redraw (ClutterStage *stage); void clutter_stage_queue_redraw (ClutterStage *stage); 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); guchar * clutter_stage_read_pixels (ClutterStage *stage, gint x, gint y, gint width, gint height); void clutter_stage_set_throttle_motion_events (ClutterStage *stage, gboolean throttle); gboolean clutter_stage_get_throttle_motion_events (ClutterStage *stage); ClutterPerspective; void clutter_stage_set_perspective (ClutterStage *stage, ClutterPerspective *perspective); void clutter_stage_get_perspective (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, ClutterFog *fog); void clutter_stage_get_fog (ClutterStage *stage, ClutterFog *fog);
GObject +----GInitiallyUnowned +----ClutterActor +----ClutterGroup +----ClutterStage
"color" ClutterColor* : Read / Write "cursor-visible" gboolean : Read / Write "fog" ClutterFog* : Read / Write "fullscreen-set" gboolean : Read "offscreen" gboolean : Read / Write "perspective" ClutterPerspective* : Read / Write "title" gchar* : Read / Write "use-fog" gboolean : Read / Write "user-resizable" gboolean : Read / Write
"activate" : Run Last "deactivate" : Run Last "fullscreen" : Run First "unfullscreen" : Run Last
ClutterStage is a top level 'window' on which child actors are placed and manipulated.
Clutter creates a default stage upon initialization, which can be retrieved
using clutter_stage_get_default()
. Clutter always provides the default
stage, unless the backend is unable to create one. The stage returned
by clutter_stage_get_default()
is guaranteed to always be the same.
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.
typedef struct _ClutterStage ClutterStage;
The ClutterStage structure contains only private data and should be accessed using the provided API
Since 0.1
typedef struct { /* signals */ void (* fullscreen) (ClutterStage *stage); void (* unfullscreen) (ClutterStage *stage); void (* activate) (ClutterStage *stage); void (* deactivate) (ClutterStage *stage); } ClutterStageClass;
The ClutterStageClass structure contains only private data
|
handler for the "fullscreen" signal |
|
handler for the "unfullscreen" signal |
|
handler for the "activate" signal |
|
handler for the "deactive" signal |
Since 0.1
#define CLUTTER_STAGE_WIDTH()
Macro that evaluates to the width of the default stage
Since 0.2
#define CLUTTER_STAGE_HEIGHT()
Macro that evaluates to the height of the default stage
Since 0.2
ClutterActor * clutter_stage_get_default (void);
Returns the main stage. The default 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.
Clutter guarantess the existence of the default stage.
Returns : |
transfer none. transfer none. |
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_create()
.
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
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.
|
a ClutterStage |
Returns : |
TRUE if the passed stage is the default one
|
Since 0.8
void clutter_stage_set_color (ClutterStage *stage, const ClutterColor *color);
Sets the stage color.
|
A ClutterStage |
|
A ClutterColor |
void clutter_stage_get_color (ClutterStage *stage, ClutterColor *color);
Retrieves the stage color.
|
A ClutterStage |
|
return location for a ClutterColor |
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
|
a ClutterStage |
|
TRUE to to set the stage fullscreen
|
Since 1.0
gboolean clutter_stage_get_fullscreen (ClutterStage *stage);
Retrieves whether the stage is full screen or not
|
a ClutterStage |
Returns : |
TRUE if the stage is full screen
|
Since 1.0
void clutter_stage_show_cursor (ClutterStage *stage);
Shows the cursor on the stage window
|
a ClutterStage |
void clutter_stage_hide_cursor (ClutterStage *stage);
Makes the cursor invisible on the stage window
|
a ClutterStage |
Since 0.4
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
Do not paint any actor | |
Paint only the reactive actors | |
Paint all actors |
Since 1.0
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.
|
a ClutterStage |
|
how the scene graph should be painted |
|
X coordinate to check |
|
Y coordinate to check |
Returns : |
transfer none. transfer none. |
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.
|
the ClutterStage |
Since 0.8
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+.
|
a ClutterStage |
Since 1.0
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+.
|
a ClutterStage |
Since 1.0
void clutter_stage_queue_redraw (ClutterStage *stage);
Queues a redraw for the passed stage.
clutter_actor_queue_redraw()
and not
this function.
clutter_actor_queue_redraw()
and should probably go away.
|
the ClutterStage |
Since 0.8
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.
|
a ClutterStage |
|
a ClutterEvent |
Returns : |
the return value from the signal emission |
Since 0.4
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.
|
the ClutterStage |
|
the actor to set key focus to, or NULL . allow-none. |
Since 0.6
ClutterActor * clutter_stage_get_key_focus (ClutterStage *stage);
Retrieves the actor that is currently under key focus.
|
the ClutterStage |
Returns : |
the actor with key focus, or the stage. transfer none. |
Since 0.6
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.
|
A ClutterStage |
|
x coordinate of the first pixel that is read from stage |
|
y coordinate of the first pixel that is read from stage |
|
Width dimention of pixels to be read, or -1 for the entire stage width |
|
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.
|
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.
|
a ClutterStage |
|
TRUE to throttle motion events
|
Since 1.0
gboolean clutter_stage_get_throttle_motion_events (ClutterStage *stage);
Retrieves the value set with clutter_stage_set_throttle_motion_events()
|
a ClutterStage |
Returns : |
TRUE if the motion events are being throttled,
and FALSE otherwise
|
Since 1.0
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()
.
gfloat |
the field of view angle, in degrees, in the y direction |
gfloat |
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 |
the distance from the viewer to the near clipping plane (always positive) |
gfloat |
the distance from the viewer to the far clipping plane (always positive) |
Since 0.4
void clutter_stage_set_perspective (ClutterStage *stage, ClutterPerspective *perspective);
Sets the stage perspective.
|
A ClutterStage |
|
A ClutterPerspective |
void clutter_stage_get_perspective (ClutterStage *stage, ClutterPerspective *perspective);
Retrieves the stage perspective.
|
A ClutterStage |
|
return location for a ClutterPerspective |
void clutter_stage_set_title (ClutterStage *stage, const gchar *title);
Sets the stage title.
|
A ClutterStage |
|
A utf8 string for the stage windows title. |
Since 0.4
const gchar * clutter_stage_get_title (ClutterStage *stage);
Gets the stage title.
|
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
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)
|
a ClutterStage |
|
whether the stage should be user resizable. |
Since 0.4
gboolean clutter_stage_get_user_resizable (ClutterStage *stage);
Retrieves the value set with clutter_stage_set_user_resizable()
.
|
a ClutterStage |
Returns : |
TRUE if the stage is resizable by the user.
|
Since 0.4
typedef struct { gfloat z_near; gfloat z_far; } ClutterFog;
Fog settings used to create the depth cueing effect.
gfloat |
starting distance from the viewer to the near clipping plane (always positive) |
gfloat |
final distance from the viewer to the far clipping plane (always positive) |
Since 0.6
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.
|
the ClutterStage |
|
TRUE for enabling the depth cueing effect
|
Since 0.6
gboolean clutter_stage_get_use_fog (ClutterStage *stage);
Gets whether the depth cueing effect is enabled on stage
.
|
the ClutterStage |
Returns : |
TRUE if the the depth cueing effect is enabled
|
Since 0.6
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:
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:
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_set_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 */ }
Note: 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.
We can look to improve this in the future when we can depend on fragment shaders.
|
the ClutterStage |
|
a ClutterFog structure |
Since 0.6
void clutter_stage_get_fog (ClutterStage *stage, ClutterFog *fog);
Retrieves the current depth cueing settings from the stage.
|
the ClutterStage |
|
return location for a ClutterFog structure |
Since 0.6
"cursor-visible"
property"cursor-visible" gboolean : Read / Write
Whether the mouse pointer should be visible
Default value: TRUE
"fog"
property"fog" ClutterFog* : Read / Write
The settings for the GL "fog", used only if "use-fog"
is set to TRUE
Since 1.0
"fullscreen-set"
property"fullscreen-set" gboolean : Read
Whether the main stage is fullscreen.
Default value: FALSE
"offscreen"
property"offscreen" gboolean : Read / Write
Whether the stage should be rendered in an offscreen buffer.
Not every backend supports redirecting the stage to an offscreen buffer. This property might not work and it might be deprecated at any later date.
Default value: FALSE
"perspective"
property"perspective" ClutterPerspective* : Read / Write
The parameters used for the perspective projection from 3D coordinates to 2D
Since 0.8.2
"title"
property"title" gchar* : Read / Write
The stage's title - usually displayed in stage windows title decorations.
Default value: NULL
Since 0.4
"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
"activate"
signalvoid 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.
|
the stage which was activated |
|
user data set when the signal handler was connected. |
Since 0.6
"deactivate"
signalvoid 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.
|
the stage which was deactivated |
|
user data set when the signal handler was connected. |
Since 0.6
"fullscreen"
signalvoid user_function (ClutterStage *stage, gpointer user_data) : Run First
The ::fullscreen signal is emitted when the stage is made fullscreen.
|
the stage which was fullscreened |
|
user data set when the signal handler was connected. |
Since 0.6
"unfullscreen"
signalvoid user_function (ClutterStage *stage, gpointer user_data) : Run Last
The ::unfullscreen signal is emitted when the stage leaves a fullscreen state.
|
the stage which has left a fullscreen state. |
|
user data set when the signal handler was connected. |
Since 0.6