Version 1.01.0.0

2 files changed, 200 insertions, 50 deletions

diff --git a/man/picom-trans.1.asciidoc b/man/picom-trans.1.asciidoc
new file mode 100644
index 0000000..22b1dd2
--- /dev/null
+++ b/man/picom-trans.1.asciidoc
@@ -0,0 +1,114 @@
+picom-trans(1)
+================
+:doctype:     manpage
+:man source:  picom
+:man version: {picom-version}
+:man manual:  User Commands
+
+NAME
+----
+picom-trans - an opacity setter tool
+
+SYNOPSIS
+--------
+
+*picom-trans* [-w 'WINDOW_ID'] [-n 'WINDOW_NAME'] [-c] [-s] 'OPACITY'
+
+DESCRIPTION
+-----------
+
+*picom-trans* is a bash script that sets '_NET_WM_WINDOW_OPACITY' attribute of a window using standard X11 command-line utilities, including *xprop*(1) and *xwininfo*(1). It is similar to *transset*(1) or *transset-df*(1).
+
+OPTIONS
+-------
+*-w*, *--window*='WINDOW_ID'::
+Specify the window id of the target window.
+
+*-n*, *--name*='WINDOW_NAME'::
+Specify and try to match a window name.
+
+*-c*, *--current*::
+Specify the currently active window as target. Only works if EWMH '_NET_ACTIVE_WINDOW' property exists on root window.
+
+*-s*, *--select*::
+Select target window with mouse cursor. This is the default if no window has been specified.
+
+*-o*, *--opacity*='OPACITY'::
+Specify the new opacity value for the window. This value can be anywhere from 1-100. If it is prefixed with a plus or minus (+/-), this will increment or decrement from the target window's current opacity instead.
+
+*-g*, *--get*::
+Print the target window's opacity instead of setting it.
+
+*-d*, *--delete*::
+Delete opacity of the target window instead of setting it.
+
+*-t*, *--toggle*::
+Toggle the target window's opacity: Set opacity if not already set, and delete if already set.
+
+*-r*, *--reset*::
+Reset opacity for all windows instead of setting it.
+
+EXAMPLES
+--------
+
+* Set the opacity of the window with specific window ID to 75%:
++
+------------
+picom-trans -w "$WINDOWID" 75
+------------
+
+* Set the opacity of the window with the name "urxvt" to 75%:
++
+------------
+picom-trans -n "urxvt" 75
+------------
+
+* Set current window to opacity of 75%:
++
+------------
+picom-trans -c 75
+------------
+
+* Select target window and set opacity to 75%:
++
+------------
+picom-trans -s 75
+------------
+
+* Increment opacity of current active window by 5%:
++
+------------
+picom-trans -c +5
+------------
+
+* Decrement opacity of current active window by 5%:
++
+------------
+picom-trans -c -- -5
+------------
+
+* Delete current window's opacity:
++
+------------
+picom-trans -c --delete
+------------
+
+* Toggle current window's opacity between 90 and unset
++
+------------
+picom-trans -c --toggle 90
+------------
+
+* Reset all windows:
++
+------------
+picom-trans --reset
+------------
+
+BUGS
+----
+Please submit bug reports to <https://github.com/yshui/picom>.
+
+SEE ALSO
+--------
+link:picom.1.html[*picom*(1)], *xprop*(1), *xwininfo*(1)
diff --git a/man/picom.1.asciidoc b/man/picom.1.asciidoc
index 2a3f327..61af5a2 100644
--- a/man/picom.1.asciidoc
+++ b/man/picom.1.asciidoc
@@ -15,7 +15,7 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-picom is a compositor for X11 which gives features to WM and DE such as opacity, blurring, rounded edges, shadows and most importantly. Animations!
+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
 -------
@@ -43,9 +43,6 @@ OPTIONS
 *-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.
 
@@ -55,28 +52,6 @@ OPTIONS
 *-F*::
 	Equals to *-f*. Deprecated.
 
