picom/man/picom.1.asciidoc

picom(1)
========
:doctype:     manpage
:man source:  picom
:man version: {picom-version}
:man manual:  User Commands

NAME
----
picom - a compositor for X11

SYNOPSIS
--------
*picom* ['OPTIONS']

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

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)

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

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

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

*-b*, *--daemon*::
	Daemonize process. Fork to background after initialization. This option can only be set from the command line, setting this in the configuration file will have no effect.

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

*--legacy-backends*::
	Use the old version of the backends. This option can not be set from 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 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 path.

*--plugins* 'PATH'::
	Specify plugins to load. Plugins will first be searched in current working directory (unless specified in the config file, in which case this step is skipped), then in `$XDG_CONFIG_HOME/picom/plugins`, then in `$XDG_CONFIG_DIRS/picom/plugins`. If all of the above fail, the plugin name is passed directly to the dynamic loader. Can be specified multiple times to load more than one plugins.

*--shadow-color* 'STRING'::
	Color of shadow, as a hex string ('#000000')

*--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* override the '_NET_WM_WINDOW_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)

*--corner-radius* 'VALUE'::
	Sets the radius of rounded window corners. When > 0, the compositor will round the corners of windows. Does not interact well with *--transparent-clipping*. (defaults to 0).

*--corner-radius-rules* 'RADIUS':'CONDITION'::
	Specify a list of corner radius rules. Overrides the corner radii of matching windows. This option takes precedence over the *--rounded-corners-exclude* option, and also overrides the default exclusion of fullscreen windows. The condition has the same format as *--opacity-rule*.

*--rounded-corners-exclude* 'CONDITION'::
	Exclude conditions for rounded corners.

*--no-frame-pacing*::
	Disable vsync-aware frame pacing. By default, the compositor tries to make sure it only renders once per vblank interval, and also the render happens as late as possible to minimize the latency from updates to the screen. However this can sometimes cause stuttering, or even lowered frame rate. This option can be used to disable frame pacing.

*--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_WINDOW_OPACITY' on client windows, useful for window managers not passing '_NET_WM_WINDOW_OPACITY' of client windows to frame windows.

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

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

*--unredir-if-possible*::
	Unredirect all windows in some cases. Known to cause flickering when redirecting/unredirecting windows. Currently, unredirecting is triggered by following conditions:
	    * If the top level window is taking up the entire screen. In multi-monitor setup, this means ALL monitors.
	    * If there is no window.
	    * If a window is fullscreen according to its WM hints. (can be disabled with *--no-ewmh-fullscreen*).
	    * If a window requests to bypass the compositor ('_NET_WM_BYPASS_COMPOSITOR').
	Windows are also unredirected unconditionally when monitors are powered off, regardless if *--unredir-if-possible* is set.


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

*--clip-shadow-above* 'CONDITION'::
	Specify a list of conditions of windows that should have no shadow painted over, such as a dock window.

*--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. This usually means windows from the same application will be considered focused or unfocused at the same time.'WM_TRANSIENT_FOR' has higher priority if *--detect-transient* is enabled, too.

*--blur-method*, *--blur-size*, *--blur-deviation*, *--blur-strength*::
	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 . If you find yourself needing to generate custom blur kernels, you might want to try the new blur configuration (See *BLUR*).

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

*--crop-shadow-to-monitor*::
	Crop shadow of a window fully on a particular monitor to that monitor. This is currently implemented using the X RandR extension.

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

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

*--xrender-sync-fence*::
	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 examples. Only works with *--legacy-backends* enabled.

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

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

*--max-brightness*::
	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)

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

*--transparent-clipping-exclude* 'CONDITION'::
	Specify a list of conditions of windows that should never have transparent clipping applied. Useful for screenshot tools, where you need to be able to see through transparent parts of the window.

*--window-shader-fg* 'SHADER'::
	Specify GLSL fragment shader path for rendering window contents. Does not work when *--legacy-backends* is enabled. Shader is searched first relative to the directory the configuration file is in, then in the usual places for a configuration file. See section *SHADER INTERFACE* below for more details on the interface.

