COMPTON(1) | LOCAL USER COMMANDS | COMPTON(1) |
NAME¶
compton - a compositor for X11SYNOPSIS¶
compton [OPTIONS]WARNING¶
This man page may be less up-to-date than the usage text in compton (compton -h).DESCRIPTION¶
compton is a compositor based on Dana Jansens' 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.OPTIONS¶
-h, --helpGet the usage text embedded in program code, which may be
more up-to-date than this man page.
-d DISPLAY
Display to be managed.
-r RADIUS
The blur radius for shadows, in pixels. (defaults to
12)
-o OPACITY
The opacity of shadows. (0.0 - 1.0, defaults to
0.75)
-l OFFSET
The left offset for shadows, in pixels. (defaults to
-15)
-t OFFSET
The top offset for shadows, in pixels. (defaults to
-15)
-I OPACITY_STEP
Opacity change between steps while fading in. (0.01 -
1.0, defaults to 0.028)
-O OPACITY_STEP
Opacity change between steps while fading out. (0.01 -
1.0, defaults to 0.03)
-D MILLISECONDS
The time between steps in fade step, in milliseconds.
(> 0, defaults to 10)
-m OPACITY
Default opacity for dropdown menus and popup menus. (0.0
- 1.0, defaults to 1.0)
-c
Enabled client-side shadows on windows. Note desktop
windows (windows with _NET_WM_WINDOW_TYPE_DESKTOP) never get
shadow.
-C
Avoid drawing shadows on dock/panel windows.
-z
Zero the part of the shadow’s mask behind the
window. Note this may not work properly on ARGB windows with fully transparent
areas.
-f
Fade windows in/out when opening/closing and when opacity
changes, unless --no-fading-openclose is used.
-F
Equals -f. Deprecated.
-i OPACITY
Opacity of inactive windows. (0.1 - 1.0, disabled by
default)
-e OPACITY
Opacity of window titlebars and borders. (0.1 - 1.0,
disabled by default)
-G
Don’t draw shadows on drag-and-drop windows.
-b
Daemonize process. Fork to background after
initialization.
-S
Enable synchronous X operation (for debugging).
--config PATH
Look for configuration file at the path. See
CONFIGURATION FILES section below for where compton looks for a
configuration file by default.
--shadow-red VALUE
Red color value of shadow (0.0 - 1.0, defaults to
0).
--shadow-green VALUE
Green color value of shadow (0.0 - 1.0, defaults to
0).
--shadow-blue VALUE
Blue color value of shadow (0.0 - 1.0, defaults to
0).
--inactive-opacity-override
Let inactive opacity set by -i overrides the
windows' _NET_WM_OPACITY values.
--active-opacity OPACITY
Default opacity for active windows. (0.0 - 1.0)
--inactive-dim VALUE
Dim inactive windows. (0.0 - 1.0, defaults to 0.0)
--mark-wmwin-focused
Try to detect WM windows (a non-override-redirect window
with no child that has WM_STATE) and mark them as active.
--mark-ovredir-focused
Mark override-redirect windows that doesn’t have a
child window with WM_STATE focused.
--no-fading-openclose
Do not fade on window open/close.
--shadow-ignore-shaped
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.
--detect-rounded-corners
Try to detect windows with rounded corners and
don’t consider them shaped windows. The accuracy is not very high,
unfortunately.
--detect-client-opacity
Detect _NET_WM_OPACITY on client windows, useful
for window managers not passing _NET_WM_OPACITY of client windows to
frame windows.
--refresh-rate REFRESH_RATE
Specify refresh rate of the screen. If not specified or
0, compton will try detecting this with X RandR extension.
--vsync VSYNC_METHOD
Set VSync method. VSync methods currently available:
--vsync-aggressive
•none: No VSync
•drm: VSync with
DRM_IOCTL_WAIT_VBLANK. May only work on some drivers.
•opengl: Try to VSync with
SGI_video_sync OpenGL extension. Only work on some drivers.
•opengl-oml: Try to VSync with
OML_sync_control OpenGL extension. Only work on some drivers.
•opengl-swc: Try to VSync with
SGI_swap_control OpenGL extension. Only work on some drivers. Works
only with GLX backend. Known to be most effective on many drivers. Does not
actually control paint timing, only buffer swap is affected, so it
doesn’t have the effect of --sw-opti unlike other methods.
Experimental.
•opengl-mswc: Try to VSync with
MESA_swap_control OpenGL extension. Basically the same as
opengl-swc above, except the extension we use.
(Note some VSync methods may not be enabled at compile time.)Attempt to send painting request before VBlank and do
XFlush() during VBlank. Reported to work pretty terribly. This switch may be
lifted out at any moment.
--alpha-step VALUE
X Render backend: Step for pregenerating alpha pictures.
(0.01 - 1.0, defaults to 0.03)
--dbe
Enable DBE painting mode, intended to use with VSync to
(hopefully) eliminate tearing. Reported to have no effect, though.
--paint-on-overlay
Painting on X Composite overlay window instead of on root
window.
--sw-opti
Limit compton to repaint at most once every 1 /
refresh_rate second to boost performance. This should not be used with
--vsync drm/opengl/opengl-oml as they essentially does
--sw-opti's job already, unless you wish to specify a lower refresh
rate than the actual value.
--use-ewmh-active-win
Use EWMH _NET_ACTIVE_WINDOW to determine currently
focused window, rather than listening to FocusIn/FocusOut event.
Might have more accuracy, provided that the WM supports it.
--respect-prop-shadow
Respect _COMPTON_SHADOW. This a prototype-level
feature, which you must not rely on.
--unredir-if-possible
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. --paint-on-overlay
may make the flickering less obvious.
--unredir-if-possible-delay MILLISECONDS
Delay before unredirecting the window, in milliseconds.
Defaults to 0.
--unredir-if-possible-exclude CONDITION
Conditions of windows that shouldn’t be considered
full-screen for unredirecting screen.
--shadow-exclude CONDITION
Specify a list of conditions of windows that should have
no shadow.
--fade-exclude CONDITION
Specify a list of conditions of windows that should not
be faded.
--focus-exclude CONDITION
Specify a list of conditions of windows that should
always be considered focused.
--inactive-dim-fixed
Use fixed inactive dim value, instead of adjusting
according to window opacity.
--detect-transient
Use WM_TRANSIENT_FOR to group windows, and
consider windows in the same group focused at the same time.
--detect-client-leader
Use WM_CLIENT_LEADER to group windows, and
consider windows in the same group focused at the same time.
WM_TRANSIENT_FOR has higher priority if --detect-transient is
enabled, too.
--blur-background
Blur background of semi-transparent / ARGB windows. Bad
in performance, with driver-dependent behavior. The name of the switch may
change without prior notifications.
--blur-background-frame
Blur background of windows when the window frame is not
opaque. Implies --blur-background. Bad in performance, with
driver-dependent behavior. The name may change.
--blur-background-fixed
Use fixed blur strength rather than adjusting according
to window opacity.
--blur-kern MATRIX
Specify the blur convolution kernel, with the following
format:
The element in the center must not be included, it will be forever 1.0 or
changing based on opacity, depending on whether you have
--blur-background-fixed. Yet the automatic adjustment of blur factor may not
work well with a custom blur kernel.
A 7x7 Guassian blur kernel (sigma = 0.84089642) looks like:
May also be one of the predefined kernels: 3x3box (default), 5x5box, 7x7box,
3x3gaussian, 5x5gaussian, 7x7gaussian, 9x9gaussian, 11x11gaussian. All
Guassian kernels are generated with sigma = 0.84089642 . You may use the
accompanied compton-convgen.py to generate blur kernels.
--blur-background-exclude CONDITION
WIDTH,HEIGHT,ELE1,ELE2,ELE3,ELE4,ELE5...
--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'
Exclude conditions for background blur.
--resize-damage INTEGER
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
--dbe or --glx-swap-method, those pixels will still be
incorrectly painted to screen.) Primarily used to fix the line corruption
issues of blur, in which case you should use the blur radius value here (e.g.
with a 3x3 kernel, you should use --resize-damage 1, with a 5x5 one you
use --resize-damage 2, and so on). May or may not work with
--glx-no-stencil. Shrinking doesn’t function correctly.
--invert-color-include CONDITION
Specify a list of conditions of windows that should be
painted with inverted color. Resource-hogging, and is not well tested.
--opacity-rule OPACITY:'CONDITION'
Specify a list of opacity rules, in the format
PERCENT:PATTERN, like 50:name *= "Firefox". compton-trans is
recommended over this. Note we do not distinguish 100% and unset, and we
don’t make any guarantee about possible conflicts with other programs
that set _NET_WM_WINDOW_OPACITY on frame or client windows.
--shadow-exclude-reg GEOMETRY
Specify a X geometry that describes the region in which
shadow should not be painted in, such as a dock window region. Use
--shadow-exclude-reg x10+0-0, for example, if the 10 pixels on the bottom of
the screen should not have shadows painted on.
--xinerama-shadow-crop
Crop shadow of a window fully on a particular Xinerama
screen to the screen.
--backend BACKEND
Specify the backend to use: xrender or glx. GLX (OpenGL)
backend generally has much superior performance as far as you have a graphic
card/chip and driver.
--glx-no-stencil
GLX backend: Avoid using stencil buffer, useful if you
don’t have a stencil buffer. Might cause incorrect opacity when
rendering transparent content (but never practically happened) and may not
work with --blur-background. My tests show a 15% performance boost.
Recommended.
--glx-copy-from-front
GLX backend: Copy unmodified regions from front buffer
instead of redrawing them all. My tests with nvidia-drivers show a 10%
decrease in performance when the whole screen is modified, but a 20% increase
when only 1/4 is. My tests on nouveau show terrible slowdown. Useful with
--glx-swap-method, as well.
--glx-use-copysubbuffermesa
GLX backend: Use MESA_copy_sub_buffer to do
partial screen update. My tests on nouveau shows a 200% performance boost when
only 1/4 of the screen is updated. May break VSync and is not available on
some drivers. Overrides --glx-copy-from-front.
--glx-no-rebind-pixmap
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). Recommended if it
works.
--glx-swap-method undefined/exchange/copy/3/4/5/6/buffer-age
GLX backend: GLX buffer swap method we assume. Could be
undefined (0), copy (1), exchange (2), 3-6, or buffer-age (-1). undefined is
the slowest and the safest, and the default value. copy is fastest, but may
fail on some drivers, 2-6 are gradually slower but safer (6 is still faster
than 0). Usually, double buffer means 2, triple buffer means 3. buffer-age
means auto-detect using GLX_EXT_buffer_age, supported by some drivers.
Useless with --glx-use-copysubbuffermesa. Partially breaks
--resize-damage. Defaults to undefined.
--glx-use-gpushader4
GLX backend: Use GL_EXT_gpu_shader4 for some
optimization on blur GLSL code. My tests on GTX 670 show no noticeable
effect.
--dbus
Enable remote control via D-Bus. See the D-BUS API
section below for more details.
--benchmark CYCLES
Benchmark mode. Repeatedly paint until reaching the
specified cycles.
--benchmark-wid WINDOW_ID
Specify window ID to repaint in benchmark mode. If
omitted or is 0, the whole screen is repainted.
FORMAT OF CONDITIONS¶
Some options accept a condition string to match certain windows. A condition string is formed by one or more conditions, joined by logical operators. A condition with "exists" operator looks like this:<NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE>
<NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE> <NEGATION> <OP QUALIFIER> <MATCH TYPE> = <PATTERN>
<NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE> <NEGATION> <OPERATOR> <PATTERN>
# If the window is focused focused focused = 1 # If the window is not override-redirected !override_redirect override_redirect = false override_redirect != true override_redirect != 1 # If the window is a menu window_type *= "menu" _NET_WM_WINDOW_TYPE@:a *= "MENU" # If the window name contains "Firefox", ignore case name *?= "Firefox" _NET_WM_NAME@:s *?= "Firefox" # If the window name ends with "Firefox" name %= "*Firefox" name ~= "Firefox$" # If the window has a property _COMPTON_SHADOW with value 0, type CARDINAL, # format 32, value 0, on its frame window _COMPTON_SHADOW:32c = 0 # If the third value of _NET_FRAME_EXTENTS is less than 20, or there's no # _NET_FRAME_EXTENTS property on client window _NET_FRAME_EXTENTS@[2]:32c < 20 || !_NET_FRAME_EXTENTS@:32c # The pattern here will be parsed as "dd4" name = "\x64\x64\o64" # The pattern here will be parsed as "\x64\x64\x64" name = r"\x64\x64\o64"
LEGACY FORMAT OF CONDITIONS¶
This is the old condition format we once used. Support of this format might be removed in the future.condition = TARGET:TYPE[FLAGS]:PATTERN
CONFIGURATION FILES¶
compton could read from a configuration file if libconfig support is compiled in. If --config is not used, compton will seek for a configuration file in $XDG_CONFIG_HOME/compton.conf (~/.config/compton.conf, usually), then ~/.compton.conf, then compton.conf under $XDG_DATA_DIRS (often /etc/xdg/compton.conf). compton uses general libconfig configurtion file format. A sample configuration file is available as compton.sample.conf in the source tree. Most commandline switches each could be replaced with an option in configuration file, thus documented above. Window-type-specific settings are exposed only in configuration file and has the following format:wintypes: { WINDOW_TYPE = { fade = BOOL; shadow = BOOL; opacity = FLOAT; focus = BOOL; }; };
SIGNALS¶
•compton reinitializes itself upon receiving
SIGUSR1.
D-BUS API¶
It’s possible to control compton via D-Bus messages, by running compton with --dbus and send messages to com.github.chjj.compton.<DISPLAY>. <DISPLAY> is the display used by compton, with all non-alphanumeric characters transformed to underscores. For DISPLAY=:0.0 you should use com.github.chjj.compton._0_0, for example. The D-Bus methods and signals are not yet stable, thus undocumented right now.EXAMPLES¶
•Disable configuration file parsing:
$ compton --config /dev/null
•Run compton with client-side shadow and fading,
disable shadow on dock windows and drag-and-drop windows:
$ compton -cCGf
•Same thing as above, plus making inactive windows
80% transparent, making frame 80% transparent, don’t fade on window
open/close, enable software optimization, and fork to background:
$ compton -bcCGf -i 0.8 -e 0.8 --no-fading-openclose --sw-opti
•Draw white shadows:
$ compton -c --shadow-red 1 --shadow-green 1 --shadow-blue 1
•Avoid drawing shadows on wbar window:
$ compton -c --shadow-exclude 'class_g = "wbar"'
•Enable OpenGL SGI_swap_control VSync with GLX
backend:
$ compton --backend glx --vsync opengl-swc
BUGS¶
Please report any you find to https://github.com/chjj/compton .AUTHORS¶
xcompmgr, originally written by Keith Packard, with contributions from Matthew Allum, Eric Anholt, Dan Doel, Thomas Luebking, Matthew Hawn, Ely Levy, Phil Blundell, and Carl Worth. Compton by Christopher Jeffrey, based on Dana Jansens' original work, with contributions from Richard Grenville.RESOURCES¶
Homepage: https://github.com/chjj/comptonSEE ALSO¶
xcompmgr(1), compton-trans(1)11/03/2013 | compton nightly-20130421 |