Function libmpv_sys::mpv_observe_property

pub unsafe extern "C" fn mpv_observe_property(
    mpv: *mut mpv_handle, 
    reply_userdata: u64, 
    name: *const c_char, 
    format: mpv_format
) -> c_int

Get a notification whenever the given property changes. You will receive updates as MPV_EVENT_PROPERTY_CHANGE. Note that this is not very precise: 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.

You always get an initial change notification. This is meant to initialize the user's state to the current value of the property.

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.

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 changed. 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 the change notifications triggered by your own change.

Only the mpv_handle on which this was called will receive the property change events, or can unobserve them.

Safe to be called from mpv render API threads.

@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 from the change events. @return error code (usually fails only on OOM or unsupported format)