compton

COMPTON(1)                       User Commands                      COMPTON(1)



NAME
       compton - a compositor for X11

SYNOPSIS
       compton [OPTIONS]

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, --help
           Get the usage text embedded in program code, which may be more
           up-to-date than this man page.

       -r, --shadow-radius=RADIUS
           The blur radius for shadows, in pixels. (defaults to 12)

       -o, --shadow-opacity=OPACITY
           The opacity of shadows. (0.0 - 1.0, defaults to 0.75)

       -l, --shadow-offset-x=OFFSET
           The left offset for shadows, in pixels. (defaults to -15)

       -t, --shadow-offset-y=OFFSET
           The top offset for shadows, in pixels. (defaults to -15)

       -I, --fade-in-step=OPACITY_STEP
           Opacity change between steps while fading in. (0.01 - 1.0, defaults
           to 0.028)

       -O, --fade-out-step=OPACITY_STEP
           Opacity change between steps while fading out. (0.01 - 1.0,
           defaults to 0.03)

       -D, --fade-delta=MILLISECONDS
           The time between steps in fade step, in milliseconds. (> 0,
           defaults to 10)

       -m, --menu-opacity=OPACITY
           Default opacity for dropdown menus and popup menus. (0.0 - 1.0,
           defaults to 1.0)

       -c, --shadow
           Enabled client-side shadows on windows. Note desktop windows
           (windows with _NET_WM_WINDOW_TYPE_DESKTOP) never get shadow, unless
           explicitly requested using the wintypes option.

       -C, --no-dock-shadow
           Avoid drawing shadows on dock/panel windows. This option is
           deprecated, you should use the wintypes option in your config file
           instead.

       -f, --fading
           Fade windows in/out when opening/closing and when opacity changes,
           unless --no-fading-openclose is used.

       -F
           Equals to -f. Deprecated.

       -i, --inactive-opacity=OPACITY
           Opacity of inactive windows. (0.1 - 1.0, defaults to 1.0)

       -e, --frame-opacity=OPACITY
           Opacity of window titlebars and borders. (0.1 - 1.0, disabled by
           default)

       -G, --no-dnd-shadow
           Don’t draw shadows on drag-and-drop windows. This option is
           deprecated, you should use the wintypes option in your config file
           instead.

       -b, --daemon
           Daemonize process. Fork to background after initialization. Causes
           issues with certain (badly-written) drivers.

       --log-level
           Set the log level. Possible values are "TRACE", "DEBUG", "INFO",
           "WARN", "ERROR", in increasing level of importance. Case doesn’t
           matter. If using the "TRACE" log level, it’s better to log into a
           file using --log-file, since it can generate a huge stream of logs.

       --log-file
           Set the log file. If --log-file 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.

       --experimental-backends
           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.

       --show-all-xerrors
           Show all X errors (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. Use /dev/null to avoid loading configuration file.

       --write-pid-path PATH
           Write process ID to a file.

       --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, defaults to 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.

       --no-fading-destroyed-argb
           Do not fade destroyed ARGB windows with WM frame. Workaround of
           bugs in Openbox, Fluxbox, etc.

       --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. Deprecated, use
           --shadow-exclude 'bounding_shaped' or --shadow-exclude
           'bounding_shaped && !rounded_corners' instead.

       --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
           Enable VSync.

       --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-method, --blur-size, --blur-deviation
           Parameters for background blurring, see the BLUR section for more
           information.

       --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:

               WIDTH,HEIGHT,ELE1,ELE2,ELE3,ELE4,ELE5...

           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 width * height - 1 numbers specifies
           the numbers in the matrix, row by row, excluding the center
           element.

           The elements are finite floating point numbers. The decimal pointer
           has to be .  (a period), scientific notation is not supported.

           The element in the center will either be 1.0 or varying 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 Gaussian blur kernel (sigma = 0.84089642) looks like:

               --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'

           May also be one of the predefined kernels: 3x3box (default),
           5x5box, 7x7box, 3x3gaussian, 5x5gaussian, 7x7gaussian, 9x9gaussian,
           11x11gaussian. All Gaussian kernels are generated with sigma =
           0.84089642 . You may use the accompanied compton-convgen.py to
           generate blur kernels.

       --blur-background-exclude CONDITION
           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 --use-damage, 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 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, glx, or xr_glx_hybrid.
           xrender is the default one.

           ·   xrender backend performs all rendering operations with X Render
               extension. It is what xcompmgr uses, and is generally a safe
               fallback when you encounter rendering artifacts or instability.

           ·   glx (OpenGL) backend performs all rendering operations with
               OpenGL. It is more friendly to some VSync methods, and has
               significantly superior performance on color inversion
               (--invert-color-include) or blur (--blur-background). It
               requires proper OpenGL 2.0 support from your driver and
               hardware. You may wish to look at the GLX performance
               optimization options below.  --xrender-sync-fence might be
               needed on some systems to avoid delay in changes of screen
               contents.

           ·   xr_glx_hybrid 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.
               --vsync-use-glfinish might fix some rendering issues with this
               backend.

       --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-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, xf86-video-intel,
           etc.). Recommended if it works.

       --use-damage
           Use the damage information to limit rendering to parts of the
           screen that has actually changed. Potentially improves the
           performance.

       --xrender-sync-fence
           Use X Sync fence to sync clients' draw calls, to make sure all draw
           calls are finished before compton starts drawing. Needed on
           nvidia-drivers with GLX backend for some users.

       --glx-fshader-win SHADER
           GLX backend: Use specified GLSL fragment shader for rendering
           window contents. See compton-default-fshader-win.glsl and
           compton-fake-transparency-fshader-win.glsl in the source tree for
           examples.

       --force-win-blend
           Force all windows to be painted with blending. Useful if you have a
           --glx-fshader-win that could turn opaque pixels transparent.

       --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>

       With equals operator it looks like:

           <NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE> <NEGATION> <OP QUALIFIER> <MATCH TYPE> = <PATTERN>

       With greater-than/less-than operators it looks like:

           <NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] : <FORMAT> <TYPE> <NEGATION> <OPERATOR> <PATTERN>

       NEGATION (optional) is one or more exclamation marks;

       TARGET 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 --detect-rounded-corners),
       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.

       CLIENT/FRAME is a single @ if the window attribute should be be looked
       up on client window, nothing if on frame window;

       INDEX (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.

       FORMAT (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.

       TYPE is a single character representing the type of the property to
       match for: c for CARDINAL, a for ATOM, w for WINDOW, d for DRAWABLE, s
       for STRING (and any other string types, such as UTF8_STRING). Do not
       specify it for predefined targets.

       OP QUALIFIER (optional), applicable only for equals operator, could be
       ? (ignore-case).

       MATCH TYPE (optional), applicable only for equals operator, could be
       nothing (exact match), * (match anywhere), ^ (match from start), %
       (wildcard), or ~ (PCRE regular expression).

       OPERATOR 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).

       PATTERN 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.

       Supported logical operators are && (and) and || (or). && has higher
       precedence than ||, left-to-right associativity. Use parentheses to
       change precedence.

       Examples:

           # 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

       TARGET is one of "n" (window name), "i" (window class instance), "g"
       (window general class), and "r" (window role).

       TYPE 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).

       FLAGS could be a series of flags. Currently the only defined flag is
       "i" (ignore case).

       PATTERN is the actual pattern string.

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_CONFIG_DIRS (often /etc/xdg/compton.conf).

       compton uses general libconfig configuration file format. A sample
       configuration file is available as compton.sample.conf in the source
       tree. Most of commandline switches can be used as options in
       configuration file as well. For example, --vsync option documented
       above can be set in the configuration file using `vsync = `. Command
       line options will always overwrite the settings in the configuration
       file.

       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; full-shadow = BOOL; redir-ignore = BOOL; };
           };

       WINDOW_TYPE 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", "notify",
       "combo", and "dnd".

       Following per window-type options are available:

           fade, shadow
               Controls window-type-specific shadow and fade settings.

           opacity
               Controls default opacity of the window type.

           focus
               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.)

           full-shadow
               Controls whether shadow is drawn under the parts of the window
               that you normally won’t be able to see. Useful when the window
               has parts of it transparent, and you want shadows in those
               areas.

           redir-ignore
               Controls whether this type of windows should cause screen to
               become redirected again after been unredirected. If you have
               --unredir-if-possible set, and doesn’t want certain window to
               cause unnecessary screen redirection, you can set this to true.

