diff options
Diffstat (limited to 'libmpv')
-rw-r--r-- | libmpv/client.h | 105 | ||||
-rw-r--r-- | libmpv/mpv.def | 1 | ||||
-rw-r--r-- | libmpv/render_gl.h | 18 | ||||
-rw-r--r-- | libmpv/stream_cb.h | 2 |
4 files changed, 103 insertions, 23 deletions
diff --git a/libmpv/client.h b/libmpv/client.h index 39df20a8c0..51beb1a41b 100644 --- a/libmpv/client.h +++ b/libmpv/client.h @@ -107,8 +107,9 @@ extern "C" { * careful not accidentally interpret the mpv_event->reply_userdata if an * event is not a reply. (For non-replies, this field is set to 0.) * - * Currently, asynchronous calls are always strictly ordered (even with - * synchronous calls) for each client, although that may change in the future. + * Asynchronous calls may be reordered in arbitrarily with other synchronous + * and asynchronous calls. If you want a guaranteed order, you need to wait + * until asynchronous calls report completion before doing the next call. * * Multithreading * -------------- @@ -195,6 +196,18 @@ extern "C" { * 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. + * + * Future changes + * -------------- + * + * This are the planned changes that will most likely be done on the next major + * bump of the library: + * + * - remove all symbols and include files that are marked as deprecated + * - reassign enum numerical values to remove gaps + * - remove the mpv_opengl_init_params.extra_exts field + * - change the type of mpv_event_end_file.reason + * - disabling all events by default */ /** @@ -210,7 +223,7 @@ extern "C" { * relational operators (<, >, <=, >=). */ #define MPV_MAKE_VERSION(major, minor) (((major) << 16) | (minor) | 0UL) -#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 102) +#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 103) /** * The API user is allowed to "#define MPV_ENABLE_DEPRECATED 0" before @@ -928,10 +941,25 @@ int mpv_command(mpv_handle *ctx, const char **args); * * Does not use OSD and string expansion by default. * - * @param[in] args mpv_node with format set to MPV_FORMAT_NODE_ARRAY; each entry - * is an argument using an arbitrary format (the format must be - * compatible to the used command). Usually, the first item is - * the command name (as MPV_FORMAT_STRING). + * The args argument can have one of the following formats: + * + * MPV_FORMAT_NODE_ARRAY: + * Positional arguments. Each entry is an argument using an arbitrary + * format (the format must be compatible to the used command). Usually, + * the first item is the command name (as MPV_FORMAT_STRING). The order + * of arguments is as documented in each command description. + * + * MPV_FORMAT_NODE_MAP: + * Named arguments. This requires at least an entry with the key "name" + * to be present, which must be a string, and contains the command name. + * The special entry "_flags" is optional, and if present, must be an + * array of strings, each being a command prefix to apply. All other + * entries are interpreted as arguments. They must use the argument names + * as documented in each command description. Some commands do not + * support named arguments at all, and must use MPV_FORMAT_NODE_ARRAY. + * + * @param[in] args mpv_node with format set to one of the values documented + * above (see there for details) * @param[out] result Optional, pass NULL if unused. If not NULL, and if the * function succeeds, this is set to command-specific return * data. You must call mpv_free_node_contents() to free it @@ -954,14 +982,11 @@ int mpv_command_string(mpv_handle *ctx, const char *args); * Same as mpv_command, but run the command asynchronously. * * Commands are executed asynchronously. You will receive a - * MPV_EVENT_COMMAND_REPLY event. (This event will also have an - * error code set if running the command failed.) - * - * This has nothing to do with the "async" command prefix, although they might - * be unified in the future. For now, calling this API means that the command - * will be synchronously executed on the core, without blocking the API user. + * MPV_EVENT_COMMAND_REPLY event. This event will also have an + * error code set if running the command failed. For commands that + * return data, the data is put into mpv_event_command.result. * - * * Safe to be called from mpv render API threads. + * Safe to be called from mpv render API threads. * * @param reply_userdata the value mpv_event.reply_userdata of the reply will * be set to (see section about asynchronous calls) @@ -976,8 +1001,7 @@ int mpv_command_async(mpv_handle *ctx, uint64_t reply_userdata, * function is to mpv_command_node() what mpv_command_async() is to * mpv_command(). * - * See mpv_command_async() for details. Retrieving the result is not - * supported yet. + * See mpv_command_async() for details. * * Safe to be called from mpv render API threads. * @@ -990,6 +1014,38 @@ int mpv_command_node_async(mpv_handle *ctx, uint64_t reply_userdata, mpv_node *args); /** + * Signal to all async requests with the matching ID to abort. This affects + * the following API calls: + * + * mpv_command_async + * mpv_command_node_async + * + * All of these functions take a reply_userdata parameter. This API function + * tells all requests with the matching reply_userdata value to try to return + * as soon as possible. If there are multiple requests with matching ID, it + * aborts all of them. + * + * This API function is mostly asynchronous itself. It will not wait until the + * command is aborted. Instead, the command will terminate as usual, but with + * some work not done. How this is signaled depends on the specific command (for + * example, the "subprocess" command will indicate it by "killed_by_us" set to + * true in the result). How long it takes also depends on the situation. The + * aborting process is completely asynchronous. + * + * Not all commands may support this functionality. In this case, this function + * will have no effect. The same is true if the request using the passed + * reply_userdata has already terminated, has not been started yet, or was + * never in use at all. + * + * You have to be careful of race conditions: the time during which the abort + * request will be effective is _after_ e.g. mpv_command_async() has returned, + * and before the command has signaled completion with MPV_EVENT_COMMAND_REPLY. + * + * @param reply_userdata ID of the request to be aborted (see above) + */ +void mpv_abort_async_command(mpv_handle *ctx, uint64_t reply_userdata); + +/** * Set a property to a given value. Properties are essentially variables which * can be queried or set at runtime. For example, writing to the pause property * will actually pause or unpause playback. @@ -1202,7 +1258,8 @@ typedef enum mpv_event_id { */ MPV_EVENT_SET_PROPERTY_REPLY = 4, /** - * Reply to a mpv_command_async() request. + * Reply to a mpv_command_async() or mpv_command_node_async() request. + * See also mpv_event and mpv_event_command. */ MPV_EVENT_COMMAND_REPLY = 5, /** @@ -1549,6 +1606,17 @@ typedef struct mpv_event_hook { uint64_t id; } mpv_event_hook; +// Since API version 1.102. +typedef struct mpv_event_command { + /** + * Result data of the command. Note that success/failure is signaled + * separately via mpv_event.error. This field is only for result data + * in case of success. Most commands leave it at MPV_FORMAT_NONE. Set + * to MPV_FORMAT_NONE on failure. + */ + mpv_node result; +} mpv_event_command; + typedef struct mpv_event { /** * One of mpv_event. Keep in mind that later ABI compatible releases might @@ -1575,6 +1643,7 @@ typedef struct mpv_event { * MPV_EVENT_SET_PROPERTY_REPLY * MPV_EVENT_COMMAND_REPLY * MPV_EVENT_PROPERTY_CHANGE + * MPV_EVENT_HOOK */ uint64_t reply_userdata; /** @@ -1584,6 +1653,8 @@ typedef struct mpv_event { * MPV_EVENT_LOG_MESSAGE: mpv_event_log_message* * MPV_EVENT_CLIENT_MESSAGE: mpv_event_client_message* * MPV_EVENT_END_FILE: mpv_event_end_file* + * MPV_EVENT_HOOK: mpv_event_hook* + * MPV_EVENT_COMMAND_REPLY* mpv_event_command* * other: NULL * * Note: future enhancements might add new event structs for existing or new diff --git a/libmpv/mpv.def b/libmpv/mpv.def index b74378c4ae..5b1c2423ff 100644 --- a/libmpv/mpv.def +++ b/libmpv/mpv.def @@ -1,3 +1,4 @@ +mpv_abort_async_command mpv_client_api_version mpv_client_name mpv_command diff --git a/libmpv/render_gl.h b/libmpv/render_gl.h index 690b126906..69bec75c47 100644 --- a/libmpv/render_gl.h +++ b/libmpv/render_gl.h @@ -107,11 +107,13 @@ typedef struct mpv_opengl_init_params { /** * This retrieves OpenGL function pointers, and will use them in subsequent * operation. - * Usually, GL context APIs do this for you (e.g. with glXGetProcAddressARB - * or wglGetProcAddress), but some APIs do not always return pointers for - * all standard functions (even if present); in this case you have to - * compensate by looking up these functions yourself and returning them - * from this callback. + * Usually, you can simply call the GL context APIs from this callback (e.g. + * glXGetProcAddressARB or wglGetProcAddress), but some APIs do not always + * return pointers for all standard functions (even if present); in this + * case you have to compensate by looking up these functions yourself when + * libmpv wants to resolve them through this callback. + * libmpv will not normally attempt to resolve GL functions on its own, nor + * does it link to GL libraries directly. */ void *(*get_proc_address)(void *ctx, const char *name); /** @@ -147,6 +149,9 @@ typedef struct mpv_opengl_fbo { int internal_format; } mpv_opengl_fbo; +/** + * For MPV_RENDER_PARAM_DRM_DISPLAY. + */ typedef struct mpv_opengl_drm_params { /** * DRM fd (int). Set to a negative number if invalid. @@ -177,6 +182,9 @@ typedef struct mpv_opengl_drm_params { int render_fd; } mpv_opengl_drm_params; +/** + * For MPV_RENDER_PARAM_DRM_DRAW_SURFACE_SIZE. + */ typedef struct mpv_opengl_drm_draw_surface_size { /** * size of the draw plane surface in pixels. diff --git a/libmpv/stream_cb.h b/libmpv/stream_cb.h index 01de4700b2..5971aa2c32 100644 --- a/libmpv/stream_cb.h +++ b/libmpv/stream_cb.h @@ -112,7 +112,7 @@ typedef int64_t (*mpv_stream_cb_read_fn)(void *cookie, char *buf, uint64_t nbyte * is used to test whether the stream is seekable (since seekability might * depend on the URI contents, not just the protocol). Return * MPV_ERROR_UNSUPPORTED if seeking is not implemented for this stream. This - * seek also servies to establish the fact that streams start at position 0. + * seek also serves to establish the fact that streams start at position 0. * * This callback can be NULL, in which it behaves as if always returning * MPV_ERROR_UNSUPPORTED. |