From 5feec17ca8ef7c0959b8a0cc17b7937c44a29378 Mon Sep 17 00:00:00 2001 From: wm4 Date: Tue, 7 Oct 2014 21:19:04 +0200 Subject: [PATCH] client API: improve mpv_observe_property docs 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. --- libmpv/client.h | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/libmpv/client.h b/libmpv/client.h index 54b4718155..fe7efa66f8 100644 --- a/libmpv/client.h +++ b/libmpv/client.h @@ -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