67bf902022
Since we only have one API reference, we can drop the clutter/ sub-level, and have all the files under doc/reference.
386 lines
15 KiB
XML
386 lines
15 KiB
XML
<part id="running-clutter">
|
|
<partinfo>
|
|
<author>
|
|
<firstname>Emmanuele</firstname>
|
|
<surname>Bassi</surname>
|
|
<affiliation>
|
|
<address>
|
|
<email>ebassi@linux.intel.com</email>
|
|
</address>
|
|
</affiliation>
|
|
</author>
|
|
</partinfo>
|
|
|
|
<title>Running Clutter</title>
|
|
|
|
<partintro>
|
|
|
|
<section id="environment-variables">
|
|
<title>Environment Variables</title>
|
|
|
|
<para>
|
|
Clutter automatically checks environment variables during
|
|
its initialization. These environment variables are meant
|
|
as debug tools, overrides for default behaviours or to
|
|
address known hardware issues:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>CLUTTER_BACKEND</term>
|
|
<listitem>
|
|
<para>Changes the windowing system backend used by Clutter.
|
|
The allowed values for this environment variable depend on
|
|
the configuration options used when compiling Clutter. The
|
|
available values are:</para>
|
|
<itemizedlist>
|
|
<listitem><simpara>x11, for the X11 backend</simpara></listitem>
|
|
<listitem><simpara>wayland, for the Wayland backend</simpara></listitem>
|
|
<listitem><simpara>win32, for the Windows backend</simpara></listitem>
|
|
<listitem><simpara>osx, for the MacOS X backend</simpara></listitem>
|
|
<listitem><simpara>gsk, for the GDK backend</simpara></listitem>
|
|
<listitem><simpara>eglnative, for the EGL/KMS backend</simpara></listitem>
|
|
<listitem><simpara>cex100, for the CEx100 backend</simpara></listitem>
|
|
</itemizedlist>
|
|
<para>All of the above options except for the <varname>eglnative</varname>
|
|
and <varname>cex100</varname> backends also have an input backend.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>CLUTTER_INPUT_BACKEND</term>
|
|
<listitem>
|
|
<para>Changes the input backend used by Clutter.
|
|
The allowed values for this environment variable depend on
|
|
the configuration options used when compiling Clutter. The
|
|
available values are:</para>
|
|
<itemizedlist>
|
|
<listitem><simpara>tslib</simpara></listitem>
|
|
<listitem><simpara>evdev</simpara></listitem>
|
|
<listitem><simpara>null</simpara></listitem>
|
|
</itemizedlist>
|
|
<para>This environment variable is only useful for setting the input
|
|
backend when using a windowing system backend that does not have an
|
|
input API, like the <varname>eglnative</varname> or the <varname>cex100</varname>
|
|
windowing system backends.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>CLUTTER_SCALE</term>
|
|
<listitem>
|
|
<para>Forces the window scaling factor to that value
|
|
inside Clutter instead of relying on what backends detect.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>CLUTTER_TEXT_DIRECTION</term>
|
|
<listitem>
|
|
<para>Forces the text direction of every Pango layout
|
|
inside Clutter. Valid values are: ltr or rtl</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>CLUTTER_SHOW_FPS</term>
|
|
<listitem>
|
|
<para>Prints out the frames per second achieved by Clutter.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>CLUTTER_DEFAULT_FPS</term>
|
|
<listitem>
|
|
<para>Sets the default framerate.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>CLUTTER_DISABLE_MIPMAPPED_TEXT</term>
|
|
<listitem>
|
|
<para>Disables mipmapping when rendering text.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>CLUTTER_FUZZY_PICK</term>
|
|
<listitem>
|
|
<para>Enables "fuzzy picking".</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>CLUTTER_DEBUG</term>
|
|
<listitem>
|
|
<para>Enables debugging modes for Clutter; debugging modes are
|
|
used to print debugging messages on the console. Clutter must be
|
|
compiled with the --enable-debug configuration switch for these
|
|
messages to be printed out. Multiple debugging modes can be
|
|
enabled by separating them using a colon (":") or a comma
|
|
(",").</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>CLUTTER_PAINT</term>
|
|
<listitem>
|
|
<para>Enables paint debugging modes for Clutter; the modes change
|
|
the way Clutter paints a scene and are useful for debugging the
|
|
behaviour of the paint cycle.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>CLUTTER_ENABLE_DIAGNOSTIC</term>
|
|
<listitem>
|
|
<para>When set to 1, enables diagnostic messages for run-time
|
|
deprecations, similarly to <varname>G_ENABLE_DIAGNOSTIC</varname> in
|
|
GLib.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>On the GLX backend there is also:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>CLUTTER_VBLANK</term>
|
|
<listitem>
|
|
<para>Selects the sync-to-vblank mode to be used.
|
|
Valid values are: none, dri or glx</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section id="command-line">
|
|
<title>Command Line Arguments</title>
|
|
|
|
<para>Similarly to the environment variables, Clutter also installs
|
|
command line switches that are parsed during initialization:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>--clutter-show-fps</term>
|
|
<listitem><para>Equivalent of CLUTTER_SHOW_FPS. Prints the
|
|
current rendering speed in frames per second.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--clutter-default-fps=FPS</term>
|
|
<listitem><para>Equivalent of CLUTTER_DEFAULT_FPS. Sets the
|
|
default framerate.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--clutter-text-direction=DIRECTION</term>
|
|
<listitem><para>Equivalent of CLUTTER_TEXT_DIRECTION. Sets the
|
|
direction for the text.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--clutter-disable-mipmapped-text</term>
|
|
<listitem><para>Equivalent of CLUTTER_DISABLE_MIPMAPPED_TEXT.
|
|
Disables mipmapping when rendering text.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--clutter-use-fuzzy-picking</term>
|
|
<listitem><para>Equivalent of CLUTTER_FUZZY_PICK. Enables
|
|
"fuzzy" picking.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--clutter-debug=FLAGS</term>
|
|
<listitem><para>Equivalent of CLUTTER_DEBUG. Sets FLAGS as the
|
|
Clutter debugging flags.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--clutter-no-debug=FLAGS</term>
|
|
<listitem><para>Unsets FLAGS from the Clutter debugging
|
|
flags.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--cogl-debug=FLAGS</term>
|
|
<listitem><para>Equivalent of COGL_DEBUG. Sets FLAGS as the
|
|
Cogl debugging flags.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--cogl-no-debug=FLAGS</term>
|
|
<listitem><para>Unsets FLAGS from the Cogl debugging
|
|
flags.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--clutter-enable-accessibility</term>
|
|
<listitem><para>Enables accessibility support.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>The X11 backends also have the following command line
|
|
options:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>--display=DISPLAY</term>
|
|
<listitem><para>Sets the X11 display to use.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--screen=SCREEN</term>
|
|
<listitem><para>Sets the X11 screen number to use.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--synch</term>
|
|
<listitem><para>Make X11 calls synchronous.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
|
|
<para>The GLX backend also has the following command line option:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>--vblank=METHOD</term>
|
|
<listitem><para>Equivalent of CLUTTER_VBLANK. Sets the sync-to-vblank
|
|
method to be used.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<section id="clutter-Debug-Flags">
|
|
<title>Debug flags for Clutter</title>
|
|
|
|
<para>The debugging flags can be used for the CLUTTER_DEBUG environment
|
|
variable and the --clutter-debug command line switch. Multiple flags can
|
|
be separated by a colon (:) or a comma (,).</para>
|
|
|
|
<!--
|
|
keep in sync with the list of Clutter debug keys inside clutter-main.c
|
|
-->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>actor</term>
|
|
<listitem><para>Generic actor-related notes</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>animation</term>
|
|
<listitem><para>#ClutterAnimation notes</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>backend</term>
|
|
<listitem><para>Backend-related notes, including initialization of
|
|
the backend features and GL context creation</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>event</term>
|
|
<listitem><para>Event handling notes</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>layout</term>
|
|
<listitem><para>#ClutterLayoutManager notes</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>misc</term>
|
|
<listitem><para>Miscellaneous notes</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>scheduler</term>
|
|
<listitem><para>Notes related to timelines and the master
|
|
clock</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>script</term>
|
|
<listitem><para>Notes related to #ClutterScript</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>It is possible to get all the debugging notes using the
|
|
special "all" flag.</para>
|
|
|
|
</section>
|
|
|
|
<section id="configuration-file">
|
|
<title>Configuration File</title>
|
|
|
|
<para>Clutter will look for files named <filename>settings.ini</filename>
|
|
located in the <filename>/etc/clutter-1.0</filename> and
|
|
<filename>$XDG_CONFIG_HOME/clutter-1.0</filename> directories. These files
|
|
must be valid key files (see #GKeyFile in the GLib documentation) and may
|
|
have three sections:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>Environment</term>
|
|
<listitem><para>The keys in this section map the environment variables
|
|
honoured by Clutter.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Debug</term>
|
|
<listitem><para>The keys in this section related to the debugging notes
|
|
that Clutter exposes when compiled with debugging support; similarly to
|
|
the environment variables and command line arguments related to the
|
|
debugging notes, Clutter must be compiled with support for these notes
|
|
in order to use them.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Settings</term>
|
|
<listitem><para>The keys in this section strictly map to the #GObject
|
|
properties exposed by the #ClutterSettings type; if Clutter is running
|
|
on an X11 platform, the XSettings manager will take precedence over the
|
|
values specified in the <filename>settings.ini</filename>
|
|
file.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<section id="configuration-keys-environment">
|
|
<title>Keys available for the Environment group</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>ShowFps</term>
|
|
<listitem><para>A boolean value, equivalent to setting
|
|
<code>CLUTTER_SHOW_FPS</code>.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>DisableMipmappedText</term>
|
|
<listitem><para>A boolean value, equivalent to setting
|
|
<code>CLUTTER_DISABLE_MIPMAPPED_TEXT</code>.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>UseFuzzyPicking</term>
|
|
<listitem><para>A boolean value, equivalent to setting
|
|
<code>CLUTTER_FUZZY_PICK</code>.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>EnableAccessibility</term>
|
|
<listitem><para>A boolean value, equivalent to setting
|
|
<code>CLUTTER_ENABLE_ACCESSIBILITY</code>.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>DefaultFps</term>
|
|
<listitem><para>An integer value, equivalent to setting
|
|
<code>CLUTTER_DEFAULT_FPS</code>.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>TextDirection</term>
|
|
<listitem><para>A string value, equivalent to setting
|
|
<code>CLUTTER_TEXT_DIRECTION</code>.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
|
|
<section id="configuration-keys-debug">
|
|
<title>Keys available for the Debug group</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>Debug</term>
|
|
<listitem><para>A string containing the debugging flags, in the same
|
|
format that should be used with the <code>CLUTTER_DEBUG</code>
|
|
environment variable.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>PaintDebug</term>
|
|
<listitem><para>A string containing the paint debugging flags, in the same
|
|
format that should be used with the <code>CLUTTER_PAINT</code>
|
|
environment variable.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>PickDebug</term>
|
|
<listitem><para>A string containing the pick debugging flags, in the same
|
|
format that should be used with the <code>CLUTTER_PICK</code>
|
|
environment variable.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</partintro>
|
|
</part>
|