path: root/man/picom.1

'\" t
.\"     Title: picom
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 09/19/2023
.\"    Manual: User Commands
.\"    Source: picom
.\"  Language: English
.\"
.TH "PICOM" "1" "09/19/2023" "picom" "User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
picom \- a compositor for X11
.SH "SYNOPSIS"
.sp
\fBpicom\fR [\fIOPTIONS\fR]
.SH "DESCRIPTION"
.sp
picom is a compositor for X11 which gives features to WM and DE such as opacity, blurring, rounded edges, shadows and most importantly\&. Animations!
.SH "OPTIONS"
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Get the usage text embedded in program code, which may be more up\-to\-date than this man page\&.
.RE
.PP
\fB\-r\fR, \fB\-\-shadow\-radius\fR=\fIRADIUS\fR
.RS 4
The blur radius for shadows, in pixels\&. (defaults to 12)
.RE
.PP
\fB\-o\fR, \fB\-\-shadow\-opacity\fR=\fIOPACITY\fR
.RS 4
The opacity of shadows\&. (0\&.0 \- 1\&.0, defaults to 0\&.75)
.RE
.PP
\fB\-l\fR, \fB\-\-shadow\-offset\-x\fR=\fIOFFSET\fR
.RS 4
The left offset for shadows, in pixels\&. (defaults to \-15)
.RE
.PP
\fB\-t\fR, \fB\-\-shadow\-offset\-y\fR=\fIOFFSET\fR
.RS 4
The top offset for shadows, in pixels\&. (defaults to \-15)
.RE
.PP
\fB\-I\fR, \fB\-\-fade\-in\-step\fR=\fIOPACITY_STEP\fR
.RS 4
Opacity change between steps while fading in\&. (0\&.01 \- 1\&.0, defaults to 0\&.028)
.RE
.PP
\fB\-O\fR, \fB\-\-fade\-out\-step\fR=\fIOPACITY_STEP\fR
.RS 4
Opacity change between steps while fading out\&. (0\&.01 \- 1\&.0, defaults to 0\&.03)
.RE
.PP
\fB\-D\fR, \fB\-\-fade\-delta\fR=\fIMILLISECONDS\fR
.RS 4
The time between steps in fade step, in milliseconds\&. (> 0, defaults to 10)
.RE
.PP
\fB\-m\fR, \fB\-\-menu\-opacity\fR=\fIOPACITY\fR
.RS 4
Default opacity for dropdown menus and popup menus\&. (0\&.0 \- 1\&.0, defaults to 1\&.0)
.RE
.PP
\fB\-c\fR, \fB\-\-shadow\fR
.RS 4
Enabled client\-side shadows on windows\&. Note desktop windows (windows with
\fI_NET_WM_WINDOW_TYPE_DESKTOP\fR) never get shadow, unless explicitly requested using the wintypes option\&.
.RE
.PP
\fB\-f\fR, \fB\-\-fading\fR
.RS 4
Fade windows in/out when opening/closing and when opacity changes, unless
\fB\-\-no\-fading\-openclose\fR
is used\&.
.RE
.PP
\fB\-F\fR
.RS 4
Equals to
\fB\-f\fR\&. Deprecated\&.
.RE
.PP
\fB\-\-animations\fR
.RS 4
Run animations for window geometry changes (movement and scaling)\&. We use spring\-based animations, which are parametrized by
\fB\-\-animation\-stiffness\fR,
\fB\-\-animation\-dampening\fR,
\fB\-\-animation\-window\-mass\fR
and
\fB\-\-animation\-clamp\fR\&.

