compton






compton − a compositor for X11



compton [OPTIONS]



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.



     −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









                             ‐2‐


     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.










                             ‐3‐


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









                             ‐4‐


     && !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.











                             ‐5‐


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









                             ‐6‐


     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









                             ‐7‐


     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









                             ‐8‐


     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.



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:









                             ‐9‐


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










                            ‐10‐


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"



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.



compton could read from a configuration file if libconfig
support is compiled in. If −−config is not used, compton









                            ‐11‐


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.









                            ‐12‐




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.



 •   compton reinitializes itself upon receiving SIGUSR1.



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.









                            ‐13‐


The D−Bus methods and signals are not yet stable, thus
undocumented right now.



 •   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



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

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



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



xcompmgr(1), compton−trans(1)