[x265] [PATCH 4 of 4] doc: describe new multi-lib behavior

[Steve Borho]

# HG changeset patch
# User Steve Borho <steve at borho.org>
# Date 1430252705 18000
#      Tue Apr 28 15:25:05 2015 -0500
# Node ID 3a10809218802898de07c3df4d662593e7ad6014
# Parent  41f1bb787a740001e6605eeee0eb26645bd2b256
doc: describe new multi-lib behavior

diff -r 41f1bb787a74 -r 3a1080921880 doc/reST/api.rst
--- a/doc/reST/api.rst	Tue Apr 28 14:31:44 2015 -0500
+++ b/doc/reST/api.rst	Tue Apr 28 15:25:05 2015 -0500
@@ -375,8 +375,25 @@
 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. Next your application must dynamically link to libx265 and
-then you must build and install a multi-lib configuration of libx265,
-which includes 8bpp and 16bpp builds of libx265 and a shim library which
-forwards x265_api_get() calls to the appropriate library using dynamic
-loading and binding.
+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:
+
+    8-bit:  libx265_main.dll
+    10-bit: libx265_main10.dll
+
+    (the shared library extension is obviously platform specific. On
+    Linux it is .so while on Mac it is .dylib)
+
+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.
+
+On Linux, x265 packagers could install 8bpp static and shared libraries
+under the name libx265 (so all applications link against 8bpp libx265)
+and then also install libx265_main10.so (symlinked to its numbered solib).
+Thus applications which use x265_api_get() will be able to generate main
+or main10 bitstreams.
diff -r 41f1bb787a74 -r 3a1080921880 doc/reST/cli.rst
--- a/doc/reST/cli.rst	Tue Apr 28 14:31:44 2015 -0500
+++ b/doc/reST/cli.rst	Tue Apr 28 15:25:05 2015 -0500
@@ -435,6 +435,15 @@
 	their param structure. Any changes made to the param structure after
 	this call might make the encode non-compliant.
 
+	The CLI will use the requested profile to select the bit-depth of
+	the encoder it creates. For instance, -P main10 will make the CLI
+	attempt to get a 10bit encoder API. If the CLI was not compiled with
+	a 10bit libx265, libx265 will try to bind a libx265_main10 shared
+	library (using the system standard library load path mechanisms) and
+	use its API. If this fails, it will try to encode with the linked
+	API but this fallback may be impossible depending on the linked
+	build of libx265 and the requested profile.
+
 	**Values:** main, main10, mainstillpicture, main422-8, main422-10, main444-8, main444-10
 
 	**CLI ONLY**
diff -r 41f1bb787a74 -r 3a1080921880 source/x265.h
--- a/source/x265.h	Tue Apr 28 14:31:44 2015 -0500
+++ b/source/x265.h	Tue Apr 28 15:25:05 2015 -0500
@@ -1299,8 +1299,14 @@
  *   Retrieve the programming interface for a linked x265 library.
  *   May return NULL if no library is available that supports the
  *   requested bit depth. If bitDepth is 0 the function is guarunteed
- *   to return a non-NULL x265_api pointer, from the system default
- *   libx265 */
+ *   to return a non-NULL x265_api pointer, from the linked libx265.
+ *
+ *   If the requested bitDepth is not supported by the linked libx265,
+ *   it will attempt to dynamically bind x265_api_get() from a shared
+ *   library with an appropriate name:
+ *     8bit:  libx265_main.so
+ *     10bit: libx265_main10.so
+ *   Obviously the shared library file extension is platform specific */
 const x265_api* x265_api_get(int bitDepth);
 
 #ifdef __cplusplus