[x265] [PATCH 1 of 2] api: introduce x265_api_get()
Steve Borho
steve at borho.org
Thu Apr 2 19:19:47 CEST 2015
# HG changeset patch
# User Steve Borho <steve at borho.org>
# Date 1427993196 18000
# Thu Apr 02 11:46:36 2015 -0500
# Branch stable
# Node ID 45f8c67a84a539eeb7ea27db5ac3f4444c781fc9
# Parent 4b4ffee98ed1198c072b7ab005b69aca72ffaee3
api: introduce x265_api_get()
diff -r 4b4ffee98ed1 -r 45f8c67a84a5 doc/reST/api.rst
--- a/doc/reST/api.rst Thu Apr 02 11:43:56 2015 -0500
+++ b/doc/reST/api.rst Thu Apr 02 11:46:36 2015 -0500
@@ -347,3 +347,36 @@
/* x265_cleanup:
* release library static allocations, reset configured CTU size */
void x265_cleanup(void);
+
+
+Multi-library Interface
+=======================
+
+If your application might want to make a runtime selection between among
+a number of libx265 libraries (perhaps 8bpp and 16bpp), then you will
+want to use the multi-library interface.
+
+Instead of directly using all of the **x265_** methods documenting
+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()::
+
+ /* x265_api_get:
+ * Retrieve the programming interface for a linked x265 library.
+ * May return NULL if no library is available that supports the
+ * requested bitdepth. 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);
+
+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. 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.
diff -r 4b4ffee98ed1 -r 45f8c67a84a5 source/CMakeLists.txt
--- a/source/CMakeLists.txt Thu Apr 02 11:43:56 2015 -0500
+++ b/source/CMakeLists.txt Thu Apr 02 11:46:36 2015 -0500
@@ -30,7 +30,7 @@
mark_as_advanced(FPROFILE_USE FPROFILE_GENERATE NATIVE_BUILD)
# X265_BUILD must be incremented each time the public API is changed
-set(X265_BUILD 50)
+set(X265_BUILD 51)
configure_file("${PROJECT_SOURCE_DIR}/x265.def.in"
"${PROJECT_BINARY_DIR}/x265.def")
configure_file("${PROJECT_SOURCE_DIR}/x265_config.h.in"
diff -r 4b4ffee98ed1 -r 45f8c67a84a5 source/encoder/api.cpp
--- a/source/encoder/api.cpp Thu Apr 02 11:43:56 2015 -0500
+++ b/source/encoder/api.cpp Thu Apr 02 11:46:36 2015 -0500
@@ -218,3 +218,36 @@
{
return x265_free(p);
}
+
+static const x265_api libapi =
+{
+ &x265_param_alloc,
+ &x265_param_free,
+ &x265_param_default,
+ &x265_param_parse,
+ &x265_param_apply_profile,
+ &x265_param_default_preset,
+ &x265_picture_alloc,
+ &x265_picture_free,
+ &x265_picture_init,
+ &x265_encoder_open,
+ &x265_encoder_parameters,
+ &x265_encoder_headers,
+ &x265_encoder_encode,
+ &x265_encoder_get_stats,
+ &x265_encoder_log,
+ &x265_encoder_close,
+ &x265_cleanup,
+ x265_version_str,
+ x265_build_info_str,
+ x265_max_bit_depth,
+};
+
+extern "C"
+const x265_api* x265_api_get(int bitDepth)
+{
+ if (bitDepth && bitDepth != X265_DEPTH)
+ return NULL;
+
+ return &libapi;
+}
diff -r 4b4ffee98ed1 -r 45f8c67a84a5 source/x265.def.in
--- a/source/x265.def.in Thu Apr 02 11:43:56 2015 -0500
+++ b/source/x265.def.in Thu Apr 02 11:46:36 2015 -0500
@@ -19,3 +19,4 @@
x265_encoder_log
x265_encoder_close
x265_cleanup
+x265_api_get_${X265_BUILD}
diff -r 4b4ffee98ed1 -r 45f8c67a84a5 source/x265.h
--- a/source/x265.h Thu Apr 02 11:43:56 2015 -0500
+++ b/source/x265.h Thu Apr 02 11:46:36 2015 -0500
@@ -1232,6 +1232,53 @@
* release library static allocations, reset configured CTU size */
void x265_cleanup(void);
+
+/* === Multi-lib API ===
+ * By using this method to gain access to the libx265 interfaces, you allow shim
+ * implementations of x265_api_get() to choose between various available libx265
+ * libraries based on the encoder parameters. The most likely use case is to
+ * choose between 8bpp and 16bpp builds of libx265. */
+
+typedef struct x265_api
+{
+ /* libx265 public API functions, documented above with x265_ prefixes */
+ x265_param* (*param_alloc)(void);
+ void (*param_free)(x265_param*);
+ void (*param_default)(x265_param*);
+ int (*param_parse)(x265_param*, const char*, const char*);
+ int (*param_apply_profile)(x265_param*, const char*);
+ int (*param_default_preset)(x265_param*, const char*, const char *);
+ x265_picture* (*picture_alloc)(void);
+ void (*picture_free)(x265_picture*);
+ void (*picture_init)(x265_param*, x265_picture*);
+ x265_encoder* (*encoder_open)(x265_param*);
+ void (*encoder_parameters)(x265_encoder*, x265_param*);
+ int (*encoder_headers)(x265_encoder*, x265_nal**, uint32_t*);
+ int (*encoder_encode)(x265_encoder*, x265_nal**, uint32_t*, x265_picture*, x265_picture*);
+ void (*encoder_get_stats)(x265_encoder*, x265_stats*, uint32_t);
+ void (*encoder_log)(x265_encoder*, int, char**);
+ void (*encoder_close)(x265_encoder*);
+ void (*cleanup)(void);
+ const char* version_str;
+ const char* build_info_str;
+ int max_bit_depth;
+} x265_api;
+
+/* Force a link error in the case of linking against an incompatible API version.
+ * Glue #defines exist to force correct macro expansion; the final output of the macro
+ * is x265_api_get_##X265_BUILD (for purposes of dlopen). */
+#define x265_api_glue1(x, y) x ## y
+#define x265_api_glue2(x, y) x265_api_glue1(x, y)
+#define x265_api_get x265_api_glue2(x265_api_get_, X265_BUILD)
+
+/* x265_api_get:
+ * Retrieve the programming interface for a linked x265 library.
+ * May return NULL if no library is available that supports the
+ * requested bitdepth. 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);
+
#ifdef __cplusplus
}
#endif
More information about the x265-devel
mailing list