A useful resource for selecting animation parameters is
https://react\-spring\-visualizer\&.com/, which allows you to interactively try out various parameters and see the resulting animation curve\&. Or you can just edit the values in the config file, which is automatically reloaded\&.
.RE
.PP
\fB\-\-animation\-for\-open\-window\fR
.RS 4
Which animation to run when opening a window\&. Must be one of
none,
fly\-in,
zoom
(default:
none)\&.
.RE
.PP
\fB\-\-animation\-stiffness\fR
.RS 4
Stiffness (a\&.k\&.a\&. tension) parameter for spring\-based animation (default: 200\&.0)\&.
.RE
.PP
\fB\-\-animation\-dampening\fR
.RS 4
Dampening (a\&.k\&.a\&. friction) parameter for spring\-based animation (default: 25\&.0)\&.
.RE
.PP
\fB\-\-animation\-window\-mass\fR
.RS 4
Mass parameter for spring\-based animation (default: 1\&.0)\&.
.RE
.PP
\fB\-\-animation\-clamping\fR
.RS 4
Whether to clamp animations (default: true)\&.
.sp
.if n \{\
.RS 4
.\}
.nf
**NOTE:** With clamping disabled, on very low performance conditions (e\&.g\&., over 100ms to render an animation frame), windows may diverge\&. If this is your case, it is strongly advised to keep clamping on, as it protects against that\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-i\fR, \fB\-\-inactive\-opacity\fR=\fIOPACITY\fR
.RS 4
Opacity of inactive windows\&. (0\&.1 \- 1\&.0, defaults to 1\&.0)
.RE
.PP
\fB\-e\fR, \fB\-\-frame\-opacity\fR=\fIOPACITY\fR
.RS 4
Opacity of window titlebars and borders\&. (0\&.1 \- 1\&.0, disabled by default)
.RE
.PP
\fB\-b\fR, \fB\-\-daemon\fR
.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
.PP
\fB\-\-log\-level\fR
.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\fR, since it can generate a huge stream of logs\&.
.RE
.PP
\fB\-\-log\-file\fR
.RS 4
Set the log file\&. If
\fB\-\-log\-file\fR
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
.PP
\fB\-\-experimental\-backends\fR
.RS 4
Use the new, reimplemented version of the backends\&. The new backends are HIGHLY UNSTABLE at this point, you have been warned\&. This option is not available in the config file\&.
.RE
.PP
\fB\-\-show\-all\-xerrors\fR
.RS 4
Show all X errors (for debugging)\&.
.RE
.PP
\fB\-\-config\fR \fIPATH\fR
.RS 4
Look for configuration file at the path\&. See
\fBCONFIGURATION FILES\fR
section below for where picom looks for a configuration file by default\&. Use
/dev/null
to avoid loading configuration file\&.
.RE
.PP
\fB\-\-write\-pid\-path\fR \fIPATH\fR
.RS 4
Write process ID to a file\&. it is recommended to use an absolute path\&.
.RE
.PP
\fB\-\-shadow\-color\fR \fISTRING\fR
.RS 4
Color of shadow, as a hex string (\fI#000000\fR)
.RE
.PP
\fB\-\-shadow\-red\fR \fIVALUE\fR
.RS 4
Red color value of shadow (0\&.0 \- 1\&.0, defaults to 0)\&.
.RE
.PP
\fB\-\-shadow\-green\fR \fIVALUE\fR
.RS 4
Green color value of shadow (0\&.0 \- 1\&.0, defaults to 0)\&.
.RE
.PP
\fB\-\-shadow\-blue\fR \fIVALUE\fR
.RS 4
Blue color value of shadow (0\&.0 \- 1\&.0, defaults to 0)\&.
.RE
.PP
\fB\-\-inactive\-opacity\-override\fR
.RS 4
Let inactive opacity set by
\fB\-i\fR
override the
\fI_NET_WM_OPACITY\fR
values of windows\&.
.RE
.PP
\fB\-\-active\-opacity\fR \fIOPACITY\fR
.RS 4
Default opacity for active windows\&. (0\&.0 \- 1\&.0, defaults to 1\&.0)
.RE
.PP
\fB\-\-inactive\-dim\fR \fIVALUE\fR
.RS 4
Dim inactive windows\&. (0\&.0 \- 1\&.0, defaults to 0\&.0)
.RE
.PP
\fB\-\-corner\-radius\fR \fIVALUE\fR
.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\fR\&. (defaults to 0)\&.
.RE
.PP
\fB\-\-rounded\-corners\-exclude\fR \fICONDITION\fR
.RS 4
Exclude conditions for rounded corners\&.
.RE
.PP
\fB\-\-mark\-wmwin\-focused\fR
.RS 4
Try to detect WM windows (a non\-override\-redirect window with no child that has
\fIWM_STATE\fR) and mark them as active\&.
.RE
.PP
\fB\-\-mark\-ovredir\-focused\fR
.RS 4
Mark override\-redirect windows that doesn\(cqt have a child window with
\fIWM_STATE\fR
focused\&.
.RE
.PP
\fB\-\-no\-fading\-openclose\fR
.RS 4
Do not fade on window open/close\&.
.RE
.PP
\fB\-\-no\-fading\-destroyed\-argb\fR
.RS 4
Do not fade destroyed ARGB windows with WM frame\&. Workaround of bugs in Openbox, Fluxbox, etc\&.
.RE
.PP
\fB\-\-shadow\-ignore\-shaped\fR
.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, use
\-\-shadow\-exclude \*(Aqbounding_shaped\*(Aq
or
\-\-shadow\-exclude \*(Aqbounding_shaped && !rounded_corners\*(Aq
instead\&.
.RE
.PP
\fB\-\-detect\-rounded\-corners\fR
.RS 4
Try to detect windows with rounded corners and don\(cqt consider them shaped windows\&. The accuracy is not very high, unfortunately\&.
.RE
.PP
\fB\-\-detect\-client\-opacity\fR
.RS 4
Detect
\fI_NET_WM_OPACITY\fR
on client windows, useful for window managers not passing
\fI_NET_WM_OPACITY\fR
of client windows to frame windows\&.
.RE
.PP
\fB\-\-refresh\-rate\fR \fIREFRESH_RATE\fR
.RS 4
Specify refresh rate of the screen\&. If not specified or 0, picom will try detecting this with X RandR extension\&.
.RE
.PP
\fB\-\-vsync\fR, \fB\-\-no\-vsync\fR
.RS 4
Enable/disable VSync\&.
.RE
.PP
\fB\-\-use\-ewmh\-active\-win\fR
.RS 4
Use EWMH
\fI_NET_ACTIVE_WINDOW\fR
to determine currently focused window, rather than listening to
\fIFocusIn\fR/\fIFocusOut\fR
event\&. Might have more accuracy, provided that the WM supports it\&.
.RE
.PP
\fB\-\-unredir\-if\-possible\fR
.RS 4
Unredirect all windows if a full\-screen opaque window is detected, to maximize performance for full\-screen windows\&. Known to cause flickering when redirecting/unredirecting windows\&.
.RE
.PP
\fB\-\-unredir\-if\-possible\-delay\fR \fIMILLISECONDS\fR
.RS 4
Delay before unredirecting the window, in milliseconds\&. Defaults to 0\&.
.RE
.PP
\fB\-\-unredir\-if\-possible\-exclude\fR \fICONDITION\fR
.RS 4
Conditions of windows that shouldn\(cqt be considered full\-screen for unredirecting screen\&.
.RE
.PP
\fB\-\-shadow\-exclude\fR \fICONDITION\fR
.RS 4
Specify a list of conditions of windows that should have no shadow\&.
.RE
.PP
\fB\-\-clip\-shadow\-above\fR \fICONDITION\fR
.RS 4
Specify a list of conditions of windows that should have no shadow painted over, such as a dock window\&.
.RE
.PP
\fB\-\-fade\-exclude\fR \fICONDITION\fR
.RS 4
Specify a list of conditions of windows that should not be faded\&.
.RE
.PP
\fB\-\-focus\-exclude\fR \fICONDITION\fR
.RS 4
Specify a list of conditions of windows that should always be considered focused\&.
.RE
.PP
\fB\-\-inactive\-dim\-fixed\fR
.RS 4
Use fixed inactive dim value, instead of adjusting according to window opacity\&.
.RE
.PP
\fB\-\-detect\-transient\fR
.RS 4
Use
\fIWM_TRANSIENT_FOR\fR
to group windows, and consider windows in the same group focused at the same time\&.
.RE
.PP
\fB\-\-detect\-client\-leader\fR
.RS 4
Use
\fIWM_CLIENT_LEADER\fR
to group windows, and consider windows in the same group focused at the same time\&.
\fIWM_TRANSIENT_FOR\fR
has higher priority if
\fB\-\-detect\-transient\fR
is enabled, too\&.
.RE
.PP
\fB\-\-blur\-method\fR, \fB\-\-blur\-size\fR, \fB\-\-blur\-deviation\fR, \fB\-\-blur\-strength\fR
.RS 4
Parameters for background blurring, see the
\fBBLUR\fR
section for more information\&.
.RE
.PP
\fB\-\-blur\-background\fR
.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
.PP
\fB\-\-blur\-background\-frame\fR
.RS 4
Blur background of windows when the window frame is not opaque\&. Implies
\fB\-\-blur\-background\fR\&. Bad in performance, with driver\-dependent behavior\&. The name may change\&.
.RE
.PP
\fB\-\-blur\-background\-fixed\fR
.RS 4
Use fixed blur strength rather than adjusting according to window opacity\&.
.RE
.PP
\fB\-\-blur\-kern\fR \fIMATRIX\fR
.RS 4
Specify the blur convolution kernel, with the following format:
.sp
.if n \{\
.RS 4
.\}
.nf
WIDTH,HEIGHT,ELE1,ELE2,ELE3,ELE4,ELE5\&.\&.\&.
.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
\fIwidth * height \- 1\fR
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\&.\fR
(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\fR\&. 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
\-\-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
.fi
.if n \{\
.RE
.\}
.sp
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 supported by the experimental backends (See
\fBBLUR\fR
and
\fB\-\-experimental\-backends\fR)\&.
.RE
.PP
\fB\-\-blur\-background\-exclude\fR \fICONDITION\fR
.RS 4
Exclude conditions for background blur\&.
.RE
.PP
\fB\-\-resize\-damage\fR \fIINTEGER\fR
.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\fR, 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
\fB\-\-glx\-no\-stencil\fR\&. Shrinking doesn\(cqt function correctly\&.
.RE
.PP
\fB\-\-invert\-color\-include\fR \fICONDITION\fR
.RS 4
Specify a list of conditions of windows that should be painted with inverted color\&. Resource\-hogging, and is not well tested\&.
.RE
.PP
\fB\-\-opacity\-rule\fR \fIOPACITY\fR:\*(AqCONDITION\*(Aq
.RS 4
Specify a list of opacity rules, in the format
PERCENT:PATTERN, like
50:name *= "Firefox"\&. 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\fR
on frame or client windows\&.
.RE
.PP
\fB\-\-shadow\-exclude\-reg\fR \fIGEOMETRY\fR
.RS 4
Specify a X geometry that describes the region in which shadow should not be painted in, such as a dock window region\&. Use
\-\-shadow\-exclude\-reg x10+0\-0, for example, if the 10 pixels on the bottom of the screen should not have shadows painted on\&.
.RE
.PP
\fB\-\-xinerama\-shadow\-crop\fR
.RS 4
Crop shadow of a window fully on a particular Xinerama screen to the screen\&.
.RE
.PP
\fB\-\-backend\fR \fIBACKEND\fR
.RS 4
Specify the backend to use:
xrender,
glx, or
xr_glx_hybrid\&.
xrender
is the default one\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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 (\fB\-\-invert\-color\-include\fR) or blur (\fB\-\-blur\-background\fR)\&. 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\fR
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
.\}
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\&.
\fB\-\-vsync\-use\-glfinish\fR
might fix some rendering issues with this backend\&.
.RE
.RE
.PP
\fB\-\-glx\-no\-stencil\fR
.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\fR\&. My tests show a 15% performance boost\&. Recommended\&.
.RE
.PP
\fB\-\-glx\-no\-rebind\-pixmap\fR
.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
.PP
\fB\-\-no\-use\-damage\fR
.RS 4
Disable the use of damage information\&. This cause the whole screen to be redrawn everytime, instead of the part of the screen has actually changed\&. Potentially degrades the performance, but might fix some artifacts\&.
.RE
.PP
\fB\-\-xrender\-sync\-fence\fR
.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
.PP
\fB\-\-glx\-fshader\-win\fR \fISHADER\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-force\-win\-blend\fR
.RS 4
Force all windows to be painted with blending\&. Useful if you have a
\fB\-\-glx\-fshader\-win\fR
that could turn opaque pixels transparent\&.
.RE
.PP
\fB\-\-dbus\fR
.RS 4
Enable remote control via D\-Bus\&. See the
\fBD\-BUS API\fR
section below for more details\&.
.RE
.PP
\fB\-\-benchmark\fR \fICYCLES\fR
.RS 4
Benchmark mode\&. Repeatedly paint until reaching the specified cycles\&.
.RE
.PP
\fB\-\-benchmark\-wid\fR \fIWINDOW_ID\fR
.RS 4
Specify window ID to repaint in benchmark mode\&. If omitted or is 0, the whole screen is repainted\&.
.RE
.PP
\fB\-\-no\-ewmh\-fullscreen\fR
.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
.PP
\fB\-\-max\-brightness\fR
.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\fR
to be disabled\&. (default: 1\&.0)
.RE
.PP
\fB\-\-transparent\-clipping\fR
.RS 4
Make transparent windows clip other windows like non\-transparent windows do, instead of blending on top of them\&.
.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
A condition with "exists" operator looks like this:
.sp
.if n \{\
.RS 4
.\}
.nf
<NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE>
.fi
.if n \{\
.RE
.\}
.sp
With equals operator it looks like:
.sp
.if n \{\
.RS 4
.\}
.nf
<NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE> <NEGATION> <OP QUALIFIER> <MATCH TYPE> = <PATTERN>
.fi
.if n \{\
.RE
.\}
.sp
With greater\-than/less\-than operators it looks like:
.sp
.if n \{\
.RS 4
.\}
.nf
<NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE> <NEGATION> <OPERATOR> <PATTERN>
.fi
.if n \{\
.RE
.\}
.sp
\fINEGATION\fR (optional) is one or more exclamation marks;
.sp
\fITARGET\fR is either a predefined target name, or the name of a window property to match\&. Supported predefined targets are id, x, y, x2 (x + widthb), y2 (like x2), width, height, widthb (width + 2 * border_width), heightb (like widthb), border_width, fullscreen, override_redirect, argb (whether the window has an ARGB visual), focused, wmwin (whether the window looks like a WM window, i\&.e\&. has no child window with WM_STATE and is not override\-redirected), bounding_shaped, rounded_corners (requires \fB\-\-detect\-rounded\-corners\fR), client (ID of client window), window_type (window type in string), leader (ID of window leader), name, class_g (= WM_CLASS[1]), class_i (= WM_CLASS[0]), and role\&.
.sp
\fICLIENT/FRAME\fR is a single @ if the window attribute should be be looked up on client window, nothing if on frame window;
.sp
\fIINDEX\fR (optional) is the index number of the property to look up\&. For example, [2] means look at the third value in the property\&. If not specified, the first value (index [0]) is used implicitly\&. Use the special value [*] to perform matching against all available property values using logical OR\&. Do not specify it for predefined targets\&.
.sp
\fIFORMAT\fR (optional) specifies the format of the property, 8, 16, or 32\&. On absence we use format X reports\&. Do not specify it for predefined or string targets\&.
.sp
\fITYPE\fR is a single character representing the type of the property to match for: c for \fICARDINAL\fR, a for \fIATOM\fR, w for \fIWINDOW\fR, d for \fIDRAWABLE\fR, s for \fISTRING\fR (and any other string types, such as \fIUTF8_STRING\fR)\&. Do not specify it for predefined targets\&.
.sp
\fIOP QUALIFIER\fR (optional), applicable only for equals operator, could be ? (ignore\-case)\&.
.sp
\fIMATCH TYPE\fR (optional), applicable only for equals operator, could be nothing (exact match), * (match anywhere), ^ (match from start), % (wildcard), or ~ (PCRE regular expression)\&.
.sp
\fIOPERATOR\fR is one of = (equals), <, >, <=, =>, or nothing (exists)\&. Exists operator checks whether a property exists on a window (but for predefined targets, exists means != 0 then)\&.
.sp
\fIPATTERN\fR is either an integer or a string enclosed by single or double quotes\&. Python\-3\-style escape sequences and raw string are supported in the string format\&.
.sp
Supported logical operators are && (and) and || (or)\&. && has higher precedence than ||, left\-to\-right associativity\&. Use parentheses to change precedence\&.
.sp
Examples:
.sp
.if n \{\
.RS 4
.\}
.nf
# If the window is focused
focused
focused = 1
# If the window is not override\-redirected
!override_redirect
override_redirect = false
override_redirect != true
override_redirect != 1
# If the window is a menu
window_type *= "menu"
_NET_WM_WINDOW_TYPE@:a *= "MENU"
# If the window is marked hidden: _NET_WM_STATE contains _NET_WM_STATE_HIDDEN
_NET_WM_STATE@[*]:a = "_NET_WM_STATE_HIDDEN"
# If the window is marked sticky: _NET_WM_STATE contains an atom that contains
# "sticky", ignore case
_NET_WM_STATE@[*]:a *?= "sticky"
# If the window name contains "Firefox", ignore case
name *?= "Firefox"
_NET_WM_NAME@:s *?= "Firefox"
# If the window name ends with "Firefox"
name %= "*Firefox"
name ~= "Firefox$"
# If the window has a property _COMPTON_SHADOW with value 0, type CARDINAL,
# format 32, value 0, on its frame window
_COMPTON_SHADOW:32c = 0
# If the third value of _NET_FRAME_EXTENTS is less than 20, or there\*(Aqs no
# _NET_FRAME_EXTENTS property on client window
_NET_FRAME_EXTENTS@[2]:32c < 20 || !_NET_FRAME_EXTENTS@:32c
# The pattern here will be parsed as "dd4"
name = "\ex64\ex64\eo64"
# The pattern here will be parsed as "\ex64\ex64\ex64"
name = r"\ex64\ex64\eo64"
.fi
.if n \{\
.RE
.\}
.SH "LEGACY FORMAT OF CONDITIONS"
.sp
This is the old condition format we once used\&. Support of this format might be removed in the future\&.
.sp
.if n \{\
.RS 4
.\}
.nf
condition = TARGET:TYPE[FLAGS]:PATTERN
.fi
.if n \{\
.RE
.\}
.sp
\fITARGET\fR is one of "n" (window name), "i" (window class instance), "g" (window general class), and "r" (window role)\&.
.sp
\fITYPE\fR is one of "e" (exact match), "a" (match anywhere), "s" (match from start), "w" (wildcard), and "p" (PCRE regular expressions, if compiled with the support)\&.
.sp
\fIFLAGS\fR could be a series of flags\&. Currently the only defined flag is "i" (ignore case)\&.
.sp
\fIPATTERN\fR is the actual pattern string\&.
.SH "CONFIGURATION FILES"
.sp
picom could read from a configuration file if libconfig support is compiled in\&. If \fB\-\-config\fR 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\&.
.sp
picom uses general libconfig configuration file format\&. A sample configuration file is available as picom\&.sample\&.conf in the source tree\&. Most of commandline switches can be used as options in configuration file as well\&. For example, \fB\-\-vsync\fR 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
Window\-type\-specific settings are exposed only in configuration file and has the following format:
.sp
.if n \{\
.RS 4
.\}
.nf
wintypes:
{
  WINDOW_TYPE = { fade = BOOL; shadow = BOOL; opacity = FLOAT; focus = BOOL; blur\-background = BOOL; full\-shadow = BOOL; clip\-shadow\-above = BOOL; redir\-ignore = BOOL; };
};
.fi
.if n \{\
.RE
.\}
.sp
\fIWINDOW_TYPE\fR 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"\&.
.PP
Following per window\-type options are available:
.RS 4
.PP
fade, shadow
.RS 4
Controls window\-type\-specific shadow and fade settings\&.
.RE
.PP
opacity
.RS 4
Controls default opacity of the window type\&.
.RE
.PP
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
.PP
blur\-background
.RS 4
Controls wether the window of this type will have its transparent background blurred\&.
.RE
.PP
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
.PP
clip\-shadow\-above
.RS 4
Controls wether 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
.PP
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\fR
set, and doesn\(cqt want certain window to cause unnecessary screen redirection, you can set this to
true\&.
.RE
.RE
.SH "BLUR"
.sp
You can configure how the window background is blurred using a \fIblur\fR section in your configuration file\&. Here is an example:
.sp
.if n \{\
.RS 4
.\}
.nf
blur:
{
  method = "gaussian";
  size = 10;
  deviation = 5\&.0;
};
.fi
.if n \{\
.RE
.\}
.PP
Available options of the \fIblur\fR section are:
.RS 4
.PP
\fBmethod\fR
.RS 4
A string\&. Controls the blur method\&. Corresponds to the
\fB\-\-blur\-method\fR
command line option\&. Available choices are:
\fInone\fR
to disable blurring;
\fIgaussian\fR
for gaussian blur;
\fIbox\fR
for box blur;
\fIkernel\fR
for convolution blur with a custom kernel;
\fIdual_kawase\fR
for dual\-filter kawase blur\&. Note:
\fIgaussian\fR,
\fIbox\fR
and
\fIdual_kawase\fR
blur methods are only supported by the experimental backends\&. (default: none)
.RE
.PP
\fBsize\fR
.RS 4
An integer\&. The size of the blur kernel, required by
\fIgaussian\fR
and
\fIbox\fR
blur methods\&. For the
\fIkernel\fR
method, the size is included in the kernel\&. Corresponds to the
\fB\-\-blur\-size\fR
command line option (default: 3)\&.
.RE
.PP
\fBdeviation\fR
.RS 4
A floating point number\&. The standard deviation for the
\fIgaussian\fR
blur method\&. Corresponds to the
\fB\-\-blur\-deviation\fR
command line option (default: 0\&.84089642)\&.
.RE
.PP
\fBstrength\fR
.RS 4
An integer in the range 0\-20\&. The strength of the
\fIdual_kawase\fR
blur method\&. Corresponds to the
\fB\-\-blur\-strength\fR
command line option\&. If set to zero, the value requested by
\fB\-\-blur\-size\fR
is approximated (default: 5)\&.
.RE
.PP
\fBkernel\fR
.RS 4
A string\&. The kernel to use for the
\fIkernel\fR
blur method, specified in the same format as the
\fB\-\-blur\-kerns\fR
option\&. Corresponds to the
\fB\-\-blur\-kerns\fR
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
SIGUSR1\&.
.RE
.SH "D\-BUS API"
.sp
It\(cqs possible to control picom via D\-Bus messages, by running picom with \fB\-\-dbus\fR 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\&.
.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
$ picom \-\-config /dev/null
.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, disable shadow on dock windows and drag\-and\-drop windows:
.sp
.if n \{\
.RS 4
.\}
.nf
$ picom \-cCGf
.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
$ picom \-bcCGf \-i 0\&.8 \-e 0\&.8 \-\-no\-fading\-openclose
.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
$ picom \-c \-\-shadow\-red 1 \-\-shadow\-green 1 \-\-shadow\-blue 1
.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
$ picom \-c \-\-shadow\-exclude \*(Aqclass_g = "wbar"\*(Aq
.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
$ picom \-\-backend glx \-\-vsync
.fi
.if n \{\
.RE
.\}
.RE
.SH "BUGS"
.sp
Please submit bug reports to https://github\&.com/allusive\-dev/picom\-allusive\&.
.sp
Out dated information in this man page is NOT considered a bug\&.
.SH "RESOURCES"
.sp
Website: https://allusive\&.dev
.sp
GithubPage: https://github\&.com/allusive\-dev/picom\-allusive