Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

       compton - a compositor for X11

       compton [OPTIONS]

       This man	page may be less up-to-date than the usage text	in compton
       (compton	-h).

       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.

       -d DISPLAY
	   Display to be managed.

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

       -C, --no-dock-shadow
	   Avoid drawing shadows on dock/panel windows.

       -z, --clear-shadow
	   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, --fading
	   Fade	windows	in/out when opening/closing and	when opacity changes,
	   unless --no-fading-openclose	is used.

	   Equals to -f. Deprecated.

       -i, --inactive-opacity=OPACITY
	   Opacity of inactive windows.	(0.1 - 1.0, disabled by	default)

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

       -G, --no-dnd-shadow
	   Don't draw shadows on drag-and-drop windows.

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

	   Enable synchronous X	operation (for debugging).

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

	   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)

	   Try to detect WM windows (a non-override-redirect window with no
	   child that has WM_STATE) and	mark them as active.

	   Mark	override-redirect windows that doesn't have a child window
	   with	WM_STATE focused.

	   Do not fade on window open/close.

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

	   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.

	   Try to detect windows with rounded corners and don't	consider them
	   shaped windows. The accuracy	is not very high, unfortunately.

	   Detect _NET_WM_OPACITY on client windows, useful for	window
	   managers not	passing	_NET_WM_OPACITY	of client windows to frame

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

	   o   none: No	VSync

	   o   drm: VSync with DRM_IOCTL_WAIT_VBLANK. May only work on some
	       (DRI-based) drivers.

	   o   opengl: Try to VSync with SGI_video_sync	OpenGL extension. Only
	       work on some drivers.

	   o   opengl-oml: Try to VSync	with OML_sync_control OpenGL
	       extension. Only work on some drivers.

	   o   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
	       guarantee to control paint timing.

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

	   Enable DBE painting mode, intended to use with VSync	to (hopefully)
	   eliminate tearing. Reported to have no effect, though.

	   Painting on X Composite overlay window instead of on	root window.

	   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 _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 _COMPTON_SHADOW. This a prototype-level feature, which you
	   must	not rely on.

	   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

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

	   Use fixed inactive dim value, instead of adjusting according	to
	   window opacity.

	   Use WM_TRANSIENT_FOR	to group windows, and consider windows in the
	   same	group focused at the same time.

	   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 of semi-transparent / ARGB windows. Bad in
	   performance,	with driver-dependent behavior.	The name of the	switch
	   may change without prior notifications.

	   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.

	   Use fixed blur strength rather than adjusting according to window

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

	   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.

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

	   o   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 and
	       --xrender-sync-fence might be needed on some systems to avoid
	       delay in	changes	of screen contents.

	   o   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

	   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.

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

       --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 backend:	Use GL_EXT_gpu_shader4 for some	optimization on	blur
	   GLSL	code. My tests on GTX 670 show no noticeable effect.

	   Attempt to synchronize client applications' draw calls with
	   XSync(), used on GLX	backend	to ensure up-to-date window content is

	   Additionally	use X Sync fence to sync clients' draw calls. Needed
	   on nvidia-drivers with GLX backend for some users. May be disabled
	   at compile time with	NO_XSYNC=1.

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

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

	   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

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

       A condition with	"exists" operator looks	like this:


       With equals operator it looks like:


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


       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.


	   # If	the window is focused
	   focused = 1
	   # If	the window is not override-redirected
	   override_redirect = false
	   override_redirect !=	true
	   override_redirect !=	1
	   # If	the window is a	menu
	   window_type *= "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.


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

	     WINDOW_TYPE = { fade = BOOL; shadow = BOOL; opacity = FLOAT; focus	= 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". "fade" and "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.)

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

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

       o   Disable configuration file parsing:

	       $ compton --config /dev/null

       o   Run compton with client-side	shadow and fading, disable shadow on
	   dock	windows	and drag-and-drop windows:

	       $ compton -cCGf

       o   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

       o   Draw	white shadows:

	       $ compton -c --shadow-red 1 --shadow-green 1 --shadow-blue 1

       o   Avoid drawing shadows on wbar window:

	       $ compton -c --shadow-exclude 'class_g =	"wbar"'

       o   Enable OpenGL SGI_swap_control VSync	with GLX backend:

	       $ compton --backend glx --vsync opengl-swc

       Please report any you find to .

       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.


       xcompmgr(1), compton-trans(1)

compton	nightly-20141124	  09/11/2021			    COMPTON(1)


Want to link to this manual page? Use this URL:

home | help