NAME¶

picom - a compositor for X11

SYNOPSIS¶

picom [OPTIONS]

DESCRIPTION¶

picom is a compositor based on Dana Jansens' version of xcompmgr (which itself was written by Keith Packard). It includes some improvements over the original xcompmgr, like window frame opacity and inactive window transparency.

OPTIONS¶

-h, --help

-r, --shadow-radius=RADIUS

-o, --shadow-opacity=OPACITY

-l, --shadow-offset-x=OFFSET

-t, --shadow-offset-y=OFFSET

-I, --fade-in-step=OPACITY_STEP

-O, --fade-out-step=OPACITY_STEP

-D, --fade-delta=MILLISECONDS

-c, --shadow

-f, --fading

-F

-i, --inactive-opacity=OPACITY

-e, --frame-opacity=OPACITY

-b, --daemon

--log-level

--log-file

--experimental-backends

--show-all-xerrors

--config PATH

--write-pid-path PATH

--shadow-color STRING

--shadow-red VALUE

--shadow-green VALUE

--shadow-blue VALUE

--inactive-opacity-override

--active-opacity OPACITY

--inactive-dim VALUE

--corner-radius VALUE

--rounded-corners-exclude CONDITION

--mark-wmwin-focused

--mark-ovredir-focused

--no-fading-openclose

--no-fading-destroyed-argb

--shadow-ignore-shaped

--detect-rounded-corners

--detect-client-opacity

--vsync, --no-vsync

--use-ewmh-active-win

--unredir-if-possible

--unredir-if-possible-delay MILLISECONDS

--unredir-if-possible-exclude CONDITION

--shadow-exclude CONDITION

--clip-shadow-above CONDITION

--fade-exclude CONDITION

--focus-exclude CONDITION

--inactive-dim-fixed

--detect-transient

--detect-client-leader

--blur-method, --blur-size, --blur-deviation, --blur-strength

--blur-background

--blur-background-frame

--blur-background-fixed

--blur-kern MATRIX

WIDTH,HEIGHT,ELE1,ELE2,ELE3,ELE4,ELE5...

--blur-kern '7,7,0.000003,0.000102,0.000849,0.001723,0.000849,0.000102,0.000003,0.000102,0.003494,0.029143,0.059106,0.029143,0.003494,0.000102,0.000849,0.029143,0.243117,0.493069,0.243117,0.029143,0.000849,0.001723,0.059106,0.493069,0.493069,0.059106,0.001723,0.000849,0.029143,0.243117,0.493069,0.243117,0.029143,0.000849,0.000102,0.003494,0.029143,0.059106,0.029143,0.003494,0.000102,0.000003,0.000102,0.000849,0.001723,0.000849,0.000102,0.000003'

--blur-background-exclude CONDITION

--resize-damage INTEGER

--invert-color-include CONDITION

--opacity-rule OPACITY:'CONDITION'

--shadow-exclude-reg GEOMETRY

--xinerama-shadow-crop

--backend BACKEND

--glx-no-stencil

--glx-no-rebind-pixmap

--no-use-damage

--xrender-sync-fence

--glx-fshader-win SHADER

--force-win-blend

--dbus

--benchmark CYCLES

--benchmark-wid WINDOW_ID

--no-ewmh-fullscreen

--max-brightness

--transparent-clipping

FORMAT OF CONDITIONS¶

Some options accept a condition string to match certain windows. A condition string is formed by one or more conditions, joined by logical operators.

A condition with "exists" operator looks like this:

<NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE>

With equals operator it looks like:

<NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE> <NEGATION> <OP QUALIFIER> <MATCH TYPE> = <PATTERN>

With greater-than/less-than operators it looks like:

<NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE> <NEGATION> <OPERATOR> <PATTERN>

NEGATION (optional) is one or more exclamation marks;

TARGET is either a predefined target name, or the name of a window property to match. Supported predefined targets are id, x, y, x2 (x + widthb), y2 (like x2), width, height, widthb (width + 2 * border_width), heightb (like widthb), border_width, fullscreen, override_redirect, argb (whether the window has an ARGB visual), focused, wmwin (whether the window looks like a WM window, i.e. has no child window with WM_STATE and is not override-redirected), bounding_shaped, rounded_corners (requires --detect-rounded-corners), client (ID of client window), window_type (window type in string), leader (ID of window leader), name, class_g (= WM_CLASS[1]), class_i (= WM_CLASS[0]), and role.

CLIENT/FRAME is a single @ if the window attribute should be be looked up on client window, nothing if on frame window;

INDEX (optional) is the index number of the property to look up. For example, [2] means look at the third value in the property. If not specified, the first value (index [0]) is used implicitly. Use the special value [*] to perform matching against all available property values using logical OR. Do not specify it for predefined targets.

FORMAT (optional) specifies the format of the property, 8, 16, or 32. On absence we use format X reports. Do not specify it for predefined or string targets.

TYPE is a single character representing the type of the property to match for: c for CARDINAL, a for ATOM, w for WINDOW, d for DRAWABLE, s for STRING (and any other string types, such as UTF8_STRING). Do not specify it for predefined targets.

OP QUALIFIER (optional), applicable only for equals operator, could be ? (ignore-case).