-*--animations*::
-	Run animations for window geometry changes (movement and scaling).
-	We use spring-based animations, which are parametrized by *--animation-stiffness*, *--animation-dampening*, *--animation-window-mass* and *--animation-clamp*. +
-	A useful resource for selecting animation parameters is https://react-spring-visualizer.com/, which allows you to interactively try out various parameters and see the resulting animation curve. Or you can just edit the values in the config file, which is automatically reloaded.
-
-*--animation-for-open-window*::
-	Which animation to run when opening a window. Must be one of `none`, `fly-in`, `zoom` (default: `none`).
-
-*--animation-stiffness*::
-	Stiffness (a.k.a. tension) parameter for spring-based animation (default: 200.0).
-
-*--animation-dampening*::
-	Dampening (a.k.a. friction) parameter for spring-based animation (default: 25.0).
-
-*--animation-window-mass*::
-	Mass parameter for spring-based animation (default: 1.0).
-
-*--animation-clamping*::
-	Whether to clamp animations (default: true).
-
-	**NOTE:** With clamping disabled, on very low performance conditions (e.g., over 100ms to render an animation frame), windows may diverge. If this is your case, it is strongly advised to keep clamping on, as it protects against that.
-
 *-i*, *--inactive-opacity*='OPACITY'::
 	Opacity of inactive windows. (0.1 - 1.0, defaults to 1.0)
 
@@ -92,8 +67,8 @@ OPTIONS
 *--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.
+*--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).
@@ -117,7 +92,7 @@ OPTIONS
 	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_OPACITY' values of windows.
+	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)
@@ -150,10 +125,7 @@ OPTIONS
 	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, picom will try detecting this with X RandR extension.
+	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.
@@ -189,7 +161,7 @@ OPTIONS
 	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.
+	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.
@@ -222,7 +194,7 @@ 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 *--experimental-backends*).
+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.
@@ -258,13 +230,13 @@ May also be one of the predefined kernels: `3x3box` (default), `5x5box`, `7x7box
 	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 everytime, instead of the part of the screen has actually changed. Potentially degrades the performance, but might fix some artifacts.
+	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.
+	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.
@@ -287,6 +259,15 @@ May also be one of the predefined kernels: `3x3box` (default), `5x5box`, `7x7box
 *--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.
+
 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.
@@ -321,7 +302,7 @@ With greater-than/less-than operators it looks like:
 
 '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.
+'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.
 
@@ -357,8 +338,6 @@ Examples:
 	_NET_FRAME_EXTENTS@[2]:32c < 20 || !_NET_FRAME_EXTENTS@:32c
 	# The pattern here will be parsed as "dd4"
 	name = "\x64\x64\o64"
-	# The pattern here will be parsed as "\x64\x64\x64"
-	name = r"\x64\x64\o64"
 
 
 LEGACY FORMAT OF CONDITIONS
@@ -376,6 +355,61 @@ This is the old condition format we once used. Support of this format might be r
 
 '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 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() {
+    vec4 c = texelFetch(tex, ivec2(texcoord), 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`.
@@ -405,13 +439,13 @@ Following per window-type options are available: ::
     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 wether the window of this type will have its transparent background blurred.
+    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 wether shadows that would have been drawn above the window should be clipped. Useful for dock windows that should have no shadow painted on top.
+    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`.
@@ -434,7 +468,7 @@ 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 only supported by the experimental backends.
+    Note: 'gaussian', 'box' and 'dual_kawase' blur methods are not supported by the legacy backends.
     (default: none)
 
   *size*:::
@@ -470,16 +504,16 @@ EXAMPLES
 $ picom --config /dev/null
 ------------
 
-* Run picom with client-side shadow and fading, disable shadow on dock windows and drag-and-drop windows:
+* Run picom with client-side shadow and fading:
 +
 ------------
-$ picom -cCGf
+$ 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 -bcCGf -i 0.8 -e 0.8 --no-fading-openclose
+$ picom -bcf -i 0.8 -e 0.8 --no-fading-openclose
 ------------
 
 * Draw white shadows:
@@ -502,12 +536,14 @@ $ picom --backend glx --vsync
 
 BUGS
 ----
-Please submit bug reports to <https://github.com/allusive-dev/picom-allusive>.
+Please submit bug reports to <https://github.com/yshui/picom>.
 
-Out dated information in this man page is NOT considered a bug.
+Out dated information in this man page is considered a bug.
 
 RESOURCES
 ---------
-Website: <https://allusive.dev>
+Homepage: <https://github.com/yshui/picom>
 
-GithubPage: <https://github.com/allusive-dev/picom-allusive>
+SEE ALSO
+--------
+*xcompmgr*(1), link:picom-trans.html[*picom-trans*(1)]