BLUR
       You can configure how the window background is blurred using a blur
       section in your configuration file. Here is an example:

           blur:
           {
             method = "gaussian";
             size = 10;
             deviation = 5.0;
           };

       Available options of the blur section are:

           method
               A string. Controls the blur method. Corresponds to the
               --blur-method command line option. Available choices are: none
               to disable blurring; gaussian for gaussian blur; box for box
               blur; kernel for convolution blur with a custom kernel. Note:
               gaussian and box blur methods are only supported by the
               experimental backends.

           size
               An integer. The size of the blur kernel, required by gaussian
               and box blur methods. For the kernel method, the size is
               included in the kernel. Corresponds to the --blur-size command
               line option.

           deviation
               A floating point number. The standard deviation for the
               gaussian blur method. Corresponds to the --blur-deviation
               command line option.

           kernel
               A string. The kernel to use for the kernel blur method,
               specified in the same format as the --blur-kerns option.
               Corresponds to the --blur-kerns command line option.

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 VSync with GLX backend:

               $ compton --backend glx --vsync

BUGS
       Please submit bug reports to https://github.com/yshui/compton.

       Out dated information in this man page is considered a bug.

RESOURCES
       Homepage: https://github.com/yshui/compton

SEE ALSO
       xcompmgr(1), compton-trans(1)



compton v7.4                      09/23/2019                        COMPTON(1)