[x265-commits] [x265] doc: replace 'bpp' in docs with 'bit' (do not imply pixels)
Steve Borho
steve at borho.org
Tue Jun 23 17:32:07 CEST 2015
details: http://hg.videolan.org/x265/rev/d5376bf40aea
branches:
changeset: 10687:d5376bf40aea
user: Steve Borho <steve at borho.org>
date: Mon Jun 22 20:11:24 2015 -0500
description:
doc: replace 'bpp' in docs with 'bit' (do not imply pixels)
Subject: [x265] clarify 8bit/10bit in code comments
details: http://hg.videolan.org/x265/rev/78c562d38eea
branches:
changeset: 10688:78c562d38eea
user: Steve Borho <steve at borho.org>
date: Mon Jun 22 20:22:25 2015 -0500
description:
clarify 8bit/10bit in code comments
Subject: [x265] param: clarify 8bit/10bit in logs
details: http://hg.videolan.org/x265/rev/901fc6837a25
branches:
changeset: 10689:901fc6837a25
user: Steve Borho <steve at borho.org>
date: Mon Jun 22 20:24:34 2015 -0500
description:
param: clarify 8bit/10bit in logs
removes the internal bit-depth logging for Main10 encodes since we now
unconditionally report the profile and level, which unambiguously displays the
internal bitdepth
Subject: [x265] cmake: change msvc multilib build folders to 8bit/10bit
details: http://hg.videolan.org/x265/rev/0b36c393bb3a
branches:
changeset: 10690:0b36c393bb3a
user: Steve Borho <steve at borho.org>
date: Mon Jun 22 20:32:39 2015 -0500
description:
cmake: change msvc multilib build folders to 8bit/10bit
Subject: [x265] cmake: change multilib namespaces to x265_8bit/x265_10bit
details: http://hg.videolan.org/x265/rev/25390edc448a
branches:
changeset: 10691:25390edc448a
user: Steve Borho <steve at borho.org>
date: Mon Jun 22 20:35:06 2015 -0500
description:
cmake: change multilib namespaces to x265_8bit/x265_10bit
Subject: [x265] doc: fix dither docs on api page (not applicable if internal bit depth != 8)
details: http://hg.videolan.org/x265/rev/98d42fd1c07c
branches:
changeset: 10692:98d42fd1c07c
user: Steve Borho <steve at borho.org>
date: Mon Jun 22 21:58:07 2015 -0500
description:
doc: fix dither docs on api page (not applicable if internal bit depth != 8)
Subject: [x265] doc: nit
details: http://hg.videolan.org/x265/rev/05165a2be4f8
branches:
changeset: 10693:05165a2be4f8
user: Steve Borho <steve at borho.org>
date: Mon Jun 22 21:58:15 2015 -0500
description:
doc: nit
Subject: [x265] doc: attempt to document statically linked multi-library implications
details: http://hg.videolan.org/x265/rev/21183e6f9444
branches:
changeset: 10694:21183e6f9444
user: Steve Borho <steve at borho.org>
date: Mon Jun 22 22:02:40 2015 -0500
description:
doc: attempt to document statically linked multi-library implications
This all has become very complicated. we probably want to deprecate most of
the exported C functions in the future and only export x265_api_get() and
x265_api_query()
diffstat:
build/vc10-x86_64/multilib.bat | 16 +-
build/vc11-x86_64/multilib.bat | 16 +-
build/vc12-x86_64/multilib.bat | 16 +-
build/vc9-x86_64/multilib.bat | 16 +-
doc/reST/api.rst | 167 +++++++++++++++++++++++-----------
source/CMakeLists.txt | 6 +-
source/common/param.cpp | 3 -
source/common/quant.h | 2 +-
source/common/version.cpp | 4 +-
source/common/x86/asm-primitives.cpp | 4 +-
source/common/x86/pixel-a.asm | 6 +-
source/encoder/api.cpp | 10 +-
source/test/testbench.cpp | 4 +-
source/x265.h | 4 +-
14 files changed, 164 insertions(+), 110 deletions(-)
diffs (truncated from 540 to 300 lines):
diff -r dfdf378a3968 -r 21183e6f9444 build/vc10-x86_64/multilib.bat
--- a/build/vc10-x86_64/multilib.bat Mon Jun 22 17:44:14 2015 -0500
+++ b/build/vc10-x86_64/multilib.bat Mon Jun 22 22:02:40 2015 -0500
@@ -4,27 +4,27 @@ if "%VS100COMNTOOLS%" == "" (
exit 1
)
- at mkdir 10bpp
- at mkdir 8bpp
+ at mkdir 10bit
+ at mkdir 8bit
- at cd 10bpp
+ at cd 10bit
if not exist x265.sln (
cmake -G "Visual Studio 10 Win64" ../../../source -DHIGH_BIT_DEPTH=ON -DEXPORT_C_API=OFF -DENABLE_SHARED=OFF -DENABLE_CLI=OFF -DWINXP_SUPPORT=ON
)
if exist x265.sln (
call "%VS100COMNTOOLS%\..\..\VC\vcvarsall.bat"
MSBuild /property:Configuration="Release" x265.sln
- copy/y Release\x265-static.lib ..\8bpp\x265-static-10bpp.lib
+ copy/y Release\x265-static.lib ..\8bit\x265-static-main10.lib
)
@cd ..
- at cd 8bpp
-if not exist x265-static-10bpp.lib (
- msg "%username%" "10bpp build failured"
+ at cd 8bit
+if not exist x265-static-main10.lib (
+ msg "%username%" "10bit build failured"
exit 1
)
if not exist x265.sln (
- cmake -G "Visual Studio 10 Win64" ../../../source -DHIGH_BIT_DEPTH=OFF -DEXPORT_C_API=OFF -DENABLE_SHARED=OFF -DENABLE_CLI=ON -DWINXP_SUPPORT=ON -DEXTRA_LIB=x265-static-10bpp.lib -DEXTRA_LINK_FLAGS="/FORCE:MULTIPLE"
+ cmake -G "Visual Studio 10 Win64" ../../../source -DHIGH_BIT_DEPTH=OFF -DEXPORT_C_API=OFF -DENABLE_SHARED=OFF -DENABLE_CLI=ON -DWINXP_SUPPORT=ON -DEXTRA_LIB=x265-static-main10.lib -DEXTRA_LINK_FLAGS="/FORCE:MULTIPLE"
)
if exist x265.sln (
call "%VS100COMNTOOLS%\..\..\VC\vcvarsall.bat"
diff -r dfdf378a3968 -r 21183e6f9444 build/vc11-x86_64/multilib.bat
--- a/build/vc11-x86_64/multilib.bat Mon Jun 22 17:44:14 2015 -0500
+++ b/build/vc11-x86_64/multilib.bat Mon Jun 22 22:02:40 2015 -0500
@@ -4,27 +4,27 @@ if "%VS110COMNTOOLS%" == "" (
exit 1
)
- at mkdir 10bpp
- at mkdir 8bpp
+ at mkdir 10bit
+ at mkdir 8bit
- at cd 10bpp
+ at cd 10bit
if not exist x265.sln (
cmake -G "Visual Studio 11 Win64" ../../../source -DHIGH_BIT_DEPTH=ON -DEXPORT_C_API=OFF -DENABLE_SHARED=OFF -DENABLE_CLI=OFF -DWINXP_SUPPORT=ON
)
if exist x265.sln (
call "%VS110COMNTOOLS%\..\..\VC\vcvarsall.bat"
MSBuild /property:Configuration="Release" x265.sln
- copy/y Release\x265-static.lib ..\8bpp\x265-static-10bpp.lib
+ copy/y Release\x265-static.lib ..\8bit\x265-static-main10.lib
)
@cd ..
- at cd 8bpp
-if not exist x265-static-10bpp.lib (
- msg "%username%" "10bpp build failured"
+ at cd 8bit
+if not exist x265-static-main10.lib (
+ msg "%username%" "10bit build failured"
exit 1
)
if not exist x265.sln (
- cmake -G "Visual Studio 11 Win64" ../../../source -DHIGH_BIT_DEPTH=OFF -DEXPORT_C_API=OFF -DENABLE_SHARED=OFF -DENABLE_CLI=ON -DWINXP_SUPPORT=ON -DEXTRA_LIB=x265-static-10bpp.lib -DEXTRA_LINK_FLAGS="/FORCE:MULTIPLE"
+ cmake -G "Visual Studio 11 Win64" ../../../source -DHIGH_BIT_DEPTH=OFF -DEXPORT_C_API=OFF -DENABLE_SHARED=OFF -DENABLE_CLI=ON -DWINXP_SUPPORT=ON -DEXTRA_LIB=x265-static-main10.lib -DEXTRA_LINK_FLAGS="/FORCE:MULTIPLE"
)
if exist x265.sln (
call "%VS110COMNTOOLS%\..\..\VC\vcvarsall.bat"
diff -r dfdf378a3968 -r 21183e6f9444 build/vc12-x86_64/multilib.bat
--- a/build/vc12-x86_64/multilib.bat Mon Jun 22 17:44:14 2015 -0500
+++ b/build/vc12-x86_64/multilib.bat Mon Jun 22 22:02:40 2015 -0500
@@ -4,27 +4,27 @@ if "%VS120COMNTOOLS%" == "" (
exit 1
)
- at mkdir 10bpp
- at mkdir 8bpp
+ at mkdir 10bit
+ at mkdir 8bit
- at cd 10bpp
+ at cd 10bit
if not exist x265.sln (
cmake -G "Visual Studio 12 Win64" ../../../source -DHIGH_BIT_DEPTH=ON -DEXPORT_C_API=OFF -DENABLE_SHARED=OFF -DENABLE_CLI=OFF -DWINXP_SUPPORT=ON
)
if exist x265.sln (
call "%VS120COMNTOOLS%\..\..\VC\vcvarsall.bat"
MSBuild /property:Configuration="Release" x265.sln
- copy/y Release\x265-static.lib ..\8bpp\x265-static-10bpp.lib
+ copy/y Release\x265-static.lib ..\8bit\x265-static-main10.lib
)
@cd ..
- at cd 8bpp
-if not exist x265-static-10bpp.lib (
- msg "%username%" "10bpp build failured"
+ at cd 8bit
+if not exist x265-static-main10.lib (
+ msg "%username%" "10bit build failured"
exit 1
)
if not exist x265.sln (
- cmake -G "Visual Studio 12 Win64" ../../../source -DHIGH_BIT_DEPTH=OFF -DEXPORT_C_API=OFF -DENABLE_SHARED=OFF -DENABLE_CLI=ON -DWINXP_SUPPORT=ON -DEXTRA_LIB=x265-static-10bpp.lib -DEXTRA_LINK_FLAGS="/FORCE:MULTIPLE"
+ cmake -G "Visual Studio 12 Win64" ../../../source -DHIGH_BIT_DEPTH=OFF -DEXPORT_C_API=OFF -DENABLE_SHARED=OFF -DENABLE_CLI=ON -DWINXP_SUPPORT=ON -DEXTRA_LIB=x265-static-main10.lib -DEXTRA_LINK_FLAGS="/FORCE:MULTIPLE"
)
if exist x265.sln (
call "%VS120COMNTOOLS%\..\..\VC\vcvarsall.bat"
diff -r dfdf378a3968 -r 21183e6f9444 build/vc9-x86_64/multilib.bat
--- a/build/vc9-x86_64/multilib.bat Mon Jun 22 17:44:14 2015 -0500
+++ b/build/vc9-x86_64/multilib.bat Mon Jun 22 22:02:40 2015 -0500
@@ -4,27 +4,27 @@ if "%VS90COMNTOOLS%" == "" (
exit 1
)
- at mkdir 10bpp
- at mkdir 8bpp
+ at mkdir 10bit
+ at mkdir 8bit
- at cd 10bpp
+ at cd 10bit
if not exist x265.sln (
cmake -G "Visual Studio 9 2008 Win64" ../../../source -DHIGH_BIT_DEPTH=ON -DEXPORT_C_API=OFF -DENABLE_SHARED=OFF -DENABLE_CLI=OFF -DWINXP_SUPPORT=ON
)
if exist x265.sln (
call "%VS90COMNTOOLS%\..\..\VC\vcvarsall.bat"
MSBuild /property:Configuration="Release" x265.sln
- copy/y Release\x265-static.lib ..\8bpp\x265-static-10bpp.lib
+ copy/y Release\x265-static.lib ..\8bit\x265-static-main10.lib
)
@cd ..
- at cd 8bpp
-if not exist x265-static-10bpp.lib (
- msg "%username%" "10bpp build failured"
+ at cd 8bit
+if not exist x265-static-main10.lib (
+ msg "%username%" "main10 build failured"
exit 1
)
if not exist x265.sln (
- cmake -G "Visual Studio 9 2008 Win64" ../../../source -DHIGH_BIT_DEPTH=OFF -DEXPORT_C_API=OFF -DENABLE_SHARED=OFF -DENABLE_CLI=ON -DWINXP_SUPPORT=ON -DEXTRA_LIB=x265-static-10bpp.lib -DEXTRA_LINK_FLAGS="/FORCE:MULTIPLE"
+ cmake -G "Visual Studio 9 2008 Win64" ../../../source -DHIGH_BIT_DEPTH=OFF -DEXPORT_C_API=OFF -DENABLE_SHARED=OFF -DENABLE_CLI=ON -DWINXP_SUPPORT=ON -DEXTRA_LIB=x265-static-main10.lib -DEXTRA_LINK_FLAGS="/FORCE:MULTIPLE"
)
if exist x265.sln (
call "%VS90COMNTOOLS%\..\..\VC\vcvarsall.bat"
diff -r dfdf378a3968 -r 21183e6f9444 doc/reST/api.rst
--- a/doc/reST/api.rst Mon Jun 22 17:44:14 2015 -0500
+++ b/doc/reST/api.rst Mon Jun 22 22:02:40 2015 -0500
@@ -41,9 +41,9 @@ string identifying the compiler and buil
x265 will accept input pixels of any depth between 8 and 16 bits
regardless of the depth of its internal pixels (8 or 10). It will shift
and mask input pixels as required to reach the internal depth. If
-downshifting is being performed using our CLI application, the
-:option:`--dither` option may be enabled to reduce banding. This feature
-is not available through the C interface.
+downshifting is being performed using our CLI application (to 8 bits),
+the :option:`--dither` option may be enabled to reduce banding. This
+feature is not available through the C interface.
Encoder
=======
@@ -190,7 +190,7 @@ changes made to the parameters for auto-
* presets is not recommended without a more fine-grained breakdown of
* parameters to take this into account. */
int x265_encoder_reconfig(x265_encoder *, x265_param *);
-
+
Pictures
========
@@ -365,65 +365,48 @@ CTU size::
Multi-library Interface
=======================
-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.
+If your application might want to make a runtime selection between a
+number of (static or dynamically linked) libx265 libraries, then you
+will want to use one of these bit-depth introspection interfaces.
-Instead of directly using all of the **x265_** methods documented
-above, you query an x265_api structure from your libx265 and then use
-the function pointers within that structure of the same name, but
-without the **x265_** prefix. So **x265_param_default()** becomes
-**api->param_default()**. The key method is x265_api_get()::
+Instead of directly using all of the **x265_** methods documented above,
+you query an x265_api structure from your libx265 and then use the
+function pointers of the same name (minus the **x265_** prefix) within
+that structure. For instance **x265_param_default()** becomes
+**api->param_default()**.
- /* x265_api_get:
- * 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 */
- const x265_api* x265_api_get(int bitDepth);
+x265_api_get
+------------
-Note that using this multi-library API in your application is only the
-first step.
+The first bit-depth instrospecton method is x265_api_get(). It designed
+for applications that might statically link with libx265, or will at
+least be tied to a particular SONAME or API version::
-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).
+ /* x265_api_get:
+ * 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 */
+ const x265_api* x265_api_get(int bitDepth);
-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:
+Like **x265_encoder_encode()**, this function has the build number
+automatically appended to the function name via macros. This ties your
+application to a particular binary API version of libx265 (the one you
+compile against). If you attempt to link with a libx265 with a different
+API version number, the link will fail.
- 8-bit: libx265_main.dll
- 10-bit: libx265_main10.dll
+Obviously this has no meaningful effect on applications which statically
+link to libx265.
- (the shared library extension is obviously platform specific. On
- Linux it is .so while on Mac it is .dylib)
+x265_api_query
+--------------
-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 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)
-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.
-
-There is a second bit-depth introspection method that is designed for
-applications which need more flexibility in API versioning. If you use
-the public API described at the top of this page or x265_api_get() then
-your application must be recompiled each time x265 changes its public
-API and bumps its build number (X265_BUILD, which is also the SONAME on
-POSIX systems). But if you use **x265_api_query** and dynamically link to
-libx265 (use dlopen() on POSIX or LoadLibrary() on Windows) your
-application is no longer directly tied to the API version of x265.h that
-it was compiled against.
+The second bit-depth introspection method is designed for applications
+which need more flexibility in API versioning. If you use
+**x265_api_query()** and dynamically link to libx265 at runtime (using
+dlopen() on POSIX or LoadLibrary() on Windows) your application is no
+longer directly tied to the API version that it was compiled against.
/* x265_api_query:
* Retrieve the programming interface for a linked x265 library, like
@@ -468,3 +451,77 @@ api->param_free(), api->param_parse(), e
any x265_param fields, then it can skip the check on the
sizeof(x265_parm) and thereby ignore changes to that structure (which
account for a large percentage of X265_BUILD bumps).
+
+Static Linking Implications
+---------------------------
+
+By default libx265 will place all of its internal C++ classes and
+functions within an x265 namespace and export all of the C functions
+documented in this file. Obviously this prevents 8bit and 10bit builds
+of libx265 from being statically linked into a single application, all
+of those symbols would collide.
+
+However, if you set the EXPORT_C_API cmake option to OFF, then libx265
+will use an x265_8bit or x265_10bit namespace for its C++ classes and
+functions (and use the same name as a prefix for its assembly functions)
+and only exports the two bit-depth introspection C functions from the
+8bit library and no C functions from the 10bit library. Thus
More information about the x265-commits
mailing list