doc/reference/clutter/running-clutter.xml

   1 <part id="running-clutter">
   2   <partinfo>
   3     <author>
   4       <firstname>Emmanuele</firstname>
   5       <surname>Bassi</surname>
   6       <affiliation>
   7         <address>
   8           <email>ebassi@linux.intel.com</email>
   9         </address>
  10       </affiliation>
  11     </author>
  12   </partinfo>
  13
  14   <title>Running Clutter</title>
  15
  16   <partintro>
  17
  18     <section id="environment-variables">
  19       <title>Environment Variables</title>
  20
  21       <para>
  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:
  26       </para>
  27
  28       <variablelist>
  29         <varlistentry>
  30           <term>CLUTTER_TEXT_DIRECTION</term>
  31           <listitem>
  32             <para>Forces the text direction of every Pango layout
  33             inside Clutter. Valid values are: ltr or rtl</para>
  34           </listitem>
  35         </varlistentry>
  36         <varlistentry>
  37           <term>CLUTTER_SHOW_FPS</term>
  38           <listitem>
  39             <para>Prints out the frames per second achieved by Clutter.</para>
  40           </listitem>
  41         </varlistentry>
  42         <varlistentry>
  43           <term>CLUTTER_DEFAULT_FPS</term>
  44           <listitem>
  45             <para>Sets the default framerate.</para>
  46           </listitem>
  47         </varlistentry>
  48         <varlistentry>
  49           <term>CLUTTER_DISABLE_MIPMAPPED_TEXT</term>
  50           <listitem>
  51             <para>Disables mipmapping when rendering text.</para>
  52           </listitem>
  53         </varlistentry>
  54         <varlistentry>
  55           <term>CLUTTER_FUZZY_PICK</term>
  56           <listitem>
  57             <para>Enables "fuzzy picking".</para>
  58           </listitem>
  59         </varlistentry>
  60         <varlistentry>
  61           <term>CLUTTER_DEBUG</term>
  62           <listitem>
  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
  68             (",").</para>
  69           </listitem>
  70         </varlistentry>
  71         <varlistentry>
  72           <term>CLUTTER_PAINT</term>
  73           <listitem>
  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>
  77           </listitem>
  78         </varlistentry>
  79         <varlistentry>
  80           <term>CLUTTER_ENABLE_DIAGNOSTIC</term>
  81           <listitem>
  82             <para>When set to 1, enables diagnostic messages for run-time
  83             deprecations, similarly to <envvar>G_ENABLE_DIAGNOSTIC</envvar> in
  84             GLib.</para>
  85           </listitem>
  86         </varlistentry>
  87       </variablelist>
  88
  89       <para>On the GLX backend there is also:</para>
  90
  91       <variablelist>
  92         <varlistentry>
  93           <term>CLUTTER_VBLANK</term>
  94           <listitem>
  95             <para>Selects the sync-to-vblank mode to be used.
  96             Valid values are: none, dri or glx</para>
  97           </listitem>
  98         </varlistentry>
  99       </variablelist>
 100
 101     </section>
 102
 103     <section id="command-line">
 104       <title>Command Line Arguments</title>
 105
 106       <para>Similarly to the environment variables, Clutter also installs
 107       command line switches that are parsed during initialization:</para>
 108
 109       <variablelist>
 110         <varlistentry>
 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>
 114         </varlistentry>
 115         <varlistentry>
 116           <term>--clutter-default-fps=FPS</term>
 117           <listitem><para>Equivalent of CLUTTER_DEFAULT_FPS. Sets the
 118           default framerate.</para></listitem>
 119         </varlistentry>
 120         <varlistentry>
 121           <term>--clutter-text-direction=DIRECTION</term>
 122           <listitem><para>Equivalent of CLUTTER_TEXT_DIRECTION. Sets the
 123           direction for the text.</para></listitem>
 124         </varlistentry>
 125         <varlistentry>
 126           <term>--clutter-disable-mipmapped-text</term>
 127           <listitem><para>Equivalent of CLUTTER_DISABLE_MIPMAPPED_TEXT.
 128           Disables mipmapping when rendering text.</para></listitem>
 129         </varlistentry>
 130         <varlistentry>
 131           <term>--clutter-use-fuzzy-picking</term>
 132           <listitem><para>Equivalent of CLUTTER_FUZZY_PICK. Enables
 133           "fuzzy" picking.</para></listitem>
 134         </varlistentry>
 135         <varlistentry>
 136           <term>--clutter-debug=FLAGS</term>
 137           <listitem><para>Equivalent of CLUTTER_DEBUG. Sets FLAGS as the
 138           Clutter debugging flags.</para></listitem>
 139         </varlistentry>
 140         <varlistentry>
 141           <term>--clutter-no-debug=FLAGS</term>
 142           <listitem><para>Unsets FLAGS from the Clutter debugging
 143           flags.</para></listitem>
 144         </varlistentry>
 145         <varlistentry>
 146           <term>--cogl-debug=FLAGS</term>
 147           <listitem><para>Equivalent of COGL_DEBUG. Sets FLAGS as the
 148           Cogl debugging flags.</para></listitem>
 149         </varlistentry>
 150         <varlistentry>
 151           <term>--cogl-no-debug=FLAGS</term>
 152           <listitem><para>Unsets FLAGS from the Cogl debugging
 153           flags.</para></listitem>
 154         </varlistentry>
 155         <varlistentry>
 156           <term>--clutter-enable-accessibility</term>
 157           <listitem><para>Enables accessibility support.</para></listitem>
 158         </varlistentry>
 159       </variablelist>
 160
 161       <para>The X11 backends also have the following command line
 162       options:</para>
 163
 164       <variablelist>
 165         <varlistentry>
 166           <term>--display=DISPLAY</term>
 167           <listitem><para>Sets the X11 display to use.</para></listitem>
 168         </varlistentry>
 169         <varlistentry>
 170           <term>--screen=SCREEN</term>
 171           <listitem><para>Sets the X11 screen number to use.</para></listitem>
 172         </varlistentry>
 173         <varlistentry>
 174           <term>--synch</term>
 175           <listitem><para>Make X11 calls synchronous.</para></listitem>
 176         </varlistentry>
 177       </variablelist>
 178     </section>
 179
 180     <para>The GLX backend also has the following command line option:</para>
 181
 182     <variablelist>
 183       <varlistentry>
 184         <term>--vblank=METHOD</term>
 185         <listitem><para>Equivalent of CLUTTER_VBLANK. Sets the sync-to-vblank
 186         method to be used.</para></listitem>
 187       </varlistentry>
 188     </variablelist>
 189
 190     <section id="clutter-Debug-Flags">
 191       <title>Debug flags for Clutter</title>
 192
 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>
 196
 197       <!--
 198       keep in sync with the list of Clutter debug keys inside clutter-main.c
 199       -->
 200       <variablelist>
 201         <varlistentry>
 202           <term>actor</term>
 203           <listitem><para>Generic actor-related notes</para></listitem>
 204         </varlistentry>
 205         <varlistentry>
 206           <term>animation</term>
 207           <listitem><para>#ClutterAnimation notes</para></listitem>
 208         </varlistentry>
 209         <varlistentry>
 210           <term>backend</term>
 211           <listitem><para>Backend-related notes, including initialization of
 212           the backend features and GL context creation</para></listitem>
 213         </varlistentry>
 214         <varlistentry>
 215           <term>event</term>
 216           <listitem><para>Event handling notes</para></listitem>
 217         </varlistentry>
 218         <varlistentry>
 219           <term>layout</term>
 220           <listitem><para>#ClutterLayoutManager notes</para></listitem>
 221         </varlistentry>
 222         <varlistentry>
 223           <term>misc</term>
 224           <listitem><para>Miscellaneous notes</para></listitem>
 225         </varlistentry>
 226         <varlistentry>
 227           <term>scheduler</term>
 228           <listitem><para>Notes related to timelines and the master
 229           clock</para></listitem>
 230         </varlistentry>
 231         <varlistentry>
 232           <term>script</term>
 233           <listitem><para>Notes related to #ClutterScript</para></listitem>
 234         </varlistentry>
 235       </variablelist>
 236
 237       <para>It is possible to get all the debugging notes using the
 238       special "all" flag.</para>
 239
 240     </section>
 241
 242     <section id="configuration-file">
 243       <title>Configuration File</title>
 244
 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>
 250
 251       <variablelist>
 252         <varlistentry>
 253           <term>Environment</term>
 254           <listitem><para>The keys in this section map the environment variables
 255           honoured by Clutter.</para></listitem>
 256         </varlistentry>
 257         <varlistentry>
 258           <term>Debug</term>
 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>
 264         </varlistentry>
 265         <varlistentry>
 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>
 272         </varlistentry>
 273       </variablelist>
 274
 275       <section id="configuration-keys-environment">
 276         <title>Keys available for the Environment group</title>
 277
 278         <variablelist>
 279           <varlistentry>
 280             <term>ShowFps</term>
 281             <listitem><para>A boolean value, equivalent to setting
 282             <code>CLUTTER_SHOW_FPS</code>.</para></listitem>
 283           </varlistentry>
 284           <varlistentry>
 285             <term>DisableMipmappedText</term>
 286             <listitem><para>A boolean value, equivalent to setting
 287             <code>CLUTTER_DISABLE_MIPMAPPED_TEXT</code>.</para></listitem>
 288           </varlistentry>
 289           <varlistentry>
 290             <term>UseFuzzyPicking</term>
 291             <listitem><para>A boolean value, equivalent to setting
 292             <code>CLUTTER_FUZZY_PICK</code>.</para></listitem>
 293           </varlistentry>
 294           <varlistentry>
 295             <term>EnableAccessibility</term>
 296             <listitem><para>A boolean value, equivalent to setting
 297             <code>CLUTTER_ENABLE_ACCESSIBILITY</code>.</para></listitem>
 298           </varlistentry>
 299           <varlistentry>
 300             <term>DefaultFps</term>
 301             <listitem><para>An integer value, equivalent to setting
 302             <code>CLUTTER_DEFAULT_FPS</code>.</para></listitem>
 303           </varlistentry>
 304           <varlistentry>
 305             <term>TextDirection</term>
 306             <listitem><para>A string value, equivalent to setting
 307             <code>CLUTTER_TEXT_DIRECTION</code>.</para></listitem>
 308           </varlistentry>
 309         </variablelist>
 310       </section>
 311
 312       <section id="configuration-keys-debug">
 313         <title>Keys available for the Debug group</title>
 314
 315         <variablelist>
 316           <varlistentry>
 317             <term>Debug</term>
 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>
 321           </varlistentry>
 322           <varlistentry>
 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>
 327           </varlistentry>
 328           <varlistentry>
 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>
 333           </varlistentry>
 334         </variablelist>
 335       </section>
 336
 337     </section>
 338
 339   </partintro>
 340 </part>