1 '\" t
2 .\" Title: picom
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 11/11/2020
6 .\" Manual: User Commands
7 .\" Source: picom v8.2
8 .\" Language: English
9 .\"
10 .TH "PICOM" "1" "11/11/2020" "picom v8\&.2" "User Commands"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30
31
32 .SH "NAME"
33 picom \- a compositor for X11
34 .SH "SYNOPSIS"
35 .sp
36 \fBpicom\fR [\fIOPTIONS\fR]
37
38 .SH "DESCRIPTION"
39
40 .sp
41 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\&.
42
43 .SH "OPTIONS"
44
45
46
47 .PP
48 \fB\-h\fR, \fB\-\-help\fR
49 .RS 4
50
51
52
53 Get the usage text embedded in program code, which may be more up\-to\-date than this man page\&.
54
55 .RE
56 .PP
57 \fB\-r\fR, \fB\-\-shadow\-radius\fR=\fIRADIUS\fR
58 .RS 4
59
60
61
62 The blur radius for shadows, in pixels\&. (defaults to 12)
63
64 .RE
65 .PP
66 \fB\-o\fR, \fB\-\-shadow\-opacity\fR=\fIOPACITY\fR
67 .RS 4
68
69
70
71 The opacity of shadows\&. (0\&.0 \- 1\&.0, defaults to 0\&.75)
72
73 .RE
74 .PP
75 \fB\-l\fR, \fB\-\-shadow\-offset\-x\fR=\fIOFFSET\fR
76 .RS 4
77
78
79
80 The left offset for shadows, in pixels\&. (defaults to \-15)
81
82 .RE
83 .PP
84 \fB\-t\fR, \fB\-\-shadow\-offset\-y\fR=\fIOFFSET\fR
85 .RS 4
86
87
88
89 The top offset for shadows, in pixels\&. (defaults to \-15)
90
91 .RE
92 .PP
93 \fB\-I\fR, \fB\-\-fade\-in\-step\fR=\fIOPACITY_STEP\fR
94 .RS 4
95
96
97
98 Opacity change between steps while fading in\&. (0\&.01 \- 1\&.0, defaults to 0\&.028)
99
100 .RE
101 .PP
102 \fB\-O\fR, \fB\-\-fade\-out\-step\fR=\fIOPACITY_STEP\fR
103 .RS 4
104
105
106
107 Opacity change between steps while fading out\&. (0\&.01 \- 1\&.0, defaults to 0\&.03)
108
109 .RE
110 .PP
111 \fB\-D\fR, \fB\-\-fade\-delta\fR=\fIMILLISECONDS\fR
112 .RS 4
113
114
115
116 The time between steps in fade step, in milliseconds\&. (> 0, defaults to 10)
117
118 .RE
119 .PP
120 \fB\-m\fR, \fB\-\-menu\-opacity\fR=\fIOPACITY\fR
121 .RS 4
122
123
124
125 Default opacity for dropdown menus and popup menus\&. (0\&.0 \- 1\&.0, defaults to 1\&.0)
126
127 .RE
128 .PP
129 \fB\-c\fR, \fB\-\-shadow\fR
130 .RS 4
131
132
133
134 Enabled client\-side shadows on windows\&. Note desktop windows (windows with
135 \fI_NET_WM_WINDOW_TYPE_DESKTOP\fR) never get shadow, unless explicitly requested using the wintypes option\&.
136
137 .RE
138 .PP
139 \fB\-C\fR, \fB\-\-no\-dock\-shadow\fR
140 .RS 4
141
142
143
144 Avoid drawing shadows on dock/panel windows\&. This option is deprecated, you should use the
145 \fBwintypes\fR
146 option in your config file instead\&.
147
148 .RE
149 .PP
150 \fB\-f\fR, \fB\-\-fading\fR
151 .RS 4
152
153
154
155 Fade windows in/out when opening/closing and when opacity changes, unless
156 \fB\-\-no\-fading\-openclose\fR
157 is used\&.
158
159 .RE
160 .PP
161 \fB\-F\fR
162 .RS 4
163
164
165
166 Equals to
167 \fB\-f\fR\&. Deprecated\&.
168
169 .RE
170 .PP
171 \fB\-i\fR, \fB\-\-inactive\-opacity\fR=\fIOPACITY\fR
172 .RS 4
173
174
175
176 Opacity of inactive windows\&. (0\&.1 \- 1\&.0, defaults to 1\&.0)
177
178 .RE
179 .PP
180 \fB\-e\fR, \fB\-\-frame\-opacity\fR=\fIOPACITY\fR
181 .RS 4
182
183
184
185 Opacity of window titlebars and borders\&. (0\&.1 \- 1\&.0, disabled by default)
186
187 .RE
188 .PP
189 \fB\-G\fR, \fB\-\-no\-dnd\-shadow\fR
190 .RS 4
191
192
193
194 Don\(cqt draw shadows on drag\-and\-drop windows\&. This option is deprecated, you should use the
195 \fBwintypes\fR
196 option in your config file instead\&.
197
198 .RE
199 .PP
200 \fB\-b\fR, \fB\-\-daemon\fR
201 .RS 4
202
203
204
205 Daemonize process\&. Fork to background after initialization\&. Causes issues with certain (badly\-written) drivers\&.
206
207 .RE
208 .PP
209 \fB\-\-log\-level\fR
210 .RS 4
211
212
213
214 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
215 \fB\-\-log\-file\fR, since it can generate a huge stream of logs\&.
216
217 .RE
218 .PP
219 \fB\-\-log\-file\fR
220 .RS 4
221
222
223
224 Set the log file\&. If
225 \fB\-\-log\-file\fR
226 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\&.
227
228 .RE
229 .PP
230 \fB\-\-experimental\-backends\fR
231 .RS 4
232
233
234
235 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\&.
236
237 .RE
238 .PP
239 \fB\-\-show\-all\-xerrors\fR
240 .RS 4
241
242
243
244 Show all X errors (for debugging)\&.
245
246 .RE
247 .PP
248 \fB\-\-config\fR \fIPATH\fR
249 .RS 4
250
251
252
253 Look for configuration file at the path\&. See
254 \fBCONFIGURATION FILES\fR
255 section below for where picom looks for a configuration file by default\&. Use
256 /dev/null
257 to avoid loading configuration file\&.
258
259 .RE
260 .PP
261 \fB\-\-write\-pid\-path\fR \fIPATH\fR
262 .RS 4
263
264
265
266 Write process ID to a file\&. it is recommended to use an absolute path\&.
267
268 .RE
269 .PP
270 \fB\-\-shadow\-red\fR \fIVALUE\fR
271 .RS 4
272
273
274
275 Red color value of shadow (0\&.0 \- 1\&.0, defaults to 0)\&.
276
277 .RE
278 .PP
279 \fB\-\-shadow\-green\fR \fIVALUE\fR
280 .RS 4
281
282
283
284 Green color value of shadow (0\&.0 \- 1\&.0, defaults to 0)\&.
285
286 .RE
287 .PP
288 \fB\-\-shadow\-blue\fR \fIVALUE\fR
289 .RS 4
290
291
292
293 Blue color value of shadow (0\&.0 \- 1\&.0, defaults to 0)\&.
294
295 .RE
296 .PP
297 \fB\-\-inactive\-opacity\-override\fR
298 .RS 4
299
300
301
302 Let inactive opacity set by
303 \fB\-i\fR
304 override the
305 \fI_NET_WM_OPACITY\fR
306 values of windows\&.
307
308 .RE
309 .PP
310 \fB\-\-active\-opacity\fR \fIOPACITY\fR
311 .RS 4
312
313
314
315 Default opacity for active windows\&. (0\&.0 \- 1\&.0, defaults to 1\&.0)
316
317 .RE
318 .PP
319 \fB\-\-inactive\-dim\fR \fIVALUE\fR
320 .RS 4
321
322
323
324 Dim inactive windows\&. (0\&.0 \- 1\&.0, defaults to 0\&.0)
325
326 .RE
327 .PP
328 \fB\-\-mark\-wmwin\-focused\fR
329 .RS 4
330
331
332
333 Try to detect WM windows (a non\-override\-redirect window with no child that has
334 \fIWM_STATE\fR) and mark them as active\&.
335
336 .RE
337 .PP
338 \fB\-\-mark\-ovredir\-focused\fR
339 .RS 4
340
341
342
343 Mark override\-redirect windows that doesn\(cqt have a child window with
344 \fIWM_STATE\fR
345 focused\&.
346
347 .RE
348 .PP
349 \fB\-\-no\-fading\-openclose\fR
350 .RS 4
351
352
353
354 Do not fade on window open/close\&.
355
356 .RE
357 .PP
358 \fB\-\-no\-fading\-destroyed\-argb\fR
359 .RS 4
360
361
362
363 Do not fade destroyed ARGB windows with WM frame\&. Workaround of bugs in Openbox, Fluxbox, etc\&.
364
365 .RE
366 .PP
367 \fB\-\-shadow\-ignore\-shaped\fR
368 .RS 4
369
370
371
372 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
373 \-\-shadow\-exclude \*(Aqbounding_shaped\*(Aq
374 or
375 \-\-shadow\-exclude \*(Aqbounding_shaped && !rounded_corners\*(Aq
376 instead\&.
377
378 .RE
379 .PP
380 \fB\-\-detect\-rounded\-corners\fR
381 .RS 4
382
383
384
385 Try to detect windows with rounded corners and don\(cqt consider them shaped windows\&. The accuracy is not very high, unfortunately\&.
386
387 .RE
388 .PP
389 \fB\-\-detect\-client\-opacity\fR
390 .RS 4
391
392
393
394 Detect
395 \fI_NET_WM_OPACITY\fR
396 on client windows, useful for window managers not passing
397 \fI_NET_WM_OPACITY\fR
398 of client windows to frame windows\&.
399
400 .RE
401 .PP
402 \fB\-\-refresh\-rate\fR \fIREFRESH_RATE\fR
403 .RS 4
404
405
406
407 Specify refresh rate of the screen\&. If not specified or 0, picom will try detecting this with X RandR extension\&.
408
409 .RE
410 .PP
411 \fB\-\-vsync\fR, \fB\-\-no\-vsync\fR
412 .RS 4
413
414
415
416 Enable/disable VSync\&.
417
418 .RE
419 .PP
420 \fB\-\-sw\-opti\fR
421 .RS 4
422
423
424
425 Limit picom to repaint at most once every 1 /
426 \fIrefresh_rate\fR
427 second to boost performance\&. This should not be used with
428 \fB\-\-vsync\fR
429 drm/opengl/opengl\-oml as they essentially does
430 \fB\-\-sw\-opti\fR\*(Aqs job already, unless you wish to specify a lower refresh rate than the actual value\&.
431
432 .RE
433 .PP
434 \fB\-\-use\-ewmh\-active\-win\fR
435 .RS 4
436
437
438
439 Use EWMH
440 \fI_NET_ACTIVE_WINDOW\fR
441 to determine currently focused window, rather than listening to
442 \fIFocusIn\fR/\fIFocusOut\fR
443 event\&. Might have more accuracy, provided that the WM supports it\&.
444
445 .RE
446 .PP
447 \fB\-\-unredir\-if\-possible\fR
448 .RS 4
449
450
451
452 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\&.
453
454 .RE
455 .PP
456 \fB\-\-unredir\-if\-possible\-delay\fR \fIMILLISECONDS\fR
457 .RS 4
458
459
460
461 Delay before unredirecting the window, in milliseconds\&. Defaults to 0\&.
462
463 .RE
464 .PP
465 \fB\-\-unredir\-if\-possible\-exclude\fR \fICONDITION\fR
466 .RS 4
467
468
469
470 Conditions of windows that shouldn\(cqt be considered full\-screen for unredirecting screen\&.
471
472 .RE
473 .PP
474 \fB\-\-shadow\-exclude\fR \fICONDITION\fR
475 .RS 4
476
477
478
479 Specify a list of conditions of windows that should have no shadow\&.
480
481 .RE
482 .PP
483 \fB\-\-fade\-exclude\fR \fICONDITION\fR
484 .RS 4
485
486
487
488 Specify a list of conditions of windows that should not be faded\&.
489
490 .RE
491 .PP
492 \fB\-\-focus\-exclude\fR \fICONDITION\fR
493 .RS 4
494
495
496
497 Specify a list of conditions of windows that should always be considered focused\&.
498
499 .RE
500 .PP
501 \fB\-\-inactive\-dim\-fixed\fR
502 .RS 4
503
504
505
506 Use fixed inactive dim value, instead of adjusting according to window opacity\&.
507
508 .RE
509 .PP
510 \fB\-\-detect\-transient\fR
511 .RS 4
512
513
514
515 Use
516 \fIWM_TRANSIENT_FOR\fR
517 to group windows, and consider windows in the same group focused at the same time\&.
518
519 .RE
520 .PP
521 \fB\-\-detect\-client\-leader\fR
522 .RS 4
523
524
525
526 Use
527 \fIWM_CLIENT_LEADER\fR
528 to group windows, and consider windows in the same group focused at the same time\&.
529 \fIWM_TRANSIENT_FOR\fR
530 has higher priority if
531 \fB\-\-detect\-transient\fR
532 is enabled, too\&.
533
534 .RE
535 .PP
536 \fB\-\-blur\-method\fR, \fB\-\-blur\-size\fR, \fB\-\-blur\-deviation\fR
537 .RS 4
538
539
540
541 Parameters for background blurring, see the
542 \fBBLUR\fR
543 section for more information\&.
544
545 .RE
546 .PP
547 \fB\-\-blur\-background\fR
548 .RS 4
549
550
551
552 Blur background of semi\-transparent / ARGB windows\&. Bad in performance, with driver\-dependent behavior\&. The name of the switch may change without prior notifications\&.
553
554 .RE
555 .PP
556 \fB\-\-blur\-background\-frame\fR
557 .RS 4
558
559
560
561 Blur background of windows when the window frame is not opaque\&. Implies
562 \fB\-\-blur\-background\fR\&. Bad in performance, with driver\-dependent behavior\&. The name may change\&.
563
564 .RE
565 .PP
566 \fB\-\-blur\-background\-fixed\fR
567 .RS 4
568
569
570
571 Use fixed blur strength rather than adjusting according to window opacity\&.
572
573 .RE
574 .PP
575 \fB\-\-blur\-kern\fR \fIMATRIX\fR
576 .RS 4
577
578
579
580 Specify the blur convolution kernel, with the following format:
581
582 .sp
583 .if n \{\
584 .RS 4
585 .\}
586 .nf
587 WIDTH,HEIGHT,ELE1,ELE2,ELE3,ELE4,ELE5\&.\&.\&.
588 .fi
589 .if n \{\
590 .RE
591 .\}
592 .sp
593
594 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
595 \fIwidth * height \- 1\fR
596 numbers specifies the numbers in the matrix, row by row, excluding the center element\&.
597 .sp
598
599 The elements are finite floating point numbers\&. The decimal pointer has to be
600 \fI\&.\fR
601 (a period), scientific notation is not supported\&.
602 .sp
603
604 The element in the center will either be 1\&.0 or varying based on opacity, depending on whether you have
605 \fB\-\-blur\-background\-fixed\fR\&. Yet the automatic adjustment of blur factor may not work well with a custom blur kernel\&.
606 .sp
607
608 A 7x7 Gaussian blur kernel (sigma = 0\&.84089642) looks like:
609
610 .sp
611 .if n \{\
612 .RS 4
613 .\}
614 .nf
615 \-\-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
616 .fi
617 .if n \{\
618 .RE
619 .\}
620 .sp
621
622 May also be one of the predefined kernels:
623 3x3box
624 (default),
625 5x5box,
626 7x7box,
627 3x3gaussian,
628 5x5gaussian,
629 7x7gaussian,
630 9x9gaussian,
631 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
632 \fBBLUR\fR
633 and
634 \fB\-\-experimental\-backends\fR)\&.
635
636 .RE
637 .PP
638 \fB\-\-blur\-background\-exclude\fR \fICONDITION\fR
639 .RS 4
640
641
642
643 Exclude conditions for background blur\&.
644
645 .RE
646 .PP
647 \fB\-\-resize\-damage\fR \fIINTEGER\fR
648 .RS 4
649
650
651
652 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
653 \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
654 \-\-resize\-damage 1, with a 5x5 one you use
655 \-\-resize\-damage 2, and so on)\&. May or may not work with
656 \fB\-\-glx\-no\-stencil\fR\&. Shrinking doesn\(cqt function correctly\&.
657
658 .RE
659 .PP
660 \fB\-\-invert\-color\-include\fR \fICONDITION\fR
661 .RS 4
662
663
664
665 Specify a list of conditions of windows that should be painted with inverted color\&. Resource\-hogging, and is not well tested\&.
666
667 .RE
668 .PP
669 \fB\-\-opacity\-rule\fR \fIOPACITY\fR:\*(AqCONDITION\*(Aq
670 .RS 4
671
672
673
674 Specify a list of opacity rules, in the format
675 PERCENT:PATTERN, like
676 50:name *= "Firefox"\&. picom\-trans is recommended over this\&. Note we don\(cqt make any guarantee about possible conflicts with other programs that set
677 \fI_NET_WM_WINDOW_OPACITY\fR
678 on frame or client windows\&.
679
680 .RE
681 .PP
682 \fB\-\-shadow\-exclude\-reg\fR \fIGEOMETRY\fR
683 .RS 4
684
685
686
687 Specify a X geometry that describes the region in which shadow should not be painted in, such as a dock window region\&. Use
688 \-\-shadow\-exclude\-reg x10+0\-0, for example, if the 10 pixels on the bottom of the screen should not have shadows painted on\&.
689
690 .RE
691 .PP
692 \fB\-\-xinerama\-shadow\-crop\fR
693 .RS 4
694
695
696
697 Crop shadow of a window fully on a particular Xinerama screen to the screen\&.
698
699 .RE
700 .PP
701 \fB\-\-backend\fR \fIBACKEND\fR
702 .RS 4
703
704
705
706 Specify the backend to use:
707 xrender,
708 glx, or
709 xr_glx_hybrid\&.
710 xrender
711 is the default one\&.
712
713
714 .sp
715 .RS 4
716 .ie n \{\
717 \h'-04'\(bu\h'+03'\c
718 .\}
719 .el \{\
720 .sp -1
721 .IP \(bu 2.3
722 .\}
723
724 xrender
725 backend performs all rendering operations with X Render extension\&. It is what
726 xcompmgr
727 uses, and is generally a safe fallback when you encounter rendering artifacts or instability\&.
728 .RE
729 .sp
730 .RS 4
731 .ie n \{\
732 \h'-04'\(bu\h'+03'\c
733 .\}
734 .el \{\
735 .sp -1
736 .IP \(bu 2.3
737 .\}
738
739 glx
740 (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\&.
741 \fB\-\-xrender\-sync\-fence\fR
742 might be needed on some systems to avoid delay in changes of screen contents\&.
743 .RE
744 .sp
745 .RS 4
746 .ie n \{\
747 \h'-04'\(bu\h'+03'\c
748 .\}
749 .el \{\
750 .sp -1
751 .IP \(bu 2.3
752 .\}
753
754 xr_glx_hybrid
755 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\&.
756 \fB\-\-vsync\-use\-glfinish\fR
757 might fix some rendering issues with this backend\&.
758 .RE
759 .sp
760
761 .RE
762 .PP
763 \fB\-\-glx\-no\-stencil\fR
764 .RS 4
765
766
767
768 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
769 \fB\-\-blur\-background\fR\&. My tests show a 15% performance boost\&. Recommended\&.
770
771 .RE
772 .PP
773 \fB\-\-glx\-no\-rebind\-pixmap\fR
774 .RS 4
775
776
777
778 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\&.
779
780 .RE
781 .PP
782 \fB\-\-no\-use\-damage\fR
783 .RS 4
784
785
786
787 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\&.
788
789 .RE
790 .PP
791 \fB\-\-xrender\-sync\-fence\fR
792 .RS 4
793
794
795
796 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\&.
797
798 .RE
799 .PP
800 \fB\-\-glx\-fshader\-win\fR \fISHADER\fR
801 .RS 4
802
803
804
805 GLX backend: Use specified GLSL fragment shader for rendering window contents\&. See
806 compton\-default\-fshader\-win\&.glsl
807 and
808 compton\-fake\-transparency\-fshader\-win\&.glsl
809 in the source tree for examples\&.
810
811 .RE
812 .PP
813 \fB\-\-force\-win\-blend\fR
814 .RS 4
815
816
817
818 Force all windows to be painted with blending\&. Useful if you have a
819 \fB\-\-glx\-fshader\-win\fR
820 that could turn opaque pixels transparent\&.
821
822 .RE
823 .PP
824 \fB\-\-dbus\fR
825 .RS 4
826
827
828
829 Enable remote control via D\-Bus\&. See the
830 \fBD\-BUS API\fR
831 section below for more details\&.
832
833 .RE
834 .PP
835 \fB\-\-benchmark\fR \fICYCLES\fR
836 .RS 4
837
838
839
840 Benchmark mode\&. Repeatedly paint until reaching the specified cycles\&.
841
842 .RE
843 .PP
844 \fB\-\-benchmark\-wid\fR \fIWINDOW_ID\fR
845 .RS 4
846
847
848
849 Specify window ID to repaint in benchmark mode\&. If omitted or is 0, the whole screen is repainted\&.
850
851 .RE
852 .PP
853 \fB\-\-no\-ewmh\-fullscreen\fR
854 .RS 4
855
856
857
858 Do not use EWMH to detect fullscreen windows\&. Reverts to checking if a window is fullscreen based only on its size and coordinates\&.
859
860 .RE
861 .PP
862 \fB\-\-max\-brightness\fR
863 .RS 4
864
865
866
867 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
868 \fB\-\-use\-damage\fR
869 to be disabled\&. (default: 1\&.0)
870
871 .RE
872 .PP
873 \fB\-\-transparent\-clipping\fR
874 .RS 4
875
876
877
878 Make transparent windows clip other windows like non\-transparent windows do, instead of blending on top of them\&.
879
880 .RE
881
882 .SH "FORMAT OF CONDITIONS"
883
884 .sp
885 Some options accept a condition string to match certain windows\&. A condition string is formed by one or more conditions, joined by logical operators\&.
886 .sp
887 A condition with "exists" operator looks like this:
888
889 .sp
890 .if n \{\
891 .RS 4
892 .\}
893 .nf
894 <NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE>
895 .fi
896 .if n \{\
897 .RE
898 .\}
899 .sp
900 With equals operator it looks like:
901
902 .sp
903 .if n \{\
904 .RS 4
905 .\}
906 .nf
907 <NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE> <NEGATION> <OP QUALIFIER> <MATCH TYPE> = <PATTERN>
908 .fi
909 .if n \{\
910 .RE
911 .\}
912 .sp
913 With greater\-than/less\-than operators it looks like:
914
915 .sp
916 .if n \{\
917 .RS 4
918 .\}
919 .nf
920 <NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE> <NEGATION> <OPERATOR> <PATTERN>
921 .fi
922 .if n \{\
923 .RE
924 .\}
925 .sp
926 \fINEGATION\fR (optional) is one or more exclamation marks;
927 .sp
928 \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, width, height, widthb (width + 2 * border_width), heightb, 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\&.
929 .sp
930 \fICLIENT/FRAME\fR is a single @ if the window attribute should be be looked up on client window, nothing if on frame window;
931 .sp
932 \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\&. Do not specify it for predefined targets\&.
933 .sp
934 \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\&.
935 .sp
936 \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\&.
937 .sp
938 \fIOP QUALIFIER\fR (optional), applicable only for equals operator, could be ? (ignore\-case)\&.
939 .sp
940 \fIMATCH TYPE\fR (optional), applicable only for equals operator, could be nothing (exact match), * (match anywhere), ^ (match from start), % (wildcard), or ~ (PCRE regular expression)\&.
941 .sp
942 \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)\&.
943 .sp
944 \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\&.
945 .sp
946 Supported logical operators are && (and) and || (or)\&. && has higher precedence than ||, left\-to\-right associativity\&. Use parentheses to change precedence\&.
947 .sp
948 Examples:
949
950 .sp
951 .if n \{\
952 .RS 4
953 .\}
954 .nf
955 # If the window is focused
956 focused
957 focused = 1
958 # If the window is not override\-redirected
959 !override_redirect
960 override_redirect = false
961 override_redirect != true
962 override_redirect != 1
963 # If the window is a menu
964 window_type *= "menu"
965 _NET_WM_WINDOW_TYPE@:a *= "MENU"
966 # If the window name contains "Firefox", ignore case
967 name *?= "Firefox"
968 _NET_WM_NAME@:s *?= "Firefox"
969 # If the window name ends with "Firefox"
970 name %= "*Firefox"
971 name ~= "Firefox$"
972 # If the window has a property _COMPTON_SHADOW with value 0, type CARDINAL,
973 # format 32, value 0, on its frame window
974 _COMPTON_SHADOW:32c = 0
975 # If the third value of _NET_FRAME_EXTENTS is less than 20, or there\*(Aqs no
976 # _NET_FRAME_EXTENTS property on client window
977 _NET_FRAME_EXTENTS@[2]:32c < 20 || !_NET_FRAME_EXTENTS@:32c
978 # The pattern here will be parsed as "dd4"
979 name = "\ex64\ex64\eo64"
980 # The pattern here will be parsed as "\ex64\ex64\ex64"
981 name = r"\ex64\ex64\eo64"
982 .fi
983 .if n \{\
984 .RE
985 .\}
986 .sp
987
988 .SH "LEGACY FORMAT OF CONDITIONS"
989
990 .sp
991 This is the old condition format we once used\&. Support of this format might be removed in the future\&.
992
993 .sp
994 .if n \{\
995 .RS 4
996 .\}
997 .nf
998 condition = TARGET:TYPE[FLAGS]:PATTERN
999 .fi
1000 .if n \{\
1001 .RE
1002 .\}
1003 .sp
1004 \fITARGET\fR is one of "n" (window name), "i" (window class instance), "g" (window general class), and "r" (window role)\&.
1005 .sp
1006 \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)\&.
1007 .sp
1008 \fIFLAGS\fR could be a series of flags\&. Currently the only defined flag is "i" (ignore case)\&.
1009 .sp
1010 \fIPATTERN\fR is the actual pattern string\&.
1011
1012 .SH "CONFIGURATION FILES"
1013
1014 .sp
1015 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\&.
1016 .sp
1017 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\&.
1018 .sp
1019 Window\-type\-specific settings are exposed only in configuration file and has the following format:
1020
1021 .sp
1022 .if n \{\
1023 .RS 4
1024 .\}
1025 .nf
1026 wintypes:
1027 {
1028 WINDOW_TYPE = { fade = BOOL; shadow = BOOL; opacity = FLOAT; focus = BOOL; full\-shadow = BOOL; redir\-ignore = BOOL; };
1029 };
1030 .fi
1031 .if n \{\
1032 .RE
1033 .\}
1034 .sp
1035 \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"\&.
1036
1037
1038 .PP
1039 Following per window\-type options are available:
1040 .RS 4
1041
1042
1043
1044 .PP
1045 fade, shadow
1046 .RS 4
1047
1048
1049
1050 Controls window\-type\-specific shadow and fade settings\&.
1051
1052 .RE
1053 .PP
1054 opacity
1055 .RS 4
1056
1057
1058
1059 Controls default opacity of the window type\&.
1060
1061 .RE
1062 .PP
1063 focus
1064 .RS 4
1065
1066
1067
1068 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\&.)
1069
1070 .RE
1071 .PP
1072 full\-shadow
1073 .RS 4
1074
1075
1076
1077 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\&.
1078
1079 .RE
1080 .PP
1081 redir\-ignore
1082 .RS 4
1083
1084
1085
1086 Controls whether this type of windows should cause screen to become redirected again after been unredirected\&. If you have
1087 \fB\-\-unredir\-if\-possible\fR
1088 set, and doesn\(cqt want certain window to cause unnecessary screen redirection, you can set this to
1089 true\&.
1090
1091 .RE
1092 .sp
1093
1094 .RE
1095
1096 .SH "BLUR"
1097
1098 .sp
1099 You can configure how the window background is blurred using a \fIblur\fR section in your configuration file\&. Here is an example:
1100
1101 .sp
1102 .if n \{\
1103 .RS 4
1104 .\}
1105 .nf
1106 blur:
1107 {
1108 method = "gaussian";
1109 size = 10;
1110 deviation = 5\&.0;
1111 };
1112 .fi
1113 .if n \{\
1114 .RE
1115 .\}
1116 .sp
1117
1118
1119 .PP
1120 Available options of the \fIblur\fR section are:
1121 .RS 4
1122
1123
1124
1125 .PP
1126 \fBmethod\fR
1127 .RS 4
1128
1129
1130
1131 A string\&. Controls the blur method\&. Corresponds to the
1132 \fB\-\-blur\-method\fR
1133 command line option\&. Available choices are:
1134 \fInone\fR
1135 to disable blurring;
1136 \fIgaussian\fR
1137 for gaussian blur;
1138 \fIbox\fR
1139 for box blur;
1140 \fIkernel\fR
1141 for convolution blur with a custom kernel\&. Note:
1142 \fIgaussian\fR
1143 and
1144 \fIbox\fR
1145 blur methods are only supported by the experimental backends\&. (default: none)
1146
1147 .RE
1148 .PP
1149 \fBsize\fR
1150 .RS 4
1151
1152
1153
1154 An integer\&. The size of the blur kernel, required by
1155 \fIgaussian\fR
1156 and
1157 \fIbox\fR
1158 blur methods\&. For the
1159 \fIkernel\fR
1160 method, the size is included in the kernel\&. Corresponds to the
1161 \fB\-\-blur\-size\fR
1162 command line option (default: 3)\&.
1163
1164 .RE
1165 .PP
1166 \fBdeviation\fR
1167 .RS 4
1168
1169
1170
1171 A floating point number\&. The standard deviation for the
1172 \fIgaussian\fR
1173 blur method\&. Corresponds to the
1174 \fB\-\-blur\-deviation\fR
1175 command line option (default: 0\&.84089642)\&.
1176
1177 .RE
1178 .PP
1179 \fBkernel\fR
1180 .RS 4
1181
1182
1183
1184 A string\&. The kernel to use for the
1185 \fIkernel\fR
1186 blur method, specified in the same format as the
1187 \fB\-\-blur\-kerns\fR
1188 option\&. Corresponds to the
1189 \fB\-\-blur\-kerns\fR
1190 command line option\&.
1191
1192 .RE
1193 .sp
1194
1195 .RE
1196
1197 .SH "SIGNALS"
1198
1199
1200 .sp
1201 .RS 4
1202 .ie n \{\
1203 \h'-04'\(bu\h'+03'\c
1204 .\}
1205 .el \{\
1206 .sp -1
1207 .IP \(bu 2.3
1208 .\}
1209
1210 picom reinitializes itself upon receiving
1211 SIGUSR1\&.
1212 .RE
1213 .SH "D\-BUS API"
1214
1215 .sp
1216 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\&.
1217 .sp
1218 The D\-Bus methods and signals are not yet stable, thus undocumented right now\&.
1219
1220 .SH "EXAMPLES"
1221
1222
1223 .sp
1224 .RS 4
1225 .ie n \{\
1226 \h'-04'\(bu\h'+03'\c
1227 .\}
1228 .el \{\
1229 .sp -1
1230 .IP \(bu 2.3
1231 .\}
1232
1233 Disable configuration file parsing:
1234
1235 .sp
1236 .if n \{\
1237 .RS 4
1238 .\}
1239 .nf
1240 $ picom \-\-config /dev/null
1241 .fi
1242 .if n \{\
1243 .RE
1244 .\}
1245 .sp
1246 .RE
1247 .sp
1248 .RS 4
1249 .ie n \{\
1250 \h'-04'\(bu\h'+03'\c
1251 .\}
1252 .el \{\
1253 .sp -1
1254 .IP \(bu 2.3
1255 .\}
1256
1257 Run picom with client\-side shadow and fading, disable shadow on dock windows and drag\-and\-drop windows:
1258
1259 .sp
1260 .if n \{\
1261 .RS 4
1262 .\}
1263 .nf
1264 $ picom \-cCGf
1265 .fi
1266 .if n \{\
1267 .RE
1268 .\}
1269 .sp
1270 .RE
1271 .sp
1272 .RS 4
1273 .ie n \{\
1274 \h'-04'\(bu\h'+03'\c
1275 .\}
1276 .el \{\
1277 .sp -1
1278 .IP \(bu 2.3
1279 .\}
1280
1281 Same thing as above, plus making inactive windows 80% transparent, making frame 80% transparent, don\(cqt fade on window open/close, enable software optimization, and fork to background:
1282
1283 .sp
1284 .if n \{\
1285 .RS 4
1286 .\}
1287 .nf
1288 $ picom \-bcCGf \-i 0\&.8 \-e 0\&.8 \-\-no\-fading\-openclose \-\-sw\-opti
1289 .fi
1290 .if n \{\
1291 .RE
1292 .\}
1293 .sp
1294 .RE
1295 .sp
1296 .RS 4
1297 .ie n \{\
1298 \h'-04'\(bu\h'+03'\c
1299 .\}
1300 .el \{\
1301 .sp -1
1302 .IP \(bu 2.3
1303 .\}
1304
1305 Draw white shadows:
1306
1307 .sp
1308 .if n \{\
1309 .RS 4
1310 .\}
1311 .nf
1312 $ picom \-c \-\-shadow\-red 1 \-\-shadow\-green 1 \-\-shadow\-blue 1
1313 .fi
1314 .if n \{\
1315 .RE
1316 .\}
1317 .sp
1318 .RE
1319 .sp
1320 .RS 4
1321 .ie n \{\
1322 \h'-04'\(bu\h'+03'\c
1323 .\}
1324 .el \{\
1325 .sp -1
1326 .IP \(bu 2.3
1327 .\}
1328
1329 Avoid drawing shadows on wbar window:
1330
1331 .sp
1332 .if n \{\
1333 .RS 4
1334 .\}
1335 .nf
1336 $ picom \-c \-\-shadow\-exclude \*(Aqclass_g = "wbar"\*(Aq
1337 .fi
1338 .if n \{\
1339 .RE
1340 .\}
1341 .sp
1342 .RE
1343 .sp
1344 .RS 4
1345 .ie n \{\
1346 \h'-04'\(bu\h'+03'\c
1347 .\}
1348 .el \{\
1349 .sp -1
1350 .IP \(bu 2.3
1351 .\}
1352
1353 Enable VSync with GLX backend:
1354
1355 .sp
1356 .if n \{\
1357 .RS 4
1358 .\}
1359 .nf
1360 $ picom \-\-backend glx \-\-vsync
1361 .fi
1362 .if n \{\
1363 .RE
1364 .\}
1365 .sp
1366 .RE
1367 .SH "BUGS"
1368
1369 .sp
1370 Please submit bug reports to \m[blue]\fBhttps://github\&.com/yshui/picom\fR\m[]\&.
1371 .sp
1372 Out dated information in this man page is considered a bug\&.
1373
1374 .SH "RESOURCES"
1375
1376 .sp
1377 Homepage: \m[blue]\fBhttps://github\&.com/yshui/picom\fR\m[]
1378
1379 .SH "SEE ALSO"
1380
1381 .sp
1382 \fBxcompmgr\fR(1), \m[blue]\fB\fBpicom\-trans\fR(1)\fR\m[]\&\s-2\u[1]\d\s+2
|
