RepoMirrors/mpv
1
0
Fork 0
mirror of https://github.com/mpv-player/mpv synced 2024-12-25 08:12:17 +00:00
Code Issues Releases Wiki Activity

client API: improve mpv_observe_property docs

Browse Source 
Document the "normal" behavior (if MPV_FORMAT_NONE is not used) first,
and then introduce MPV_FORMAT_NONE as exception.

The actual semantics didn't change in mpv; this is only clarification.
This commit is contained in:
wm4 2014-10-07 21:19:04 +02:00
parent 128bb68d29
commit 5feec17ca8
1 changed files with 18 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
libmpv/client.h
View File

@ -779,37 +779,44 @@ int mpv_get_property_async(mpv_handle *ctx, uint64_t reply_userdata,
/**
* Get a notification whenever the given property changes. You will receive
* updates as MPV_EVENT_PROPERTY_CHANGE. Note that this is not very precise:
* it can send updates even if the property in fact did not change, or (in
* some cases) not send updates even if the property changed - it usually
* depends on the property. It's a valid feature request to ask for better
* update handling of a specific property.
* for some properties, it may not send updates even if the property changed.
* This depends on the property, and it's a valid feature request to ask for
* better update handling of a specific property. (For some properties, like
* ``clock``, which shows the wall clock, this mechanism doesn't make too
* much sense anyway.)
*
* Property changes are coalesced: the change events are returned only once the
* 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.
*
* 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. In
* this case, the API will also suppress redundant change events by comparing
* the raw value against the previous value.
* Normally, change events are sent only if the property value changes according
* to the requested format. mpv_event_property will contain the property value
* as data member.
*
* 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
* format parameter was set to a different value. In this case, the
* mpv_event_property.data field is invalid.
*
* Observing a property that doesn't exist is allowed, although it may still
* cause some sporadic change events.
* If the property is observed with the format parameter set to MPV_FORMAT_NONE,
* you get low-level notifications whether the property _may_ have changed, and
* the data member in mpv_event_property will be unset. With this mode, you
* will have to determine yourself whether the property really changd. On the
* other hand, this mechanism can be faster and uses less resources.
*
* Observing a property that doesn't exist is allowed. (Although it may still
* cause some sporadic change events.)
*
* 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 you react to the change notifications triggered by your own change.
*
* @param reply_userdata This will be used for the mpv_event.reply_userdata
* field for the received MPV_EVENT_PROPERTY_CHANGE
* events. (Also see section about asynchronous calls,
* although this function is somewhat different from
* actual asynchronous calls.)
* If you have no use for this, pass 0.
* Also see mpv_unobserve_property().
* @param name The property name.
* @param format see enum mpv_format. Can be MPV_FORMAT_NONE to omit values