MATCH TYPE (optional), applicable only for equals operator, could be nothing (exact match), * (match anywhere), ^ (match from start), % (wildcard), or ~ (PCRE regular expression).

OPERATOR is one of = (equals), <, >, <=, =>, or nothing (exists). Exists operator checks whether a property exists on a window (but for predefined targets, exists means != 0 then).

PATTERN is either an integer or a string enclosed by single or double quotes. Python-3-style escape sequences and raw string are supported in the string format.

Supported logical operators are && (and) and || (or). && has higher precedence than ||, left-to-right associativity. Use parentheses to change precedence.

Examples:

# If the window is focused
focused
focused = 1
# If the window is not override-redirected
!override_redirect
override_redirect = false
override_redirect != true
override_redirect != 1
# If the window is a menu
window_type *= "menu"
_NET_WM_WINDOW_TYPE@:a *= "MENU"
# If the window is marked hidden: _NET_WM_STATE contains _NET_WM_STATE_HIDDEN
_NET_WM_STATE@[*]:a = "_NET_WM_STATE_HIDDEN"
# If the window is marked sticky: _NET_WM_STATE contains an atom that contains
# "sticky", ignore case
_NET_WM_STATE@[*]:a *?= "sticky"
# If the window name contains "Firefox", ignore case
name *?= "Firefox"
_NET_WM_NAME@:s *?= "Firefox"
# If the window name ends with "Firefox"
name %= "*Firefox"
name ~= "Firefox$"
# If the window has a property _COMPTON_SHADOW with value 0, type CARDINAL,
# format 32, value 0, on its frame window
_COMPTON_SHADOW:32c = 0
# If the third value of _NET_FRAME_EXTENTS is less than 20, or there's no
# _NET_FRAME_EXTENTS property on client window
_NET_FRAME_EXTENTS@[2]:32c < 20 || !_NET_FRAME_EXTENTS@:32c
# The pattern here will be parsed as "dd4"
name = "\x64\x64\o64"
# The pattern here will be parsed as "\x64\x64\x64"
name = r"\x64\x64\o64"

LEGACY FORMAT OF CONDITIONS¶

This is the old condition format we once used. Support of this format might be removed in the future.

condition = TARGET:TYPE[FLAGS]:PATTERN

TARGET is one of "n" (window name), "i" (window class instance), "g" (window general class), and "r" (window role).

TYPE is one of "e" (exact match), "a" (match anywhere), "s" (match from start), "w" (wildcard), and "p" (PCRE regular expressions, if compiled with the support).

FLAGS could be a series of flags. Currently the only defined flag is "i" (ignore case).

PATTERN is the actual pattern string.

CONFIGURATION FILES¶

picom could read from a configuration file if libconfig support is compiled in. If --config is not used, picom will seek for a configuration file in $XDG_CONFIG_HOME/picom.conf (~/.config/picom.conf, usually), then $XDG_CONFIG_HOME/picom/picom.conf, then $XDG_CONFIG_DIRS/picom.conf (often /etc/xdg/picom.conf), then $XDG_CONFIG_DIRS/picom/picom.conf.

picom uses general libconfig configuration file format. A sample configuration file is available as picom.sample.conf in the source tree. Most of commandline switches can be used as options in configuration file as well. For example, --vsync option documented above can be set in the configuration file using `vsync = `. Command line options will always overwrite the settings in the configuration file.

Window-type-specific settings are exposed only in configuration file and has the following format:

wintypes:
{


  WINDOW_TYPE = { fade = BOOL; shadow = BOOL; opacity = FLOAT; focus = BOOL; blur-background = BOOL; full-shadow = BOOL; clip-shadow-above = BOOL; redir-ignore = BOOL; };
};

WINDOW_TYPE is one of the 15 window types defined in EWMH standard: "unknown", "desktop", "dock", "toolbar", "menu", "utility", "splash", "dialog", "normal", "dropdown_menu", "popup_menu", "tooltip", "notification", "combo", and "dnd".

Following per window-type options are available:

BLUR¶

You can configure how the window background is blurred using a blur section in your configuration file. Here is an example:

blur:
{


  method = "gaussian";


  size = 10;


  deviation = 5.0;
};

Available options of the blur section are:

SIGNALS¶

D-BUS API¶

It’s possible to control picom via D-Bus messages, by running picom with --dbus and send messages to com.github.chjj.compton.<DISPLAY>. <DISPLAY> is the display used by picom, with all non-alphanumeric characters transformed to underscores. For DISPLAY=:0.0 you should use com.github.chjj.compton._0_0, for example.

The D-Bus methods and signals are not yet stable, thus undocumented right now.

EXAMPLES¶

$ picom --config /dev/null

$ picom -cf

$ picom -bcf -i 0.8 -e 0.8 --no-fading-openclose

$ picom -c --shadow-red 1 --shadow-green 1 --shadow-blue 1

$ picom -c --shadow-exclude 'class_g = "wbar"'

$ picom --backend glx --vsync

BUGS¶

Please submit bug reports to https://github.com/yshui/picom.

Out dated information in this man page is considered a bug.

RESOURCES¶

Homepage: https://github.com/yshui/picom

SEE ALSO¶

xcompmgr(1), picom-trans(1)