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

-i, --inactive-opacity=OPACITY

-e, --frame-opacity=OPACITY

-b, --daemon

--log-level

--log-file

--legacy-backends

--show-all-xerrors

--config PATH

--write-pid-path PATH

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

--corner-radius-rules RADIUS:CONDITION

--rounded-corners-exclude CONDITION

--no-frame-pacing

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

--crop-shadow-to-monitor

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

--transparent-clipping-exclude CONDITION

--window-shader-fg SHADER

--window-shader-fg-rule SHADER:CONDITION

--dithered-present

WINDOW RULES

Window rules allow you to set window-specific options which can be used to change appearance of windows based on certain conditions. Note there are other options that also cover some of the functionality of window rules, but window rules are more flexible and powerful. If you are creating a fresh configuration file, it is recommended to use window rules instead of the other options.

Following is a list of all the options that are superseded by window rules:

--shadow-ignore-shaped, -i, --inactive-opacity=OPACITY, --active-opacity OPACITY, --inactive-opacity-override, --inactive-dim VALUE, --mark-wmwin-focused, --mark-ovredir-focused, --invert-color-include CONDITION, --shadow-exclude CONDITION, --fade-exclude CONDITION, --focus-exclude CONDITION, --rounded-corners-exclude CONDITION, --blur-background-exclude CONDITION, --opacity-rule OPACITY:CONDITION, --corner-radius-rules RADIUS:CONDITION, --window-shader-fg-rule SHADER:CONDITION, --clip-shadow-above CONDITION. As well as the wintypes configuration file option.

If window rules option is used, none of the above options will have any effect. And warning messages will be issued. When the window rules option is used, the compositor will also behave somewhat differently in certain cases. One such case is that fullscreen windows will no longer have their rounded corners disabled by default.

If you are currently using some of these options and want to switch to window rules, or if you want to keep the existing behavior, see the Migrating old rules section for how to convert them.

rules = (
        { match = "focused"; opacity = 1; },
        { match = "name = 'firefox'"; shadow = true; },
        # ... and so on
)

rules = (
        { match = "fullscreen"; corner-radius = 0; },
)

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.

Formal grammar for a condition looks like this:

Condition <- Term ('||' Term)*
Term <- Item ('&&' Item)*
Item <- '!'? Target '@'? ('[' Index ']')? (Operator Pattern)? | '(' Condition ')'

Concretely speaking, a condition is a sequence of one or more simple pattern matching Items, joined by logical operators && (and) and || (or). && has higher precedence than ||. Both operators are left-associative. Parentheses can be used to raise precedence. If an Item has a leading negation operator (!), the result of the item is negated.

Inside an Item:

Target

Index

Operator and Pattern

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@ *= "MENU"
# If the window is marked hidden: _NET_WM_STATE contains _NET_WM_STATE_HIDDEN
_NET_WM_STATE@[*] = "_NET_WM_STATE_HIDDEN"
# If the window is marked sticky: _NET_WM_STATE contains an atom that contains
# "sticky", ignore case
_NET_WM_STATE@[*] *?= "sticky"
# If the window name contains "Firefox", ignore case
name *?= "Firefox"
_NET_WM_NAME@ *?= "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 = 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] < 20 || !_NET_FRAME_EXTENTS@
# The pattern here will be parsed as "dd4"
name = "\x64\x64\o64"
# These two are equivalent
name = 'Firefox' || name = 'Chromium' && class_i = 'Navigator'
name = 'Firefox' || (name = 'Chromium' && class_i = 'Navigator')

ANIMATIONS

picom supports fading animation when you open or close a window. In addition to that, picom also has a very powerful animation script system, which can be used to animate many aspects of a window based on certain triggers. Animation scripts can be defined in your configuration file by setting the option animations. It is also possible to define animations per-window using the WINDOW RULES system, by setting the animations option in a rule. (Read the rest of this section first before you go there.)

The basic syntax of the animations option is as follows:

animations = ({
        triggers = [ ... ];
        suppressions = [ ... ];
        # more options follow
        ...
}, {
        # another animation script
}, ...)

