mirror of
https://github.com/mpv-player/mpv
synced 2025-04-01 23:00:41 +00:00
DOCS: add a file listing API changes for the client API
This commit is contained in:
parent
0bda8f48e2
commit
0004aaf788
35
DOCS/client-api-changes.rst
Normal file
35
DOCS/client-api-changes.rst
Normal file
@ -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
|
@ -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
|
||||
|
||||
|
@ -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.
|
||||
|
Loading…
Reference in New Issue
Block a user