2c524fbf73
We have an hardcoded list of drivers we have to go through when creating a Cogl context. Some platforms may expose those drivers, but not be the preferred ones. In order to allow users and system integrators to override the list of drivers, we should crib the same approach used by GDK, and have an environment variable with a list of drivers to try. The new environment variable is called `CLUTTER_DRIVER` and accepts a comma-separated list of driver names, which will be tested in sequence until one succeeds. There's also an additional '*' token which is used to ask Clutter to fall back to the internally defined preferred list of drivers. https://bugzilla.gnome.org/show_bug.cgi?id=742678
403 lines
16 KiB
XML
403 lines
16 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_DRIVER</term>
|
|
<listitem>
|
|
<para>Changes the GL driver used when initializing Clutter.
|
|
The allowed values for this environment variable are:</para>
|
|
<itemizedlist>
|
|
<listitem><simpara>gl3, for the GL driver using a 3.2+ core profile</simpara></listitem>
|
|
<listitem><simpara>gl, for the GL driver using a legacy profile</simpara></listitem>
|
|
<listitem><simpara>gles2, for the GLES 2.0 driver</simpara></listitem>
|
|
<listitem><simpara>any, for the default chosen by Cogl</simpara></listitem>
|
|
</itemizedlist>
|
|
<para>The special '*' value can be used to ask Clutter to use the
|
|
default list of drivers, e.g. 'CLUTTER_DRIVER=gles2,*' will ask Clutter
|
|
to try the GLES 2.0 driver first, and then fall back to the default list
|
|
of Cogl drivers.</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>
|