picom - Man Page

• Enable picom during a session: picom &
• Start picom as a background process: picom -b
• Use a custom configuration file: picom --config path/to/config_file

tldr.sh

picom [Options]

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.

-h,  --help

Get the usage text embedded in program code, which may be more up-to-date than this man page.

-r,  --shadow-radius=RADIUS

The blur radius for shadows, in pixels. (defaults to 12)

-o,  --shadow-opacity=OPACITY

The opacity of shadows. (0.0 - 1.0, defaults to 0.75)

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

The left offset for shadows, in pixels. (defaults to -15)

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

The top offset for shadows, in pixels. (defaults to -15)

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

Opacity change between steps while fading in. (0.01 - 1.0, defaults to 0.028)

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

Opacity change between steps while fading out. (0.01 - 1.0, defaults to 0.03)

-D,  --fade-delta=MILLISECONDS

The time between steps in fade step, in milliseconds. (> 0, defaults to 10)

-c,  --shadow

Enabled client-side shadows on windows. Note desktop windows (windows with _NET_WM_WINDOW_TYPE_DESKTOP) never get shadow, unless explicitly requested using the wintypes option.

-f,  --fading

Fade windows in/out when opening/closing and when opacity changes, unless --no-fading-openclose is used.

-i,  --inactive-opacity=OPACITY

Opacity of inactive windows. (0.1 - 1.0, defaults to 1.0). Using this option is discouraged, see the Window Rules section for the recommended way to set window-specific opacity.

-e,  --frame-opacity=OPACITY

Opacity of window titlebars and borders. (0.1 - 1.0, disabled by default)

-b,  --daemon

Daemonize process. Fork to background after initialization. This option can only be set from the command line, setting this in the configuration file will have no effect.

--log-level

Set the log level. Possible values are "TRACE", "DEBUG", "INFO", "WARN", "ERROR", in increasing level of importance. Case doesn’t matter. If using the "TRACE" log level, it’s better to log into a file using --log-file, since it can generate a huge stream of logs.

--log-file

Set the log file. If --log-file is never specified, logs will be written to stderr. Otherwise, logs will to written to the given file, though some of the early logs might still be written to the stderr. When setting this option from the config file, it is recommended to use an absolute path.

--legacy-backends

Use the old version of the backends. This option can not be set from the config file.

--show-all-xerrors

Show all X errors (for debugging).

--config PATH

Look for configuration file at the path. See Configuration Files section below for where picom looks for a configuration file by default. Use /dev/null to avoid loading configuration file.

--write-pid-path PATH

Write process ID to a file. it is recommended to use an absolute path.

--plugins PATH

Specify plugins to load. Plugins will first be searched in current working directory (unless specified in the config file, in which case this step is skipped), then in $XDG_CONFIG_HOME/picom/plugins, then in $XDG_CONFIG_DIRS/picom/plugins. If all of the above fail, the plugin name is passed directly to the dynamic loader. Can be specified multiple times to load more than one plugins.

--shadow-color STRING

