summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2014-07-03 01:24:41 +0200
committerwm4 <wm4@nowhere>2014-07-03 01:26:19 +0200
commit0004aaf7884b51b56b04a6dbe1812237b7201fad (patch)
tree0ab345d4a07e52e9e2964854197fc9e822510508
parent0bda8f48e27c576ceab28230853ad3e05fc49892 (diff)
downloadmpv-0004aaf7884b51b56b04a6dbe1812237b7201fad.tar.bz2
mpv-0004aaf7884b51b56b04a6dbe1812237b7201fad.tar.xz
DOCS: add a file listing API changes for the client API
-rw-r--r--DOCS/client-api-changes.rst35
-rw-r--r--DOCS/man/input.rst1
-rw-r--r--libmpv/client.h27
3 files changed, 61 insertions, 2 deletions
diff --git a/DOCS/client-api-changes.rst b/DOCS/client-api-changes.rst
new file mode 100644
index 0000000000..548832be5f
--- /dev/null
+++ b/DOCS/client-api-changes.rst
@@ -0,0 +1,35 @@
+Introduction
+============
+
+This file lists all changes that can cause compatibility issues when using
+mpv through the client API (libmpv and ``client.h``). Since the client API
+interfaces to input handling (commands, properties) as well as command line
+options, this list is interesting for other uses of mpv, such as the Lua
+scripting interface, key bindings in ``input.rst``, or plain command line
+usage.
+
+Normally, changes to the C API that are incompatible to previous iterations
+receive a major version bump (i.e. the first version number is increased),
+while C API additions bump the minor version (i.e. the second number is
+increased). Changes to properties/commands/options may also lead to a minor
+version bump, in particular if they are incompatible.
+
+The version number is the same as used for MPV_CLIENT_API_VERSION (see
+``client.h`` how to convert between major/minor version numbers and the flat
+32 bit integer).
+
+Also, read the section ``Compatibility`` in ``client.h``.
+
+API changes
+===========
+
+ 1.1 - remap dvdnav:// to dvd://
+ - add "--cache-file", "--cache-file-size"
+ - add "--colormatrix-primaries" (and property)
+ - add "primaries" sub-field to image format properties
+ - add "playback-time" property
+ - extend the "--start" option; a leading "+", which was previously
+ insignificant is now significant
+ - add "cache-free" and "cache-used" properties
+ - OSX: the "coreaudio" AO spdif code is split into a separate AO
+ 1.0 - the API is declared stable
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 2e0f06c252..da3bd8f2a1 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -987,6 +987,7 @@ Property list
"par" MPV_FORMAT_DOUBLE
"colormatrix" MPV_FORMAT_STRING
"colorlevels" MPV_FORMAT_STRING
+ "primaries" MPV_FORMAT_STRING
"chroma-location" MPV_FORMAT_STRING
"rotate" MPV_FORMAT_INT64
diff --git a/libmpv/client.h b/libmpv/client.h
index b2b48f390f..51866959ef 100644
--- a/libmpv/client.h
+++ b/libmpv/client.h
@@ -114,7 +114,7 @@ extern "C" {
* handler is process-wide, and there's no proper way to share it with other
* xlib users within the same process. This might confuse GUI toolkits.
* - mpv uses some other libraries that are not library-safe, such as Fribidi
- * (used through libass), LittleCMS, ALSA, FFmpeg, and possibly more.
+ * (used through libass), ALSA, FFmpeg, and possibly more.
* - The FPU precision must be set at least to double precision.
* - On Windows, mpv will call timeBeginPeriod(1).
* - On memory exhaustion, mpv will kill the process.
@@ -131,6 +131,24 @@ extern "C" {
* aspect ratio of the window and the video mismatch).
*
* On OSX, embedding is not yet possible, because Cocoa makes this non-trivial.
+ *
+ * Compatibility
+ * -------------
+ *
+ * mpv development doesn't stand still, and changes to mpv internals as well as
+ * to its interface can cause compatibility issues to client API users.
+ *
+ * The API is versioned (see MPV_CLIENT_API_VERSION), and changes to it are
+ * documented in DOCS/client-api-changes.rst. The C API itself will probably
+ * remain compatible for a long time, but the functionality exposed by it
+ * could change more rapidly. For example, it's possible that options are
+ * renamed, or change the set of allowed values.
+ *
+ * Defensive programming should be used to potentially deal with the fact that
+ * options, commands, and properties could disappear, change their value range,
+ * or change the underlying datatypes. It might be a good idea to prefer
+ * MPV_FORMAT_STRING over other types to decouple your code from potential
+ * mpv changes.
*/
/**
@@ -139,8 +157,13 @@ extern "C" {
* the API becomes incompatible to previous versions, the major version
* number is incremented. This affects only C part, and not properties and
* options.
+ *
+ * The version number is often converted into a human readable form by writing
+ * the major and minor version number in decimal. E.g.:
+ * version 0x001001FF
+ * becomes 16.511 (dec(0x0010) + "." + dec(0x01FF))
*/
-#define MPV_CLIENT_API_VERSION 0x00010000UL
+#define MPV_CLIENT_API_VERSION 0x00010001UL
/**
* Return the MPV_CLIENT_API_VERSION the mpv source has been compiled with.