*--window-shader-fg-rule* 'SHADER':'CONDITION'::
	Specify GLSL fragment shader path for rendering window contents using patterns. Similar to *--opacity-rule*, arguments should be in the format of 'SHADER:CONDITION', e.g. "shader.frag:name = \'window\'". Leading and trailing whitespaces in 'SHADER' will be trimmed. If 'SHADER' is "default", then the default shader will be used for the matching windows. (This also unfortunately means you can't use a shader file named "default"). Does not work when *--legacy-backends* is enabled.

*--dithered-present*
	Use higher precision during rendering, and apply dither when presenting the rendered screen. Reduces banding artifacts, but might cause performance degradation. Only works with OpenGL.

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

With equals operator it looks like:

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

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

	<NEGATION> <TARGET> <CLIENT/FRAME> [<INDEX>] <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` (like `x2`), `width`, `height`, `widthb` (`width` + 2 * `border_width`), `heightb` (like `widthb`), `border_width`, `fullscreen`, `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. If not specified, the first value (index `[0]`) is used implicitly. Use the special value `[*]` to perform matching against all available property values using logical OR. 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 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@ *= "MENU"
	# If the window is marked hidden: _NET_WM_STATE contains _NET_WM_STATE_HIDDEN
	_NET_WM_STATE@[*] = "_NET_WM_STATE_HIDDEN"
	# If the window is marked sticky: _NET_WM_STATE contains an atom that contains
	# "sticky", ignore case
	_NET_WM_STATE@[*] *?= "sticky"
	# If the window name contains "Firefox", ignore case
	name *?= "Firefox"
	_NET_WM_NAME@ *?= "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 = 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] < 20 || !_NET_FRAME_EXTENTS@
	# The pattern here will be parsed as "dd4"
	name = "\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.

SHADER INTERFACE
----------------

This secion describes the interface of a custom shader, how it is used by picom, and what parameters are passed by picom to the shader. This does not apply to the legacy backends.

A custom shader is a GLSL fragment shader program, which can be used to override the default way of how a window is rendered. If a custom shader is used, the default picom effects (e.g. dimming, color inversion, etc.) will no longer be automatically applied. It would be the custom shader's responsibility to apply these effects.

The interface between picom and a custom shader is dependent on which backend is being used. The xrender backend doesn't support shader at all. Here we descibe the interface provided by the glx backend.

The shader must define a function, 'vec4 window_shader()', which would be the entry point of the shader. The returned 'vec4' will be used to set 'gl_FragColor'. A function, 'vec4 default_post_processing(vec4 c)', is provided for applying the default picom effects to input color 'c'.

The following uniform/input variables are made available to the shader:

[source,glsl]
----
in vec2 texcoord;             // texture coordinate of the fragment

uniform float opacity;        // opacity of the window (0.0 - 1.0)
uniform float dim;            // dimming factor of the window (0.0 - 1.0, higher means more dim)
uniform float corner_radius;  // corner radius of the window (pixels)
uniform float border_width;   // estimated border width of the window (pixels)
uniform bool invert_color;    // whether to invert the color of the window
uniform sampler2D tex;        // texture of the window
uniform vec2 effective_size;  // effective dimensions of the texture (repeats pixels if larger than tex)
uniform sampler2D brightness; // estimated brightness of the window, 1x1 texture
uniform float max_brightness; // configured maximum brightness of the window (0.0 - 1.0)
uniform float time;           // time in milliseconds, counting from an unspecified starting point
----

The default behavior of picom window rendering can be replicated by the following shader:

[source,glsl]
----
#version 330
in vec2 texcoord;             // texture coordinate of the fragment

uniform sampler2D tex;        // texture of the window

// Default window post-processing:
// 1) invert color
// 2) opacity / transparency
// 3) max-brightness clamping
// 4) rounded corners
vec4 default_post_processing(vec4 c);

// Default window shader:
// 1) fetch the specified pixel
// 2) apply default post-processing
vec4 window_shader() {
    vec2 texsize = textureSize(tex, 0);
    vec4 c = texture2D(tex, texcoord / texsize, 0);
    return default_post_processing(c);
}
----

The interface is expected to be mostly stable.

CONFIGURATION FILES
-------------------
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`.

When `@include` directive is used in the config file, picom will first search for the included file in the parent directory of `picom.conf`, then in `$XDG_CONFIG_HOME/picom/include/`, then in `$XDG_CONFIG_DIRS/picom/include`.

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 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; blur-background = BOOL; full-shadow = BOOL; clip-shadow-above = 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.

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

  blur-background:::
    Controls whether the window of this type will have its transparent background blurred.

  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.

  clip-shadow-above:::
    Controls whether shadows that would have been drawn above the window should be clipped. Useful for dock windows that should have no shadow painted on top.

  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; 'dual_kawase' for dual-filter kawase blur.
    Note: 'gaussian', 'box' and 'dual_kawase' blur methods are not supported by the legacy backends.
    (default: none)

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

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

  *strength*:::
    An integer in the range 0-20. The strength of the 'dual_kawase' blur method. Corresponds to the *--blur-strength* command line option. If set to zero, the value requested by *--blur-size* is approximated (default: 5).

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

SIGNALS
-------

* picom reinitializes itself upon receiving `SIGUSR1`.

D-BUS API
---------

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.

EXAMPLES
--------

* Disable configuration file parsing:
+
------------
$ picom --config /dev/null
------------

* Run picom with client-side shadow and fading:
+
------------
$ picom -cf
------------

* Same thing as above, plus making inactive windows 80% transparent, making frame 80% transparent, don't fade on window open/close, and fork to background:
+
------------
$ picom -bcf -i 0.8 -e 0.8 --no-fading-openclose
------------

* Draw white shadows:
+
------------
$ picom -c --shadow-red 1 --shadow-green 1 --shadow-blue 1
------------

* Avoid drawing shadows on wbar window:
+
------------
$ picom -c --shadow-exclude 'class_g = "wbar"'
------------

* Enable VSync with GLX backend:
+
------------
$ picom --backend glx --vsync
------------

BUGS
----
Please submit bug reports to <https://github.com/yshui/picom>.

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

RESOURCES
---------
Homepage: <https://github.com/yshui/picom>

SEE ALSO
--------
*xcompmgr*(1), link:picom-inspect.html[*picom-inspect*(1)], link:picom-trans.html[*picom-trans*(1)]