Part III. Running Clutter

Emmanuele Bassi



          

        

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
  • gsk, 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.