vo_opengl: make compute shaders more flexible

This allows users to do their own custom sample writing, mainly meant to
address use cases such as RAVU. Also clean up the compute shader code a
bit.

1 files changed, 17 insertions, 7 deletions

diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index 02cb4d826d..80dfdceb54 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -4329,16 +4329,26 @@ The following video options are currently all specific to ``--vo=opengl`` and
         should be stored in the texture, up to 4 (rgba). By default, this value
         is equal to the number of components in HOOKED.
 
-    COMPUTE bw bh
+    COMPUTE <bw> <bh> [<tw> <th>]
         Specifies that this shader should be treated as a compute shader, with
         the block size bw and bh. The compute shader will be dispatched with
         however many blocks are necessary to completely tile over the output.
-        Compute shaders in mpv are treated similarly to fragment shaders, and
-        are still required to produce an output color. In addition, mpv
-        provides a special function NAME_map(id) to map from the global ID
-        space to the texture coordinates for all bound textures. The only real
-        difference is the fact that you can use shared memory inside compute
-        shaders.
+        Within each block, there will bw tw*th threads, forming a single work
+        group. In other words: tw and th specify the work group size, which can
+        be different from the block size. So for example, a compute shader with
+        bw, bh = 32 and tw, th = 8 running on a 500x500 texture would dispatch
+        16x16 blocks (rounded up), each with 8x8 threads.
+
+        Compute shaders in mpv are treated a bit different from fragment
+        shaders. Instead of defining a ``vec4 hook`` that produces an output
+        sample, you directly define ``void hook`` which writes to a fixed
+        writeonly image unit named ``out_image`` (this is bound by mpv) using
+        `imageStore`. To help translate texture coordinates in the absence of
+        vertices, mpv provides a special function ``NAME_map(id)`` to map from
+        the texel space of the output image to the texture coordinates for all
+        bound textures. In particular, ``NAME_pos`` is equivalent to
+        ``NAME_map(gl_GlobalInvocationID)``, although using this only really
+        makes sense if (tw,th) == (bw,bh).
 
     Each bound mpv texture (via ``BIND``) will make available the following
     definitions to that shader pass, where NAME is the name of the bound