Part III. Running Clutter: Clutter Reference Manual

# Part III. Running Clutter

### Emmanuele Bassi

`<ebassi`linux.intel.com`>`

## Environment Variables

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:

CLUTTER_BACKEND | 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: x11, for the X11 backend wayland, for the Wayland backend win32, for the Windows backend osx, for the MacOS X backend gdk, for the GDK backend eglnative, for the EGL/KMS backend cex100, for the CEx100 backend All of the above options except for the `eglnative` and `cex100` backends also have an input backend.
CLUTTER_INPUT_BACKEND | 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: tslib evdev null 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 `eglnative` or the `cex100` windowing system backends.
CLUTTER_DRIVER | Changes the GL driver used when initializing Clutter. The allowed values for this environment variable are: gl3, for the GL driver using a 3.2+ core profile gl, for the GL driver using a legacy profile gles2, for the GLES 2.0 driver any, for the default chosen by Cogl 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.
CLUTTER_SCALE | Forces the window scaling factor to that value inside Clutter instead of relying on what backends detect.
CLUTTER_TEXT_DIRECTION | Forces the text direction of every Pango layout inside Clutter. Valid values are: ltr or rtl
CLUTTER_SHOW_FPS | Prints out the frames per second achieved by Clutter.
CLUTTER_DEFAULT_FPS | Sets the default framerate.
CLUTTER_DISABLE_MIPMAPPED_TEXT | Disables mipmapping when rendering text.
CLUTTER_FUZZY_PICK | Enables "fuzzy picking".
CLUTTER_DEBUG | 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 (",").
CLUTTER_PAINT | 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.
CLUTTER_ENABLE_DIAGNOSTIC | When set to 1, enables diagnostic messages for run-time deprecations, similarly to `G_ENABLE_DIAGNOSTIC` in GLib.

On the GLX backend there is also:

CLUTTER_VBLANK | Selects the sync-to-vblank mode to be used. Valid values are: none, dri or glx

## Command Line Arguments

Similarly to the environment variables, Clutter also installs command line switches that are parsed during initialization:

--clutter-show-fps | Equivalent of CLUTTER_SHOW_FPS. Prints the current rendering speed in frames per second.
--clutter-default-fps=FPS | Equivalent of CLUTTER_DEFAULT_FPS. Sets the default framerate.
--clutter-text-direction=DIRECTION | Equivalent of CLUTTER_TEXT_DIRECTION. Sets the direction for the text.
--clutter-disable-mipmapped-text | Equivalent of CLUTTER_DISABLE_MIPMAPPED_TEXT. Disables mipmapping when rendering text.
--clutter-use-fuzzy-picking | Equivalent of CLUTTER_FUZZY_PICK. Enables "fuzzy" picking.
--clutter-debug=FLAGS | Equivalent of CLUTTER_DEBUG. Sets FLAGS as the Clutter debugging flags.
--clutter-no-debug=FLAGS | Unsets FLAGS from the Clutter debugging flags.
--cogl-debug=FLAGS | Equivalent of COGL_DEBUG. Sets FLAGS as the Cogl debugging flags.
--cogl-no-debug=FLAGS | Unsets FLAGS from the Cogl debugging flags.
--clutter-enable-accessibility | Enables accessibility support.

The X11 backends also have the following command line options:

--display=DISPLAY | Sets the X11 display to use.
--screen=SCREEN | Sets the X11 screen number to use.
--synch | Make X11 calls synchronous.

The GLX backend also has the following command line option:

--vblank=METHOD | Equivalent of CLUTTER_VBLANK. Sets the sync-to-vblank method to be used.

## Debug flags for Clutter

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 (,).

actor | Generic actor-related notes
animation | ClutterAnimation notes
backend | Backend-related notes, including initialization of the backend features and GL context creation
event | Event handling notes
layout | ClutterLayoutManager notes
misc | Miscellaneous notes
scheduler | Notes related to timelines and the master clock
script | Notes related to ClutterScript

It is possible to get all the debugging notes using the special "all" flag.

## Configuration File

Clutter will look for files named `settings.ini` located in the `/etc/clutter-1.0` and `$XDG_CONFIG_HOME/clutter-1.0` directories. These files must be valid key files (see GKeyFile in the GLib documentation) and may have three sections:

Environment | The keys in this section map the environment variables honoured by Clutter.
Debug | 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.
Settings | 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 `settings.ini` file.

### Keys available for the Environment group

Backends | A string value, equivalent to setting `CLUTTER_BACKEND`.
Drivers | A string value, equivalent to setting `CLUTTER_DRIVER`.
ShowFps | A boolean value, equivalent to setting `CLUTTER_SHOW_FPS`.
DisableMipmappedText | A boolean value, equivalent to setting `CLUTTER_DISABLE_MIPMAPPED_TEXT`.
UseFuzzyPicking | A boolean value, equivalent to setting `CLUTTER_FUZZY_PICK`.
EnableAccessibility | A boolean value, equivalent to setting `CLUTTER_ENABLE_ACCESSIBILITY`.
SyncToVblank | A boolean value, equivalent to setting `CLUTTER_VBLANK`.
DefaultFps | An integer value, equivalent to setting `CLUTTER_DEFAULT_FPS`.
TextDirection | A string value, equivalent to setting `CLUTTER_TEXT_DIRECTION`.

### Keys available for the Debug group

Debug | A string containing the debugging flags, in the same format that should be used with the `CLUTTER_DEBUG` environment variable.
PaintDebug | A string containing the paint debugging flags, in the same format that should be used with the `CLUTTER_PAINT` environment variable.
PickDebug | A string containing the pick debugging flags, in the same format that should be used with the `CLUTTER_PICK` environment variable.