Color of shadow, as a hex string (e.g. #000000)

--shadow-red VALUE

Red color value of shadow (0.0 - 1.0, defaults to 0).

--shadow-green VALUE

Green color value of shadow (0.0 - 1.0, defaults to 0).

--shadow-blue VALUE

Blue color value of shadow (0.0 - 1.0, defaults to 0).

--inactive-opacity-override

Let inactive opacity set by -i override the _NET_WM_WINDOW_OPACITY values of windows. Using this is discouraged, see the Window Rules section for the recommended way to set window-specific opacity.

--active-opacity OPACITY

Default opacity for active windows. (0.0 - 1.0, defaults to 1.0). Using this is discouraged, see the Window Rules section for the recommended way to set window-specific opacity.

--inactive-dim VALUE

Dim inactive windows. (0.0 - 1.0, defaults to 0.0). Using this option is discouraged, see the Window Rules section for the recommended way to set window-specific dim levels.

--corner-radius VALUE

Sets the radius of rounded window corners. When > 0, the compositor will round the corners of windows. Does not interact well with --transparent-clipping. (defaults to 0).

--corner-radius-rules RADIUS:CONDITION

Specify a list of corner radius rules. Overrides the corner radii of matching windows. This option takes precedence over the --rounded-corners-exclude option, and also overrides the default exclusion of fullscreen windows. The condition has the same format as --opacity-rule. Using this is discouraged, see the Window Rules section for the recommended way to set window-specific corner radius.

--rounded-corners-exclude CONDITION

Exclude conditions for rounded corners. Using this is discouraged, see the Window Rules section for the recommended way to set window-specific corner radius.

--no-frame-pacing

Disable vsync-aware frame pacing. By default, the compositor tries to make sure it only renders once per vblank interval, and also the render happens as late as possible to minimize the latency from updates to the screen. However this can sometimes cause stuttering, or even lowered frame rate. This option can be used to disable frame pacing.

--mark-wmwin-focused

Try to detect WM windows (a non-override-redirect window with no child that has WM_STATE) and mark them as active. Using this is discouraged, see the Window Rules section for the recommended way to set window-specific rules.

--mark-ovredir-focused

Mark override-redirect windows that doesn’t have a child window with WM_STATE focused. Using this is discouraged, see the Window Rules section for the recommended way to set window-specific rules.

--no-fading-openclose

Do not fade on window open/close.

--no-fading-destroyed-argb

Do not fade destroyed ARGB windows with WM frame. Workaround of bugs in Openbox, Fluxbox, etc.

--shadow-ignore-shaped

Do not paint shadows on shaped windows. Note shaped windows here means windows setting its shape through X Shape extension. Those using ARGB background is beyond our control. Deprecated, see the Window Rules section for the recommended way to set window-specific shadow.

--detect-rounded-corners

Try to detect windows with rounded corners and don’t consider them shaped windows. The accuracy is not very high, unfortunately.

--detect-client-opacity

Detect _NET_WM_WINDOW_OPACITY on client windows, useful for window managers not passing _NET_WM_WINDOW_OPACITY of client windows to frame windows.

--vsync,  --no-vsync

Enable/disable VSync.

--use-ewmh-active-win

Use EWMH _NET_ACTIVE_WINDOW to determine currently focused window, rather than listening to 'FocusIn'/'FocusOut' event. Might have more accuracy, provided that the WM supports it.

--unredir-if-possible

Unredirect all windows in some cases. Known to cause flickering when redirecting/unredirecting windows. Currently, unredirecting is triggered by following conditions:

• If the top level window is taking up the entire screen. In multi-monitor setup, this means ALL monitors.
• If there is no window.
• If a window is fullscreen according to its WM hints. (can be disabled with --no-ewmh-fullscreen).
• If a window requests to bypass the compositor (_NET_WM_BYPASS_COMPOSITOR). Windows are also unredirected unconditionally when monitors are powered off, regardless if --unredir-if-possible is set.

--unredir-if-possible-delay MILLISECONDS

Delay before unredirecting the window, in milliseconds. Defaults to 0.

--unredir-if-possible-exclude CONDITION

Conditions of windows that shouldn’t be considered full-screen for unredirecting screen. Using this is discouraged, see the Window Rules section for the recommended way to set window-specific unredirect.

--shadow-exclude CONDITION

Specify a list of conditions of windows that should have no shadow. Using this is discouraged, see the Window Rules section for the recommended way to set window-specific shadow.

--clip-shadow-above CONDITION

Specify a list of conditions of windows that should have no shadow painted over, such as a dock window. Using this is discouraged, see the Window Rules section for the recommended way to set window-specific shadow clipping.

--fade-exclude CONDITION

Specify a list of conditions of windows that should not be faded. Using this is discouraged, see the Window Rules section for the recommended way to set window-specific fading.

--focus-exclude CONDITION

Specify a list of conditions of windows that should always be considered focused. Using this is discouraged, see the Window Rules section for the recommended way for doing this.

--inactive-dim-fixed

Use fixed inactive dim value, instead of adjusting according to window opacity.

--detect-transient

Use WM_TRANSIENT_FOR to group windows, and consider windows in the same group focused at the same time.

--detect-client-leader

Use WM_CLIENT_LEADER to group windows, and consider windows in the same group focused at the same time. This usually means windows from the same application will be considered focused or unfocused at the same time.WM_TRANSIENT_FOR has higher priority if --detect-transient is enabled, too.

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

Parameters for background blurring, see the Blur section for more information.

--blur-background

Blur background of semi-transparent / ARGB windows. Bad in performance, with driver-dependent behavior. The name of the switch may change without prior notifications.

--blur-background-frame

Blur background of windows when the window frame is not opaque.  Implies --blur-background. Bad in performance, with driver-dependent behavior. The name may change.

--blur-background-fixed

Use fixed blur strength rather than adjusting according to window opacity.

--blur-kern MATRIX

Specify the blur convolution kernel, with the following format:

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

In other words, the matrix is formatted as a list of comma separated numbers. The first two numbers must be integers, which specify the width and height of the matrix. They must be odd numbers. Then, the following width * height - 1 numbers specifies the numbers in the matrix, row by row, excluding the center element.

The elements are finite floating point numbers. The decimal pointer has to be . (a period), scientific notation is not supported.

The element in the center will either be 1.0 or varying based on opacity, depending on whether you have --blur-background-fixed. Yet the automatic adjustment of blur factor may not work well with a custom blur kernel.

A 7x7 Gaussian blur kernel (sigma = 0.84089642) looks like:

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

May also be one of the predefined kernels: 3x3box (default), 5x5box, 7x7box, 3x3gaussian, 5x5gaussian, 7x7gaussian, 9x9gaussian, 11x11gaussian. All Gaussian kernels are generated with sigma = 0.84089642 . If you find yourself needing to generate custom blur kernels, you might want to try the new blur configuration (See Blur).

--blur-background-exclude CONDITION

Exclude conditions for background blur.

--resize-damage INTEGER

Resize damaged region by a specific number of pixels. A positive value enlarges it while a negative one shrinks it. If the value is positive, those additional pixels will not be actually painted to screen, only used in blur calculation, and such. (Due to technical limitations, with --use-damage, those pixels will still be incorrectly painted to screen.) Primarily used to fix the line corruption issues of blur, in which case you should use the blur radius value here (e.g. with a 3x3 kernel, you should use --resize-damage 1, with a 5x5 one you use --resize-damage 2, and so on). May or may not work with --glx-no-stencil. Only works with --legacy-backends. Shrinking doesn’t function correctly.

--invert-color-include CONDITION

Specify a list of conditions of windows that should be painted with inverted color. Resource-hogging, and is not well tested. Using this is discouraged, see the Window Rules section for the recommended way to do this.

--opacity-rule OPACITY:CONDITION

Specify a list of opacity rules, in the format PERCENT:PATTERN, like 50:name *= "Firefox". picom-trans is recommended over this. Note we don’t make any guarantee about possible conflicts with other programs that set _NET_WM_WINDOW_OPACITY on frame or client windows. Using this is discouraged, see the Window Rules section for the recommended way to set window-specific opacity.

--crop-shadow-to-monitor

Crop shadow of a window fully on a particular monitor to that monitor. This is currently implemented using the X RandR extension.

--backend BACKEND

Specify the backend to use: xrender, glx, or xr_glx_hybrid. xrender is the default one.

• xrender backend performs all rendering operations with X Render extension. It is what xcompmgr uses, and is generally a safe fallback when you encounter rendering artifacts or instability.
• glx (OpenGL) backend performs all rendering operations with OpenGL. It is more friendly to some VSync methods, and has significantly superior performance on color inversion (--invert-color-include) or blur (--blur-background). It requires proper OpenGL 2.0 support from your driver and hardware. You may wish to look at the GLX performance optimization options below. --xrender-sync-fence might be needed on some systems to avoid delay in changes of screen contents.
• xr_glx_hybrid backend renders the updated screen contents with X Render and presents it on the screen with GLX. It attempts to address the rendering issues some users encountered with GLX backend and enables the better VSync of GLX backends. --vsync-use-glfinish might fix some rendering issues with this backend.

--glx-no-stencil

GLX backend: Avoid using stencil buffer, useful if you don’t have a stencil buffer. Might cause incorrect opacity when rendering transparent content (but never practically happened) and may not work with --blur-background. My tests show a 15% performance boost. Recommended.

--glx-no-rebind-pixmap

GLX backend: Avoid rebinding pixmap on window damage. Probably could improve performance on rapid window content changes, but is known to break things on some drivers (LLVMpipe, xf86-video-intel, etc.). Recommended if it works.

--no-use-damage

Disable the use of damage information. This cause the whole screen to be redrawn every time, instead of the part of the screen has actually changed. Potentially degrades the performance, but might fix some artifacts.

--xrender-sync-fence

Use X Sync fence to sync clients' draw calls, to make sure all draw calls are finished before picom starts drawing. Needed on nvidia-drivers with GLX backend for some users.

--glx-fshader-win SHADER

GLX backend: Use specified GLSL fragment shader for rendering window contents. See compton-default-fshader-win.glsl and compton-fake-transparency-fshader-win.glsl in the source tree for examples. Only works with --legacy-backends enabled.

--force-win-blend

Force all windows to be painted with blending. Useful if you have a --glx-fshader-win that could turn opaque pixels transparent.

--dbus

Enable remote control via D-Bus. See the D-Bus API section below for more details.

--benchmark CYCLES

Benchmark mode. Repeatedly paint until reaching the specified cycles.

--benchmark-wid WINDOW_ID

Specify window ID to repaint in benchmark mode. If omitted or is 0, the whole screen is repainted.

--no-ewmh-fullscreen

Do not use EWMH to detect fullscreen windows. Reverts to checking if a window is fullscreen based only on its size and coordinates.

--max-brightness

Dimming bright windows so their brightness doesn’t exceed this set value. Brightness of a window is estimated by averaging all pixels in the window, so this could comes with a performance hit. Setting this to 1.0 disables this behaviour. Requires --use-damage to be disabled. (default: 1.0)

--transparent-clipping

Make transparent windows clip other windows like non-transparent windows do, instead of blending on top of them.

--transparent-clipping-exclude CONDITION

Specify a list of conditions of windows that should never have transparent clipping applied. Useful for screenshot tools, where you need to be able to see through transparent parts of the window.

--window-shader-fg SHADER

Specify GLSL fragment shader path for rendering window contents. Does not work when --legacy-backends is enabled. Shader is searched first relative to the directory the configuration file is in, then in the usual places for a configuration file. See section Shader Interface below for more details on the interface.

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

Specify GLSL fragment shader path for rendering window contents using patterns. Similar to --opacity-rule, arguments should be in the format of SHADER:CONDITION, e.g. "shader.frag:name = 'window'". Leading and trailing whitespaces in SHADER will be trimmed. If SHADER is "default", then the default shader will be used for the matching windows. (This also unfortunately means you can’t use a shader file named "default"). Does not work when --legacy-backends is enabled. Using this is discouraged, see the Window Rules section for the recommended way to set window-specific shaders.

--dithered-present

Use higher precision during rendering, and apply dither when presenting the rendered screen. Reduces banding artifacts, but might cause performance degradation. Only works with OpenGL.

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; },
)

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

