1 <part id="running-clutter">
4 <firstname>Emmanuele</firstname>
5 <surname>Bassi</surname>
8 <email>ebassi@linux.intel.com</email>
14 <title>Running Clutter</title>
18 <section id="environment-variables">
19 <title>Environment Variables</title>
22 Clutter automatically checks environment variables during
23 its initialization. These environment variables are meant
24 as debug tools, overrides for default behaviours or to
25 address known hardware issues:
30 <term>CLUTTER_TEXT_DIRECTION</term>
32 <para>Forces the text direction of every Pango layout
33 inside Clutter. Valid values are: ltr or rtl</para>
37 <term>CLUTTER_SHOW_FPS</term>
39 <para>Prints out the frames per second achieved by Clutter.</para>
43 <term>CLUTTER_DEFAULT_FPS</term>
45 <para>Sets the default framerate.</para>
49 <term>CLUTTER_DISABLE_MIPMAPPED_TEXT</term>
51 <para>Disables mipmapping when rendering text.</para>
55 <term>CLUTTER_FUZZY_PICK</term>
57 <para>Enables "fuzzy picking".</para>
61 <term>CLUTTER_DEBUG</term>
63 <para>Enables debugging modes for Clutter; debugging modes are
64 used to print debugging messages on the console. Clutter must be
65 compiled with the --enable-debug configuration switch for these
66 messages to be printed out. Multiple debugging modes can be
67 enabled by separating them using a colon (":") or a comma
72 <term>CLUTTER_PAINT</term>
74 <para>Enables paint debugging modes for Clutter; the modes change
75 the way Clutter paints a scene and are useful for debugging the
76 behaviour of the paint cycle.</para>
80 <term>CLUTTER_ENABLE_DIAGNOSTIC</term>
82 <para>When set to 1, enables diagnostic messages for run-time
83 deprecations, similarly to <envvar>G_ENABLE_DIAGNOSTIC</envvar> in
89 <para>On the GLX backend there is also:</para>
93 <term>CLUTTER_VBLANK</term>
95 <para>Selects the sync-to-vblank mode to be used.
96 Valid values are: none, dri or glx</para>
103 <section id="command-line">
104 <title>Command Line Arguments</title>
106 <para>Similarly to the environment variables, Clutter also installs
107 command line switches that are parsed during initialization:</para>
111 <term>--clutter-show-fps</term>
112 <listitem><para>Equivalent of CLUTTER_SHOW_FPS. Prints the
113 current rendering speed in frames per second.</para></listitem>
116 <term>--clutter-default-fps=FPS</term>
117 <listitem><para>Equivalent of CLUTTER_DEFAULT_FPS. Sets the
118 default framerate.</para></listitem>
121 <term>--clutter-text-direction=DIRECTION</term>
122 <listitem><para>Equivalent of CLUTTER_TEXT_DIRECTION. Sets the
123 direction for the text.</para></listitem>
126 <term>--clutter-disable-mipmapped-text</term>
127 <listitem><para>Equivalent of CLUTTER_DISABLE_MIPMAPPED_TEXT.
128 Disables mipmapping when rendering text.</para></listitem>
131 <term>--clutter-use-fuzzy-picking</term>
132 <listitem><para>Equivalent of CLUTTER_FUZZY_PICK. Enables
133 "fuzzy" picking.</para></listitem>
136 <term>--clutter-debug=FLAGS</term>
137 <listitem><para>Equivalent of CLUTTER_DEBUG. Sets FLAGS as the
138 Clutter debugging flags.</para></listitem>
141 <term>--clutter-no-debug=FLAGS</term>
142 <listitem><para>Unsets FLAGS from the Clutter debugging
143 flags.</para></listitem>
146 <term>--cogl-debug=FLAGS</term>
147 <listitem><para>Equivalent of COGL_DEBUG. Sets FLAGS as the
148 Cogl debugging flags.</para></listitem>
151 <term>--cogl-no-debug=FLAGS</term>
152 <listitem><para>Unsets FLAGS from the Cogl debugging
153 flags.</para></listitem>
156 <term>--clutter-enable-accessibility</term>
157 <listitem><para>Enables accessibility support.</para></listitem>
161 <para>The X11 backends also have the following command line
166 <term>--display=DISPLAY</term>
167 <listitem><para>Sets the X11 display to use.</para></listitem>
170 <term>--screen=SCREEN</term>
171 <listitem><para>Sets the X11 screen number to use.</para></listitem>
175 <listitem><para>Make X11 calls synchronous.</para></listitem>
180 <para>The GLX backend also has the following command line option:</para>
184 <term>--vblank=METHOD</term>
185 <listitem><para>Equivalent of CLUTTER_VBLANK. Sets the sync-to-vblank
186 method to be used.</para></listitem>
190 <section id="clutter-Debug-Flags">
191 <title>Debug flags for Clutter</title>
193 <para>The debugging flags can be used for the CLUTTER_DEBUG environment
194 variable and the --clutter-debug command line switch. Multiple flags can
195 be separated by a colon (:) or a comma (,).</para>
198 keep in sync with the list of Clutter debug keys inside clutter-main.c
203 <listitem><para>Generic actor-related notes</para></listitem>
206 <term>animation</term>
207 <listitem><para>#ClutterAnimation notes</para></listitem>
211 <listitem><para>Backend-related notes, including initialization of
212 the backend features and GL context creation</para></listitem>
216 <listitem><para>Event handling notes</para></listitem>
220 <listitem><para>#ClutterLayoutManager notes</para></listitem>
224 <listitem><para>Miscellaneous notes</para></listitem>
227 <term>scheduler</term>
228 <listitem><para>Notes related to timelines and the master
229 clock</para></listitem>
233 <listitem><para>Notes related to #ClutterScript</para></listitem>
237 <para>It is possible to get all the debugging notes using the
238 special "all" flag.</para>
242 <section id="configuration-file">
243 <title>Configuration File</title>
245 <para>Clutter will look for files named <filename>settings.ini</filename>
246 located in the <filename>/etc/clutter-1.0</filename> and
247 <filename>$XDG_CONFIG_HOME/clutter-1.0</filename> directories. These files
248 must be valid key files (see #GKeyFile in the GLib documentation) and may
249 have three sections:</para>
253 <term>Environment</term>
254 <listitem><para>The keys in this section map the environment variables
255 honoured by Clutter.</para></listitem>
259 <listitem><para>The keys in this section related to the debugging notes
260 that Clutter exposes when compiled with debugging support; similarly to
261 the environment variables and command line arguments related to the
262 debugging notes, Clutter must be compiled with support for these notes
263 in order to use them.</para></listitem>
266 <term>Settings</term>
267 <listitem><para>The keys in this section strictly map to the #GObject
268 properties exposed by the #ClutterSettings type; if Clutter is running
269 on an X11 platform, the XSettings manager will take precedence over the
270 values specified in the <filename>settings.ini</filename>
271 file.</para></listitem>
275 <section id="configuration-keys-environment">
276 <title>Keys available for the Environment group</title>
281 <listitem><para>A boolean value, equivalent to setting
282 <code>CLUTTER_SHOW_FPS</code>.</para></listitem>
285 <term>DisableMipmappedText</term>
286 <listitem><para>A boolean value, equivalent to setting
287 <code>CLUTTER_DISABLE_MIPMAPPED_TEXT</code>.</para></listitem>
290 <term>UseFuzzyPicking</term>
291 <listitem><para>A boolean value, equivalent to setting
292 <code>CLUTTER_FUZZY_PICK</code>.</para></listitem>
295 <term>EnableAccessibility</term>
296 <listitem><para>A boolean value, equivalent to setting
297 <code>CLUTTER_ENABLE_ACCESSIBILITY</code>.</para></listitem>
300 <term>DefaultFps</term>
301 <listitem><para>An integer value, equivalent to setting
302 <code>CLUTTER_DEFAULT_FPS</code>.</para></listitem>
305 <term>TextDirection</term>
306 <listitem><para>A string value, equivalent to setting
307 <code>CLUTTER_TEXT_DIRECTION</code>.</para></listitem>
312 <section id="configuration-keys-debug">
313 <title>Keys available for the Debug group</title>
318 <listitem><para>A string containing the debugging flags, in the same
319 format that should be used with the <code>CLUTTER_DEBUG</code>
320 environment variable.</para></listitem>
323 <term>PaintDebug</term>
324 <listitem><para>A string containing the paint debugging flags, in the same
325 format that should be used with the <code>CLUTTER_PAINT</code>
326 environment variable.</para></listitem>
329 <term>PickDebug</term>
330 <listitem><para>A string containing the pick debugging flags, in the same
331 format that should be used with the <code>CLUTTER_PICK</code>
332 environment variable.</para></listitem>