From 0a444511e86a02feb2c945287ed535d0ca650b9b Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 19 Apr 2014 15:29:05 +0200 Subject: manpage: add notes when to use/not use certain AO and VO drivers --- DOCS/man/en/ao.rst | 26 +++++++++++++++++++++++++- DOCS/man/en/vo.rst | 25 +++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 1 deletion(-) (limited to 'DOCS') diff --git a/DOCS/man/en/ao.rst b/DOCS/man/en/ao.rst index 47b93649ad..c7fedbcfc1 100644 --- a/DOCS/man/en/ao.rst +++ b/DOCS/man/en/ao.rst @@ -18,7 +18,12 @@ normal driver parameters. .. note:: - See ``--ao=help`` for a list of compiled-in audio output drivers. + See ``--ao=help`` for a list of compiled-in audio output drivers. The + driver ``--ao=alsa`` is preferred. ``--ao=pulse`` is preferred on systems + where PulseAudio is forced. On Windows, ``--ao=wasapi`` is preferred, + though it might cause trouble sometimes, in which case ``--ao=dsound`` + should be used. On BSD systems, ``--ao=oss`` or `--ao=sndio`` may work + (the latter being experimental). On OSX systems, use ``--ao=coreaudio``. .. admonition:: Examples @@ -115,6 +120,9 @@ Available audio output drivers are: ``openal`` Experimental OpenAL audio output driver + .. note:: This driver is not very useful. Playing multi-channel audio with + it is slow. + ``pulse`` PulseAudio audio output driver @@ -133,6 +141,10 @@ Available audio output drivers are: PortAudio audio output driver. This works on all platforms, and has extensive MS Windows support. + .. note:: This driver is not very useful. It was added in the hope of + providing portable audio API across all platforms, but turned + our semi-broken and underfeatured. + ``device`` Specify the subdevice to use. Giving ``help`` as device name lists all devices found by PortAudio. Devices can be given as numeric values, @@ -141,6 +153,8 @@ Available audio output drivers are: ``dsound`` (Windows only) DirectX DirectSound audio output driver + .. note:: This driver is for compatibility with old systems. + ``device=`` Sets the device number to use. Playing a file with ``-v`` will show a list of available devices. @@ -150,6 +164,10 @@ Available audio output drivers are: 1.2, but may require the ``SDL_AUDIODRIVER`` environment variable to be set appropriately for your system. + .. note:: This driver is for compatibility with extremely foreign + environments, such as systems where none of the other drivers + are available. + ``buflen=`` Sets the audio buffer length in seconds. Is used only as a hint by the sound system. Playing a file with ``-v`` will show the requested and @@ -201,6 +219,10 @@ Available audio output drivers are: ``rsound`` Audio output to an RSound daemon + .. note:: Completely useless, unless you intend to run RSound. Not to be + confused with RoarAudio, which is something completely + differently. + ``host=`` Set the address of the server (default: localhost). Can be either a network hostname for TCP connections or a Unix domain socket path @@ -212,6 +234,8 @@ Available audio output drivers are: ``sndio`` Audio output to the OpenBSD sndio sound system + .. note:: Experimental. There are known bugs and issues. + (Note: only supports mono, stereo, 4.0, 5.1 and 7.1 channel layouts.) diff --git a/DOCS/man/en/vo.rst b/DOCS/man/en/vo.rst index c7209859e2..795618ee4f 100644 --- a/DOCS/man/en/vo.rst +++ b/DOCS/man/en/vo.rst @@ -20,6 +20,9 @@ normal driver parameters. See ``--vo=help`` for a list of compiled-in video output drivers. + The recommended output drivers are ``--vo=vdpau`` and ``--vo=opengl-hq``. + All other drivers are just for compatibility or special purposes. + .. admonition:: Example ``--vo=opengl,xv,`` @@ -32,6 +35,8 @@ Available video output drivers are: the most compatible VO on X, but may be low-quality, and has issues with OSD and subtitle display. + .. note:: This driver is for compatibility with old systems. + ``adaptor=`` Select a specific XVideo adaptor (check xvinfo results). ``port=`` @@ -172,6 +177,9 @@ Available video output drivers are: ``direct3d_shaders`` (Windows only) Video output driver that uses the Direct3D interface. + .. note:: This driver is for compatibility with systems that don't provide + proper OpenGL drivers. + ``prefer-stretchrect`` Use ``IDirect3DDevice9::StretchRect`` over other methods if possible. @@ -228,11 +236,15 @@ Available video output drivers are: Same as ``direct3d_shaders``, but with the options ``disable-textures`` and ``disable-shaders`` forced. + .. note:: This driver is for compatibility with old systems. + ``corevideo`` (Mac OS X 10.6 and later) Mac OS X CoreVideo video output driver. Uses the CoreVideo APIs to fill PixelBuffers and generate OpenGL textures from them (useful as a fallback for ``opengl``). + .. note:: This driver is for compatibility with old systems. + ``opengl`` OpenGL video output driver. It supports extended scaling methods, dithering and color management. @@ -541,6 +553,8 @@ Available video output drivers are: implementation, even if you do not get any error message. Use ``glxinfo`` or a similar tool to display the supported OpenGL extensions. + .. note:: This driver is for compatibility with old systems. + ``(no-)ati-hack`` ATI drivers may give a corrupted image when PBOs are used (when using ``force-pbo``). This option fixes this, at the expense of using a bit @@ -714,6 +728,9 @@ Available video output drivers are: hardware acceleration. Should work on all platforms supported by SDL 2.0. For tuning, refer to your copy of the file ``SDL_hints.h``. + .. note:: This driver is for compatibility with systems that don't provide + proper graphics drivers, or which support GLES only. + ``sw`` Continue even if a software renderer is detected. @@ -726,6 +743,9 @@ Available video output drivers are: hardware decoding to save power on laptops, or possibly preventing video tearing with some setups. + .. note:: This driver is for compatibility with crappy systems. You can + use vaapi hardware decoding with ``--vo=opengl`` too. + ``scaling=`` default Driver default (mpv default as well). @@ -766,6 +786,8 @@ Available video output drivers are: ``caca`` Color ASCII art video output driver that works on a text console. + .. note:: This driver is a joke. + ``image`` Output each frame into an image file in the current directory. Each file takes the frame number padded with leading zeros as name. @@ -811,6 +833,9 @@ Available video output drivers are: ``wayland`` (Wayland only) Wayland shared memory video output as fallback for ``opengl``. + .. note:: This driver is for compatibility with systems that don't provide + working OpenGL drivers. + ``alpha`` Use a buffer format that supports videos and images with alpha information -- cgit v1.2.3