1PICOM(1) User Commands PICOM(1)
2
6 picom - a compositor for X11
7
9 picom [OPTIONS]
10
12 picom is a compositor based on Dana Jansens' version of xcompmgr (which
13 itself was written by Keith Packard). It includes some improvements
14 over the original xcompmgr, like window frame opacity and inactive
15 window transparency.
16
18 -h, --help
19 Get the usage text embedded in program code, which may be more
20 up-to-date than this man page.
21 -r, --shadow-radius=RADIUS
23 The blur radius for shadows, in pixels. (defaults to 12)
24 -o, --shadow-opacity=OPACITY
26 The opacity of shadows. (0.0 - 1.0, defaults to 0.75)
27 -l, --shadow-offset-x=OFFSET
29 The left offset for shadows, in pixels. (defaults to -15)
30 -t, --shadow-offset-y=OFFSET
32 The top offset for shadows, in pixels. (defaults to -15)
33 -I, --fade-in-step=OPACITY_STEP
35 Opacity change between steps while fading in. (0.01 - 1.0, defaults
36 to 0.028)
37 -O, --fade-out-step=OPACITY_STEP
39 Opacity change between steps while fading out. (0.01 - 1.0,
40 defaults to 0.03)
41 -D, --fade-delta=MILLISECONDS
43 The time between steps in fade step, in milliseconds. (> 0,
44 defaults to 10)
45 -c, --shadow
47 Enabled client-side shadows on windows. Note desktop windows
48 (windows with _NET_WM_WINDOW_TYPE_DESKTOP) never get shadow, unless
49 explicitly requested using the wintypes option.
50 -f, --fading
52 Fade windows in/out when opening/closing and when opacity changes,
53 unless --no-fading-openclose is used.
54 -F
56 Equals to -f. Deprecated.
57 -i, --inactive-opacity=OPACITY
59 Opacity of inactive windows. (0.1 - 1.0, defaults to 1.0)
60 -e, --frame-opacity=OPACITY
62 Opacity of window titlebars and borders. (0.1 - 1.0, disabled by
63 default)
64 -b, --daemon
66 Daemonize process. Fork to background after initialization. This
67 option can only be set from the command line, setting this in the
68 configuration file will have no effect.
69 --log-level
71 Set the log level. Possible values are "TRACE", "DEBUG", "INFO",
72 "WARN", "ERROR", in increasing level of importance. Case doesn’t
73 matter. If using the "TRACE" log level, it’s better to log into a
74 file using --log-file, since it can generate a huge stream of logs.
75 --log-file
77 Set the log file. If --log-file is never specified, logs will be
78 written to stderr. Otherwise, logs will to written to the given
79 file, though some of the early logs might still be written to the
80 stderr. When setting this option from the config file, it is
81 recommended to use an absolute path.
82 --experimental-backends
84 Use the new, reimplemented version of the backends. The new
85 backends are HIGHLY UNSTABLE at this point, you have been warned.
86 This option is not available in the config file.
87 --show-all-xerrors
89 Show all X errors (for debugging).
90 --config PATH
92 Look for configuration file at the path. See CONFIGURATION FILES
93 section below for where picom looks for a configuration file by
94 default. Use /dev/null to avoid loading configuration file.
95 --write-pid-path PATH
97 Write process ID to a file. it is recommended to use an absolute
98 path.
99 --shadow-color STRING
101 Color of shadow, as a hex string (#000000)
102 --shadow-red VALUE
104 Red color value of shadow (0.0 - 1.0, defaults to 0).
105 --shadow-green VALUE
107 Green color value of shadow (0.0 - 1.0, defaults to 0).
108 --shadow-blue VALUE
110 Blue color value of shadow (0.0 - 1.0, defaults to 0).
111 --inactive-opacity-override
113 Let inactive opacity set by -i override the _NET_WM_WINDOW_OPACITY
114 values of windows.
115 --active-opacity OPACITY
117 Default opacity for active windows. (0.0 - 1.0, defaults to 1.0)
118 --inactive-dim VALUE
120 Dim inactive windows. (0.0 - 1.0, defaults to 0.0)
121 --corner-radius VALUE
123 Sets the radius of rounded window corners. When > 0, the compositor
124 will round the corners of windows. Does not interact well with
125 --transparent-clipping. (defaults to 0).
126 --rounded-corners-exclude CONDITION
128 Exclude conditions for rounded corners.
129 --mark-wmwin-focused
131 Try to detect WM windows (a non-override-redirect window with no
132 child that has WM_STATE) and mark them as active.
133 --mark-ovredir-focused
135 Mark override-redirect windows that doesn’t have a child window
136 with WM_STATE focused.
137 --no-fading-openclose
139 Do not fade on window open/close.
140 --no-fading-destroyed-argb
142 Do not fade destroyed ARGB windows with WM frame. Workaround of
143 bugs in Openbox, Fluxbox, etc.
144 --shadow-ignore-shaped
146 Do not paint shadows on shaped windows. Note shaped windows here
147 means windows setting its shape through X Shape extension. Those
148 using ARGB background is beyond our control. Deprecated, use
149 --shadow-exclude 'bounding_shaped' or --shadow-exclude
150 'bounding_shaped && !rounded_corners' instead.
151 --detect-rounded-corners
153 Try to detect windows with rounded corners and don’t consider them
154 shaped windows. The accuracy is not very high, unfortunately.
155 --detect-client-opacity
157 Detect _NET_WM_WINDOW_OPACITY on client windows, useful for window
158 managers not passing _NET_WM_WINDOW_OPACITY of client windows to
159 frame windows.
160 --vsync, --no-vsync
162 Enable/disable VSync.
163 --use-ewmh-active-win
165 Use EWMH _NET_ACTIVE_WINDOW to determine currently focused window,
166 rather than listening to FocusIn/FocusOut event. Might have more
167 accuracy, provided that the WM supports it.
168 --unredir-if-possible
170 Unredirect all windows if a full-screen opaque window is detected,
171 to maximize performance for full-screen windows. Known to cause
172 flickering when redirecting/unredirecting windows.
173 --unredir-if-possible-delay MILLISECONDS
175 Delay before unredirecting the window, in milliseconds. Defaults to
176 0.
177 --unredir-if-possible-exclude CONDITION
179 Conditions of windows that shouldn’t be considered full-screen for
180 unredirecting screen.
181 --shadow-exclude CONDITION
183 Specify a list of conditions of windows that should have no shadow.
184 --clip-shadow-above CONDITION
186 Specify a list of conditions of windows that should have no shadow
187 painted over, such as a dock window.
188 --fade-exclude CONDITION
190 Specify a list of conditions of windows that should not be faded.
191 --focus-exclude CONDITION
193 Specify a list of conditions of windows that should always be
194 considered focused.
195 --inactive-dim-fixed
197 Use fixed inactive dim value, instead of adjusting according to
198 window opacity.
199 --detect-transient
201 Use WM_TRANSIENT_FOR to group windows, and consider windows in the
202 same group focused at the same time.
203 --detect-client-leader
205 Use WM_CLIENT_LEADER to group windows, and consider windows in the
206 same group focused at the same time. This usually means windows
207 from the same application will be considered focused or unfocused
208 at the same time.WM_TRANSIENT_FOR has higher priority if
209 --detect-transient is enabled, too.
210 --blur-method, --blur-size, --blur-deviation, --blur-strength
212 Parameters for background blurring, see the BLUR section for more
213 information.
214 --blur-background
216 Blur background of semi-transparent / ARGB windows. Bad in
217 performance, with driver-dependent behavior. The name of the switch
218 may change without prior notifications.
219 --blur-background-frame
221 Blur background of windows when the window frame is not opaque.
222 Implies --blur-background. Bad in performance, with
223 driver-dependent behavior. The name may change.
224 --blur-background-fixed
226 Use fixed blur strength rather than adjusting according to window
227 opacity.
228 --blur-kern MATRIX
230 Specify the blur convolution kernel, with the following format:
231 WIDTH,HEIGHT,ELE1,ELE2,ELE3,ELE4,ELE5...
233 In other words, the matrix is formatted as a list of comma
235 separated numbers. The first two numbers must be integers, which
236 specify the width and height of the matrix. They must be odd
237 numbers. Then, the following width * height - 1 numbers specifies
238 the numbers in the matrix, row by row, excluding the center
239 element.
240 The elements are finite floating point numbers. The decimal pointer
242 has to be . (a period), scientific notation is not supported.
243 The element in the center will either be 1.0 or varying based on
245 opacity, depending on whether you have --blur-background-fixed. Yet
246 the automatic adjustment of blur factor may not work well with a
247 custom blur kernel.
248 A 7x7 Gaussian blur kernel (sigma = 0.84089642) looks like:
250 --blur-kern '7,7,0.000003,0.000102,0.000849,0.001723,0.000849,0.000102,0.000003,0.000102,0.003494,0.029143,0.059106,0.029143,0.003494,0.000102,0.000849,0.029143,0.243117,0.493069,0.243117,0.029143,0.000849,0.001723,0.059106,0.493069,0.493069,0.059106,0.001723,0.000849,0.029143,0.243117,0.493069,0.243117,0.029143,0.000849,0.000102,0.003494,0.029143,0.059106,0.029143,0.003494,0.000102,0.000003,0.000102,0.000849,0.001723,0.000849,0.000102,0.000003'
252 May also be one of the predefined kernels: 3x3box (default),
254 5x5box, 7x7box, 3x3gaussian, 5x5gaussian, 7x7gaussian, 9x9gaussian,
255 11x11gaussian. All Gaussian kernels are generated with sigma =
256 0.84089642 . If you find yourself needing to generate custom blur
257 kernels, you might want to try the new blur configuration supported
258 by the experimental backends (See BLUR and
259 --experimental-backends).
260 --blur-background-exclude CONDITION
262 Exclude conditions for background blur.
263 --resize-damage INTEGER
265 Resize damaged region by a specific number of pixels. A positive
266 value enlarges it while a negative one shrinks it. If the value is
267 positive, those additional pixels will not be actually painted to
268 screen, only used in blur calculation, and such. (Due to technical
269 limitations, with --use-damage, those pixels will still be
270 incorrectly painted to screen.) Primarily used to fix the line
271 corruption issues of blur, in which case you should use the blur
272 radius value here (e.g. with a 3x3 kernel, you should use
273 --resize-damage 1, with a 5x5 one you use --resize-damage 2, and so
274 on). May or may not work with --glx-no-stencil. Shrinking doesn’t
275 function correctly.
276 --invert-color-include CONDITION
278 Specify a list of conditions of windows that should be painted with
279 inverted color. Resource-hogging, and is not well tested.
280 --opacity-rule OPACITY:'CONDITION'
282 Specify a list of opacity rules, in the format PERCENT:PATTERN,
283 like 50:name *= "Firefox". picom-trans is recommended over this.
284 Note we don’t make any guarantee about possible conflicts with
285 other programs that set _NET_WM_WINDOW_OPACITY on frame or client
286 windows.
287 --shadow-exclude-reg GEOMETRY
289 Specify a X geometry that describes the region in which shadow
290 should not be painted in, such as a dock window region. Use
291 --shadow-exclude-reg x10+0-0, for example, if the 10 pixels on the
292 bottom of the screen should not have shadows painted on.
293 --xinerama-shadow-crop
295 Crop shadow of a window fully on a particular Xinerama screen to
296 the screen.
297 --backend BACKEND
299 Specify the backend to use: xrender, glx, or xr_glx_hybrid.
300 xrender is the default one.
301 • xrender backend performs all rendering operations with X Render
303 extension. It is what xcompmgr uses, and is generally a safe
304 fallback when you encounter rendering artifacts or instability.
305 • glx (OpenGL) backend performs all rendering operations with
307 OpenGL. It is more friendly to some VSync methods, and has
308 significantly superior performance on color inversion
309 (--invert-color-include) or blur (--blur-background). It
310 requires proper OpenGL 2.0 support from your driver and
311 hardware. You may wish to look at the GLX performance
312 optimization options below. --xrender-sync-fence might be
313 needed on some systems to avoid delay in changes of screen
314 contents.
315 • xr_glx_hybrid backend renders the updated screen contents with
317 X Render and presents it on the screen with GLX. It attempts to
318 address the rendering issues some users encountered with GLX
319 backend and enables the better VSync of GLX backends.
320 --vsync-use-glfinish might fix some rendering issues with this
321 backend.
322 --glx-no-stencil
324 GLX backend: Avoid using stencil buffer, useful if you don’t have a
325 stencil buffer. Might cause incorrect opacity when rendering
326 transparent content (but never practically happened) and may not
327 work with --blur-background. My tests show a 15% performance boost.
328 Recommended.
329 --glx-no-rebind-pixmap
331 GLX backend: Avoid rebinding pixmap on window damage. Probably
332 could improve performance on rapid window content changes, but is
333 known to break things on some drivers (LLVMpipe, xf86-video-intel,
334 etc.). Recommended if it works.
335 --no-use-damage
337 Disable the use of damage information. This cause the whole screen
338 to be redrawn everytime, instead of the part of the screen has
339 actually changed. Potentially degrades the performance, but might
340 fix some artifacts.
341 --xrender-sync-fence
343 Use X Sync fence to sync clients' draw calls, to make sure all draw
344 calls are finished before picom starts drawing. Needed on
345 nvidia-drivers with GLX backend for some users.
346 --glx-fshader-win SHADER
348 GLX backend: Use specified GLSL fragment shader for rendering
349 window contents. See compton-default-fshader-win.glsl and
350 compton-fake-transparency-fshader-win.glsl in the source tree for
351 examples.
352 --force-win-blend
354 Force all windows to be painted with blending. Useful if you have a
355 --glx-fshader-win that could turn opaque pixels transparent.
356 --dbus
358 Enable remote control via D-Bus. See the D-BUS API section below
359 for more details.
360 --benchmark CYCLES
362 Benchmark mode. Repeatedly paint until reaching the specified
363 cycles.
364 --benchmark-wid WINDOW_ID
366 Specify window ID to repaint in benchmark mode. If omitted or is 0,
367 the whole screen is repainted.
368 --no-ewmh-fullscreen
370 Do not use EWMH to detect fullscreen windows. Reverts to checking
371 if a window is fullscreen based only on its size and coordinates.
372 --max-brightness
374 Dimming bright windows so their brightness doesn’t exceed this set
375 value. Brightness of a window is estimated by averaging all pixels
376 in the window, so this could comes with a performance hit. Setting
377 this to 1.0 disables this behaviour. Requires --use-damage to be
378 disabled. (default: 1.0)
379 --transparent-clipping
381 Make transparent windows clip other windows like non-transparent
382 windows do, instead of blending on top of them.
383
385 Some options accept a condition string to match certain windows. A
386 condition string is formed by one or more conditions, joined by logical
387 operators.
388 A condition with "exists" operator looks like this:
390 <NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE>
392 With equals operator it looks like:
394 <NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE> <NEGATION> <OP QUALIFIER> <MATCH TYPE> = <PATTERN>
396 With greater-than/less-than operators it looks like:
398 <NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE> <NEGATION> <OPERATOR> <PATTERN>
400 NEGATION (optional) is one or more exclamation marks;
402 TARGET is either a predefined target name, or the name of a window
404 property to match. Supported predefined targets are id, x, y, x2 (x +
405 widthb), y2 (like x2), width, height, widthb (width + 2 *
406 border_width), heightb (like widthb), border_width, fullscreen,
407 override_redirect, argb (whether the window has an ARGB visual),
408 focused, wmwin (whether the window looks like a WM window, i.e. has no
409 child window with WM_STATE and is not override-redirected),
410 bounding_shaped, rounded_corners (requires --detect-rounded-corners),
411 client (ID of client window), window_type (window type in string),
412 leader (ID of window leader), name, class_g (= WM_CLASS[1]), class_i (=
413 WM_CLASS[0]), and role.
414 CLIENT/FRAME is a single @ if the window attribute should be be looked
416 up on client window, nothing if on frame window;
417 INDEX (optional) is the index number of the property to look up. For
419 example, [2] means look at the third value in the property. If not
420 specified, the first value (index [0]) is used implicitly. Use the
421 special value [*] to perform matching against all available property
422 values using logical OR. Do not specify it for predefined targets.
423 FORMAT (optional) specifies the format of the property, 8, 16, or 32.
425 On absence we use format X reports. Do not specify it for predefined or
426 string targets.
427 TYPE is a single character representing the type of the property to
429 match for: c for CARDINAL, a for ATOM, w for WINDOW, d for DRAWABLE, s
430 for STRING (and any other string types, such as UTF8_STRING). Do not
431 specify it for predefined targets.
432 OP QUALIFIER (optional), applicable only for equals operator, could be
434 ? (ignore-case).
435 MATCH TYPE (optional), applicable only for equals operator, could be
437 nothing (exact match), * (match anywhere), ^ (match from start), %
438 (wildcard), or ~ (PCRE regular expression).
439 OPERATOR is one of = (equals), <, >, <=, =>, or nothing (exists).
441 Exists operator checks whether a property exists on a window (but for
442 predefined targets, exists means != 0 then).
443 PATTERN is either an integer or a string enclosed by single or double
445 quotes. Python-3-style escape sequences and raw string are supported in
446 the string format.
447 Supported logical operators are && (and) and || (or). && has higher
449 precedence than ||, left-to-right associativity. Use parentheses to
450 change precedence.
451 Examples:
453 # If the window is focused
455 focused
456 focused = 1
457 # If the window is not override-redirected
458 !override_redirect
459 override_redirect = false
460 override_redirect != true
461 override_redirect != 1
462 # If the window is a menu
463 window_type *= "menu"
464 _NET_WM_WINDOW_TYPE@:a *= "MENU"
465 # If the window is marked hidden: _NET_WM_STATE contains _NET_WM_STATE_HIDDEN
466 _NET_WM_STATE@[*]:a = "_NET_WM_STATE_HIDDEN"
467 # If the window is marked sticky: _NET_WM_STATE contains an atom that contains
468 # "sticky", ignore case
469 _NET_WM_STATE@[*]:a *?= "sticky"
470 # If the window name contains "Firefox", ignore case
471 name *?= "Firefox"
472 _NET_WM_NAME@:s *?= "Firefox"
473 # If the window name ends with "Firefox"
474 name %= "*Firefox"
475 name ~= "Firefox$"
476 # If the window has a property _COMPTON_SHADOW with value 0, type CARDINAL,
477 # format 32, value 0, on its frame window
478 _COMPTON_SHADOW:32c = 0
479 # If the third value of _NET_FRAME_EXTENTS is less than 20, or there's no
480 # _NET_FRAME_EXTENTS property on client window
481 _NET_FRAME_EXTENTS@[2]:32c < 20 || !_NET_FRAME_EXTENTS@:32c
482 # The pattern here will be parsed as "dd4"
483 name = "\x64\x64\o64"
484 # The pattern here will be parsed as "\x64\x64\x64"
485 name = r"\x64\x64\o64"
486
488 This is the old condition format we once used. Support of this format
489 might be removed in the future.
490 condition = TARGET:TYPE[FLAGS]:PATTERN
492 TARGET is one of "n" (window name), "i" (window class instance), "g"
494 (window general class), and "r" (window role).
495 TYPE is one of "e" (exact match), "a" (match anywhere), "s" (match from
497 start), "w" (wildcard), and "p" (PCRE regular expressions, if compiled
498 with the support).
499 FLAGS could be a series of flags. Currently the only defined flag is
501 "i" (ignore case).
502 PATTERN is the actual pattern string.
504
506 picom could read from a configuration file if libconfig support is
507 compiled in. If --config is not used, picom will seek for a
508 configuration file in $XDG_CONFIG_HOME/picom.conf
509 (~/.config/picom.conf, usually), then
510 $XDG_CONFIG_HOME/picom/picom.conf, then $XDG_CONFIG_DIRS/picom.conf
511 (often /etc/xdg/picom.conf), then $XDG_CONFIG_DIRS/picom/picom.conf.
512 picom uses general libconfig configuration file format. A sample
514 configuration file is available as picom.sample.conf in the source
515 tree. Most of commandline switches can be used as options in
516 configuration file as well. For example, --vsync option documented
517 above can be set in the configuration file using `vsync = `. Command
518 line options will always overwrite the settings in the configuration
519 file.
520 Window-type-specific settings are exposed only in configuration file
522 and has the following format:
523 wintypes:
525 {
526 WINDOW_TYPE = { fade = BOOL; shadow = BOOL; opacity = FLOAT; focus = BOOL; blur-background = BOOL; full-shadow = BOOL; clip-shadow-above = BOOL; redir-ignore = BOOL; };
527 };
528 WINDOW_TYPE is one of the 15 window types defined in EWMH standard:
530 "unknown", "desktop", "dock", "toolbar", "menu", "utility", "splash",
531 "dialog", "normal", "dropdown_menu", "popup_menu", "tooltip",
532 "notification", "combo", and "dnd".
533 Following per window-type options are available:
535 fade, shadow
537 Controls window-type-specific shadow and fade settings.
538 opacity
540 Controls default opacity of the window type.
541 focus
543 Controls whether the window of this type is to be always
544 considered focused. (By default, all window types except
545 "normal" and "dialog" has this on.)
546 blur-background
548 Controls wether the window of this type will have its
549 transparent background blurred.
550 full-shadow
552 Controls whether shadow is drawn under the parts of the window
553 that you normally won’t be able to see. Useful when the window
554 has parts of it transparent, and you want shadows in those
555 areas.
556 clip-shadow-above
558 Controls wether shadows that would have been drawn above the
559 window should be clipped. Useful for dock windows that should
560 have no shadow painted on top.
561 redir-ignore
563 Controls whether this type of windows should cause screen to
564 become redirected again after been unredirected. If you have
565 --unredir-if-possible set, and doesn’t want certain window to
566 cause unnecessary screen redirection, you can set this to true.
567
569 You can configure how the window background is blurred using a blur
570 section in your configuration file. Here is an example:
571 blur:
573 {
574 method = "gaussian";
575 size = 10;
576 deviation = 5.0;
577 };
578 Available options of the blur section are:
580 method
582 A string. Controls the blur method. Corresponds to the
583 --blur-method command line option. Available choices are: none
584 to disable blurring; gaussian for gaussian blur; box for box
585 blur; kernel for convolution blur with a custom kernel;
586 dual_kawase for dual-filter kawase blur. Note: gaussian, box
587 and dual_kawase blur methods are only supported by the
588 experimental backends. (default: none)
589 size
591 An integer. The size of the blur kernel, required by gaussian
592 and box blur methods. For the kernel method, the size is
593 included in the kernel. Corresponds to the --blur-size command
594 line option (default: 3).
595 deviation
597 A floating point number. The standard deviation for the
598 gaussian blur method. Corresponds to the --blur-deviation
599 command line option (default: 0.84089642).
600 strength
602 An integer in the range 0-20. The strength of the dual_kawase
603 blur method. Corresponds to the --blur-strength command line
604 option. If set to zero, the value requested by --blur-size is
605 approximated (default: 5).
606 kernel
608 A string. The kernel to use for the kernel blur method,
609 specified in the same format as the --blur-kerns option.
610 Corresponds to the --blur-kerns command line option.
611
613 • picom reinitializes itself upon receiving SIGUSR1.
614
616 It’s possible to control picom via D-Bus messages, by running picom
617 with --dbus and send messages to com.github.chjj.compton.<DISPLAY>.
618 <DISPLAY> is the display used by picom, with all non-alphanumeric
619 characters transformed to underscores. For DISPLAY=:0.0 you should use
620 com.github.chjj.compton._0_0, for example.
621 The D-Bus methods and signals are not yet stable, thus undocumented
623 right now.
624
626 • Disable configuration file parsing:
627 $ picom --config /dev/null
629 • Run picom with client-side shadow and fading:
631 $ picom -cf
633 • Same thing as above, plus making inactive windows 80% transparent,
635 making frame 80% transparent, don’t fade on window open/close, and
636 fork to background:
637 $ picom -bcf -i 0.8 -e 0.8 --no-fading-openclose
639 • Draw white shadows:
641 $ picom -c --shadow-red 1 --shadow-green 1 --shadow-blue 1
643 • Avoid drawing shadows on wbar window:
645 $ picom -c --shadow-exclude 'class_g = "wbar"'
647 • Enable VSync with GLX backend:
649 $ picom --backend glx --vsync
651
653 Please submit bug reports to https://github.com/yshui/picom.
654 Out dated information in this man page is considered a bug.
656
658 Homepage: https://github.com/yshui/picom
659
661 xcompmgr(1), picom-trans(1)
662picom v9.1 02/14/2022 PICOM(1)