1COMPTON(1) LOCAL USER COMMANDS COMPTON(1)
2
6 compton - a compositor for X11
7
9 compton [OPTIONS]
10
12 This man page may be less up-to-date than the usage text in compton
13 (compton -h).
14
16 compton is a compositor based on Dana Jansens' version of xcompmgr
17 (which itself was written by Keith Packard). It includes some
18 improvements over the original xcompmgr, like window frame opacity and
19 inactive window transparency.
20
22 -h, --help
23 Get the usage text embedded in program code, which may be more
24 up-to-date than this man page.
25 -d DISPLAY
27 Display to be managed.
28 -r, --shadow-radius=RADIUS
30 The blur radius for shadows, in pixels. (defaults to 12)
31 -o, --shadow-opacity=OPACITY
33 The opacity of shadows. (0.0 - 1.0, defaults to 0.75)
34 -l, --shadow-offset-x=OFFSET
36 The left offset for shadows, in pixels. (defaults to -15)
37 -t, --shadow-offset-y=OFFSET
39 The top offset for shadows, in pixels. (defaults to -15)
40 -I, --fade-in-step=OPACITY_STEP
42 Opacity change between steps while fading in. (0.01 - 1.0, defaults
43 to 0.028)
44 -O, --fade-out-step=OPACITY_STEP
46 Opacity change between steps while fading out. (0.01 - 1.0,
47 defaults to 0.03)
48 -D, --fade-delta=MILLISECONDS
50 The time between steps in fade step, in milliseconds. (> 0,
51 defaults to 10)
52 -m, --menu-opacity=OPACITY
54 Default opacity for dropdown menus and popup menus. (0.0 - 1.0,
55 defaults to 1.0)
56 -c, --shadow
58 Enabled client-side shadows on windows. Note desktop windows
59 (windows with _NET_WM_WINDOW_TYPE_DESKTOP) never get shadow.
60 -C, --no-dock-shadow
62 Avoid drawing shadows on dock/panel windows.
63 -z, --clear-shadow
65 Zero the part of the shadow’s mask behind the window. Note this may
66 not work properly on ARGB windows with fully transparent areas.
67 -f, --fading
69 Fade windows in/out when opening/closing and when opacity changes,
70 unless --no-fading-openclose is used.
71 -F
73 Equals to -f. Deprecated.
74 -i, --inactive-opacity=OPACITY
76 Opacity of inactive windows. (0.1 - 1.0, disabled by default)
77 -e, --frame-opacity=OPACITY
79 Opacity of window titlebars and borders. (0.1 - 1.0, disabled by
80 default)
81 -G, --no-dnd-shadow
83 Don’t draw shadows on drag-and-drop windows.
84 -b, --daemon
86 Daemonize process. Fork to background after initialization. Causes
87 issues with certain (badly-written) drivers.
88 -S
90 Enable synchronous X operation (for debugging).
91 --show-all-xerrors
93 Show all X errors (for debugging).
94 --config PATH
96 Look for configuration file at the path. See CONFIGURATION FILES
97 section below for where compton looks for a configuration file by
98 default. Use /dev/null to avoid loading configuration file.
99 --write-pid-path PATH
101 Write process ID to a file.
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 overrides the windows'
114 _NET_WM_OPACITY values.
115 --active-opacity OPACITY
117 Default opacity for active windows. (0.0 - 1.0)
118 --inactive-dim VALUE
120 Dim inactive windows. (0.0 - 1.0, defaults to 0.0)
121 --mark-wmwin-focused
123 Try to detect WM windows (a non-override-redirect window with no
124 child that has WM_STATE) and mark them as active.
125 --mark-ovredir-focused
127 Mark override-redirect windows that doesn’t have a child window
128 with WM_STATE focused.
129 --no-fading-openclose
131 Do not fade on window open/close.
132 --no-fading-destroyed-argb
134 Do not fade destroyed ARGB windows with WM frame. Workaround of
135 bugs in Openbox, Fluxbox, etc.
136 --shadow-ignore-shaped
138 Do not paint shadows on shaped windows. Note shaped windows here
139 means windows setting its shape through X Shape extension. Those
140 using ARGB background is beyond our control. Deprecated, use
141 --shadow-exclude 'bounding_shaped' or --shadow-exclude
142 'bounding_shaped && !rounded_corners' instead.
143 --detect-rounded-corners
145 Try to detect windows with rounded corners and don’t consider them
146 shaped windows. The accuracy is not very high, unfortunately.
147 --detect-client-opacity
149 Detect _NET_WM_OPACITY on client windows, useful for window
150 managers not passing _NET_WM_OPACITY of client windows to frame
151 windows.
152 --refresh-rate REFRESH_RATE
154 Specify refresh rate of the screen. If not specified or 0, compton
155 will try detecting this with X RandR extension.
156 --vsync VSYNC_METHOD
158 Set VSync method. VSync methods currently available:
159 • none: No VSync
161 • drm: VSync with DRM_IOCTL_WAIT_VBLANK. May only work on some
163 (DRI-based) drivers.
164 • opengl: Try to VSync with SGI_video_sync OpenGL extension. Only
166 work on some drivers.
167 • opengl-oml: Try to VSync with OML_sync_control OpenGL
169 extension. Only work on some drivers.
170 • opengl-swc: Try to VSync with SGI_swap_control OpenGL
172 extension. Only work on some drivers. Works only with GLX
173 backend. Known to be most effective on many drivers. Does not
174 guarantee to control paint timing.
175 • opengl-mswc: Try to VSync with MESA_swap_control OpenGL
177 extension. Basically the same as opengl-swc above, except the
178 extension we use.
179 (Note some VSync methods may not be enabled at compile time.)
181 --vsync-aggressive
183 Attempt to send painting request before VBlank and do XFlush()
184 during VBlank. Reported to work pretty terribly. This switch may be
185 lifted out at any moment.
186 --alpha-step VALUE
188 X Render backend: Step for pregenerating alpha pictures. (0.01 -
189 1.0, defaults to 0.03)
190 --dbe
192 Enable DBE painting mode, intended to use with VSync to (hopefully)
193 eliminate tearing. Reported to have no effect, though.
194 --paint-on-overlay
196 Painting on X Composite overlay window instead of on root window.
197 --sw-opti
199 Limit compton to repaint at most once every 1 / refresh_rate second
200 to boost performance. This should not be used with --vsync
201 drm/opengl/opengl-oml as they essentially does --sw-opti's job
202 already, unless you wish to specify a lower refresh rate than the
203 actual value.
204 --use-ewmh-active-win
206 Use EWMH _NET_ACTIVE_WINDOW to determine currently focused window,
207 rather than listening to FocusIn/FocusOut event. Might have more
208 accuracy, provided that the WM supports it.
209 --respect-prop-shadow
211 Respect _COMPTON_SHADOW. This a prototype-level feature, which you
212 must not rely on.
213 --unredir-if-possible
215 Unredirect all windows if a full-screen opaque window is detected,
216 to maximize performance for full-screen windows. Known to cause
217 flickering when redirecting/unredirecting windows.
218 --paint-on-overlay may make the flickering less obvious.
219 --unredir-if-possible-delay MILLISECONDS
221 Delay before unredirecting the window, in milliseconds. Defaults to
222 0.
223 --unredir-if-possible-exclude CONDITION
225 Conditions of windows that shouldn’t be considered full-screen for
226 unredirecting screen.
227 --shadow-exclude CONDITION
229 Specify a list of conditions of windows that should have no shadow.
230 --fade-exclude CONDITION
232 Specify a list of conditions of windows that should not be faded.
233 --focus-exclude CONDITION
235 Specify a list of conditions of windows that should always be
236 considered focused.
237 --inactive-dim-fixed
239 Use fixed inactive dim value, instead of adjusting according to
240 window opacity.
241 --detect-transient
243 Use WM_TRANSIENT_FOR to group windows, and consider windows in the
244 same group focused at the same time.
245 --detect-client-leader
247 Use WM_CLIENT_LEADER to group windows, and consider windows in the
248 same group focused at the same time. WM_TRANSIENT_FOR has higher
249 priority if --detect-transient is enabled, too.
250 --blur-background
252 Blur background of semi-transparent / ARGB windows. Bad in
253 performance, with driver-dependent behavior. The name of the switch
254 may change without prior notifications.
255 --blur-background-frame
257 Blur background of windows when the window frame is not opaque.
258 Implies --blur-background. Bad in performance, with
259 driver-dependent behavior. The name may change.
260 --blur-background-fixed
262 Use fixed blur strength rather than adjusting according to window
263 opacity.
264 --blur-kern MATRIX
266 Specify the blur convolution kernel, with the following format:
267 WIDTH,HEIGHT,ELE1,ELE2,ELE3,ELE4,ELE5...
269 The element in the center must not be included, it will be forever
271 1.0 or changing based on opacity, depending on whether you have
272 --blur-background-fixed. Yet the automatic adjustment of blur
273 factor may not work well with a custom blur kernel.
274 A 7x7 Gaussian blur kernel (sigma = 0.84089642) looks like:
276 --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'
278 May also be one of the predefined kernels: 3x3box (default),
280 5x5box, 7x7box, 3x3gaussian, 5x5gaussian, 7x7gaussian, 9x9gaussian,
281 11x11gaussian. All Gaussian kernels are generated with sigma =
282 0.84089642 . You may use the accompanied compton-convgen.py to
283 generate blur kernels.
284 --blur-background-exclude CONDITION
286 Exclude conditions for background blur.
287 --resize-damage INTEGER
289 Resize damaged region by a specific number of pixels. A positive
290 value enlarges it while a negative one shrinks it. If the value is
291 positive, those additional pixels will not be actually painted to
292 screen, only used in blur calculation, and such. (Due to technical
293 limitations, with --dbe or --glx-swap-method, those pixels will
294 still be incorrectly painted to screen.) Primarily used to fix the
295 line corruption issues of blur, in which case you should use the
296 blur radius value here (e.g. with a 3x3 kernel, you should use
297 --resize-damage 1, with a 5x5 one you use --resize-damage 2, and so
298 on). May or may not work with --glx-no-stencil. Shrinking doesn’t
299 function correctly.
300 --invert-color-include CONDITION
302 Specify a list of conditions of windows that should be painted with
303 inverted color. Resource-hogging, and is not well tested.
304 --opacity-rule OPACITY:'CONDITION'
306 Specify a list of opacity rules, in the format PERCENT:PATTERN,
307 like 50:name *= "Firefox". compton-trans is recommended over this.
308 Note we do not distinguish 100% and unset, and we don’t make any
309 guarantee about possible conflicts with other programs that set
310 _NET_WM_WINDOW_OPACITY on frame or client windows.
311 --shadow-exclude-reg GEOMETRY
313 Specify a X geometry that describes the region in which shadow
314 should not be painted in, such as a dock window region. Use
315 --shadow-exclude-reg x10+0-0, for example, if the 10 pixels on the
316 bottom of the screen should not have shadows painted on.
317 --xinerama-shadow-crop
319 Crop shadow of a window fully on a particular Xinerama screen to
320 the screen.
321 --backend BACKEND
323 Specify the backend to use: xrender, glx, or xr_glx_hybrid.
324 xrender is the default one.
325 • xrender backend performs all rendering operations with X Render
327 extension. It is what xcompmgr uses, and is generally a safe
328 fallback when you encounter rendering artifacts or instability.
329 • glx (OpenGL) backend performs all rendering operations with
331 OpenGL. It is more friendly to some VSync methods, and has
332 significantly superior performance on color inversion
333 (--invert-color-include) or blur (--blur-background). It
334 requires proper OpenGL 2.0 support from your driver and
335 hardware. You may wish to look at the GLX performance
336 optimization options below. --xrender-sync and
337 --xrender-sync-fence might be needed on some systems to avoid
338 delay in changes of screen contents.
339 • xr_glx_hybrid backend renders the updated screen contents with
341 X Render and presents it on the screen with GLX. It attempts to
342 address the rendering issues some users encountered with GLX
343 backend and enables the better VSync of GLX backends.
344 --vsync-use-glfinish might fix some rendering issues with this
345 backend.
346 --glx-no-stencil
348 GLX backend: Avoid using stencil buffer, useful if you don’t have a
349 stencil buffer. Might cause incorrect opacity when rendering
350 transparent content (but never practically happened) and may not
351 work with --blur-background. My tests show a 15% performance boost.
352 Recommended.
353 --glx-copy-from-front
355 GLX backend: Copy unmodified regions from front buffer instead of
356 redrawing them all. My tests with nvidia-drivers show a 10%
357 decrease in performance when the whole screen is modified, but a
358 20% increase when only 1/4 is. My tests on nouveau show terrible
359 slowdown. Useful with --glx-swap-method, as well.
360 --glx-use-copysubbuffermesa
362 GLX backend: Use MESA_copy_sub_buffer to do partial screen update.
363 My tests on nouveau shows a 200% performance boost when only 1/4 of
364 the screen is updated. May break VSync and is not available on some
365 drivers. Overrides --glx-copy-from-front.
366 --glx-no-rebind-pixmap
368 GLX backend: Avoid rebinding pixmap on window damage. Probably
369 could improve performance on rapid window content changes, but is
370 known to break things on some drivers (LLVMpipe, xf86-video-intel,
371 etc.). Recommended if it works.
372 --glx-swap-method undefined/exchange/copy/3/4/5/6/buffer-age
374 GLX backend: GLX buffer swap method we assume. Could be undefined
375 (0), copy (1), exchange (2), 3-6, or buffer-age (-1). undefined is
376 the slowest and the safest, and the default value. copy is
377 fastest, but may fail on some drivers, 2-6 are gradually slower but
378 safer (6 is still faster than 0). Usually, double buffer means 2,
379 triple buffer means 3. buffer-age means auto-detect using
380 GLX_EXT_buffer_age, supported by some drivers. Useless with
381 --glx-use-copysubbuffermesa. Partially breaks --resize-damage.
382 Defaults to undefined.
383 --glx-use-gpushader4
385 GLX backend: Use GL_EXT_gpu_shader4 for some optimization on blur
386 GLSL code. My tests on GTX 670 show no noticeable effect.
387 --xrender-sync
389 Attempt to synchronize client applications' draw calls with
390 XSync(), used on GLX backend to ensure up-to-date window content is
391 painted.
392 --xrender-sync-fence
394 Additionally use X Sync fence to sync clients' draw calls. Needed
395 on nvidia-drivers with GLX backend for some users. May be disabled
396 at compile time with NO_XSYNC=1.
397 --glx-fshader-win SHADER
399 GLX backend: Use specified GLSL fragment shader for rendering
400 window contents. See compton-default-fshader-win.glsl and
401 compton-fake-transparency-fshader-win.glsl in the source tree for
402 examples.
403 --force-win-blend
405 Force all windows to be painted with blending. Useful if you have a
406 --glx-fshader-win that could turn opaque pixels transparent.
407 --dbus
409 Enable remote control via D-Bus. See the D-BUS API section below
410 for more details.
411 --benchmark CYCLES
413 Benchmark mode. Repeatedly paint until reaching the specified
414 cycles.
415 --benchmark-wid WINDOW_ID
417 Specify window ID to repaint in benchmark mode. If omitted or is 0,
418 the whole screen is repainted.
419
421 Some options accept a condition string to match certain windows. A
422 condition string is formed by one or more conditions, joined by logical
423 operators.
424 A condition with "exists" operator looks like this:
426 <NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE>
428 With equals operator it looks like:
430 <NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE> <NEGATION> <OP QUALIFIER> <MATCH TYPE> = <PATTERN>
432 With greater-than/less-than operators it looks like:
434 <NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE> <NEGATION> <OPERATOR> <PATTERN>
436 NEGATION (optional) is one or more exclamation marks;
438 TARGET is either a predefined target name, or the name of a window
440 property to match. Supported predefined targets are id, x, y, x2 (x +
441 widthb), y2, width, height, widthb (width + 2 * border_width), heightb,
442 override_redirect, argb (whether the window has an ARGB visual),
443 focused, wmwin (whether the window looks like a WM window, i.e. has no
444 child window with WM_STATE and is not override-redirected),
445 bounding_shaped, rounded_corners (requires --detect-rounded-corners),
446 client (ID of client window), window_type (window type in string),
447 leader (ID of window leader), name, class_g (= WM_CLASS[1]), class_i (=
448 WM_CLASS[0]), and role.
449 CLIENT/FRAME is a single @ if the window attribute should be be looked
451 up on client window, nothing if on frame window;
452 INDEX (optional) is the index number of the property to look up. For
454 example, [2] means look at the third value in the property. Do not
455 specify it for predefined targets.
456 FORMAT (optional) specifies the format of the property, 8, 16, or 32.
458 On absence we use format X reports. Do not specify it for predefined or
459 string targets.
460 TYPE is a single character representing the type of the property to
462 match for: c for CARDINAL, a for ATOM, w for WINDOW, d for DRAWABLE, s
463 for STRING (and any other string types, such as UTF8_STRING). Do not
464 specify it for predefined targets.
465 OP QUALIFIER (optional), applicable only for equals operator, could be
467 ? (ignore-case).
468 MATCH TYPE (optional), applicable only for equals operator, could be
470 nothing (exact match), * (match anywhere), ^ (match from start), %
471 (wildcard), or ~ (PCRE regular expression).
472 OPERATOR is one of = (equals), <, >, <=, =>, or nothing (exists).
474 Exists operator checks whether a property exists on a window (but for
475 predefined targets, exists means != 0 then).
476 PATTERN is either an integer or a string enclosed by single or double
478 quotes. Python-3-style escape sequences and raw string are supported in
479 the string format.
480 Supported logical operators are && (and) and || (or). && has higher
482 precedence than ||, left-to-right associativity. Use parentheses to
483 change precedence.
484 Examples:
486 # If the window is focused
488 focused
489 focused = 1
490 # If the window is not override-redirected
491 !override_redirect
492 override_redirect = false
493 override_redirect != true
494 override_redirect != 1
495 # If the window is a menu
496 window_type *= "menu"
497 _NET_WM_WINDOW_TYPE@:a *= "MENU"
498 # If the window name contains "Firefox", ignore case
499 name *?= "Firefox"
500 _NET_WM_NAME@:s *?= "Firefox"
501 # If the window name ends with "Firefox"
502 name %= "*Firefox"
503 name ~= "Firefox$"
504 # If the window has a property _COMPTON_SHADOW with value 0, type CARDINAL,
505 # format 32, value 0, on its frame window
506 _COMPTON_SHADOW:32c = 0
507 # If the third value of _NET_FRAME_EXTENTS is less than 20, or there's no
508 # _NET_FRAME_EXTENTS property on client window
509 _NET_FRAME_EXTENTS@[2]:32c < 20 || !_NET_FRAME_EXTENTS@:32c
510 # The pattern here will be parsed as "dd4"
511 name = "\x64\x64\o64"
512 # The pattern here will be parsed as "\x64\x64\x64"
513 name = r"\x64\x64\o64"
514
516 This is the old condition format we once used. Support of this format
517 might be removed in the future.
518 condition = TARGET:TYPE[FLAGS]:PATTERN
520 TARGET is one of "n" (window name), "i" (window class instance), "g"
522 (window general class), and "r" (window role).
523 TYPE is one of "e" (exact match), "a" (match anywhere), "s" (match from
525 start), "w" (wildcard), and "p" (PCRE regular expressions, if compiled
526 with the support).
527 FLAGS could be a series of flags. Currently the only defined flag is
529 "i" (ignore case).
530 PATTERN is the actual pattern string.
532
534 compton could read from a configuration file if libconfig support is
535 compiled in. If --config is not used, compton will seek for a
536 configuration file in $XDG_CONFIG_HOME/compton.conf
537 (~/.config/compton.conf, usually), then ~/.compton.conf, then
538 compton.conf under $XDG_CONFIG_DIRS (often /etc/xdg/compton.conf).
539 compton uses general libconfig configuration file format. A sample
541 configuration file is available as compton.sample.conf in the source
542 tree. Most commandline switches each could be replaced with an option
543 in configuration file, thus documented above. Window-type-specific
544 settings are exposed only in configuration file and has the following
545 format:
546 wintypes:
548 {
549 WINDOW_TYPE = { fade = BOOL; shadow = BOOL; opacity = FLOAT; focus = BOOL; };
550 };
551 WINDOW_TYPE is one of the 15 window types defined in EWMH standard:
553 "unknown", "desktop", "dock", "toolbar", "menu", "utility", "splash",
554 "dialog", "normal", "dropdown_menu", "popup_menu", "tooltip", "notify",
555 "combo", and "dnd". "fade" and "shadow" controls window-type-specific
556 shadow and fade settings. "opacity" controls default opacity of the
557 window type. "focus" controls whether the window of this type is to be
558 always considered focused. (By default, all window types except
559 "normal" and "dialog" has this on.)
560
562 • compton reinitializes itself upon receiving SIGUSR1.
563
565 It’s possible to control compton via D-Bus messages, by running compton
566 with --dbus and send messages to com.github.chjj.compton.<DISPLAY>.
567 <DISPLAY> is the display used by compton, with all non-alphanumeric
568 characters transformed to underscores. For DISPLAY=:0.0 you should use
569 com.github.chjj.compton._0_0, for example.
570 The D-Bus methods and signals are not yet stable, thus undocumented
572 right now.
573
575 • Disable configuration file parsing:
576 $ compton --config /dev/null
578 • Run compton with client-side shadow and fading, disable shadow on
580 dock windows and drag-and-drop windows:
581 $ compton -cCGf
583 • Same thing as above, plus making inactive windows 80% transparent,
585 making frame 80% transparent, don’t fade on window open/close,
586 enable software optimization, and fork to background:
587 $ compton -bcCGf -i 0.8 -e 0.8 --no-fading-openclose --sw-opti
589 • Draw white shadows:
591 $ compton -c --shadow-red 1 --shadow-green 1 --shadow-blue 1
593 • Avoid drawing shadows on wbar window:
595 $ compton -c --shadow-exclude 'class_g = "wbar"'
597 • Enable OpenGL SGI_swap_control VSync with GLX backend:
599 $ compton --backend glx --vsync opengl-swc
601
603 Please report any you find to https://github.com/chjj/compton .
604
606 xcompmgr, originally written by Keith Packard, with contributions from
607 Matthew Allum, Eric Anholt, Dan Doel, Thomas Luebking, Matthew Hawn,
608 Ely Levy, Phil Blundell, and Carl Worth. Compton by Christopher
609 Jeffrey, based on Dana Jansens' original work, with contributions from
610 Richard Grenville.
611
613 Homepage: https://github.com/chjj/compton
614
616 xcompmgr(1), compton-trans(1)
617compton nightly-20141124 01/19/2022 COMPTON(1)