'\" t
.\"     Title: picom
.\"    Author: Yuxuan Shui
.\" Generator: Asciidoctor 2.0.23
.\"      Date: 2024-10-16
.\"    Manual: User Commands
.\"    Source: picom
.\"  Language: English
.\"
.TH "PICOM" "1" "2024-10-16" "picom" "User Commands"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
picom \- a compositor for X11
.SH "SYNOPSIS"
.sp
\fBpicom\fP [\fIOPTIONS\fP]
.SH "DESCRIPTION"
.sp
picom is a compositor based on Dana Jansens\*(Aq 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.
.SH "OPTIONS"
.sp
\fB\-h\fP, \fB\-\-help\fP
.RS 4
Get the usage text embedded in program code, which may be more up\-to\-date than this man page.
.RE
.sp
\fB\-r\fP, \fB\-\-shadow\-radius\fP=\fIRADIUS\fP
.RS 4
The blur radius for shadows, in pixels. (defaults to 12)
.RE
.sp
\fB\-o\fP, \fB\-\-shadow\-opacity\fP=\fIOPACITY\fP
.RS 4
The opacity of shadows. (0.0 \- 1.0, defaults to 0.75)
.RE
.sp
\fB\-l\fP, \fB\-\-shadow\-offset\-x\fP=\fIOFFSET\fP
.RS 4
The left offset for shadows, in pixels. (defaults to \-15)
.RE
.sp
\fB\-t\fP, \fB\-\-shadow\-offset\-y\fP=\fIOFFSET\fP
.RS 4
The top offset for shadows, in pixels. (defaults to \-15)
.RE
.sp
\fB\-I\fP, \fB\-\-fade\-in\-step\fP=\fIOPACITY_STEP\fP
.RS 4
Opacity change between steps while fading in. (0.01 \- 1.0, defaults to 0.028)
.RE
.sp
\fB\-O\fP, \fB\-\-fade\-out\-step\fP=\fIOPACITY_STEP\fP
.RS 4
Opacity change between steps while fading out. (0.01 \- 1.0, defaults to 0.03)
.RE
.sp
\fB\-D\fP, \fB\-\-fade\-delta\fP=\fIMILLISECONDS\fP
.RS 4
The time between steps in fade step, in milliseconds. (> 0, defaults to 10)
.RE
.sp
\fB\-c\fP, \fB\-\-shadow\fP
.RS 4
Enabled client\-side shadows on windows. Note desktop windows (windows with \fI_NET_WM_WINDOW_TYPE_DESKTOP\fP) never get shadow, unless explicitly requested using the wintypes option.
.RE
.sp
\fB\-f\fP, \fB\-\-fading\fP
.RS 4
Fade windows in/out when opening/closing and when opacity changes, unless \fB\-\-no\-fading\-openclose\fP is used.
.RE
.sp
\fB\-i\fP, \fB\-\-inactive\-opacity\fP=\fIOPACITY\fP
.RS 4
Opacity of inactive windows. (0.1 \- 1.0, defaults to 1.0). Using this option is discouraged, see the \fBWINDOW RULES\fP section for the recommended way to set window\-specific opacity.
.RE
.sp
\fB\-e\fP, \fB\-\-frame\-opacity\fP=\fIOPACITY\fP
.RS 4
Opacity of window titlebars and borders. (0.1 \- 1.0, disabled by default)
.RE
.sp
\fB\-b\fP, \fB\-\-daemon\fP
.RS 4
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.
.RE
.sp
\fB\-\-log\-level\fP
.RS 4
Set the log level. Possible values are "TRACE", "DEBUG", "INFO", "WARN", "ERROR", in increasing level of importance. Case doesn\(cqt matter. If using the "TRACE" log level, it\(cqs better to log into a file using \fB\-\-log\-file\fP, since it can generate a huge stream of logs.
.RE
.sp
\fB\-\-log\-file\fP
.RS 4
Set the log file. If \fB\-\-log\-file\fP 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.
.RE
.sp
\fB\-\-legacy\-backends\fP
.RS 4
Use the old version of the backends. This option can not be set from the config file.
.RE
.sp
\fB\-\-show\-all\-xerrors\fP
.RS 4
Show all X errors (for debugging).
.RE
.sp
\fB\-\-config\fP \fIPATH\fP
.RS 4
Look for configuration file at the path. See \fBCONFIGURATION FILES\fP section below for where picom looks for a configuration file by default. Use \f(CR/dev/null\fP to avoid loading configuration file.
.RE
.sp
\fB\-\-write\-pid\-path\fP \fIPATH\fP
.RS 4
Write process ID to a file. it is recommended to use an absolute path.
.RE
.sp
\fB\-\-plugins\fP \fIPATH\fP
.RS 4
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 \f(CR$XDG_CONFIG_HOME/picom/plugins\fP, then in \f(CR$XDG_CONFIG_DIRS/picom/plugins\fP. 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.
.RE
.sp
\fB\-\-shadow\-color\fP \fISTRING\fP
.RS 4
Color of shadow, as a hex string (e.g. \fI#000000\fP)
.RE
.sp
\fB\-\-shadow\-red\fP \fIVALUE\fP
.RS 4
Red color value of shadow (0.0 \- 1.0, defaults to 0).
.RE
.sp
\fB\-\-shadow\-green\fP \fIVALUE\fP
.RS 4
Green color value of shadow (0.0 \- 1.0, defaults to 0).
.RE
.sp
\fB\-\-shadow\-blue\fP \fIVALUE\fP
.RS 4
Blue color value of shadow (0.0 \- 1.0, defaults to 0).
.RE
.sp
\fB\-\-inactive\-opacity\-override\fP
.RS 4
Let inactive opacity set by \fB\-i\fP override the \fI_NET_WM_WINDOW_OPACITY\fP values of windows. Using this is discouraged, see the \fBWINDOW RULES\fP section for the recommended way to set window\-specific opacity.
.RE
.sp
\fB\-\-active\-opacity\fP \fIOPACITY\fP
.RS 4
Default opacity for active windows. (0.0 \- 1.0, defaults to 1.0). Using this is discouraged, see the \fBWINDOW RULES\fP section for the recommended way to set window\-specific opacity.
.RE
.sp
\fB\-\-inactive\-dim\fP \fIVALUE\fP
.RS 4
Dim inactive windows. (0.0 \- 1.0, defaults to 0.0). Using this option is discouraged, see the \fBWINDOW RULES\fP section for the recommended way to set window\-specific dim levels.
.RE
.sp
\fB\-\-corner\-radius\fP \fIVALUE\fP
.RS 4
Sets the radius of rounded window corners. When > 0, the compositor will round the corners of windows. Does not interact well with \fB\-\-transparent\-clipping\fP. (defaults to 0).
.RE
.sp
\fB\-\-corner\-radius\-rules\fP \fIRADIUS\fP:\fICONDITION\fP
.RS 4
Specify a list of corner radius rules. Overrides the corner radii of matching windows. This option takes precedence over the \fB\-\-rounded\-corners\-exclude\fP option, and also overrides the default exclusion of fullscreen windows. The condition has the same format as \fB\-\-opacity\-rule\fP. Using this is discouraged, see the \fBWINDOW RULES\fP section for the recommended way to set window\-specific corner radius.
.RE
.sp
\fB\-\-rounded\-corners\-exclude\fP \fICONDITION\fP
.RS 4
Exclude conditions for rounded corners. Using this is discouraged, see the \fBWINDOW RULES\fP section for the recommended way to set window\-specific corner radius.
.RE
.sp
\fB\-\-no\-frame\-pacing\fP
.RS 4
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.
.RE
.sp
\fB\-\-mark\-wmwin\-focused\fP
.RS 4
Try to detect WM windows (a non\-override\-redirect window with no child that has \fIWM_STATE\fP) and mark them as active. Using this is discouraged, see the \fBWINDOW RULES\fP section for the recommended way to set window\-specific rules.
.RE
.sp
\fB\-\-mark\-ovredir\-focused\fP
.RS 4
Mark override\-redirect windows that doesn\(cqt have a child window with \fIWM_STATE\fP focused. Using this is discouraged, see the \fBWINDOW RULES\fP section for the recommended way to set window\-specific rules.
.RE
.sp
\fB\-\-no\-fading\-openclose\fP
.RS 4
Do not fade on window open/close.
.RE
.sp
\fB\-\-no\-fading\-destroyed\-argb\fP
.RS 4
Do not fade destroyed ARGB windows with WM frame. Workaround of bugs in Openbox, Fluxbox, etc.
.RE
.sp
\fB\-\-shadow\-ignore\-shaped\fP
.RS 4
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 \fBWINDOW RULES\fP section for the recommended way to set window\-specific shadow.
.RE
.sp
\fB\-\-detect\-rounded\-corners\fP
.RS 4
Try to detect windows with rounded corners and don\(cqt consider them shaped windows. The accuracy is not very high, unfortunately.
.RE
.sp
\fB\-\-detect\-client\-opacity\fP
.RS 4
Detect \fI_NET_WM_WINDOW_OPACITY\fP on client windows, useful for window managers not passing \fI_NET_WM_WINDOW_OPACITY\fP of client windows to frame windows.
.RE
.sp
\fB\-\-vsync\fP, \fB\-\-no\-vsync\fP
.RS 4
Enable/disable VSync.
.RE
.sp
\fB\-\-use\-ewmh\-active\-win\fP
.RS 4
Use EWMH \fI_NET_ACTIVE_WINDOW\fP to determine currently focused window, rather than listening to \*(AqFocusIn\*(Aq/\*(AqFocusOut\*(Aq event. Might have more accuracy, provided that the WM supports it.
.RE
.sp
\fB\-\-unredir\-if\-possible\fP
.RS 4
Unredirect all windows in some cases. Known to cause flickering when redirecting/unredirecting windows. Currently, unredirecting is triggered by following conditions:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
If the top level window is taking up the entire screen. In multi\-monitor setup, this means ALL monitors.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
If there is no window.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
If a window is fullscreen according to its WM hints. (can be disabled with \fB\-\-no\-ewmh\-fullscreen\fP).
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
If a window requests to bypass the compositor (\fI_NET_WM_BYPASS_COMPOSITOR\fP).
Windows are also unredirected unconditionally when monitors are powered off, regardless if \fB\-\-unredir\-if\-possible\fP is set.
.RE
.RE
.sp
\fB\-\-unredir\-if\-possible\-delay\fP \fIMILLISECONDS\fP
.RS 4
Delay before unredirecting the window, in milliseconds. Defaults to 0.
.RE
.sp
\fB\-\-unredir\-if\-possible\-exclude\fP \fICONDITION\fP
.RS 4
Conditions of windows that shouldn\(cqt be considered full\-screen for unredirecting screen. Using this is discouraged, see the \fBWINDOW RULES\fP section for the recommended way to set window\-specific unredirect.
.RE
.sp
\fB\-\-shadow\-exclude\fP \fICONDITION\fP
.RS 4
Specify a list of conditions of windows that should have no shadow. Using this is discouraged, see the \fBWINDOW RULES\fP section for the recommended way to set window\-specific shadow.
.RE
.sp
\fB\-\-clip\-shadow\-above\fP \fICONDITION\fP
.RS 4
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 \fBWINDOW RULES\fP section for the recommended way to set window\-specific shadow clipping.
.RE
.sp
\fB\-\-fade\-exclude\fP \fICONDITION\fP
.RS 4
Specify a list of conditions of windows that should not be faded. Using this is discouraged, see the \fBWINDOW RULES\fP section for the recommended way to set window\-specific fading.
.RE
.sp
\fB\-\-focus\-exclude\fP \fICONDITION\fP
.RS 4
Specify a list of conditions of windows that should always be considered focused. Using this is discouraged, see the \fBWINDOW RULES\fP section for the recommended way for doing this.
.RE
.sp
\fB\-\-inactive\-dim\-fixed\fP
.RS 4
Use fixed inactive dim value, instead of adjusting according to window opacity.
.RE
.sp
\fB\-\-detect\-transient\fP
.RS 4
Use \fIWM_TRANSIENT_FOR\fP to group windows, and consider windows in the same group focused at the same time.
.RE
.sp
\fB\-\-detect\-client\-leader\fP
.RS 4
Use \fIWM_CLIENT_LEADER\fP 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.\fIWM_TRANSIENT_FOR\fP has higher priority if \fB\-\-detect\-transient\fP is enabled, too.
.RE
.sp
\fB\-\-blur\-method\fP, \fB\-\-blur\-size\fP, \fB\-\-blur\-deviation\fP, \fB\-\-blur\-strength\fP
.RS 4
Parameters for background blurring, see the \fBBLUR\fP section for more information.
.RE
.sp
\fB\-\-blur\-background\fP
.RS 4
Blur background of semi\-transparent / ARGB windows. Bad in performance, with driver\-dependent behavior. The name of the switch may change without prior notifications.
.RE
.sp
\fB\-\-blur\-background\-frame\fP
.RS 4
Blur background of windows when the window frame is not opaque.  Implies \fB\-\-blur\-background\fP. Bad in performance, with driver\-dependent behavior. The name may change.
.RE
.sp
\fB\-\-blur\-background\-fixed\fP
.RS 4
Use fixed blur strength rather than adjusting according to window opacity.
.RE
.sp
\fB\-\-blur\-kern\fP \fIMATRIX\fP
.RS 4
Specify the blur convolution kernel, with the following format:
.sp
.if n .RS 4
.nf
.fam C
WIDTH,HEIGHT,ELE1,ELE2,ELE3,ELE4,ELE5...
.fam
.fi
.if n .RE
.sp
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 \f(CRwidth * height \- 1\fP numbers specifies the numbers in the matrix, row by row, excluding the center element.
.sp
The elements are finite floating point numbers. The decimal pointer has to be \fI.\fP (a period), scientific notation is not supported.
.sp
The element in the center will either be 1.0 or varying based on opacity, depending on whether you have \fB\-\-blur\-background\-fixed\fP. Yet the automatic adjustment of blur factor may not work well with a custom blur kernel.
.sp
A 7x7 Gaussian blur kernel (sigma = 0.84089642) looks like:
.sp
.if n .RS 4
.nf
.fam C
\-\-blur\-kern \*(Aq7,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\*(Aq
.fam
.fi
.if n .RE
.sp
May also be one of the predefined kernels: \f(CR3x3box\fP (default), \f(CR5x5box\fP, \f(CR7x7box\fP, \f(CR3x3gaussian\fP, \f(CR5x5gaussian\fP, \f(CR7x7gaussian\fP, \f(CR9x9gaussian\fP, \f(CR11x11gaussian\fP. 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 \fBBLUR\fP).
.RE
.sp
\fB\-\-blur\-background\-exclude\fP \fICONDITION\fP
.RS 4
Exclude conditions for background blur.
.RE
.sp
\fB\-\-resize\-damage\fP \fIINTEGER\fP
.RS 4
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 \fB\-\-use\-damage\fP, 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 \f(CR\-\-resize\-damage 1\fP, with a 5x5 one you use \f(CR\-\-resize\-damage 2\fP, and so on). May or may not work with \fB\-\-glx\-no\-stencil\fP. Only works with \fB\-\-legacy\-backends\fP. Shrinking doesn\(cqt function correctly.
.RE
.sp
\fB\-\-invert\-color\-include\fP \fICONDITION\fP
.RS 4
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 \fBWINDOW RULES\fP section for the recommended way to do this.
.RE
.sp
\fB\-\-opacity\-rule\fP \fIOPACITY\fP:\fICONDITION\fP
.RS 4
Specify a list of opacity rules, in the format \f(CRPERCENT:PATTERN\fP, like \f(CR50:name *= "Firefox"\fP. picom\-trans is recommended over this. Note we don\(cqt make any guarantee about possible conflicts with other programs that set \fI_NET_WM_WINDOW_OPACITY\fP on frame or client windows. Using this is discouraged, see the \fBWINDOW RULES\fP section for the recommended way to set window\-specific opacity.
.RE
.sp
\fB\-\-crop\-shadow\-to\-monitor\fP
.RS 4
Crop shadow of a window fully on a particular monitor to that monitor. This is currently implemented using the X RandR extension.
.RE
.sp
\fB\-\-backend\fP \fIBACKEND\fP
.RS 4
Specify the backend to use: \f(CRxrender\fP, \f(CRglx\fP, or \f(CRxr_glx_hybrid\fP. \f(CRxrender\fP is the default one.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRxrender\fP backend performs all rendering operations with X Render extension. It is what \f(CRxcompmgr\fP uses, and is generally a safe fallback when you encounter rendering artifacts or instability.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRglx\fP (OpenGL) backend performs all rendering operations with OpenGL. It is more friendly to some VSync methods, and has significantly superior performance on color inversion (\fB\-\-invert\-color\-include\fP) or blur (\fB\-\-blur\-background\fP). It requires proper OpenGL 2.0 support from your driver and hardware. You may wish to look at the GLX performance optimization options below. \fB\-\-xrender\-sync\-fence\fP might be needed on some systems to avoid delay in changes of screen contents.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRxr_glx_hybrid\fP 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. \fB\-\-vsync\-use\-glfinish\fP might fix some rendering issues with this backend.
.RE
.RE
.sp
\fB\-\-glx\-no\-stencil\fP
.RS 4
GLX backend: Avoid using stencil buffer, useful if you don\(cqt have a stencil buffer. Might cause incorrect opacity when rendering transparent content (but never practically happened) and may not work with \fB\-\-blur\-background\fP. My tests show a 15% performance boost. Recommended.
.RE
.sp
\fB\-\-glx\-no\-rebind\-pixmap\fP
.RS 4
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.
.RE
.sp
\fB\-\-no\-use\-damage\fP
.RS 4
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.
.RE
.sp
\fB\-\-xrender\-sync\-fence\fP
.RS 4
Use X Sync fence to sync clients\*(Aq draw calls, to make sure all draw calls are finished before picom starts drawing. Needed on nvidia\-drivers with GLX backend for some users.
.RE
.sp
\fB\-\-glx\-fshader\-win\fP \fISHADER\fP
.RS 4
GLX backend: Use specified GLSL fragment shader for rendering window contents. See \f(CRcompton\-default\-fshader\-win.glsl\fP and \f(CRcompton\-fake\-transparency\-fshader\-win.glsl\fP in the source tree for examples. Only works with \fB\-\-legacy\-backends\fP enabled.
.RE
.sp
\fB\-\-force\-win\-blend\fP
.RS 4
Force all windows to be painted with blending. Useful if you have a \fB\-\-glx\-fshader\-win\fP that could turn opaque pixels transparent.
.RE
.sp
\fB\-\-dbus\fP
.RS 4
Enable remote control via D\-Bus. See the \fBD\-BUS API\fP section below for more details.
.RE
.sp
\fB\-\-benchmark\fP \fICYCLES\fP
.RS 4
Benchmark mode. Repeatedly paint until reaching the specified cycles.
.RE
.sp
\fB\-\-benchmark\-wid\fP \fIWINDOW_ID\fP
.RS 4
Specify window ID to repaint in benchmark mode. If omitted or is 0, the whole screen is repainted.
.RE
.sp
\fB\-\-no\-ewmh\-fullscreen\fP
.RS 4
Do not use EWMH to detect fullscreen windows. Reverts to checking if a window is fullscreen based only on its size and coordinates.
.RE
.sp
\fB\-\-max\-brightness\fP
.RS 4
Dimming bright windows so their brightness doesn\(cqt 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 \fB\-\-use\-damage\fP to be disabled. (default: 1.0)
.RE
.sp
\fB\-\-transparent\-clipping\fP
.RS 4
Make transparent windows clip other windows like non\-transparent windows do, instead of blending on top of them.
.RE
.sp
\fB\-\-transparent\-clipping\-exclude\fP \fICONDITION\fP
.RS 4
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.
.RE
.sp
\fB\-\-window\-shader\-fg\fP \fISHADER\fP
.RS 4
Specify GLSL fragment shader path for rendering window contents. Does not work when \fB\-\-legacy\-backends\fP 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 \fBSHADER INTERFACE\fP below for more details on the interface.
.RE
.sp
\fB\-\-window\-shader\-fg\-rule\fP \fISHADER\fP:\fICONDITION\fP
.RS 4
Specify GLSL fragment shader path for rendering window contents using patterns. Similar to \fB\-\-opacity\-rule\fP, arguments should be in the format of \fISHADER:CONDITION\fP, e.g. "shader.frag:name = \*(Aqwindow\*(Aq". Leading and trailing whitespaces in \fISHADER\fP will be trimmed. If \fISHADER\fP is "default", then the default shader will be used for the matching windows. (This also unfortunately means you can\(cqt use a shader file named "default"). Does not work when \fB\-\-legacy\-backends\fP is enabled. Using this is discouraged, see the \fBWINDOW RULES\fP section for the recommended way to set window\-specific shaders.
.RE
.sp
\fB\-\-dithered\-present\fP
.RS 4
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.
.RE
.SH "WINDOW RULES"
.sp
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.
.sp
Following is a list of all the options that are superseded by window rules:
.sp
\fB\-\-shadow\-ignore\-shaped\fP, \fB\-i\fP, \fB\-\-inactive\-opacity\fP=\fIOPACITY\fP, \fB\-\-active\-opacity\fP \fIOPACITY\fP, \fB\-\-inactive\-opacity\-override\fP, \fB\-\-inactive\-dim\fP \fIVALUE\fP, \fB\-\-mark\-wmwin\-focused\fP, \fB\-\-mark\-ovredir\-focused\fP, \fB\-\-invert\-color\-include\fP \fICONDITION\fP, \fB\-\-shadow\-exclude\fP \fICONDITION\fP, \fB\-\-fade\-exclude\fP \fICONDITION\fP, \fB\-\-focus\-exclude\fP \fICONDITION\fP, \fB\-\-rounded\-corners\-exclude\fP \fICONDITION\fP, \fB\-\-blur\-background\-exclude\fP \fICONDITION\fP, \fB\-\-opacity\-rule\fP \fIOPACITY\fP:\fICONDITION\fP, \fB\-\-corner\-radius\-rules\fP \fIRADIUS\fP:\fICONDITION\fP, \fB\-\-window\-shader\-fg\-rule\fP \fISHADER\fP:\fICONDITION\fP, \fB\-\-clip\-shadow\-above\fP \fICONDITION\fP. As well as the \fBwintypes\fP configuration file option.
.sp
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.
.sp
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 \fBMigrating old rules\fP section for how to convert them.
.SS "Syntax"
.sp
Window rules are only available in the configuration file. To set window rules, set the \f(CRrules\fP option in the configuration file to something like this:
.sp
.if n .RS 4
.nf
.fam C
rules = (
        { match = "focused"; opacity = 1; },
        { match = "name = \*(Aqfirefox\*(Aq"; shadow = true; },
        # ... and so on
)
.fam
.fi
.if n .RE
.sp
\f(CRrules = ( ... )\fP sets the option to a list, which can contain multiple sub\-items. For \f(CRrules\fP, each sub\-item must be a group (i.e. \f(CR{ key = value; ... }\fP), 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.
.sp
Within each sub\-item, these keys are available:
.RS 4
.sp
match
.RS 4
The condition string to match windows with. See the \fBFORMAT OF CONDITIONS\fP section below for the syntax of condition strings. If not specified, the rule will always match.
.RE
.sp
shadow
.RS 4
Whether to draw shadow under the matching window.
.RE
.sp
full\-shadow
.RS 4
Controls whether shadow is drawn under the parts of the window that you normally won\(cqt be able to see. Useful when the window has parts of it transparent, and you want shadows in those areas.
.RE
.sp
fade
.RS 4
Whether to fade the matching window in/out when opening/closing it. When animations are used, this will have no effect. This can only be used to disable fading animations enabled by option \fB\-f\fP, \fB\-\-fading\fP.
.RE
.sp
opacity
.RS 4
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. _NET_WM_WINDOW_OPACITY) will be used.
.RE
.sp
dim
.RS 4
Dim level of the matching window. Larger value means more dimming. (0.0 \- 1.0)
.RE
.sp
corner\-radius
.RS 4
Corner radius of the matching window in number of pixels. 0 means no corner rounding.
.RE
.sp
blur\-background
.RS 4
Whether the background of the matching window should be blurred.
.RE
.sp
invert\-color
.RS 4
Whether to invert the color of the matching window.
.RE
.sp
clip\-shadow\-above
.RS 4
Whether to prevent the matching window from being painted over by shadows.
.RE
.sp
unredir
.RS 4
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 \fItrue\fP, the screen will be unredirected if the matching window meets certain conditions; if \fIfalse\fP, 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 \f(CRunredir\fP to either \fIpreferred\fP, such windows will not cause the screen to be redirected in this situation, and will behave like \f(CRtrue\fP otherwise; or \fIpassive\fP, which not only won\(cqt cause redirection in this case, but also won\(cqt actively cause the screen to be unredirected. The last possible value for this option is \fIforced\fP, any of the windows having their \f(CRunredir\fP set to \f(CRforced\fP will cause the screen to be unredirected unconditionally. The value of the \fI_NET_WM_BYPASS_COMPOSITOR\fP property on the window will be considered iff \f(CRunredir\fP is not explicitly set by any rule.
.RE
.sp
transparent\-clipping
.RS 4
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.
.RE
.sp
shader
.RS 4
GLSL fragment shader path for rendering window contents. See section \fBSHADER INTERFACE\fP below for more details on the interface.
.RE
.sp
animations
.RS 4
Define window\-specific animation scripts. The format of this option is the same as the top\-level \fIanimations\fP option. You can find more information in the \fBANIMATIONS\fP section. If animation scripts are defined in multiple matching rules, they will be merged together. If multiple matching rules contain animation scripts for the same trigger, the last one will take effect, the same as other options.
.RE
.RE
.SS "Migrating old rules"
.sp
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.
.sp
\fBInactive dimming and opacity\fP
.RS 4
This includes options \fB\-i\fP, \fB\-\-inactive\-opacity\fP=\fIOPACITY\fP, \fB\-\-inactive\-dim\fP \fIVALUE\fP, \fB\-\-active\-opacity\fP \fIOPACITY\fP,
\fB\-\-inactive\-opacity\-override\fP, \fB\-\-mark\-wmwin\-focused\fP, and \fB\-\-mark\-ovredir\-focused\fP. 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 \f(CRmatch = "focused || group_focused"\fP 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. \fB\-\-mark\-wmwin\-focused\fP and \fB\-\-mark\-ovredir\-focused\fP can be achieved by adding \f(CR|| wmwin\fP and \f(CR|| override_redirect\fP to the match string, respectively. \fB\-\-inactive\-opacity\-override\fP can be achieved by setting \f(CRopacity\-override = true\fP.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
Setting \fIopacity\fP explicitly with a rule will override the opacity value from the window properties (i.e. \fI_NET_WM_WINDOW_OPACITY\fP), which is used by tools like \f(CRpicom\-trans\fP for setting the opacity of window. If you would like to keep using tools like \f(CRpicom\-trans\fP, you can choose to set the opacity only for windows without the opacity property by matching \f(CR! _NET_WM_WINDOW_OPACITY\fP.
.sp .5v
.RE
.RE
.sp
\fBActive window\fP
.RS 4
This includes option \fB\-\-focus\-exclude\fP \fICONDITION\fP. This option 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), this option is no longer needed.
.RE
.sp
\fBRounded corners and fullscreen windows\fP
.RS 4
Rounded corners are no longer automatically disabled for fullscreen windows. If you want to disable rounded corners for fullscreen windows, you can use the following rule:
.sp
.if n .RS 4
.nf
.fam C
rules = (
        { match = "fullscreen"; corner\-radius = 0; },
)
.fam
.fi
.if n .RE
.RE
.SH "FORMAT OF CONDITIONS"
.sp
Some options accept a condition string to match certain windows. A condition string is formed by one or more conditions, joined by logical operators.
.sp
Formal grammar for a condition looks like this:
.sp
.if n .RS 4
.nf
.fam C
Condition <\- Term (\*(Aq||\*(Aq Term)*
Term <\- Item (\*(Aq&&\*(Aq Item)*
Item <\- \*(Aq!\*(Aq? Target \*(Aq@\*(Aq? (\*(Aq[\*(Aq Index \*(Aq]\*(Aq)? (Operator Pattern)? | \*(Aq(\*(Aq Condition \*(Aq)\*(Aq
.fam
.fi
.if n .RE
.sp
Concretely speaking, a condition is a sequence of one or more simple pattern matching \fIItem\fPs, joined by logical operators \f(CR&&\fP (and) and \f(CR||\fP (or). \f(CR&&\fP has higher precedence than \f(CR||\fP. Both operators are left\-associative. Parentheses can be used to raise precedence. If an \fIItem\fP has a leading negation operator (\f(CR!\fP), the result of the item is negated.
.sp
Inside an \fIItem\fP:
.sp
\fITarget\fP
.RS 4
is either a predefined target name, or the name of a window property to match.
.sp
Supported predefined targets are:
.RS 4
.sp
\f(CRx\fP, \f(CRy\fP, \f(CRx2\fP, \f(CRy2\fP
.RS 4
Window coordinates, from the top\-left corner of the window \f(CR(x, y)\fP to the bottom\-right corner \f(CR(x2, y2)\fP.
.RE
.sp
\f(CRwidth\fP, \f(CRheight\fP
.RS 4
Size of the window.
.RE
.sp
\f(CRwidthb\fP, \f(CRheightb\fP
.RS 4
Like \f(CRwidth\fP and \f(CRheight\fP, but including the window border.
.RE
.sp
\f(CRborder_width\fP
.RS 4
Width of the window border.
.RE
.sp
\f(CRfullscreen\fP
.RS 4
Whether the window is fullscreen. If \fB\-\-no\-ewmh\-fullscreen\fP is set, this is determined by the window size and position; otherwise, it is determined by the \fI_NET_WM_STATE_FULLSCREEN\fP property.
.RE
.sp
\f(CRoverride_redirect\fP
.RS 4
Whether the window is override\-redirect.
.RE
.sp
\f(CRargb\fP
.RS 4
Whether the window has an ARGB visual.
.RE
.sp
\f(CRfocused\fP
.RS 4
Whether the window is focused.
.RE
.sp
\f(CRgroup_focused\fP
.RS 4
Whether the window is in the same window group as the focused window. This requires \fB\-\-detect\-transient\fP or \fB\-\-detect\-client\-leader\fP.
.RE
.sp
\f(CRwmwin\fP
.RS 4
Whether the window looks like a WM window, i.e. has no client window and is not override\-redirected.
.RE
.sp
\f(CRbounding_shaped\fP
.RS 4
Whether the window has a bounding shape.
.RE
.sp
\f(CRrounded_corners\fP
.RS 4
Whether the window bounding shape only has rounded corners, and is otherwise rectangular. This implies \f(CRbounding_shaped\fP. Requires \fB\-\-detect\-rounded\-corners\fP. This has no relation to \fB\-\-corner\-radius\fP \fIVALUE\fP.
.RE
.sp
\f(CRwindow_type\fP
.RS 4
Window type, as defined by \fI_NET_WM_WINDOW_TYPE\fP. Name only, e.g. \fInormal\fP means \fI_NET_WM_WINDOW_TYPE_NORMAL\fP. Because a window can have multiple types, testing for equality succeeds if any of the window\(cqs types match.
.RE
.sp
\f(CRname\fP
.RS 4
Name of the window. This is either \fI_NET_WM_NAME\fP or \fI_WM_NAME\fP.
.RE
.sp
\f(CRclass_i\fP, \f(CRclass_g\fP
.RS 4
Instance and general class of the window. This is the first and second value of \fI_WM_CLASS\fP, respectively.
.RE
.sp
\f(CRrole\fP
.RS 4
Window role. This is the value of \fI_WM_WINDOW_ROLE\fP.
.RE
.RE
.sp
\fITarget\fP can be followed by an optional \f(CR@\fP if the window attribute should be be looked up on client window. Otherwise the frame window will be used.
.RE
.sp
\fIIndex\fP
.RS 4
is the index number of the property to look up. For example, \f(CR[2]\fP returns the third value of the property. If not specified, the first value (index \f(CR[0]\fP) is used implicitly. Use the special value \f(CR[*]\fP 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.
.RE
.sp
\fIOperator\fP and \fIPattern\fP
.RS 4
define how \fITarget\fP will be matched. They can be omitted together, in which case the existence of the window property is checked when \fITarget\fP is not a predefined target; for a predefined \fITarget\fP, omitting \fIOperator\fP and \fIPattern\fP is equivalent to writing \f(CR!= 0\fP.
.sp
Available operators change depends on the type of \fITarget\fP being matched. If the target is a number, the operators are \f(CR=\fP, \f(CR>\fP, \f(CR<\fP, \f(CR>=\fP, \f(CR<=\fP, as well as their negation, obtained by prefixing the operator with \f(CR!\fP (e.g. \f(CR!=\fP, \f(CR!>\fP, etc.). If the target is a string, the operators are \f(CR=\fP (strict equal), \f(CR*=\fP (substring match), \f(CR^=\fP (starts with), \f(CR%=\fP (match with glob), \f(CR~=\fP (match with regex), as well as their case insensitive variants \f(CR?=\fP, \f(CR*?=\fP, \f(CR^?=\fP, \f(CR%?=\fP, \f(CR~?=\fP. String operators can be negated by prefixing the operator with \f(CR!\fP as well (e.g. \f(CR!=\fP, \f(CR!*=\fP, etc.).
.sp
\fIPattern\fP 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 \f(CRtrue\fP is equivalent to \f(CR1\fP, and \f(CRfalse\fP \f(CR0\fP.
.RE
.sp
Examples:
.sp
.if n .RS 4
.nf
.fam C
# 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\*(Aqs 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 = "\(rsx64\(rsx64\(rso64"
# These two are equivalent
name = \*(AqFirefox\*(Aq || name = \*(AqChromium\*(Aq && class_i = \*(AqNavigator\*(Aq
name = \*(AqFirefox\*(Aq || (name = \*(AqChromium\*(Aq && class_i = \*(AqNavigator\*(Aq)
.fam
.fi
.if n .RE
.SH "ANIMATIONS"
.sp
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 \fIanimations\fP. It is also possible to define animations per\-window using the \fBWINDOW RULES\fP system, by setting the animations option in a rule. (Read the rest of this section first before you go there.)
.sp
The basic syntax of the \fIanimations\fP option is as follows:
.sp
.if n .RS 4
.nf
.fam C
animations = ({
        triggers = [ ... ];
        suppressions = [ ... ];

        # more options follow
        ...
}, {
        # another animation script
}, ...)
.fam
.fi
.if n .RE
.sp
\f(CRanimations = ( ... )\fP sets \fIanimations\fP 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. \f(CR{ key = value; ... }\fP). All animation scripts share some common options, like \fItriggers\fP and \fIsuppressions\fP, they also contain more options that either defines the actual animation, or selects an animation preset.
.SS "Common options"
.sp
\fItriggers\fP
.RS 4
A list of triggers specifying when this animation should be started. Each trigger can have at most one animation script associated to it, otherwise the behavior is undefined, and a warning will be issued.
.sp
Valid triggers are:
.RS 4
.sp
\fIopen\fP
.RS 4
When a window is opened.
.RE
.sp
\fIclose\fP
.RS 4
When a window is closed.
.RE
.sp
\fIshow\fP
.RS 4
When a minimized or iconified window is shown.
.RE
.sp
\fIhide\fP
.RS 4
When a window is minimized or iconified.
.RE
.sp
\fIincrease\-opacity\fP
.RS 4
When the opacity of a window is increased.
.RE
.sp
\fIdecrease\-opacity\fP
.RS 4
When the opacity of a window is decreased.
.RE
.sp
\fIgeometry\fP
.RS 4
When the geometry of a window is changed. (EXPERIMENTAL)
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Warning
.ps -1
.br
.sp
The \fIgeometry\fP trigger is experimental. Using this means you accept the caveat that geometry animations will also trigger when you manually resize or move a window, like when you drag the window around with your mouse.
.sp .5v
.RE
.RE
.RE
.RE
.sp
\fIsuppressions\fP
.RS 4
Which other animations should be suppressed when this animation is running. Normally, if another trigger is activated while an animation is already running, the animation in progress will be interrupted and the new animation will start. If you want to prevent this, you can set the \f(CRsuppressions\fP option to a list of triggers that should be suppressed. This is optional, the default value for this is an empty list.
.RE
.SS "Presets"
.sp
Defining an animation is a bit involved. To make animations more approachable, without you having to learn the nitty\-gritty details of the script system, picom provides a number of presets that you can use by just specifying a handful of options.
.sp
To choose a preset, add a \fIpreset\fP option to an animation script group, like this:
.sp
.if n .RS 4
.nf
.fam C
animations = ({
        triggers = [ "close", "hide" ];
        preset = "slide\-out";
        direction = "down";
        ...
}, ...)
.fam
.fi
.if n .RE
.sp
Some presets have additional options that you can set to customize the animation. In this example, the \fIslide\-out\fP preset has a \fIdirection\fP option specifying the direction of the sliding animation.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
Describing animations with only words is difficult. We have short video clips showing off each preset, but sadly they cannot be included in this manpage. The web version of this document hosted on our website at \c
.URL "https://picom.app" "" ""
on the other hand, does have those clips.
.sp .5v
.RE
.sp
The following presets are available:
.RS 4
.sp
\fIslide\-in\fP, \fIslide\-out\fP
.RS 4
.sp
Show/hide the window with a sliding animation.

.sp
\fBOptions\fP
.RS 4
.sp
\fIdirection\fP
.RS 4
The sliding direction, valid values are \fIup\fP, \fIdown\fP, \fIleft\fP, \fIright\fP.
.RE
.sp
\fIduration\fP
.RS 4
Duration of the animation in seconds. (Can be fractional).
.RE
.RE
.RE
.sp
\fIfly\-in\fP, \fIfly\-out\fP
.RS 4
.sp
Show/hide the window with a flying animation.

.sp
\fBOptions\fP
.RS 4
.sp
\fIdirection\fP
.RS 4
The flying direction, valid values are \fIup\fP, \fIdown\fP, \fIleft\fP, \fIright\fP.
.RE
.sp
\fIduration\fP
.RS 4
Duration of the animation in seconds.
.RE
.RE
.RE
.sp
\fIappear\fP, \fIdisappear\fP
.RS 4
.sp
Show/hide the window with a combination of scaling and fading.

.sp
\fBOptions\fP
.RS 4
.sp
\fIscale\fP
.RS 4
The scaling factor of the window, 1.0 means no scaling.
.RE
.sp
\fIduration\fP
.RS 4
Duration of the animation in seconds.
.RE
.RE
.RE
.sp
\fIgeometry\-change\fP
.RS 4
.sp
Animate the geometry (i.e. size and position) change of the window.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Warning
.ps -1
.br
.sp
This makes use of both the \fIgeometry\fP trigger, and the \fIsaved\-image\-blend\fP output variable. Both of these features are experimental and may not work as expected.
.sp .5v
.RE

.sp
\fBOptions\fP
.RS 4
.sp
\fIduration\fP
.RS 4
Duration of the animation in seconds.
.RE
.RE
.RE
.RE
.SS "Advanced"
.sp
If the existing presets don\(cqt meet your needs, it is always possible to define your own animations. To put it simply, an animation script is just a collection of variables, and how their values should be computed. Animation scripts, when running, are evaluated once per frame, and the values of some of the variables are then used to animate the window.
.sp
\fBBasic syntax\fP
.sp
To concretely illustrate what the above means, here is an example:
.sp
.if n .RS 4
.nf
.fam C
# 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
        # ...
}, ...)
.fam
.fi
.if n .RE
.sp
A variable can be defined as a number, an expression, or a timing function. In the example above, \fIa\fP is defined to be a number (10), \fIb\fP is defined to be the result of the expression \f(CRa * 10\fP, and \fIc\fP similarly. Expression used to define one variable can refer to other variables in the same script. This is how you can create complex animations. Where the variables are defined in the script does not matter, as long as no circular references exist.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
Because variable names can contain dashes (\f(CR\-\fP), minus signs in expressions must be surrounded by spaces. For example, \f(CRa \- 10\fP means \f(CRa\fP minus \f(CR10\fP, whereas \f(CRa\-10\fP is a variable named \f(CRa\-10\fP.
.sp .5v
.RE
.sp
\fId\fP is a timing function, which is a group with several options specifying its behavior. Timing functions are what drives an animation. If no timing function is defined in an animation script, nothing will be animated and the animation will end instantly.
.sp
These options are valid for a timing function:
.RS 4
.sp
\fIcurve\fP
.RS 4
Type of the curve and its parameters. It can be \fIlinear\fP, which takes no parameters and defines a linear curve; or \fIcubic\-bezier\fP, which takes four parameters for the four control points of the cubic bezier curve; or \fIstep\fP, which takes one or two parameters, the first is the number of steps, the second is the "jumpterm", which can be \fIjump\-start\fP, \fIjump\-end\fP, \fIjump\-none\fP, or \fIjump\-both\fP. This option is optional, is not specified, the curve will be linear.
.RE
.sp
\fIdelay\fP
.RS 4
The number of seconds to wait before the value starts changing. Optional, defaults to 0.
.RE
.sp
\fIduration\fP
.RS 4
The number of seconds it will take for the value to go from \fIstart\fP to \fIend\fP once it starts changing. Mandatory. And must be greater than 0.
.RE
.sp
\fIstart\fP
.RS 4
The start value of the variable. Mandatory.
.RE
.sp
\fIend\fP
.RS 4
The end value of the variable. Mandatory.
.RE
.RE
.sp
All options except \fIcurve\fP can be set to expressions. Timing function options are not variables themselves.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
If any of \fIdelay\fP, \fIduration\fP, \fIstart\fP, or \fIend\fP is defined with an expression, the expression will be evaluated only once when the animation starts. The values of \fIdelay\fP, \fIduration\fP, \fIstart\fP, and \fIend\fP will then be fixed for the duration of the animation.
.sp .5v
.RE
.sp
The total duration of an animation is determined by the duration of the timing function with the longest duration. The animation will end when the longest timing function ends. Once an animation ends, its effects on the window will be removed.
.sp
There isn\(cqt any restriction on what you can name the variables. Obviously they cannot conflict with the names of common options (\fItriggers\fP, \fIsuppressions\fP, and \fIpreset\fP), but other than that, you can name them whatever you want as long as libconfig allows it. Some variable names have special meanings as we will see below.
.sp
\fBOutput variables\fP
.sp
Now you know how to write an animation script. But what we just wrote doesn\(cqt actually do anything to the window. To animate a window, we define a set of special variable names which we will call "output variables". If you define variables with these names, their values will be used to animate the window.
.sp
For example, if you define an animation script like this:
.sp
.if n .RS 4
.nf
.fam C
animations = ({
        triggers = [ "open" ];
        offset\-x = {
                duration = 2;
                start = 0;
                end = 100;
        };
}, ...)
.fam
.fi
.if n .RE
.sp
Then when a window opens, it will move 100 pixels to the right over the course of 2 seconds.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Warning
.ps -1
.br
.sp
Although we did say you can name your variables whatever you want, if some of them become output variables in the future, your animation script will behave unexpectedly. To avoid this kind of problems, we reserve several classes of variable names which we will never use for special variables. These are: 1) any names that start with a single letter followed by a dash (e.g. \f(CRa\-\fP, \f(CRb\-\fP, etc.); 2) any names that start with \f(CRvar\-\fP, \f(CRtmp\-\fP, or \f(CRuser\-\fP. If you need to define a non\-output variable, use one of these names.
.sp .5v
.RE
.sp
Currently, these output variables are supported:
.RS 4
.sp
\fIoffset\-x\fP, \fIoffset\-y\fP
.RS 4
The offset of the window in the X and Y direction, respectively. The window body will be moved by this amount. Note this does not affect the shadow, so if you define these but not \fIshadow\-offset\-x\fP or \fIshadow\-offset\-y\fP, the shadow will remain where the window was without the animation.
.RE
.sp
\fIshadow\-offset\-x\fP, \fIshadow\-offset\-y\fP
.RS 4
The offset of the shadow in the X and Y direction, respectively. The shadow will be moved by this amount.
.RE
.sp
\fIopacity\fP
.RS 4
The opacity of the window. This is a number between 0 and 1.
.RE
.sp
\fIblur\-opacity\fP
.RS 4
The opacity of the blur behind the window. This is a number between 0 and 1.
.RE
.sp
\fIshadow\-opacity\fP
.RS 4
The opacity of the shadow. This is a number between 0 and 1.
.RE
.sp
\fIscale\-x\fP, \fIscale\-y\fP, \fIshadow\-scale\-x\fP, \fIshadow\-scale\-y\fP
.RS 4
The scaling factor of the window and shadow in the X and Y direction, respectively. 1.0 means no scaling. The window body and the shadow are scaled independently.
.RE
.sp
\fIcrop\-x\fP, \fIcrop\-y\fP, \fIcrop\-width\fP, \fIcrop\-height\fP
.RS 4
These four values combined defines a rectangle on the screen. The window and its shadow will be cropped to this rectangle. If not defined, the window and shadow will not be cropped.
.RE
.sp
\fIsaved\-image\-blend\fP
.RS 4
When the window\(cqs geometry changes, its content will often change drastically, creating a jarring discontinuity. This output variable allows you to blend the window\(cqs content before and after the geometry change, the before and after images will be stretched appropriately to match the animation. This way you can smoothly animated geometry changes. This is a number between 0 and 1. 0 means the saved image is not used, whereas 1 means you will only see the saved image. (EXPERIMENTAL)
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Warning
.ps -1
.br
.sp
The \fIsaved\-image\-blend\fP variable is experimental. It might work incorrectly, cause visual artifacts, or slow down your system. You are welcome to open an issue on GitHub if you encounter any problems to help us improve it, though resolution is not guaranteed.
.sp .5v
.RE
.RE
.RE
.sp
All coordinates are in pixels, and are in the coordinate system of the screen. Sizes are also in pixels.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Important
.ps -1
.br
.sp
If an output variable name is not defined in your animation script, it will take the default value for whichever state the window is in. Specifically, if you don\(cqt define an \fIopacity\fP variable in the animation script for the "close" or "hide" trigger, a closed window will, by default, have 0 opacity. So you will just see it disappear instantly. Oftentimes, you will want to set \fIopacity\fP to 1 to make the window visible for the duration of the animation.
.sp .5v
.RE
.sp
\fBContext variables\fP
.sp
Now you know how to animate a window. But this is still not powerful enough to support most animations you might want to define. For example, if you want your window to fly out the right side of your screen, the amount of pixels it has to move depends on where it is on the screen, and its width. For the last piece of the puzzle, we have context variables.
.sp
A context variable is a variable picom defines for you, and you can use them in expressions like any other variables. Their values reflect certain attributes of the window you are animating.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Warning
.ps -1
.br
.sp
If you define a variable with the same name as a context variable, your variable will shadow the context variable. Since more context variables can be added in the future, this can be difficult to avoid. Thus, the same rule for output variables applies here as well: if you need to define a temporary variable, use one of the reserved names.
.sp .5v
.RE
.sp
Currently, these context variables are defined:
.RS 4
.sp
\fIwindow\-x\fP, \fIwindow\-y\fP
.RS 4
The coordinates of the top\-left corner of the window.
.RE
.sp
\fIwindow\-width\fP, \fIwindow\-height\fP
.RS 4
The size of the window.
.RE
.sp
\fIwindow\-x\-before\fP, \fIwindow\-y\-before\fP, \fIwindow\-width\-before\fP, \fIwindow\-height\-before\fP
.RS 4
The size and coordinates of the window from the previous frame. This is only meaningfully different from the normal window geometry variables inside animations triggered by the \fIgeometry\fP trigger.
.RE
.sp
\fIwindow\-monitor\-x\fP, \fIwindow\-monitor\-y\fP, \fIwindow\-monitor\-width\fP, \fIwindow\-monitor\-height\fP
.RS 4
Defines the rectangle which reflects the monitor the window is on. If the window is not fully contained in any monitor, the rectangle will reflect the entire virtual screen.
.RE
.sp
\fIwindow\-raw\-opacity\-before\fP, \fIwindow\-raw\-opacity\fP
.RS 4
Animation triggers are usually accompanied by a change in the window\(cqs opacity. For example, when a window is opened, its opacity changes from 0 to 1. These two variables reflect the opacity of the window for the previous and current frame. They are useful if you want to smoothly transition the window\(cqs opacity.
.RE
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Important
.ps -1
.br
.sp
All of the \fIwindow\-*\-before\fP variables are updated every frame, and reflects the state of the window in the previous frame. Which means they will only be meaningful for a single frame, when an animation has just been triggered. Which means you should only use them to define the \fIstart\fP, \fIend\fP, \fIduration\fP, or \fIdelay\fP values of a timing function, since these values are only evaluated once when the animation starts.
.sp .5v
.RE
.SS "Share your animations"
.sp
If you have created an animation script that you think is particularly cool, you are encouraged to share it with the community. You can submit an issue or a pull request to picom on GitHub, and get a chance to have your animation included as one of the presets, so it can be used by everyone.
.SH "SHADER INTERFACE"
.sp
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.
.sp
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\(cqs responsibility to apply these effects.
.sp
The interface between picom and a custom shader is dependent on which backend is being used. The xrender backend doesn\(cqt support shader at all. Here we descibe the interface provided by the glx backend.
.sp
The shader must define a function, \fIvec4 window_shader()\fP, which would be the entry point of the shader. The returned \fIvec4\fP will be used to set \fIgl_FragColor\fP. A function, \fIvec4 default_post_processing(vec4 c)\fP, is provided for applying the default picom effects to input color \*(Aqc\*(Aq.
.sp
The following uniform/input variables are made available to the shader:
.sp
.if n .RS 4
.nf
.fam C
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
.fam
.fi
.if n .RE
.sp
The default behavior of picom window rendering can be replicated by the following shader:
.sp
.if n .RS 4
.nf
.fam C
#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);
}
.fam
.fi
.if n .RE
.sp
The interface is expected to be mostly stable.
.SH "CONFIGURATION FILES"
.sp
picom could read from a configuration file if libconfig support is compiled in. If \fB\-\-config\fP is not used, picom will seek for a configuration file in \f(CR$XDG_CONFIG_HOME/picom.conf\fP (\f(CR~/.config/picom.conf\fP, usually), then \f(CR$XDG_CONFIG_HOME/picom/picom.conf\fP, then \f(CR$XDG_CONFIG_DIRS/picom.conf\fP (often \f(CR/etc/xdg/picom.conf\fP), then \f(CR$XDG_CONFIG_DIRS/picom/picom.conf\fP.
.sp
When \f(CR@include\fP directive is used in the config file, picom will first search for the included file in the parent directory of \f(CRpicom.conf\fP, then in \f(CR$XDG_CONFIG_HOME/picom/include/\fP, then in \f(CR$XDG_CONFIG_DIRS/picom/include\fP.
.sp
picom uses general libconfig configuration file format. A sample configuration file is available as \f(CRpicom.sample.conf\fP in the source tree. Most of command line switches can be used as options in configuration file as well. For example, \fB\-\-vsync\fP option documented above can be set in the configuration file using `vsync = `. Command line options will always overwrite the settings in the configuration file.
.sp
Some options can only be set in the configuration file. Such options include \f(CRrules\fP (see \fBWINDOW RULES\fP), \f(CRanimations\fP (see \fBANIMATIONS\fP), \f(CRwintypes\fP (see below).
.sp
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:
.sp
.if n .RS 4
.nf
.fam C
wintypes:
{
  WINDOW_TYPE = { fade = BOOL; shadow = BOOL; opacity = FLOAT; focus = BOOL; blur\-background = BOOL; full\-shadow = BOOL; clip\-shadow\-above = BOOL; redir\-ignore = BOOL; };
};
.fam
.fi
.if n .RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Warning
.ps -1
.br
.sp
Using this is highly discouraged, see the \fBWINDOW RULES\fP section for the recommended way to set window\-specific options.
.sp .5v
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Important
.ps -1
.br
.sp
According to the window manager specification, a window can have multiple types. But due to the limitation of how \fIwintypes\fP was implemented, if a window has multiple types, then for the purpose of applying \f(CRwintypes\fP options, one of the window types will be chosen at random. Again, you are recommended to use \fBWINDOW RULES\fP instead.
.sp .5v
.RE
.sp
\fIWINDOW_TYPE\fP 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".
.sp
Following per window\-type options are available:
.RS 4
.sp
fade, shadow
.RS 4
Controls window\-type\-specific shadow and fade settings.
.RE
.sp
opacity
.RS 4
Controls default opacity of the window type.
.RE
.sp
focus
.RS 4
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.)
.RE
.sp
blur\-background
.RS 4
Controls whether the window of this type will have its transparent background blurred.
.RE
.sp
full\-shadow
.RS 4
Controls whether shadow is drawn under the parts of the window that you normally won\(cqt be able to see. Useful when the window has parts of it transparent, and you want shadows in those areas.
.RE
.sp
clip\-shadow\-above
.RS 4
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.
.RE
.sp
redir\-ignore
.RS 4
Controls whether this type of windows should cause screen to become redirected again after been unredirected. If you have \fB\-\-unredir\-if\-possible\fP set, and doesn\(cqt want certain window to cause unnecessary screen redirection, you can set this to \f(CRtrue\fP.
.RE
.RE
.SH "BLUR"
.sp
You can configure how the window background is blurred using a \*(Aqblur\*(Aq section in your configuration file. Here is an example:
.sp
.if n .RS 4
.nf
.fam C
blur:
{
  method = "gaussian";
  size = 10;
  deviation = 5.0;
};
.fam
.fi
.if n .RE
.sp
Available options of the \fIblur\fP section are:
.RS 4
.sp
\fBmethod\fP
.RS 4
A string. Controls the blur method. Corresponds to the \fB\-\-blur\-method\fP command line option. Available choices are:
\fInone\fP to disable blurring; \fIgaussian\fP for gaussian blur; \fIbox\fP for box blur; \fIkernel\fP for convolution blur with a custom kernel; \fIdual_kawase\fP for dual\-filter kawase blur.
Note: \fIgaussian\fP, \fIbox\fP and \fIdual_kawase\fP blur methods are not supported by the legacy backends.
(default: none)
.RE
.sp
\fBsize\fP
.RS 4
An integer. The size of the blur kernel, required by \fIgaussian\fP and \fIbox\fP blur methods. For the \fIkernel\fP method, the size is included in the kernel. Corresponds to the \fB\-\-blur\-size\fP command line option (default: 3).
.RE
.sp
\fBdeviation\fP
.RS 4
A floating point number. The standard deviation for the \fIgaussian\fP blur method. Corresponds to the \fB\-\-blur\-deviation\fP command line option (default: 0.84089642).
.RE
.sp
\fBstrength\fP
.RS 4
An integer in the range 0\-20. The strength of the \fIdual_kawase\fP blur method. Corresponds to the \fB\-\-blur\-strength\fP command line option. If set to zero, the value requested by \fB\-\-blur\-size\fP is approximated (default: 5).
.RE
.sp
\fBkernel\fP
.RS 4
A string. The kernel to use for the \fIkernel\fP blur method, specified in the same format as the \fB\-\-blur\-kern\fP option. Corresponds to the \fB\-\-blur\-kern\fP command line option.
.RE
.RE
.SH "SIGNALS"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
picom reinitializes itself upon receiving \f(CRSIGUSR1\fP.
.RE
.SH "D\-BUS API"
.sp
It\(cqs possible to control picom via D\-Bus messages, by running picom with \fB\-\-dbus\fP and send messages to \f(CRcom.github.chjj.compton.<DISPLAY>\fP. \f(CR<DISPLAY>\fP is the display used by picom, with all non\-alphanumeric characters transformed to underscores. For \f(CRDISPLAY=:0.0\fP you should use \f(CRcom.github.chjj.compton._0_0\fP, for example.
.sp
The D\-Bus methods and signals are not yet stable, thus undocumented right now.
.SH "EXAMPLES"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Disable configuration file parsing:
.sp
.if n .RS 4
.nf
.fam C
$ picom \-\-config /dev/null
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Run picom with client\-side shadow and fading:
.sp
.if n .RS 4
.nf
.fam C
$ picom \-cf
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Same thing as above, plus making inactive windows 80% transparent, making frame 80% transparent, don\(cqt fade on window open/close, and fork to background:
.sp
.if n .RS 4
.nf
.fam C
$ picom \-bcf \-i 0.8 \-e 0.8 \-\-no\-fading\-openclose
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Draw white shadows:
.sp
.if n .RS 4
.nf
.fam C
$ picom \-c \-\-shadow\-red 1 \-\-shadow\-green 1 \-\-shadow\-blue 1
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Avoid drawing shadows on wbar window:
.sp
.if n .RS 4
.nf
.fam C
$ picom \-c \-\-shadow\-exclude \*(Aqclass_g = "wbar"\*(Aq
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Enable VSync with GLX backend:
.sp
.if n .RS 4
.nf
.fam C
$ picom \-\-backend glx \-\-vsync
.fam
.fi
.if n .RE
.RE
.SH "BUGS"
.sp
Please submit bug reports to \c
.URL "https://github.com/yshui/picom" "" "."
.sp
Out dated information in this man page is considered a bug.
.SH "RESOURCES"
.sp
Homepage: \c
.URL "https://github.com/yshui/picom" "" ""
.SH "SEE ALSO"
.sp
\fBxcompmgr\fP(1), \fBpicom\-inspect\fP(1), \fBpicom\-trans\fP(1)
.SH "AUTHOR"
.sp
Yuxuan Shui