is either a predefined target name, or the name of a window property to match.

Supported predefined targets are:

x, y, x2, y2

Window coordinates, from the top-left corner of the window (x, y) to the bottom-right corner (x2, y2).

width, height

Size of the window.

widthb, heightb

Like width and height, but including the window border.

border_width

Width of the window border.

fullscreen

Whether the window is fullscreen. If --no-ewmh-fullscreen is set, this is determined by the window size and position; otherwise, it is determined by the _NET_WM_STATE_FULLSCREEN property.

override_redirect

Whether the window is override-redirect.

argb

Whether the window has an ARGB visual.

focused

Whether the window is focused.

group_focused

Whether the window is in the same window group as the focused window. This requires --detect-transient or --detect-client-leader.

wmwin

Whether the window looks like a WM window, i.e. has no client window and is not override-redirected.

bounding_shaped

Whether the window has a bounding shape.

rounded_corners

Whether the window bounding shape only has rounded corners, and is otherwise rectangular. This implies bounding_shaped. Requires --detect-rounded-corners. This has no relation to --corner-radius VALUE.

window_type

Window type, as defined by _NET_WM_WINDOW_TYPE. Name only, e.g. normal means _NET_WM_WINDOW_TYPE_NORMAL. Because a window can have multiple types, testing for equality succeeds if any of the window’s types match.

