RepoMirrors
/
mpv
mirror of https://github.com/mpv-player/mpv
1
0
Fork 0
Code Issues Releases Wiki Activity

client API: improve comments

This commit is contained in:
wm4 2014-04-10 23:53:42 +02:00
parent f0e08c01ff
commit f0c8c26e29
1 changed files with 31 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
libmpv/client.h
View File

@ -56,9 +56,10 @@ extern "C" {
* Event loop * Event loop
* ---------- * ----------
* *
* In general, the API user should run an event loop (with mpv_wait_event()) * In general, the API user should run an event loop in order to receive events.
* in order to receive events, although it also should be possible to integrate * This even loop should call mpv_wait_event(), which will return once a new
* client API usage in other event loops (e.g. GUI toolkits) with the * mpv client API is available. It should also be possible to integrate client
* API usage in other event loops (e.g. GUI toolkits) with the
* mpv_set_wakeup_callback() function, and then polling for events by calling * mpv_set_wakeup_callback() function, and then polling for events by calling
* mpv_wait_event() with a 0 timeout. * mpv_wait_event() with a 0 timeout.
* *
@ -352,8 +353,7 @@ void mpv_resume(mpv_handle *ctx);
/** /**
* Return the internal time in microseconds. This has an arbitrary start offset, * Return the internal time in microseconds. This has an arbitrary start offset,
* but will never wrap or go backwards (note: the latter is probably a lie in * but will never wrap or go backwards.
* the current implementation, it can go backwards on system clock changes).
* *
* Note that this is always the real time, and doesn't necessarily have to do * Note that this is always the real time, and doesn't necessarily have to do
* with playback time. For example, playback could go faster or slower due to * with playback time. For example, playback could go faster or slower due to
@ -369,7 +369,7 @@ int64_t mpv_get_time_us(mpv_handle *ctx);
*/ */
typedef enum mpv_format { typedef enum mpv_format {
/** /**
* Invalid. * Invalid. Sometimes used for empty values.
*/ */
MPV_FORMAT_NONE = 0, MPV_FORMAT_NONE = 0,
/** /**
@ -487,7 +487,9 @@ typedef enum mpv_format {
* Generic data storage. * Generic data storage.
* *
* If mpv writes this struct (e.g. via mpv_get_property()), you must not change * If mpv writes this struct (e.g. via mpv_get_property()), you must not change
* the data. You have to free it with mpv_free_node_contents(). * the data. In some cases (mpv_get_property()), you have to free it with
* mpv_free_node_contents(). If you fill this struct yourself, you're also
* responsible for freeing it, and you must not call mpv_free_node_contents().
*/ */
typedef struct mpv_node { typedef struct mpv_node {
union { union {
@ -634,7 +636,7 @@ int mpv_command_async(mpv_handle *ctx, uint64_t reply_userdata,
* usually will fail with MPV_ERROR_PROPERTY_FORMAT. In some cases, the data * usually will fail with MPV_ERROR_PROPERTY_FORMAT. In some cases, the data
* is automatically converted and access succeeds. For example, MPV_FORMAT_INT64 * is automatically converted and access succeeds. For example, MPV_FORMAT_INT64
* is always converted to MPV_FORMAT_DOUBLE, and access using MPV_FORMAT_STRING * is always converted to MPV_FORMAT_DOUBLE, and access using MPV_FORMAT_STRING
* usually invokes a string formatter. * usually invokes a string parser.
* *
* @param name The property name. See input.rst for a list of properties. * @param name The property name. See input.rst for a list of properties.
* @param format see enum mpv_format. Currently, only MPV_FORMAT_STRING is valid. * @param format see enum mpv_format. Currently, only MPV_FORMAT_STRING is valid.
@ -674,7 +676,7 @@ int mpv_set_property_async(mpv_handle *ctx, uint64_t reply_userdata,
* usually will fail with MPV_ERROR_PROPERTY_FORMAT. In some cases, the data * usually will fail with MPV_ERROR_PROPERTY_FORMAT. In some cases, the data
* is automatically converted and access succeeds. For example, MPV_FORMAT_INT64 * is automatically converted and access succeeds. For example, MPV_FORMAT_INT64
* is always converted to MPV_FORMAT_DOUBLE, and access using MPV_FORMAT_STRING * is always converted to MPV_FORMAT_DOUBLE, and access using MPV_FORMAT_STRING
* usually invokes a string parser. * usually invokes a string formatter.
* *
* @param name The property name. * @param name The property name.
* @param format see enum mpv_format. * @param format see enum mpv_format.
@ -737,12 +739,10 @@ int mpv_get_property_async(mpv_handle *ctx, uint64_t reply_userdata,
* event queue becomes empty (e.g. mpv_wait_event() would block or return * event queue becomes empty (e.g. mpv_wait_event() would block or return
* MPV_EVENT_NONE), and then only one event per changed property is returned. * MPV_EVENT_NONE), and then only one event per changed property is returned.
* *
* Keep in mind that you will get change notifications even if you change a
* property yourself. Try to avoid endless feedback loops, which could happen
* if you react to change notifications which you caused yourself.
*
* If the format parameter is set to something other than MPV_FORMAT_NONE, the * If the format parameter is set to something other than MPV_FORMAT_NONE, the
* current property value will be returned as part of mpv_event_property. * current property value will be returned as part of mpv_event_property. In
* this case, the API will also suppress redundant change events by comparing
* the raw value against the previous value.
* *
* Warning: if a property is unavailable or retrieving it caused an error, * Warning: if a property is unavailable or retrieving it caused an error,
* MPV_FORMAT_NONE will be set in mpv_event_property, even if the * MPV_FORMAT_NONE will be set in mpv_event_property, even if the
@ -752,9 +752,9 @@ int mpv_get_property_async(mpv_handle *ctx, uint64_t reply_userdata,
* Observing a property that doesn't exist is allowed, although it may still * Observing a property that doesn't exist is allowed, although it may still
* cause some sporadic change events. * cause some sporadic change events.
* *
* If you set the format parameter to a value other than MPV_FORMAT_NONE, the * Keep in mind that you will get change notifications even if you change a
* API will suppress redundant change events by comparing the raw value against * property yourself. Try to avoid endless feedback loops, which could happen
* the previous value. * if you react to change notifications which you caused yourself.
* *
* @param reply_userdata This will be used for the mpv_event.reply_userdata * @param reply_userdata This will be used for the mpv_event.reply_userdata
* field for the received MPV_EVENT_PROPERTY_CHANGE * field for the received MPV_EVENT_PROPERTY_CHANGE
@ -765,7 +765,7 @@ int mpv_get_property_async(mpv_handle *ctx, uint64_t reply_userdata,
* @param name The property name. * @param name The property name.
* @param format see enum mpv_format. Can be MPV_FORMAT_NONE to omit values * @param format see enum mpv_format. Can be MPV_FORMAT_NONE to omit values
* from the change events. * from the change events.
* @return error code (usually fails only on OOM) * @return error code (usually fails only on OOM or unsupported format)
*/ */
int mpv_observe_property(mpv_handle *mpv, uint64_t reply_userdata, int mpv_observe_property(mpv_handle *mpv, uint64_t reply_userdata,
const char *name, mpv_format format); const char *name, mpv_format format);
@ -775,8 +775,8 @@ int mpv_observe_property(mpv_handle *mpv, uint64_t reply_userdata,
* which the given number was passed as reply_userdata to mpv_observe_property. * which the given number was passed as reply_userdata to mpv_observe_property.
* *
* @param registered_reply_userdata ID that was passed to mpv_observe_property * @param registered_reply_userdata ID that was passed to mpv_observe_property
* @return negative value is an error code, number of removed properties on * @return negative value is an error code, >=0 is number of removed properties
* success (includes the case when 0 were removed) * on success (includes the case when 0 were removed)
*/ */
int mpv_unobserve_property(mpv_handle *mpv, uint64_t registered_reply_userdata); int mpv_unobserve_property(mpv_handle *mpv, uint64_t registered_reply_userdata);
@ -812,7 +812,7 @@ typedef enum mpv_event_id {
*/ */
MPV_EVENT_COMMAND_REPLY = 5, MPV_EVENT_COMMAND_REPLY = 5,
/** /**
* Notification before playback start of a file. * Notification before playback start of a file (before the file is loaded).
*/ */
MPV_EVENT_START_FILE = 6, MPV_EVENT_START_FILE = 6,
/** /**
@ -825,7 +825,9 @@ typedef enum mpv_event_id {
*/ */
MPV_EVENT_FILE_LOADED = 8, MPV_EVENT_FILE_LOADED = 8,
/** /**
* The list of video/audio/subtitle tracks was changed. * The list of video/audio/subtitle tracks was changed. (E.g. a new track
* was found. This doesn't necessarily indicate a track switch; for this,
* MPV_EVENT_TRACK_SWITCHED is used.)
*/ */
MPV_EVENT_TRACKS_CHANGED = 9, MPV_EVENT_TRACKS_CHANGED = 9,
/** /**
@ -856,6 +858,9 @@ typedef enum mpv_event_id {
* Triggered by the script_dispatch input command. The command uses the * Triggered by the script_dispatch input command. The command uses the
* client name (see mpv_client_name()) to dispatch keyboard or mouse input * client name (see mpv_client_name()) to dispatch keyboard or mouse input
* to a client. * to a client.
* (This is pretty obscure and largely replaced by MPV_EVENT_CLIENT_MESSAGE,
* but still the only way to distinguish key down/up events when binding
* script_dispatch via input.conf.)
*/ */
MPV_EVENT_SCRIPT_INPUT_DISPATCH = 15, MPV_EVENT_SCRIPT_INPUT_DISPATCH = 15,
/** /**
@ -863,6 +868,7 @@ typedef enum mpv_event_id {
* first argument of the command as client name (see mpv_client_name()) to * first argument of the command as client name (see mpv_client_name()) to
* dispatch the message, and passes along the all arguments starting from * dispatch the message, and passes along the all arguments starting from
* the seconand argument as strings. * the seconand argument as strings.
* See also mpv_event and mpv_event_client_message.
*/ */
MPV_EVENT_CLIENT_MESSAGE = 16, MPV_EVENT_CLIENT_MESSAGE = 16,
/** /**
@ -1013,7 +1019,7 @@ typedef struct mpv_event_client_message {
* Arbitrary arguments chosen by the sender of the message. If num_args > 0, * Arbitrary arguments chosen by the sender of the message. If num_args > 0,
* you can access args[0] through args[num_args - 1] (inclusive). What * you can access args[0] through args[num_args - 1] (inclusive). What
* these arguments mean is up to the sender and receiver. * these arguments mean is up to the sender and receiver.
* None of the valid items is NULL. * None of the valid items are NULL.
*/ */
int num_args; int num_args;
const char **args; const char **args;
@ -1116,8 +1122,8 @@ mpv_event *mpv_wait_event(mpv_handle *ctx, double timeout);
* *
* mpv_wait_event() will receive a MPV_EVENT_NONE if it's woken up due to * mpv_wait_event() will receive a MPV_EVENT_NONE if it's woken up due to
* this call. But note that this dummy event might be skipped if there are * this call. But note that this dummy event might be skipped if there are
* already another events queued. All what counts is that the waiting thread * already other events queued. All what counts is that the waiting thread
* is woken up. * is woken up at all.
*/ */
void mpv_wakeup(mpv_handle *ctx); void mpv_wakeup(mpv_handle *ctx);