From 4d6b9550fe1e0354461716f560d71d78196d5da5 Mon Sep 17 00:00:00 2001
From: Niklas Haas <git@nand.wakku.to>
Date: Fri, 27 Mar 2015 13:27:40 +0100
Subject: vo_opengl: add support for custom shaders

---
 DOCS/man/vo.rst | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 70 insertions(+), 2 deletions(-)

(limited to 'DOCS/man/vo.rst')

diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst
index 26d31f7498..455a0562c9 100644
--- a/DOCS/man/vo.rst
+++ b/DOCS/man/vo.rst
@@ -342,6 +342,9 @@ Available video output drivers are:
             exchange for adding some blur. This filter is good at temporal
             interpolation, and also known as "smoothmotion" (see ``tscale``).
 
+        ``custom``
+            A user-defined custom shader (see ``scale-shader``).
+
         There are some more filters, but most are not as useful. For a complete
         list, pass ``help`` as value, e.g.::
 
@@ -525,6 +528,70 @@ Available video output drivers are:
         feature doesn't work correctly with different scale factors in
         different directions.
 
+    ``source-shader=<file>``, ``scale-shader=<file>``, ``pre-shaders=<files>``, ``post-shaders=<files>``
+        Custom GLSL fragment shaders.
+
+        source-shader
+            This gets applied directly onto the source planes, before
+            any sort of upscaling or conversion whatsoever. For YCbCr content,
+            this means it gets applied on the luma and chroma planes
+            separately. In general, this shader shouldn't be making any
+            assumptions about the colorspace. It could be RGB, YCbCr, XYZ or
+            something else entirely. It's used purely for fixing numerical
+            quirks of the input, eg. debanding or deblocking.
+        pre-shaders (list)
+            These get applied after conversion to RGB and before linearization
+            and upscaling. Operates on non-linear RGB (same as input). This is
+            the best place to put things like sharpen filters.
+        scale-shader
+            This gets used instead of scale/cscale when those options are set
+            to ``custom``. The colorspace it operates on depends on the values
+            of ``linear-scaling`` and ``sigmoid-upscaling``, so no assumptions
+            should be made here.
+        post-shaders (list)
+            These get applied after upscaling and subtitle blending (when
+            ``blend-subtitles`` is enabled), but before color management.
+            Operates on linear RGB if ``linear-scaling`` is in effect,
+            otherwise non-linear RGB. This is the best place for colorspace
+            transformations (eg. saturation mapping).
+
+        These files must define a function with the following signature::
+
+            vec4 sample(sampler2D tex, vec2 pos, vec2 tex_size)
+
+        The meanings of the parameters are as follows:
+
+        sampler2D tex
+            The source texture for the shader.
+        vec2 pos
+            The position to be sampled, in coordinate space [0-1].
+        vec2 tex_size
+            The size of the texture, in pixels. This may differ from image_size,
+            eg. for subsampled content or for post-shaders.
+
+        In addition to these parameters, the following uniforms are also
+        globally available:
+
+        float random
+            A random number in the range [0-1], different per frame.
+        int frame
+            A simple count of frames rendered, increases by one per frame and
+            never resets (regardless of seeks).
+        vec2 image_size
+            The size in pixels of the input image.
+        float cmul (source-shader only)
+            The multiplier needed to pull colors up to the right bit depth. The
+            source-shader must multiply any sampled colors by this, in order
+            to normalize them to the full scale.
+
+        For example, a shader that inverts the colors could look like this::
+
+            vec4 sample(sampler2D tex, vec2 pos, vec2 tex_size)
+            {
+                vec4 color = texture(tex, pos);
+                return vec4(1.0 - color.rgb, color.a);
+            }
+
     ``sigmoid-upscaling``
         When upscaling, use a sigmoidal color transform to avoid emphasizing
         ringing artifacts. This also enables ``linear-scaling``.
@@ -705,8 +772,9 @@ Available video output drivers are:
         Blend subtitles directly onto upscaled video frames, before
         interpolation and/or color management (default: no). Enabling this
         causes subtitles to be affected by ``icc-profile``, ``target-prim``,
-        ``target-trc``, ``interpolation``, ``gamma`` and ``linear-scaling``.
-        It also increases subtitle performance when using ``interpolation``.
+        ``target-trc``, ``interpolation``, ``gamma``, ``post-shader`` and
+        ``linear-scaling``. It also increases subtitle performance when using
+        ``interpolation``.
 
         The downside of enabling this is that it restricts subtitles to the
         visible portion of the video, so you can't have subtitles exist in the
-- 
cgit v1.2.3