PolytreeDE/picom
1
0
Fork 0
mirror of https://github.com/yshui/picom.git synced 2024-11-25 14:06:08 -05:00
Code Releases Activity

man: define the custom shader interface

Browse source 
Signed-off-by: Yuxuan Shui <yshuiv7@gmail.com>
This commit is contained in:
Yuxuan Shui 2022-08-12 14:15:23 +01:00
parent 32478df27c
commit 4e0fad5880
No known key found for this signature in database
GPG key ID: D3A4405BE6CC17F4
1 changed files with 30 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
man/picom.1.asciidoc
View file

@ -236,7 +236,7 @@ May also be one of the predefined kernels: `3x3box` (default), `5x5box`, `7x7box
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. Doesn't work with `--experimental-backends` enabled.
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. Doesn't work with *--experimental-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.
@ -260,10 +260,10 @@ May also be one of the predefined kernels: `3x3box` (default), `5x5box`, `7x7box
Make transparent windows clip other windows like non-transparent windows do, instead of blending on top of them.
*--window-shader-fg* 'SHADER'::
Specify GLSL fragment shader path for rendering window contents. Only works when `--experimental-backends` is enabled.
Specify GLSL fragment shader path for rendering window contents. Only works when *--experimental-backends* is enabled. 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. Pattern should be in the format of `SHADER:PATTERN`, similar to `--opacity-rule`. Leading and trailing whitespaces in `SHADER` will be trimmed. If `SHADER` is "default", then the default shader will be used for matching windows. (This also unfortunately means you can't use a shader file named "default"). Only works when `--experimental-backends` is enabled.
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"). Only works when *--experimental-backends* is enabled.
FORMAT OF CONDITIONS
--------------------
@ -352,6 +352,33 @@ 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 only applies to the new, experimental 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 descibes the interface provided by the glx backend.
The shader must defined 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 from applying the default picom effects to input color 'c'.
The following uniform/input variables are made available to the shader:
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 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`.