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

[Deepthi Nandakumar]

Ok, makes sense. Sending another patch which adds failures to api_get as
well as clarifies usage.

On Fri, May 1, 2015 at 11:37 PM, Steve Borho <steve at borho.org> wrote:

> 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
> _______________________________________________
> x265-devel mailing list
> x265-devel at videolan.org
> https://mailman.videolan.org/listinfo/x265-devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.videolan.org/pipermail/x265-devel/attachments/20150502/69036812/attachment.html>