name

Name of the window. This is either _NET_WM_NAME or _WM_NAME.

class_i, class_g

Instance and general class of the window. This is the first and second value of _WM_CLASS, respectively.

role

Window role. This is the value of _WM_WINDOW_ROLE.

Target can be followed by an optional @ if the window attribute should be be looked up on client window. Otherwise the frame window will be used.

Index

is the index number of the property to look up. For example, [2] returns the third value of 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. None of the predefined targets have multiple values, so do not use this with them.

Operator and Pattern

define how Target will be matched. They can be omitted together, in which case the existence of the window property is checked when Target is not a predefined target; for a predefined Target, omitting Operator and Pattern is equivalent to writing != 0.

Available operators change depends on the type of Target being matched. If the target is a number, the operators are =, >, <, >=, <=, as well as their negation, obtained by prefixing the operator with ! (e.g. !=, !>, etc.). If the target is a string, the operators are = (strict equal), *= (substring match), ^= (starts with), %= (match with glob), ~= (match with regex), as well as their case insensitive variants ?=, *?=, ^?=, %?=, ~?=. String operators can be negated by prefixing the operator with ! as well (e.g. !=, !*=, etc.).

Pattern is either an integer or a string enclosed by single or double quotes. Python-3-style escape sequences are supported for strings. Boolean values are interpreted as integers, i.e. writing true is equivalent to 1, and false 0.

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

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;
        };
}, ...)

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.

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:

