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.
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.
Opacity of inactive windows. (0.1 - 1.0, defaults to 1.0). Using this option is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific opacity.
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.
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.
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.
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.
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.
Let inactive opacity set by *-i* override the __NET_WM_WINDOW_OPACITY_ values of windows. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific opacity.
Default opacity for active windows. (0.0 - 1.0, defaults to 1.0). Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific opacity.
Dim inactive windows. (0.0 - 1.0, defaults to 0.0). Using this option is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific dim levels.
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).
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 xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific corner radius.
Exclude conditions for rounded corners. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific corner radius.
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.
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 xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific rules.
Mark override-redirect windows that doesn't have a child window with _WM_STATE_ focused. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific rules.
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 xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific shadow.
Detect _pass:[_]NET_WM_WINDOW_OPACITY_ on client windows, useful for window managers not passing _pass:[_]NET_WM_WINDOW_OPACITY_ of client windows to frame windows.
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.
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*).
Conditions of windows that shouldn't be considered full-screen for unredirecting screen. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific unredirect.
Specify a list of conditions of windows that should have no shadow. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific shadow.
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 xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific shadow clipping.
Specify a list of conditions of windows that should not be faded. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific fading.
Specify a list of conditions of windows that should always be considered focused. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way for doing this.
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 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.
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 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.
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*).
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.
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 xref:_window_rules[*WINDOW RULES*] section for the recommended way to do this.
Specify a list of opacity rules, in the format `PERCENT:PATTERN`, like `50:name pass:[*]= "Firefox"`. picom-trans is recommended over this. Note we don't make any guarantee about possible conflicts with other programs that set _pass:[_]NET_WM_WINDOW_OPACITY_ on frame or client windows. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific opacity.
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 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 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.
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.
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 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.
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)
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.
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.
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 xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific shaders.
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*, *--inactive-opacity*, *--active-opacity*, *--inactive-opacity-override*, *--inactive-dim*, *--mark-wmwin-focused*, *--mark-ovredir-focused*, *--invert-color-include*, *--shadow-exclude*, *--fade-exclude*, *--focus-exclude*, *--rounded-corners-exclude*, *--blur-background-exclude*, *--opacity-rule*, *--corner-radius-rules*, *--window-shader-fg-rule*, *--clip-shadow-above*. 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.
If you are currently using some of these options and want to switch to window rules, see the xref:_migrating_old_rules[*Migrating old rules*] section for how to convert them.
=== Syntax
Window rules are only available in the configuration file. To set window rules, set the `rules` option in the configuration file to something like this:
[listing]
rules = (
{ match = "focused"; opacity = 1; },
{ match = "name = 'firefox'"; shadow = true; },
# ... and so on
)
`rules = ( ... )` sets the option to a list, which can contain multiple sub-items. For `rules`, each sub-item must be a group (i.e. `{ key = value; ... }`), representing a condition and a set of options to apply when the condition is met. These sub-items are matched in the order they appear in the configuration file, options are applied as the conditions are matched. If the same option is set multiple times, the last one will take effect.
Within each sub-item, these keys are available: ::
match:::
The condition string to match windows with. See the xref:_format_of_conditions[*FORMAT OF CONDITIONS*] section below for the syntax of condition strings. If not specified, the rule will always match.
shadow:::
Whether to draw shadow under the matching window.
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.
fade:::
Whether to fade the matching window in/out when opening/closing it.
opacity:::
Opacity of the matching window. (0.0 - 1.0). If not explicitly set by a rule, the opacity value from the window properties (e.g. pass:[_]NET_WM_WINDOW_OPACITY) will be used.
dim:::
Dim level of the matching window. Larger value means more dimming. (0.0 - 1.0)
corner-radius:::
Corner radius of the matching window in number of pixels. 0 means no corner rounding.
blur-background:::
Whether to the background of the matching window should be blurred.
invert-color:::
Whether to invert the color of the matching window.
clip-shadow-above:::
Whether to prevent the matching window from being painted over by shadows.
unredir:::
Whether the matching window should cause the compositor to unredirect the screen, and whether it should trigger the screen to be redirected again if it is currently unredirected. This could be a boolean value, if _true_, the screen will be unredirected if the matching window meets certain conditions; if _false_, it will never cause the screen to be unredirected. If the screen is currently unredirected, and there is no other window that will trigger unredirection, both of these choices will cause the screen to be redirected again. To control that behavior as well, you can set `unredir` to either _preferred_, such windows will not cause the screen to be redirected in this situation, and will behave like `true` otherwise; or _passive_, which not only won't cause redirection in this case, but also won't actively cause the screen to be unredirected. The last possible value for this option is _forced_, any of the windows having their `unredir` set to `forced` will cause the screen to be unredirected unconditionally. The value of the _pass:[_]NET_WM_BYPASS_COMPOSITOR_ property on the window will be considered iff `unredir` is not explicitly set by any rule.
transparent-clipping:::
Whether to make the matching window clip other windows like opaque windows do, instead of blending on top of them. When applied to transparent windows, this means nothing will be painted under the transparent parts of the window, essentially cuts a hole in the screen.
shader:::
GLSL fragment shader path for rendering window contents. See section *SHADER INTERFACE* below for more details on the interface.
=== Migrating old rules
Most of the rule options should 1:1 map to the new window rules. Here is a list of the non-trivial ones and how to achieve the same effect with window rules.
*Inactive dimming and opacity*:: This includes options *--inactive-opacity*, *--inactive-dim*, *--active-opacity*,
*--inactive-opacity-override*, *--mark-wmwin-focused*, and *--mark-ovredir-focused*. When using the window rules, the compositor no longer have an "active window" concept, as it is easy to achieve with window rules. You can use `match = "focused || group_focused"` to match windows that would have been considered active with the old options. Then you can set the opacity and dim level for matched windows accordingly. *--mark-wmwin-focused* and *--mark-ovredir-focused* can be achieved by adding `|| wmmin` and `|| override_redirect` to the match string, respectively. *--inactive-opacity-override* can be achieved by setting `opacity-override = true`.
*Active window*:: This includes option *--focus-exclude*. The *--focus-exclude* was only used to influence what windows are considered active, to apply inactive opacity and dimming. Since with window rules you no longer need the compositor to help you decide what is active and what is not (see above), the *--focus-exclude* option is no longer needed.
Concretely speaking, a condition is a sequence of one or more simple pattern matching __Item__s, 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.
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 _pass:[_]NET_WM_STATE_FULLSCREEN_ property.
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*.
`window_type`::::
Window type, as defined by _pass:[_]NET_WM_WINDOW_TYPE_. Name only, e.g. _normal_ means _pass:[_]NET_WM_WINDOW_TYPE_NORMAL_.
`name`::::
Name of the window. This is either _pass:[_]NET_WM_NAME_ or _pass:[_]WM_NAME_.
`class_i`, `class_g`::::
Instance and general class of the window. This is the first and second value of _pass:[_]WM_CLASS_, respectively.
`role`::::
Window role. This is the value of _pass:[_]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 `=`, `>`, `<`, `>=`, `pass:[<=]`, 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), `pass:[*]=` (substring match), `^=` (starts with), `%=` (match with glob), `~=` (match with regex), as well as their case insensitive variants `?=`, `pass:[*]?=`, `^?=`, `%?=`, `~?=`. String operators can be negated by prefixing the operator with `!` as well (e.g. `!=`, `!pass:[*]=`, 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`.
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'.
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.
Window-type-specific settings allow you to set window-specific options based on the window type. These settings are exposed only in configuration file. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific options. The format of this option is as follows:
_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".
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.
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.
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`.
_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.
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).
A floating point number. The standard deviation for the _gaussian_ blur method. Corresponds to the *--blur-deviation* command line option (default: 0.84089642).
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).
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.
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.
* 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:
