Emmanuele Bassi

              ebassi@linux.intel.com

# Running Clutter

## 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

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`.

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.