fade, shadow

Controls window-type-specific shadow and fade settings.

opacity

Controls default opacity of the window type.

focus

Controls whether the window of this type is to be always considered focused. (By default, all window types except "normal" and "dialog" has this on.)

blur-background

Controls whether the window of this type will have its transparent background blurred.

full-shadow

Controls whether shadow is drawn under the parts of the window that you normally won’t be able to see. Useful when the window has parts of it transparent, and you want shadows in those areas.

clip-shadow-above

Controls whether shadows that would have been drawn above the window should be clipped. Useful for dock windows that should have no shadow painted on top.

redir-ignore

Controls whether this type of windows should cause screen to become redirected again after been unredirected. If you have --unredir-if-possible set, and doesn’t want certain window to cause unnecessary screen redirection, you can set this to true.

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:

method

A string. Controls the blur method. Corresponds to the --blur-method command line option. Available choices are: none to disable blurring; gaussian for gaussian blur; box for box blur; kernel for convolution blur with a custom kernel; dual_kawase for dual-filter kawase blur. Note: gaussian, box and dual_kawase blur methods are not supported by the legacy backends. (default: none)

size

An integer. The size of the blur kernel, required by gaussian and box blur methods. For the kernel method, the size is included in the kernel. Corresponds to the --blur-size command line option (default: 3).

deviation

A floating point number. The standard deviation for the gaussian blur method. Corresponds to the --blur-deviation command line option (default: 0.84089642).

strength

An integer in the range 0-20. The strength of the dual_kawase blur method. Corresponds to the --blur-strength command line option. If set to zero, the value requested by --blur-size is approximated (default: 5).

kernel

A string. The kernel to use for the kernel blur method, specified in the same format as the --blur-kern option. Corresponds to the --blur-kern command line option.

• picom reinitializes itself upon receiving SIGUSR1.

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.

• Disable configuration file parsing:

  $ picom --config /dev/null

• Run picom with client-side shadow and fading:

  $ picom -cf

• Same thing as above, plus making inactive windows 80% transparent, making frame 80% transparent, don’t fade on window open/close, and fork to background:

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

• Draw white shadows:

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

• Avoid drawing shadows on wbar window:

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

• Enable VSync with GLX backend:

  $ picom --backend glx --vsync

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

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

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

xcompmgr(1), picom-inspect(1), picom-trans(1)

Yuxuan Shui

configuration.nix(5), icewm(1), picom-inspect(1), picom-trans(1).