From e1c2f7cf8fe27c03b9323ca54b69f1e89c79c2bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Blizi=C5=84ski?= Date: Wed, 7 Oct 2020 18:55:31 +0100 Subject: [PATCH] Clarification about jack_port_get_latency_range(). jack_port_get_latency_range only returns meaningful values after ports get connected, and that is signalled via the latency callback. Saying that it's normally used in callbacks is too soft, the docs should make it clear that the function is not very useful outside of the callback, because you don't know whether the port is connected / whether the latency values changed. --- common/jack/jack.h | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/common/jack/jack.h b/common/jack/jack.h index e982b6df..cd7e2e95 100644 --- a/common/jack/jack.h +++ b/common/jack/jack.h @@ -605,6 +605,10 @@ int jack_set_xrun_callback (jack_client_t *client, * Clients that do not meet any of those conditions SHOULD * register a latency callback. * + * Another case is when a client wants to use + * @ref jack_port_get_latency_range(), which only returns meaninful + * values when ports get connected and latency values change. + * * See the documentation for @ref jack_port_set_latency_range() * on how the callback should operate. Remember that the @a mode * argument given to the latency callback will need to be @@ -1119,8 +1123,11 @@ void jack_port_set_latency (jack_port_t *port, jack_nframes_t) JACK_OPTIONAL_WEA * * See @ref LatencyFunctions for the definition of each latency value. * - * This is normally used in the LatencyCallback. - * and therefor safe to execute from callbacks. + * This function is best used from callbacks, specifically the latency callback. + * Before a port is connected, this returns the default latency: zero. + * Therefore it only makes sense to call jack_port_get_latency_range() when + * the port is connected, and that gets signalled by the latency callback. + * See @ref jack_set_latency_callback() for details. */ void jack_port_get_latency_range (jack_port_t *port, jack_latency_callback_mode_t mode, jack_latency_range_t *range) JACK_WEAK_EXPORT;