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 -m, --menu-opacity=OPACITY
47 Default opacity for dropdown menus and popup menus. (0.0 - 1.0,
48 defaults to 1.0)
49 -c, --shadow
51 Enabled client-side shadows on windows. Note desktop windows
52 (windows with _NET_WM_WINDOW_TYPE_DESKTOP) never get shadow, unless
53 explicitly requested using the wintypes option.
54 -C, --no-dock-shadow
56 Avoid drawing shadows on dock/panel windows. This option is
57 deprecated, you should use the wintypes option in your config file
58 instead.
59 -f, --fading
61 Fade windows in/out when opening/closing and when opacity changes,
62 unless --no-fading-openclose is used.
63 -F
65 Equals to -f. Deprecated.
66 -i, --inactive-opacity=OPACITY
68 Opacity of inactive windows. (0.1 - 1.0, defaults to 1.0)
69 -e, --frame-opacity=OPACITY
71 Opacity of window titlebars and borders. (0.1 - 1.0, disabled by
72 default)
73 -G, --no-dnd-shadow
75 Don’t draw shadows on drag-and-drop windows. This option is
76 deprecated, you should use the wintypes option in your config file
77 instead.
78 -b, --daemon
80 Daemonize process. Fork to background after initialization. Causes
81 issues with certain (badly-written) drivers.
82 --log-level
84 Set the log level. Possible values are "TRACE", "DEBUG", "INFO",
85 "WARN", "ERROR", in increasing level of importance. Case doesn’t
86 matter. If using the "TRACE" log level, it’s better to log into a
87 file using --log-file, since it can generate a huge stream of logs.
88 --log-file
90 Set the log file. If --log-file is never specified, logs will be
91 written to stderr. Otherwise, logs will to written to the given
92 file, though some of the early logs might still be written to the
93 stderr. When setting this option from the config file, it is
94 recommended to use an absolute path.
95 --experimental-backends
97 Use the new, reimplemented version of the backends. The new
98 backends are HIGHLY UNSTABLE at this point, you have been warned.
99 This option is not available in the config file.
100 --show-all-xerrors
102 Show all X errors (for debugging).
103 --config PATH
105 Look for configuration file at the path. See CONFIGURATION FILES
106 section below for where picom looks for a configuration file by
107 default. Use /dev/null to avoid loading configuration file.
108 --write-pid-path PATH
110 Write process ID to a file.
111 --shadow-red VALUE
113 Red color value of shadow (0.0 - 1.0, defaults to 0).
114 --shadow-green VALUE
116 Green color value of shadow (0.0 - 1.0, defaults to 0).
117 --shadow-blue VALUE
119 Blue color value of shadow (0.0 - 1.0, defaults to 0).
120 --inactive-opacity-override
122 Let inactive opacity set by -i overrides the windows'
123 _NET_WM_OPACITY values.
124 --active-opacity OPACITY
126 Default opacity for active windows. (0.0 - 1.0, defaults to 1.0)
127 --inactive-dim VALUE
129 Dim inactive windows. (0.0 - 1.0, defaults to 0.0)
130 --mark-wmwin-focused
132 Try to detect WM windows (a non-override-redirect window with no
133 child that has WM_STATE) and mark them as active.
134 --mark-ovredir-focused
136 Mark override-redirect windows that doesn’t have a child window
137 with WM_STATE focused.
138 --no-fading-openclose
140 Do not fade on window open/close.
141 --no-fading-destroyed-argb
143 Do not fade destroyed ARGB windows with WM frame. Workaround of
144 bugs in Openbox, Fluxbox, etc.
145 --shadow-ignore-shaped
147 Do not paint shadows on shaped windows. Note shaped windows here
148 means windows setting its shape through X Shape extension. Those
149 using ARGB background is beyond our control. Deprecated, use
150 --shadow-exclude 'bounding_shaped' or --shadow-exclude
151 'bounding_shaped && !rounded_corners' instead.
152 --detect-rounded-corners
154 Try to detect windows with rounded corners and don’t consider them
155 shaped windows. The accuracy is not very high, unfortunately.
156 --detect-client-opacity
158 Detect _NET_WM_OPACITY on client windows, useful for window
159 managers not passing _NET_WM_OPACITY of client windows to frame
160 windows.
161 --refresh-rate REFRESH_RATE
163 Specify refresh rate of the screen. If not specified or 0, picom
164 will try detecting this with X RandR extension.
165 --vsync
167 Enable VSync.
168 --sw-opti
170 Limit picom to repaint at most once every 1 / refresh_rate second
171 to boost performance. This should not be used with --vsync
172 drm/opengl/opengl-oml as they essentially does --sw-opti's job
173 already, unless you wish to specify a lower refresh rate than the
174 actual value.
175 --use-ewmh-active-win
177 Use EWMH _NET_ACTIVE_WINDOW to determine currently focused window,
178 rather than listening to FocusIn/FocusOut event. Might have more
179 accuracy, provided that the WM supports it.
180 --respect-prop-shadow
182 Respect _COMPTON_SHADOW. This a prototype-level feature, which you
183 must not rely on.
184 --unredir-if-possible
186 Unredirect all windows if a full-screen opaque window is detected,
187 to maximize performance for full-screen windows. Known to cause
188 flickering when redirecting/unredirecting windows.
189 --paint-on-overlay may make the flickering less obvious.
190 --unredir-if-possible-delay MILLISECONDS
192 Delay before unredirecting the window, in milliseconds. Defaults to
193 0.
194 --unredir-if-possible-exclude CONDITION
196 Conditions of windows that shouldn’t be considered full-screen for
197 unredirecting screen.
198 --shadow-exclude CONDITION
200 Specify a list of conditions of windows that should have no shadow.
201 --fade-exclude CONDITION
203 Specify a list of conditions of windows that should not be faded.
204 --focus-exclude CONDITION
206 Specify a list of conditions of windows that should always be
207 considered focused.
208 --inactive-dim-fixed
210 Use fixed inactive dim value, instead of adjusting according to
211 window opacity.
212 --detect-transient
214 Use WM_TRANSIENT_FOR to group windows, and consider windows in the
215 same group focused at the same time.
216 --detect-client-leader
218 Use WM_CLIENT_LEADER to group windows, and consider windows in the
219 same group focused at the same time. WM_TRANSIENT_FOR has higher
220 priority if --detect-transient is enabled, too.
221 --blur-method, --blur-size, --blur-deviation
223 Parameters for background blurring, see the BLUR section for more
224 information.
225 --blur-background
227 Blur background of semi-transparent / ARGB windows. Bad in
228 performance, with driver-dependent behavior. The name of the switch
229 may change without prior notifications.
230 --blur-background-frame
232 Blur background of windows when the window frame is not opaque.
233 Implies --blur-background. Bad in performance, with
234 driver-dependent behavior. The name may change.
235 --blur-background-fixed
237 Use fixed blur strength rather than adjusting according to window
238 opacity.
239 --blur-kern MATRIX
241 Specify the blur convolution kernel, with the following format:
242 WIDTH,HEIGHT,ELE1,ELE2,ELE3,ELE4,ELE5...
244 In other words, the matrix is formatted as a list of comma
246 separated numbers. The first two numbers must be integers, which
247 specify the width and height of the matrix. They must be odd
248 numbers. Then, the following width * height - 1 numbers specifies
249 the numbers in the matrix, row by row, excluding the center
250 element.
251 The elements are finite floating point numbers. The decimal pointer
253 has to be . (a period), scientific notation is not supported.
254 The element in the center will either be 1.0 or varying based on
256 opacity, depending on whether you have --blur-background-fixed. Yet
257 the automatic adjustment of blur factor may not work well with a
258 custom blur kernel.
259 A 7x7 Gaussian blur kernel (sigma = 0.84089642) looks like:
261 --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'
263 May also be one of the predefined kernels: 3x3box (default),
265 5x5box, 7x7box, 3x3gaussian, 5x5gaussian, 7x7gaussian, 9x9gaussian,
266 11x11gaussian. All Gaussian kernels are generated with sigma =
267 0.84089642 . You may use the accompanied compton-convgen.py to
268 generate blur kernels.
269 --blur-background-exclude CONDITION
271 Exclude conditions for background blur.
272 --resize-damage INTEGER
274 Resize damaged region by a specific number of pixels. A positive
275 value enlarges it while a negative one shrinks it. If the value is
276 positive, those additional pixels will not be actually painted to
277 screen, only used in blur calculation, and such. (Due to technical
278 limitations, with --use-damage, those pixels will still be
279 incorrectly painted to screen.) Primarily used to fix the line
280 corruption issues of blur, in which case you should use the blur
281 radius value here (e.g. with a 3x3 kernel, you should use
282 --resize-damage 1, with a 5x5 one you use --resize-damage 2, and so
283 on). May or may not work with --glx-no-stencil. Shrinking doesn’t
284 function correctly.
285 --invert-color-include CONDITION
287 Specify a list of conditions of windows that should be painted with
288 inverted color. Resource-hogging, and is not well tested.
289 --opacity-rule OPACITY:'CONDITION'
291 Specify a list of opacity rules, in the format PERCENT:PATTERN,
292 like 50:name *= "Firefox". picom-trans is recommended over this.
293 Note we don’t make any guarantee about possible conflicts with
294 other programs that set _NET_WM_WINDOW_OPACITY on frame or client
295 windows.
296 --shadow-exclude-reg GEOMETRY
298 Specify a X geometry that describes the region in which shadow
299 should not be painted in, such as a dock window region. Use
300 --shadow-exclude-reg x10+0-0, for example, if the 10 pixels on the
301 bottom of the screen should not have shadows painted on.
302 --xinerama-shadow-crop
304 Crop shadow of a window fully on a particular Xinerama screen to
305 the screen.
306 --backend BACKEND
308 Specify the backend to use: xrender, glx, or xr_glx_hybrid.
309 xrender is the default one.
310 · xrender backend performs all rendering operations with X Render
312 extension. It is what xcompmgr uses, and is generally a safe
313 fallback when you encounter rendering artifacts or instability.
314 · glx (OpenGL) backend performs all rendering operations with
316 OpenGL. It is more friendly to some VSync methods, and has
317 significantly superior performance on color inversion
318 (--invert-color-include) or blur (--blur-background). It
319 requires proper OpenGL 2.0 support from your driver and
320 hardware. You may wish to look at the GLX performance
321 optimization options below. --xrender-sync-fence might be
322 needed on some systems to avoid delay in changes of screen
323 contents.
324 · xr_glx_hybrid backend renders the updated screen contents with
326 X Render and presents it on the screen with GLX. It attempts to
327 address the rendering issues some users encountered with GLX
328 backend and enables the better VSync of GLX backends.
329 --vsync-use-glfinish might fix some rendering issues with this
330 backend.
331 --glx-no-stencil
333 GLX backend: Avoid using stencil buffer, useful if you don’t have a
334 stencil buffer. Might cause incorrect opacity when rendering
335 transparent content (but never practically happened) and may not
336 work with --blur-background. My tests show a 15% performance boost.
337 Recommended.
338 --glx-no-rebind-pixmap
340 GLX backend: Avoid rebinding pixmap on window damage. Probably
341 could improve performance on rapid window content changes, but is
342 known to break things on some drivers (LLVMpipe, xf86-video-intel,
343 etc.). Recommended if it works.
344 --use-damage
346 Use the damage information to limit rendering to parts of the
347 screen that has actually changed. Potentially improves the
348 performance.
349 --xrender-sync-fence
351 Use X Sync fence to sync clients' draw calls, to make sure all draw
352 calls are finished before picom starts drawing. Needed on
353 nvidia-drivers with GLX backend for some users.
354 --glx-fshader-win SHADER
356 GLX backend: Use specified GLSL fragment shader for rendering
357 window contents. See compton-default-fshader-win.glsl and
358 compton-fake-transparency-fshader-win.glsl in the source tree for
359 examples.
360 --force-win-blend
362 Force all windows to be painted with blending. Useful if you have a
363 --glx-fshader-win that could turn opaque pixels transparent.
364 --dbus
366 Enable remote control via D-Bus. See the D-BUS API section below
367 for more details.
368 --benchmark CYCLES
370 Benchmark mode. Repeatedly paint until reaching the specified
371 cycles.
372 --benchmark-wid WINDOW_ID
374 Specify window ID to repaint in benchmark mode. If omitted or is 0,
375 the whole screen is repainted.
376
378 Some options accept a condition string to match certain windows. A
379 condition string is formed by one or more conditions, joined by logical
380 operators.
381 A condition with "exists" operator looks like this:
383 <NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE>
385 With equals operator it looks like:
387 <NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE> <NEGATION> <OP QUALIFIER> <MATCH TYPE> = <PATTERN>
389 With greater-than/less-than operators it looks like:
391 <NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE> <NEGATION> <OPERATOR> <PATTERN>
393 NEGATION (optional) is one or more exclamation marks;
395 TARGET is either a predefined target name, or the name of a window
397 property to match. Supported predefined targets are id, x, y, x2 (x +
398 widthb), y2, width, height, widthb (width + 2 * border_width), heightb,
399 override_redirect, argb (whether the window has an ARGB visual),
400 focused, wmwin (whether the window looks like a WM window, i.e. has no
401 child window with WM_STATE and is not override-redirected),
402 bounding_shaped, rounded_corners (requires --detect-rounded-corners),
403 client (ID of client window), window_type (window type in string),
404 leader (ID of window leader), name, class_g (= WM_CLASS[1]), class_i (=
405 WM_CLASS[0]), and role.
406 CLIENT/FRAME is a single @ if the window attribute should be be looked
408 up on client window, nothing if on frame window;
409 INDEX (optional) is the index number of the property to look up. For
411 example, [2] means look at the third value in the property. Do not
412 specify it for predefined targets.
413 FORMAT (optional) specifies the format of the property, 8, 16, or 32.
415 On absence we use format X reports. Do not specify it for predefined or
416 string targets.
417 TYPE is a single character representing the type of the property to
419 match for: c for CARDINAL, a for ATOM, w for WINDOW, d for DRAWABLE, s
420 for STRING (and any other string types, such as UTF8_STRING). Do not
421 specify it for predefined targets.
422 OP QUALIFIER (optional), applicable only for equals operator, could be
424 ? (ignore-case).
425 MATCH TYPE (optional), applicable only for equals operator, could be
427 nothing (exact match), * (match anywhere), ^ (match from start), %
428 (wildcard), or ~ (PCRE regular expression).
429 OPERATOR is one of = (equals), <, >, <=, =>, or nothing (exists).
431 Exists operator checks whether a property exists on a window (but for
432 predefined targets, exists means != 0 then).
433 PATTERN is either an integer or a string enclosed by single or double
435 quotes. Python-3-style escape sequences and raw string are supported in
436 the string format.
437 Supported logical operators are && (and) and || (or). && has higher
439 precedence than ||, left-to-right associativity. Use parentheses to
440 change precedence.
441 Examples:
443 # If the window is focused
445 focused
446 focused = 1
447 # If the window is not override-redirected
448 !override_redirect
449 override_redirect = false
450 override_redirect != true
451 override_redirect != 1
452 # If the window is a menu
453 window_type *= "menu"
454 _NET_WM_WINDOW_TYPE@:a *= "MENU"
455 # If the window name contains "Firefox", ignore case
456 name *?= "Firefox"
457 _NET_WM_NAME@:s *?= "Firefox"
458 # If the window name ends with "Firefox"
459 name %= "*Firefox"
460 name ~= "Firefox$"
461 # If the window has a property _COMPTON_SHADOW with value 0, type CARDINAL,
462 # format 32, value 0, on its frame window
463 _COMPTON_SHADOW:32c = 0
464 # If the third value of _NET_FRAME_EXTENTS is less than 20, or there's no
465 # _NET_FRAME_EXTENTS property on client window
466 _NET_FRAME_EXTENTS@[2]:32c < 20 || !_NET_FRAME_EXTENTS@:32c
467 # The pattern here will be parsed as "dd4"
468 name = "\x64\x64\o64"
469 # The pattern here will be parsed as "\x64\x64\x64"
470 name = r"\x64\x64\o64"
471
473 This is the old condition format we once used. Support of this format
474 might be removed in the future.
475 condition = TARGET:TYPE[FLAGS]:PATTERN
477 TARGET is one of "n" (window name), "i" (window class instance), "g"
479 (window general class), and "r" (window role).
480 TYPE is one of "e" (exact match), "a" (match anywhere), "s" (match from
482 start), "w" (wildcard), and "p" (PCRE regular expressions, if compiled
483 with the support).
484 FLAGS could be a series of flags. Currently the only defined flag is
486 "i" (ignore case).
487 PATTERN is the actual pattern string.
489
491 picom could read from a configuration file if libconfig support is
492 compiled in. If --config is not used, picom will seek for a
493 configuration file in $XDG_CONFIG_HOME/picom.conf
494 (~/.config/picom.conf, usually), then
495 $XDG_CONFIG_HOME/picom/picom.conf, then $XDG_CONFIG_DIRS/picom.conf
496 (often /etc/xdg/picom.conf), then $XDG_CONFIG_DIRS/picom/picom.conf.
497 picom uses general libconfig configuration file format. A sample
499 configuration file is available as picom.sample.conf in the source
500 tree. Most of commandline switches can be used as options in
501 configuration file as well. For example, --vsync option documented
502 above can be set in the configuration file using `vsync = `. Command
503 line options will always overwrite the settings in the configuration
504 file.
505 Window-type-specific settings are exposed only in configuration file
507 and has the following format:
508 wintypes:
510 {
511 WINDOW_TYPE = { fade = BOOL; shadow = BOOL; opacity = FLOAT; focus = BOOL; full-shadow = BOOL; redir-ignore = BOOL; };
512 };
513 WINDOW_TYPE is one of the 15 window types defined in EWMH standard:
515 "unknown", "desktop", "dock", "toolbar", "menu", "utility", "splash",
516 "dialog", "normal", "dropdown_menu", "popup_menu", "tooltip", "notify",
517 "combo", and "dnd".
518 Following per window-type options are available:
520 fade, shadow
522 Controls window-type-specific shadow and fade settings.
523 opacity
525 Controls default opacity of the window type.
526 focus
528 Controls whether the window of this type is to be always
529 considered focused. (By default, all window types except
530 "normal" and "dialog" has this on.)
531 full-shadow
533 Controls whether shadow is drawn under the parts of the window
534 that you normally won’t be able to see. Useful when the window
535 has parts of it transparent, and you want shadows in those
536 areas.
537 redir-ignore
539 Controls whether this type of windows should cause screen to
540 become redirected again after been unredirected. If you have
541 --unredir-if-possible set, and doesn’t want certain window to
542 cause unnecessary screen redirection, you can set this to true.
543
545 You can configure how the window background is blurred using a blur
546 section in your configuration file. Here is an example:
547 blur:
549 {
550 method = "gaussian";
551 size = 10;
552 deviation = 5.0;
553 };
554 Available options of the blur section are:
556 method
558 A string. Controls the blur method. Corresponds to the
559 --blur-method command line option. Available choices are: none
560 to disable blurring; gaussian for gaussian blur; box for box
561 blur; kernel for convolution blur with a custom kernel. Note:
562 gaussian and box blur methods are only supported by the
563 experimental backends.
564 size
566 An integer. The size of the blur kernel, required by gaussian
567 and box blur methods. For the kernel method, the size is
568 included in the kernel. Corresponds to the --blur-size command
569 line option.
570 deviation
572 A floating point number. The standard deviation for the
573 gaussian blur method. Corresponds to the --blur-deviation
574 command line option.
575 kernel
577 A string. The kernel to use for the kernel blur method,
578 specified in the same format as the --blur-kerns option.
579 Corresponds to the --blur-kerns command line option.
580
582 · picom reinitializes itself upon receiving SIGUSR1.
583
585 It’s possible to control picom via D-Bus messages, by running picom
586 with --dbus and send messages to com.github.chjj.compton.<DISPLAY>.
587 <DISPLAY> is the display used by picom, with all non-alphanumeric
588 characters transformed to underscores. For DISPLAY=:0.0 you should use
589 com.github.chjj.compton._0_0, for example.
590 The D-Bus methods and signals are not yet stable, thus undocumented
592 right now.
593
595 · Disable configuration file parsing:
596 $ picom --config /dev/null
598 · Run picom with client-side shadow and fading, disable shadow on
600 dock windows and drag-and-drop windows:
601 $ picom -cCGf
603 · Same thing as above, plus making inactive windows 80% transparent,
605 making frame 80% transparent, don’t fade on window open/close,
606 enable software optimization, and fork to background:
607 $ picom -bcCGf -i 0.8 -e 0.8 --no-fading-openclose --sw-opti
609 · Draw white shadows:
611 $ picom -c --shadow-red 1 --shadow-green 1 --shadow-blue 1
613 · Avoid drawing shadows on wbar window:
615 $ picom -c --shadow-exclude 'class_g = "wbar"'
617 · Enable VSync with GLX backend:
619 $ picom --backend glx --vsync
621
623 Please submit bug reports to https://github.com/yshui/picom.
624 Out dated information in this man page is considered a bug.
626
628 Homepage: https://github.com/yshui/picom
629
631 xcompmgr(1), picom-trans(1)
632picom v7.5 12/06/2019 PICOM(1)