[FFmpeg-cvslog] doc/fftools-common-opts: update/ extend documentation for -opencl_bench option

[Maneesh Gupta]

ffmpeg | branch: master | Maneesh Gupta <maneesh.gupta at amd.com> | Tue Jan 27 20:46:24 2015 +0530| [1600f85cbc4594c589cfea42121e3ddad0b974e9] | committer: Stefano Sabatini

doc/fftools-common-opts: update/extend documentation for -opencl_bench option

Signed-off-by: Stefano Sabatini <stefasab at gmail.com>

> http://git.videolan.org/gitweb.cgi/ffmpeg.git/?a=commit;h=1600f85cbc4594c589cfea42121e3ddad0b974e9
---

 doc/fftools-common-opts.texi |   37 +++++++++++++++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 2 deletions(-)

diff --git a/doc/fftools-common-opts.texi b/doc/fftools-common-opts.texi
index 7d52c1a..6556909 100644
--- a/doc/fftools-common-opts.texi
+++ b/doc/fftools-common-opts.texi
@@ -294,8 +294,41 @@ Possible flags for this option are:
 @end table
 
 @item -opencl_bench
-Benchmark all available OpenCL devices and show the results. This option
-is only available when FFmpeg has been compiled with @code{--enable-opencl}.
+This option is used to benchmark all available OpenCL devices and print the
+results. This option is only available when FFmpeg has been compiled with
+ at code{--enable-opencl}.
+
+When FFmpeg is configured with @code{--enable-opencl}, the options for the
+global OpenCL context are set via @option{-opencl_options}. See the
+"OpenCL Options" section in the ffmpeg-utils manual for the complete list of
+supported options. Amongst others, these options include the ability to select
+a specific platform and device to run the OpenCL code on. By default, FFmpeg
+will run on the first device of the first platform. While the options for the
+global OpenCL context provide flexibility to the user in selecting the OpenCL
+device of their choice, most users would probably want to select the fastest
+OpenCL device for their system.
+
+This option assists the selection of the most efficient configuration by
+identifying the appropriate device for the user's system. The built-in
+benchmark is run on all the OpenCL devices and the performance is measured for
+each device. The devices in the results list are sorted based on their
+performance with the fastest device listed first. The user can subsequently
+invoke @command{ffmpeg} using the device deemed most appropriate via
+ at option{-opencl_options} to obtain the best performance for the OpenCL
+accelerated code.
+
+Typical usage to use the fastest OpenCL device involve the following steps.
+
+Run the command:
+ at example
+ffmpeg -opencl_bench
+ at end example
+Note down the platform ID (@var{pidx}) and device ID (@var{didx}) of the first
+i.e. fastest device in the list.
+Select the platform and device using the command:
+ at example
+ffmpeg -opencl_options platform_idx=@var{pidx}:device_idx=@var{didx} ...
+ at end example
 
 @item -opencl_options options (@emph{global})
 Set OpenCL environment options. This option is only available when