diff options
author | wm4 <wm4@nowhere> | 2014-07-03 01:24:41 +0200 |
---|---|---|
committer | wm4 <wm4@nowhere> | 2014-07-03 01:26:19 +0200 |
commit | 0004aaf7884b51b56b04a6dbe1812237b7201fad (patch) | |
tree | 0ab345d4a07e52e9e2964854197fc9e822510508 | |
parent | 0bda8f48e27c576ceab28230853ad3e05fc49892 (diff) | |
download | mpv-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.rst | 35 | ||||
-rw-r--r-- | DOCS/man/input.rst | 1 | ||||
-rw-r--r-- | libmpv/client.h | 27 |
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. |