manpage: improvements to vo_opengl documentation

Mention the FBO format chaos.

Some other things were not entirely correct anymore.

Also update the "builtin" documentation in vo_opengl.c.

2 files changed, 26 insertions, 14 deletions

diff --git a/DOCS/man/en/vo.rst b/DOCS/man/en/vo.rst
index f7346a55f5..6248073944 100644
--- a/DOCS/man/en/vo.rst
+++ b/DOCS/man/en/vo.rst
@@ -239,7 +239,8 @@ opengl
     Requires at least OpenGL 2.1 and the GL_ARB_texture_rg extension. For older
     drivers, ``opengl-old`` may work.
 
-    Some features are available with OpenGL 3 capable graphics drivers only.
+    Some features are available with OpenGL 3 capable graphics drivers only
+    (or if the necessary extensions are available).
 
     lscale=<filter>
         Set the scaling filter. Possible choices:
@@ -270,10 +271,11 @@ opengl
 
         bilinear
             Bilinear hardware texture filtering (fastest, mid-quality).
+            This is the default.
 
         lanczos2
-            Lanczos scaling with radius=2. Provides a good quality and speed.
-            This is the default.
+            Lanczos scaling with radius=2. Provides good quality and speed.
+            This is the default when using ``opengl-hq``.
 
         lanczos3
             Lanczos with radius=3.
@@ -322,9 +324,10 @@ opengl
         Enable gamma-correct scaling by working in linear light. This
         makes use of sRGB textures and framebuffers.
         This option forces the options 'indirect' and 'gamma'.
-        NOTE: for BT.709 colorspaces, a gamma of 2.35 is assumed. For
-        other YUV colorspaces, 2.2 is assumed. RGB input is always
+        NOTE: for YUV colorspaces, gamma 2.2 is assumed. RGB input is always
         assumed to be in sRGB.
+        This option is not really useful, as gamma-correct scaling has not much
+        influence on typical video playback.
 
     pbo
         Enable use of PBOs. This is faster, but can sometimes lead to
@@ -406,9 +409,12 @@ opengl
         is used only on YUV conversion, and only if the video uses
         chroma-subsampling.
         This mechanism is disabled on RGB input.
+        Specifying this option directly is generally useful for debugging only.
 
     fbo-format=<fmt>
-        Selects the internal format of any FBO textures used.
+        Selects the internal format of textures used for FBOs. The format can
+        influence performance and quality of the video output. (FBOs are not
+        always used, and typically only when using extended scalers.)
         fmt can be one of: rgb, rgba, rgb8, rgb10, rgb16, rgb16f, rgb32f
         Default: rgb.
 
@@ -424,7 +430,7 @@ opengl
         this file. This can be used to speed up loading, since
         LittleCMS2 can take a while to create the 3D LUT.
         Note that this file contains an uncompressed LUT. Its size depends on
-        the ``3dlut-size``, can become very big.
+        the ``3dlut-size``, and can be very big.
 
     icc-intent=<value>
         0
@@ -451,6 +457,12 @@ opengl-hq
     Note that some cheaper LCDs do dithering that gravely interferes with
     vo_opengl's dithering. Disabling dithering with ``dither-depth=-1`` helps.
 
+    Unlike ``opengl``, ``opengl-hq`` makes use of FBOs by default. Sometimes you
+    can achieve better quality or performance by changing the fbo-format
+    sub-option to ``rgb16f``, ``rgb32f`` or ``rgb``. (Known problems include
+    Mesa/Intel not accepting ``rgb16``, Mesa sometimes not being compiled with
+    float texture support, and some OSX setups being very slow with ``rgb16``,
+    but fast with ``rgb32f``.)
 
 opengl-old
     OpenGL video output driver, old version. Video size must be smaller
diff --git a/libvo/vo_opengl.c b/libvo/vo_opengl.c
index d720b0088c..b6f2ddd811 100644
--- a/libvo/vo_opengl.c
+++ b/libvo/vo_opengl.c
@@ -2490,10 +2490,10 @@ static const char help_text[] =
 "    bicubic_fast: bicubic filter (without lookup texture).\n"
 "    sharpen3: unsharp masking (sharpening) with radius=3.\n"
 "    sharpen5: unsharp masking (sharpening) with radius=5.\n"
-"    lanczos2: Lanczos with radius=2 (default, recommended).\n"
+"    lanczos2: Lanczos with radius=2 (recommended).\n"
 "    lanczos3: Lanczos with radius=3 (not recommended).\n"
 "    mitchell: Mitchell-Netravali.\n"
-"    Default: lanczos2\n"
+"    Default: bilinear\n"
 "  lparam1=<value> / lparam2=<value>\n"
 "    Set parameters for configurable filters. Affects chroma scaler\n"
 "    as well.\n"
@@ -2513,8 +2513,7 @@ static const char help_text[] =
 "    Enable gamma-correct scaling by working in linear light. This\n"
 "    makes use of sRGB textures and framebuffers.\n"
 "    This option forces the options 'indirect' and 'gamma'.\n"
-"    NOTE: for BT.709 colorspaces, a gamma of 2.35 is assumed. For\n"
-"    other YUV colorspaces, 2.2 is assumed. RGB input is always\n"
+"    NOTE: For YUV colorspaces, gamma 2.2 is assumed. RGB input is always\n"
 "    assumed to be in sRGB.\n"
 "  pbo\n"
 "    Enable use of PBOs. This is faster, but can sometimes lead to\n"
@@ -2525,7 +2524,7 @@ static const char help_text[] =
 "     0: Automatic selection. If output bit depth can't be detected,\n"
 "        8 bits per component are assumed.\n"
 "     8: Dither to 8 bit output.\n"
-"    Default: 0.\n"
+"    Default: -1.\n"
 "    Note that dithering will always be disabled if the bit depth\n"
 "    of the video is lower or qual to the detected dither-depth.\n"
 "    If color management is enabled, input depth is assumed to be\n"
@@ -2573,7 +2572,7 @@ static const char help_text[] =
 "  fbo-format=<fmt>\n"
 "    Selects the internal format of any FBO textures used.\n"
 "    fmt can be one of: rgb, rgba, rgb8, rgb10, rgb16, rgb16f, rgb32f\n"
-"    Default: rgb16.\n"
+"    Default: rgb.\n"
 "  gamma\n"
 "    Always enable gamma control. (Disables delayed enabling.)\n"
 "Color management:\n"
@@ -2584,7 +2583,7 @@ static const char help_text[] =
 "    Store and load the 3D LUT created from the ICC profile in\n"
 "    this file. This can be used to speed up loading, since\n"
 "    LittleCMS2 can take a while to create the 3D LUT.\n"
-"    Note that this file will be at most about 100 MB big.\n"
+"    Note that this file will be up to ~100 MB big.\n"
 "  icc-intent=<value>\n"
 "    0: perceptual\n"
 "    1: relative colorimetric\n"
@@ -2594,4 +2593,5 @@ static const char help_text[] =
 "    Size of the 3D LUT generated from the ICC profile in each\n"
 "    dimension. Default is 128x256x64.\n"
 "    Sizes must be a power of two, and 256 at most.\n"
+"Note: all defaults mentioned are for 'opengl', not 'opengl-hq'.\n"
 "\n";