[x265] [PATCH] api: clarify docs and use of x265_api_get()

[Steve Borho]

On 04/30, deepthi at multicorewareinc.com wrote:
> # HG changeset patch
> # User Deepthi Nandakumar <deepthi at multicorewareinc.com>
> # Date 1430367247 -19800
> #      Thu Apr 30 09:44:07 2015 +0530
> # Node ID a3ba8c92dcea057f2c5210d48d455691cc0c3e65
> # Parent  74d7fe7a81ad773c8ae66f076c4e319b253d94ab
> api: clarify docs and use of x265_api_get()
> 
> diff -r 74d7fe7a81ad -r a3ba8c92dcea doc/reST/api.rst
> --- a/doc/reST/api.rst	Wed Apr 29 11:08:44 2015 -0500
> +++ b/doc/reST/api.rst	Thu Apr 30 09:44:07 2015 +0530
> @@ -352,7 +352,7 @@
>  Multi-library Interface
>  =======================
>  
> -If your application might want to make a runtime selection between among
> +If your application might want to make a runtime selection between
>  a number of libx265 libraries (perhaps 8bpp and 16bpp), then you will
>  want to use the multi-library interface.
>  
> @@ -370,16 +370,20 @@
>       *   libx265 */
>      const x265_api* x265_api_get(int bitDepth);
>  
> -The general idea is to request the API for the bitDepth you would prefer
> -the encoder to use (8 or 10), and if that returns NULL you request the
> -API for bitDepth=0, which returns the system default libx265.
> +Note that using this multi-library API in your application is only the
> +first step.
>  
> -Note that using this multi-library API in your application is only the
> -first step.  Your application must link to one build of libx265
> -(statically or dynamically) and this linked version of libx265 will
> -support one bit-depth (8 or 10 bits). If you request a different
> -bit-depth, the linked libx265 will attempt to dynamically bind a shared
> -library libx265 with a name appropriate for the requested bit-depth:
> +Your application must link to one build of libx265 (statically or 
> +dynamically) and this linked version of libx265 will support one 
> +bit-depth (8 or 10 bits). 
> +
> +Your application must now request the API for the bitDepth you would 
> +prefer the encoder to use (8 or 10). If the requested bitdepth is zero, 
> +or if it matches the bitdepth of the system default libx265 (the 
> +currently linked library), then this library will be used for encode.
> +If you request a different bit-depth, the linked libx265 will attempt 
> +to dynamically bind a shared library with a name appropriate for the 
> +requested bit-depth:
>  
>      8-bit:  libx265_main.dll
>      10-bit: libx265_main10.dll
> @@ -390,7 +394,7 @@
>  For example on Windows, one could package together an x265.exe
>  statically linked against the 8bpp libx265 together with a
>  libx265_main10.dll in the same folder, and this executable would be able
> -to encode 10bit bitstreams by specifying -P main10 on the command line.
> +to encode main and main10 bitstreams.
>  
>  On Linux, x265 packagers could install 8bpp static and shared libraries
>  under the name libx265 (so all applications link against 8bpp libx265)
> diff -r 74d7fe7a81ad -r a3ba8c92dcea source/x265.cpp
> --- a/source/x265.cpp	Wed Apr 29 11:08:44 2015 -0500
> +++ b/source/x265.cpp	Thu Apr 30 09:44:07 2015 +0530
> @@ -458,9 +458,7 @@
>      GetConsoleTitle(orgConsoleTitle, CONSOLE_TITLE_SIZE);
>      SetThreadExecutionState(ES_CONTINUOUS | ES_SYSTEM_REQUIRED | ES_AWAYMODE_REQUIRED);
>  
> -    const x265_api* api = x265_api_get(X265_DEPTH); /* prefer what the cli was compiled against */
> -    if (!api)
> -        api = x265_api_get(0);
> +    const x265_api* api = x265_api_get(X265_DEPTH); /* Use 0 or X265_DEPTH to get what the cli was compiled against */

this comment is not actually true.  Passing X265_DEPTH will prefer the
bit depth the CLI was compiled against. Passing 0 will prefer the bit
depth of the library the CLI linked to.  Particularly on Linux where the
CLI can used shared-library versions of libx265, the compiled bit-depth
can be different from the linked bit-depth.

This is why it first tries X265_DEPTH, then tries 0.

-- 
Steve Borho