animations = ( ... ) sets animations to a list, which can contain multiple sub-items, each item is an animation script. An animation script is a group containing multiple entries (i.e. { key = value; ... }). All animation scripts share some common options, like triggers and suppressions, they also contain more options that either defines the actual animation, or selects an animation preset.

animations = ({
        triggers = [ "close", "hide" ];
        preset = "slide-out";
        direction = "down";
        ...
}, ...)

# this animation script does nothing to your windows by the way.
animations = ({
        # common options, these are not part of the collection of variables
        triggers = [ "open" ];
        # variables
        a = 10;
        b = "a * 10";
        c = "a + b";
        d = {
                curve = "cubic-bezier(0.25, 0.1, 0.25, 1.0)";
                duration = 0.5;
                delay = 0;
                start = 0;
                end = 1;
        };
        # more options follow
        # ...
}, ...)

animations = ({
        triggers = [ "open" ];
        offset-x = {
                duration = 2;
                start = 0;
                end = 100;
        };
}, ...)

SHADER INTERFACE

This secion describes the interface of a custom shader, how it is used by picom, and what parameters are passed by picom to the shader. This does not apply to the legacy backends.

A custom shader is a GLSL fragment shader program, which can be used to override the default way of how a window is rendered. If a custom shader is used, the default picom effects (e.g. dimming, color inversion, etc.) will no longer be automatically applied. It would be the custom shader’s responsibility to apply these effects.

The interface between picom and a custom shader is dependent on which backend is being used. The xrender backend doesn’t support shader at all. Here we descibe the interface provided by the glx backend.

The shader must define a function, vec4 window_shader(), which would be the entry point of the shader. The returned vec4 will be used to set gl_FragColor. A function, vec4 default_post_processing(vec4 c), is provided for applying the default picom effects to input color 'c'.

The following uniform/input variables are made available to the shader:

in vec2 texcoord;             // texture coordinate of the fragment
uniform float opacity;        // opacity of the window (0.0 - 1.0)
uniform float dim;            // dimming factor of the window (0.0 - 1.0, higher means more dim)
uniform float corner_radius;  // corner radius of the window (pixels)
uniform float border_width;   // estimated border width of the window (pixels)
uniform bool invert_color;    // whether to invert the color of the window
uniform sampler2D tex;        // texture of the window
uniform vec2 effective_size;  // effective dimensions of the texture (repeats pixels if larger than tex)
uniform sampler2D brightness; // estimated brightness of the window, 1x1 texture
uniform float max_brightness; // configured maximum brightness of the window (0.0 - 1.0)
uniform float time;           // time in milliseconds, counting from an unspecified starting point

The default behavior of picom window rendering can be replicated by the following shader:

#version 330
in vec2 texcoord;             // texture coordinate of the fragment
uniform sampler2D tex;        // texture of the window
// Default window post-processing:
// 1) invert color
// 2) opacity / transparency
// 3) max-brightness clamping
// 4) rounded corners
vec4 default_post_processing(vec4 c);
// Default window shader:
// 1) fetch the specified pixel
// 2) apply default post-processing
vec4 window_shader() {
    vec2 texsize = textureSize(tex, 0);
    vec4 c = texture2D(tex, texcoord / texsize, 0);
    return default_post_processing(c);
}

The interface is expected to be mostly stable.

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.

When @include directive is used in the config file, picom will first search for the included file in the parent directory of picom.conf, then in $XDG_CONFIG_HOME/picom/include/, then in $XDG_CONFIG_DIRS/picom/include.

picom uses general libconfig configuration file format. A sample configuration file is available as picom.sample.conf in the source tree. Most of command line 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.

Some options can only be set in the configuration file. Such options include rules (see WINDOW RULES), animations (see ANIMATIONS), wintypes (see below).

Window-type-specific settings allow you to set window-specific options based on the window type. These settings are exposed only in configuration file. The format of this option is as follows:

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-inspect(1), picom-trans(1)

AUTHOR

Yuxuan Shui