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

FreeBSD Manual Pages


home | help
PICOM(1)			 User Commands			      PICOM(1)

       picom - a compositor for	X11

       picom [OPTIONS]

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

       -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, defaults to	1.0)

       -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.	This option is
	   deprecated, you should use the wintypes option in your config file

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

	   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.

	   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.

	   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 X errors (for debugging).

       --config	PATH
	   Look	for configuration file at the path. See	CONFIGURATION FILES
	   section below for where picom 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. it is recommended to use	an absolute

       --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 override the _NET_WM_OPACITY values
	   of windows.

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

	   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, picom
	   will	try detecting this with	X RandR	extension.

       --vsync,	--no-vsync
	   Enable/disable VSync.

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

	   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.

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

	   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:


	   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

	   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 .	If you find yourself needing to	generate custom	blur
	   kernels, you	might want to try the new blur configuration supported
	   by the experimental backends	(See BLUR and

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

       --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-fence might be
	       needed on some systems to avoid delay in	changes	of screen

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

	   Disable the use of damage information. This cause the whole screen
	   to be redrawn everytime, instead of the part	of the screen has
	   actually changed. Potentially degrades the performance, but might
	   fix some artifacts.

	   Use X Sync fence to sync clients' draw calls, to make sure all draw
	   calls are finished before picom 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

	   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.

	   Do not use EWMH to detect fullscreen	windows. Reverts to checking
	   if a	window is fullscreen based only	on its size and	coordinates.

	   Dimming bright windows so their brightness doesn't exceed this set
	   value. Brightness of	a window is estimated by averaging all pixels
	   in the window, so this could	comes with a performance hit. Setting
	   this	to 1.0 disables	this behaviour.	Requires --use-damage to be
	   disabled. (default: 1.0)

	   Make	transparent windows clip other windows like non-transparent
	   windows do, instead of blending on top of them.

       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.

       picom could read	from a configuration file if libconfig support is
       compiled	in. If --config	is not used, picom will	seek for a
       configuration file in $XDG_CONFIG_HOME/picom.conf
       (~/.config/picom.conf, usually),	then
       $XDG_CONFIG_HOME/picom/picom.conf, then $XDG_CONFIG_DIRS/picom.conf
       (often /etc/xdg/picom.conf), then $XDG_CONFIG_DIRS/picom/picom.conf.

       picom uses general libconfig configuration file format. A sample
       configuration file is available as picom.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

       Window-type-specific settings are exposed only in configuration file
       and has the following format:

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

       Following per window-type options are available:

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

	       Controls	default	opacity	of the window type.

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

	       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

	       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.

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

	     method = "gaussian";
	     size = 10;
	     deviation = 5.0;

       Available options of the	blur section are:

	       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. (default:	none)

	       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 (default: 3).

	       A floating point	number.	The standard deviation for the
	       gaussian	blur method. Corresponds to the	--blur-deviation
	       command line option (default: 0.84089642).

	       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.

       o   picom reinitializes itself upon receiving SIGUSR1.

       It's possible to	control	picom via D-Bus	messages, by running picom
       with --dbus and send messages to	com.github.chjj.compton.<DISPLAY>.
       <DISPLAY> is the	display	used by	picom, 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:

	       $ picom --config	/dev/null

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

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

	       $ picom -bcCGf -i 0.8 -e	0.8 --no-fading-openclose --sw-opti

       o   Draw	white shadows:

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

       o   Avoid drawing shadows on wbar window:

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

       o   Enable VSync	with GLX backend:

	       $ picom --backend glx --vsync

       Please submit bug reports to

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


       xcompmgr(1), picom-trans(1)

picom v8.2			  03/01/2021			      PICOM(1)


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

home | help