You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
-14
Original file line number
Diff line number
Diff line change
@@ -7,20 +7,6 @@ __picom__ is a compositor for X, and a [fork of Compton](History.md).
7
7
8
8
You can leave your feedback or thoughts in the [discussion tab](https://github.com/yshui/picom/discussions).
9
9
10
-
## Call for testers
11
-
12
-
### `--experimental-backends`
13
-
14
-
This flag enables the refactored/partially rewritten backends.
15
-
16
-
Currently, new backends feature better vsync with the xrender backend and improved input lag with the glx backend (for non-NVIDIA users). The performance should be on par with the old backends.
17
-
18
-
New backend features will only be implemented on the new backends from now on, and the old backends will eventually be phased out after the new backends stabilize.
19
-
20
-
To test the new backends, add the `--experimental-backends` flag to the command you use to run picom. This flag is not available from the configuration file.
21
-
22
-
To report issues with the new backends, please state explicitly you are using the new backends in your report.
23
-
24
10
## Change Log
25
11
26
12
See [Releases](https://github.com/yshui/picom/releases)
Copy file name to clipboardexpand all lines: man/picom.1.asciidoc
+68-9
Original file line number
Diff line number
Diff line change
@@ -89,8 +89,8 @@ OPTIONS
89
89
*--log-file*::
90
90
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.
91
91
92
-
*--experimental-backends*::
93
-
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.
92
+
*--legacy-backends*::
93
+
Use the old version of the backends. This option can not be set from the config file.
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*).
219
+
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*).
220
220
221
221
*--blur-background-exclude* 'CONDITION'::
222
222
Exclude conditions for background blur.
@@ -258,7 +258,7 @@ May also be one of the predefined kernels: `3x3box` (default), `5x5box`, `7x7box
258
258
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.
259
259
260
260
*--glx-fshader-win* 'SHADER'::
261
-
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.
261
+
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.
262
262
263
263
*--force-win-blend*::
264
264
Force all windows to be painted with blending. Useful if you have a *--glx-fshader-win* that could turn opaque pixels transparent.
@@ -281,6 +281,12 @@ May also be one of the predefined kernels: `3x3box` (default), `5x5box`, `7x7box
281
281
*--transparent-clipping*::
282
282
Make transparent windows clip other windows like non-transparent windows do, instead of blending on top of them.
283
283
284
+
*--window-shader-fg* 'SHADER'::
285
+
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.
286
+
287
+
*--window-shader-fg-rule* 'SHADER':'CONDITION'::
288
+
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.
289
+
284
290
FORMAT OF CONDITIONS
285
291
--------------------
286
292
Some options accept a condition string to match certain windows. A condition string is formed by one or more conditions, joined by logical operators.
# The pattern here will be parsed as "\x64\x64\x64"
355
-
name = r"\x64\x64\o64"
356
360
357
361
358
362
LEGACY FORMAT OF CONDITIONS
@@ -370,6 +374,61 @@ This is the old condition format we once used. Support of this format might be r
370
374
371
375
'PATTERN' is the actual pattern string.
372
376
377
+
SHADER INTERFACE
378
+
----------------
379
+
380
+
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.
381
+
382
+
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.
383
+
384
+
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.
385
+
386
+
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'.
387
+
388
+
The following uniform/input variables are made available to the shader:
389
+
390
+
[source,glsl]
391
+
----
392
+
in vec2 texcoord; // texture coordinate of the fragment
393
+
394
+
uniform float opacity; // opacity of the window (0.0 - 1.0)
395
+
uniform float dim; // dimming factor of the window (0.0 - 1.0, higher means more dim)
396
+
uniform float corner_radius; // corner radius of the window (pixels)
397
+
uniform float border_width; // estimated border width of the window (pixels)
398
+
uniform bool invert_color; // whether to invert the color of the window
399
+
uniform sampler2D tex; // texture of the window
400
+
uniform sampler2D brightness; // estimated brightness of the window, 1x1 texture
401
+
uniform float max_brightness; // configured maximum brightness of the window (0.0 - 1.0)
402
+
uniform float time; // time in milliseconds, counting from an unspecified starting point
403
+
----
404
+
405
+
The default behavior of picom window rendering can be replicated by the following shader:
406
+
407
+
[source,glsl]
408
+
----
409
+
#version 330
410
+
in vec2 texcoord; // texture coordinate of the fragment
411
+
412
+
uniform sampler2D tex; // texture of the window
413
+
414
+
// Default window post-processing:
415
+
// 1) invert color
416
+
// 2) opacity / transparency
417
+
// 3) max-brightness clamping
418
+
// 4) rounded corners
419
+
vec4 default_post_processing(vec4 c);
420
+
421
+
// Default window shader:
422
+
// 1) fetch the specified pixel
423
+
// 2) apply default post-processing
424
+
vec4 window_shader() {
425
+
vec4 c = texelFetch(tex, ivec2(texcoord), 0);
426
+
return default_post_processing(c);
427
+
}
428
+
----
429
+
430
+
The interface is expected to be mostly stable.
431
+
373
432
CONFIGURATION FILES
374
433
-------------------
375
434
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`.
@@ -399,13 +458,13 @@ Following per window-type options are available: ::
399
458
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.)
400
459
401
460
blur-background:::
402
-
Controls wether the window of this type will have its transparent background blurred.
461
+
Controls whether the window of this type will have its transparent background blurred.
403
462
404
463
full-shadow:::
405
464
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.
406
465
407
466
clip-shadow-above:::
408
-
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.
467
+
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.
409
468
410
469
redir-ignore:::
411
470
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`.
@@ -428,7 +487,7 @@ Available options of the 'blur' section are: ::
428
487
*method*:::
429
488
A string. Controls the blur method. Corresponds to the *--blur-method* command line option. Available choices are:
430
489
'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.
431
-
Note: 'gaussian', 'box' and 'dual_kawase' blur methods are only supported by the experimental backends.
490
+
Note: 'gaussian', 'box' and 'dual_kawase' blur methods are not supported by the legacy backends.
0 commit comments