2 Copyright (C) 2001 Paul Davis
3 Copyright (C) 2004 Jack O'Quin
5 This program is free software; you can redistribute it and/or modify
6 it under the terms of the GNU Lesser General Public License as published by
7 the Free Software Foundation; either version 2.1 of the License, or
8 (at your option) any later version.
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU Lesser General Public License for more details.
15 You should have received a copy of the GNU Lesser General Public License
16 along with this program; if not, write to the Free Software
17 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
30 #include <jack/types.h>
31 #include <jack/transport.h>
34 * Note: More documentation can be found in jack/types.h.
38 * Open an external client session with a JACK server. This interface
39 * is more complex but more powerful than jack_client_new(). With it,
40 * clients may choose which of several servers to connect, and control
41 * whether and how to start the server automatically, if it was not
42 * already running. There is also an option for JACK to generate a
43 * unique client name, when necessary.
45 * @param client_name of at most jack_client_name_size() characters.
46 * The name scope is local to each server. Unless forbidden by the
47 * @ref JackUseExactName option, the server will modify this name to
48 * create a unique variant, if needed.
50 * @param options formed by OR-ing together @ref JackOptions bits.
51 * Only the @ref JackOpenOptions bits are allowed.
53 * @param status (if non-NULL) an address for JACK to return
54 * information from the open operation. This status word is formed by
55 * OR-ing together the relevant @ref JackStatus bits.
58 * <b>Optional parameters:</b> depending on corresponding [@a options
59 * bits] additional parameters may follow @a status (in this order).
61 * @arg [@ref JackServerName] <em>(char *) server_name</em> selects
62 * from among several possible concurrent server instances. Server
63 * names are unique to each user. If unspecified, use "default"
64 * unless \$JACK_DEFAULT_SERVER is defined in the process environment.
66 * @return Opaque client handle if successful. If this is NULL, the
67 * open operation failed, @a *status includes @ref JackFailure and the
68 * caller is not a JACK client.
70 jack_client_t
*jack_client_open (const char *client_name
,
71 jack_options_t options
,
72 jack_status_t
*status
, ...);
75 * <b>THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN
76 * NEW JACK CLIENTS</b>
79 jack_client_t
*jack_client_new (const char *client_name
);
82 * Disconnects an external client from a JACK server.
84 * @return 0 on success, otherwise a non-zero error code
86 int jack_client_close (jack_client_t
*client
);
89 * @return the maximum number of characters in a JACK client name
90 * including the final NULL character. This value is a constant.
92 int jack_client_name_size (void);
95 * @return pointer to actual client name. This is useful when @ref
96 * JackUseExactName is not specified on open and @ref
97 * JackNameNotUnique status was returned. In that case, the actual
98 * name will differ from the @a client_name requested.
100 char *jack_get_client_name (jack_client_t
*client
);
103 * Load an internal client into the Jack server.
105 * Internal clients run inside the JACK server process. They can use
106 * most of the same functions as external clients. Each internal
107 * client must declare jack_initialize() and jack_finish() entry
108 * points, called at load and unload times. See inprocess.c for an
109 * example of how to write an internal client.
111 * @deprecated Please use jack_internal_client_load().
113 * @param client_name of at most jack_client_name_size() characters.
115 * @param load_name of a shared object file containing the code for
118 * @param load_init an arbitary string passed to the jack_initialize()
119 * routine of the new client (may be NULL).
121 * @return 0 if successful.
123 int jack_internal_client_new (const char *client_name
,
124 const char *load_name
,
125 const char *load_init
);
128 * Remove an internal client from a JACK server.
130 * @deprecated Please use jack_internal_client_load().
132 void jack_internal_client_close (const char *client_name
);
135 * @param client pointer to JACK client structure.
137 * Check if the JACK subsystem is running with -R (--realtime).
139 * @return 1 if JACK is running realtime, 0 otherwise
141 int jack_is_realtime (jack_client_t
*client
);
144 * @param client pointer to JACK client structure.
145 * @param function The jack_shutdown function pointer.
146 * @param arg The arguments for the jack_shutdown function.
148 * Register a function (and argument) to be called if and when the
149 * JACK server shuts down the client thread. The function must
150 * be written as if it were an asynchonrous POSIX signal
151 * handler --- use only async-safe functions, and remember that it
152 * is executed from another thread. A typical function might
153 * set a flag or write to a pipe so that the rest of the
154 * application knows that the JACK client thread has shut
157 * NOTE: clients do not need to call this. It exists only
158 * to help more complex clients understand what is going
159 * on. It should be called before jack_client_activate().
161 void jack_on_shutdown (jack_client_t
*client
,
162 void (*function
)(void *arg
), void *arg
);
165 * Tell the Jack server to call @a process_callback whenever there is
166 * work be done, passing @a arg as the second argument.
168 * The code in the supplied function must be suitable for real-time
169 * execution. That means that it cannot call functions that might
170 * block for a long time. This includes malloc, free, printf,
171 * pthread_mutex_lock, sleep, wait, poll, select, pthread_join,
172 * pthread_cond_wait, etc, etc. See
173 * http://jackit.sourceforge.net/docs/design/design.html#SECTION00411000000000000000
174 * for more information.
176 * @return 0 on success, otherwise a non-zero error code, causing JACK
177 * to remove that client from the process() graph.
179 int jack_set_process_callback (jack_client_t
*client
,
180 JackProcessCallback process_callback
,
183 * <b>THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN
184 * NEW JACK CLIENTS</b>
186 * It should be replace by use of @ jack_cycle_wait and @ jack_cycle_signal functions.
189 jack_nframes_t
jack_thread_wait (jack_client_t
*, int status
);
192 * Wait until this JACK client should process data.
194 * @param client - pointer to a JACK client structure
196 * @return the number of frames of data to process
198 jack_nframes_t
jack_cycle_wait (jack_client_t
* client
);
201 * Signal next clients in the graph.
203 * @param client - pointer to a JACK client structure
204 * @param status - if non-zero, calling thread should exit
206 void jack_cycle_signal (jack_client_t
* client
, int status
);
209 * Tell the Jack server to call @a thread_callback in the RT thread.
210 * Typical use are in conjunction with @a jack_cycle_wait and @ jack_cycle_signal functions.
211 * The code in the supplied function must be suitable for real-time
212 * execution. That means that it cannot call functions that might
213 * block for a long time. This includes malloc, free, printf,
214 * pthread_mutex_lock, sleep, wait, poll, select, pthread_join,
215 * pthread_cond_wait, etc, etc. See
216 * http://jackit.sourceforge.net/docs/design/design.html#SECTION00411000000000000000
217 * for more information.
219 * @return 0 on success, otherwise a non-zero error code.
221 int jack_set_process_thread(jack_client_t
* client
, JackThreadCallback fun
, void *arg
);
224 * Tell JACK to call @a thread_init_callback once just after
225 * the creation of the thread in which all other callbacks
228 * The code in the supplied function does not need to be
229 * suitable for real-time execution.
231 * @return 0 on success, otherwise a non-zero error code, causing JACK
232 * to remove that client from the process() graph.
234 int jack_set_thread_init_callback (jack_client_t
*client
,
235 JackThreadInitCallback thread_init_callback
,
239 * Tell the Jack server to call @a freewheel_callback
240 * whenever we enter or leave "freewheel" mode, passing @a
241 * arg as the second argument. The first argument to the
242 * callback will be non-zero if JACK is entering freewheel
243 * mode, and zero otherwise.
245 * @return 0 on success, otherwise a non-zero error code.
247 int jack_set_freewheel_callback (jack_client_t
*client
,
248 JackFreewheelCallback freewheel_callback
,
252 * Start/Stop JACK's "freewheel" mode.
254 * When in "freewheel" mode, JACK no longer waits for
255 * any external event to begin the start of the next process
258 * As a result, freewheel mode causes "faster than realtime"
259 * execution of a JACK graph. If possessed, real-time
260 * scheduling is dropped when entering freewheel mode, and
261 * if appropriate it is reacquired when stopping.
263 * IMPORTANT: on systems using capabilities to provide real-time
264 * scheduling (i.e. Linux kernel 2.4), if onoff is zero, this function
265 * must be called from the thread that originally called jack_activate().
266 * This restriction does not apply to other systems (e.g. Linux kernel 2.6
269 * @param client pointer to JACK client structure
270 * @param onoff if non-zero, freewheel mode starts. Otherwise
271 * freewheel mode ends.
273 * @return 0 on success, otherwise a non-zero error code.
275 int jack_set_freewheel(jack_client_t
* client
, int onoff
);
278 * Change the buffer size passed to the @a process_callback.
280 * This operation stops the JACK engine process cycle, then calls all
281 * registered @a bufsize_callback functions before restarting the
282 * process cycle. This will cause a gap in the audio flow, so it
283 * should only be done at appropriate stopping points.
285 * @see jack_set_buffer_size_callback()
287 * @param client pointer to JACK client structure.
288 * @param nframes new buffer size. Must be a power of two.
290 * @return 0 on success, otherwise a non-zero error code
292 int jack_set_buffer_size (jack_client_t
*client
, jack_nframes_t nframes
);
295 * Tell JACK to call @a bufsize_callback whenever the size of the the
296 * buffer that will be passed to the @a process_callback is about to
297 * change. Clients that depend on knowing the buffer size must supply
298 * a @a bufsize_callback before activating themselves.
300 * @param client pointer to JACK client structure.
301 * @param bufsize_callback function to call when the buffer size changes.
302 * @param arg argument for @a bufsize_callback.
304 * @return 0 on success, otherwise a non-zero error code
306 int jack_set_buffer_size_callback (jack_client_t
*client
,
307 JackBufferSizeCallback bufsize_callback
,
311 * Tell the Jack server to call @a srate_callback whenever the system
312 * sample rate changes.
314 * @return 0 on success, otherwise a non-zero error code
316 int jack_set_sample_rate_callback (jack_client_t
*client
,
317 JackSampleRateCallback srate_callback
,
321 * Tell the JACK server to call @a registration_callback whenever a
322 * port is registered or unregistered, passing @a arg as a parameter.
324 * @return 0 on success, otherwise a non-zero error code
326 int jack_set_client_registration_callback (jack_client_t
*,
327 JackClientRegistrationCallback
328 registration_callback
, void *arg
);
331 * Tell the JACK server to call @a registration_callback whenever a
332 * port is registered or unregistered, passing @a arg as a parameter.
334 * @return 0 on success, otherwise a non-zero error code
336 int jack_set_port_registration_callback (jack_client_t
*,
337 JackPortRegistrationCallback
338 registration_callback
, void *arg
);
341 * Tell the JACK server to call @a connect_callback whenever a
342 * port is connected or disconnected, passing @a arg as a parameter.
344 * @return 0 on success, otherwise a non-zero error code
346 int jack_set_port_connect_callback (jack_client_t
*,
347 JackPortConnectCallback
348 connect_callback
, void *arg
);
350 * Tell the JACK server to call @a graph_callback whenever the
351 * processing graph is reordered, passing @a arg as a parameter.
353 * @return 0 on success, otherwise a non-zero error code
355 int jack_set_graph_order_callback (jack_client_t
*,
356 JackGraphOrderCallback graph_callback
,
360 * Tell the JACK server to call @a xrun_callback whenever there is a
361 * xrun, passing @a arg as a parameter.
363 * @return 0 on success, otherwise a non-zero error code
365 int jack_set_xrun_callback (jack_client_t
*,
366 JackXRunCallback xrun_callback
, void *arg
);
369 * Tell the Jack server that the program is ready to start processing
372 * @return 0 on success, otherwise a non-zero error code
374 int jack_activate (jack_client_t
*client
);
377 * Tell the Jack server to remove this @a client from the process
378 * graph. Also, disconnect all ports belonging to it, since inactive
379 * clients have no port connections.
381 * @return 0 on success, otherwise a non-zero error code
383 int jack_deactivate (jack_client_t
*client
);
386 * Create a new port for the client. This is an object used for moving
387 * data of any type in or out of the client. Ports may be connected
390 * Each port has a short name. The port's full name contains the name
391 * of the client concatenated with a colon (:) followed by its short
392 * name. The jack_port_name_size() is the maximum length of this full
393 * name. Exceeding that will cause the port registration to fail and
396 * All ports have a type, which may be any non-NULL and non-zero
397 * length string, passed as an argument. Some port types are built
398 * into the JACK API, like JACK_DEFAULT_AUDIO_TYPE or JACK_DEFAULT_MIDI_TYPE
400 * @param client pointer to JACK client structure.
401 * @param port_name non-empty short name for the new port (not
402 * including the leading @a "client_name:").
403 * @param port_type port type name. If longer than
404 * jack_port_type_size(), only that many characters are significant.
405 * @param flags @ref JackPortFlags bit mask.
406 * @param buffer_size must be non-zero if this is not a built-in @a
407 * port_type. Otherwise, it is ignored.
409 * @return jack_port_t pointer on success, otherwise NULL.
411 jack_port_t
*jack_port_register (jack_client_t
*client
,
412 const char *port_name
,
413 const char *port_type
,
415 unsigned long buffer_size
);
418 * Remove the port from the client, disconnecting any existing
421 * @return 0 on success, otherwise a non-zero error code
423 int jack_port_unregister (jack_client_t
*, jack_port_t
*);
426 * This returns a pointer to the memory area associated with the
427 * specified port. For an output port, it will be a memory area
428 * that can be written to; for an input port, it will be an area
429 * containing the data from the port's connection(s), or
430 * zero-filled. if there are multiple inbound connections, the data
431 * will be mixed appropriately.
433 * FOR OUTPUT PORTS ONLY : WILL BE DEPRECATED in Jack 2.0 !!
434 * ---------------------------------------------------------
435 * You may cache the value returned, but only between calls to
436 * your "blocksize" callback. For this reason alone, you should
437 * either never cache the return value or ensure you have
438 * a "blocksize" callback and be sure to invalidate the cached
439 * address from there.
441 * Caching output ports is DEPRECATED in Jack 2.0, due to some new optimization (like "pipelining").
442 * Port buffers have to be retrieved in each callback for proper functionning.
444 void *jack_port_get_buffer (jack_port_t
*, jack_nframes_t
);
447 * @return the full name of the jack_port_t (including the @a
448 * "client_name:" prefix).
450 * @see jack_port_name_size().
452 const char *jack_port_name (const jack_port_t
*port
);
455 * @return the short name of the jack_port_t (not including the @a
456 * "client_name:" prefix).
458 * @see jack_port_name_size().
460 const char *jack_port_short_name (const jack_port_t
*port
);
463 * @return the @ref JackPortFlags of the jack_port_t.
465 int jack_port_flags (const jack_port_t
*port
);
468 * @return the @a port type, at most jack_port_type_size() characters
469 * including a final NULL.
471 const char *jack_port_type (const jack_port_t
*port
);
474 * @return TRUE if the jack_port_t belongs to the jack_client_t.
476 int jack_port_is_mine (const jack_client_t
*, const jack_port_t
*port
);
479 * @return number of connections to or from @a port.
481 * @pre The calling client must own @a port.
483 int jack_port_connected (const jack_port_t
*port
);
486 * @return TRUE if the locally-owned @a port is @b directly connected
487 * to the @a port_name.
489 * @see jack_port_name_size()
491 int jack_port_connected_to (const jack_port_t
*port
,
492 const char *port_name
);
495 * @return a null-terminated array of full port names to which the @a
496 * port is connected. If none, returns NULL.
498 * The caller is responsible for calling free(3) on any non-NULL
501 * @param port locally owned jack_port_t pointer.
503 * @see jack_port_name_size(), jack_port_get_all_connections()
505 const char **jack_port_get_connections (const jack_port_t
*port
);
508 * @return a null-terminated array of full port names to which the @a
509 * port is connected. If none, returns NULL.
511 * The caller is responsible for calling free(3) on any non-NULL
514 * This differs from jack_port_get_connections() in two important
517 * 1) You may not call this function from code that is
518 * executed in response to a JACK event. For example,
519 * you cannot use it in a GraphReordered handler.
521 * 2) You need not be the owner of the port to get information
522 * about its connections.
524 * @see jack_port_name_size()
526 const char **jack_port_get_all_connections (const jack_client_t
*client
,
527 const jack_port_t
*port
);
530 * A client may call this on a pair of its own ports to
531 * semi-permanently wire them together. This means that
532 * a client that wants to direct-wire an input port to
533 * an output port can call this and then no longer
534 * have to worry about moving data between them. Any data
535 * arriving at the input port will appear automatically
536 * at the output port.
538 * The 'destination' port must be an output port. The 'source'
539 * port must be an input port. Both ports must belong to
540 * the same client. You cannot use this to tie ports between
541 * clients. That is what a connection is for.
543 * @return 0 on success, otherwise a non-zero error code
545 int jack_port_tie (jack_port_t
*src
, jack_port_t
*dst
);
548 * This undoes the effect of jack_port_tie(). The port
549 * should be same as the 'destination' port passed to
552 * @return 0 on success, otherwise a non-zero error code
554 int jack_port_untie (jack_port_t
*port
);
557 * @return the time (in frames) between data being available or
558 * delivered at/to a port, and the time at which it arrived at or is
559 * delivered to the "other side" of the port. E.g. for a physical
560 * audio output port, this is the time between writing to the port and
561 * when the signal will leave the connector. For a physical audio
562 * input port, this is the time between the sound arriving at the
563 * connector and the corresponding frames being readable from the
566 jack_nframes_t
jack_port_get_latency (jack_port_t
*port
);
569 * The maximum of the sum of the latencies in every
570 * connection path that can be drawn between the port and other
571 * ports with the @ref JackPortIsTerminal flag set.
573 jack_nframes_t
jack_port_get_total_latency (jack_client_t
*,
577 * The port latency is zero by default. Clients that control
578 * physical hardware with non-zero latency should call this
579 * to set the latency to its correct value. Note that the value
580 * should include any systemic latency present "outside" the
581 * physical hardware controlled by the client. For example,
582 * for a client controlling a digital audio interface connected
583 * to an external digital converter, the latency setting should
584 * include both buffering by the audio interface *and* the converter.
586 void jack_port_set_latency (jack_port_t
*, jack_nframes_t
);
589 * Request a complete recomputation of a port's total latency. This
590 * can be called by a client that has just changed the internal
591 * latency of its port using @function jack_port_set_latency
592 * and wants to ensure that all signal pathways in the graph
593 * are updated with respect to the values that will be returned
594 * by @function jack_port_get_total_latency.
596 * @return zero for successful execution of the request. non-zero
599 int jack_recompute_total_latency (jack_client_t
*, jack_port_t
* port
);
602 * Request a complete recomputation of all port latencies. This
603 * can be called by a client that has just changed the internal
604 * latency of its port using @function jack_port_set_latency
605 * and wants to ensure that all signal pathways in the graph
606 * are updated with respect to the values that will be returned
607 * by @function jack_port_get_total_latency. It allows a client
608 * to change multiple port latencies without triggering a
609 * recompute for each change.
611 * @return zero for successful execution of the request. non-zero
614 int jack_recompute_total_latencies (jack_client_t
*);
617 * Modify a port's short name. May be called at any time. If the
618 * resulting full name (including the @a "client_name:" prefix) is
619 * longer than jack_port_name_size(), it will be truncated.
621 * @return 0 on success, otherwise a non-zero error code.
623 int jack_port_set_name (jack_port_t
*port
, const char *port_name
);
626 * Set @a alias as an alias for @a port. May be called at any time.
627 * If the alias is longer than jack_port_name_size(), it will be truncated.
629 * After a successful call, and until JACK exits or
630 * @function jack_port_unset_alias() is called, @alias may be
631 * used as a alternate name for the port.
633 * Ports can have up to two aliases - if both are already
634 * set, this function will return an error.
636 * @return 0 on success, otherwise a non-zero error code.
638 int jack_port_set_alias (jack_port_t
*port
, const char *alias
);
641 * Remove @a alias as an alias for @a port. May be called at any time.
643 * After a successful call, @a alias can no longer be
644 * used as a alternate name for the port.
646 * @return 0 on success, otherwise a non-zero error code.
648 int jack_port_unset_alias (jack_port_t
*port
, const char *alias
);
651 * Get any aliases known for @port.
653 * @return the number of aliases discovered for the port
655 int jack_port_get_aliases (const jack_port_t
*port
, char* const aliases
[2]);
658 * If @ref JackPortCanMonitor is set for this @a port, turn input
659 * monitoring on or off. Otherwise, do nothing.
661 int jack_port_request_monitor (jack_port_t
*port
, int onoff
);
664 * If @ref JackPortCanMonitor is set for this @a port_name, turn input
665 * monitoring on or off. Otherwise, do nothing.
667 * @return 0 on success, otherwise a non-zero error code.
669 * @see jack_port_name_size()
671 int jack_port_request_monitor_by_name (jack_client_t
*client
,
672 const char *port_name
, int onoff
);
675 * If @ref JackPortCanMonitor is set for a port, this function turns
676 * on input monitoring if it was off, and turns it off if only one
677 * request has been made to turn it on. Otherwise it does nothing.
679 * @return 0 on success, otherwise a non-zero error code
681 int jack_port_ensure_monitor (jack_port_t
*port
, int onoff
);
684 * @return TRUE if input monitoring has been requested for @a port.
686 int jack_port_monitoring_input (jack_port_t
*port
);
689 * Establish a connection between two ports.
691 * When a connection exists, data written to the source port will
692 * be available to be read at the destination port.
694 * @pre The port types must be identical.
696 * @pre The @ref JackPortFlags of the @a source_port must include @ref
699 * @pre The @ref JackPortFlags of the @a destination_port must include
700 * @ref JackPortIsInput.
702 * @return 0 on success, EEXIST if the connection is already made,
703 * otherwise a non-zero error code
705 int jack_connect (jack_client_t
*,
706 const char *source_port
,
707 const char *destination_port
);
710 * Remove a connection between two ports.
712 * @pre The port types must be identical.
714 * @pre The @ref JackPortFlags of the @a source_port must include @ref
717 * @pre The @ref JackPortFlags of the @a destination_port must include
718 * @ref JackPortIsInput.
720 * @return 0 on success, otherwise a non-zero error code
722 int jack_disconnect (jack_client_t
*,
723 const char *source_port
,
724 const char *destination_port
);
727 * Perform the same function as jack_disconnect() using port handles
728 * rather than names. This avoids the name lookup inherent in the
729 * name-based version.
731 * Clients connecting their own ports are likely to use this function,
732 * while generic connection clients (e.g. patchbays) would use
735 int jack_port_disconnect (jack_client_t
*, jack_port_t
*);
738 * @return the maximum number of characters in a full JACK port name
739 * including the final NULL character. This value is a constant.
741 * A port's full name contains the owning client name concatenated
742 * with a colon (:) followed by its short name and a NULL
745 int jack_port_name_size(void);
748 * @return the maximum number of characters in a JACK port type name
749 * including the final NULL character. This value is a constant.
751 int jack_port_type_size(void);
754 * @return the sample rate of the jack system, as set by the user when
757 jack_nframes_t
jack_get_sample_rate (jack_client_t
*);
760 * @return the current maximum size that will ever be passed to the @a
761 * process_callback. It should only be used *before* the client has
762 * been activated. This size may change, clients that depend on it
763 * must register a @a bufsize_callback so they will be notified if it
766 * @see jack_set_buffer_size_callback()
768 jack_nframes_t
jack_get_buffer_size (jack_client_t
*);
771 * @param port_name_pattern A regular expression used to select
772 * ports by name. If NULL or of zero length, no selection based
773 * on name will be carried out.
774 * @param type_name_pattern A regular expression used to select
775 * ports by type. If NULL or of zero length, no selection based
776 * on type will be carried out.
777 * @param flags A value used to select ports by their flags.
778 * If zero, no selection based on flags will be carried out.
780 * @return a NULL-terminated array of ports that match the specified
781 * arguments. The caller is responsible for calling free(3) any
782 * non-NULL returned value.
784 * @see jack_port_name_size(), jack_port_type_size()
786 const char **jack_get_ports (jack_client_t
*,
787 const char *port_name_pattern
,
788 const char *type_name_pattern
,
789 unsigned long flags
);
792 * @return address of the jack_port_t named @a port_name.
794 * @see jack_port_name_size()
796 jack_port_t
*jack_port_by_name (jack_client_t
*, const char *port_name
);
799 * @return address of the jack_port_t of a @a port_id.
801 jack_port_t
*jack_port_by_id (jack_client_t
*client
,
802 jack_port_id_t port_id
);
805 * Old-style interface to become the timebase for the entire JACK
808 * @deprecated This function still exists for compatibility with the
809 * earlier transport interface, but it does nothing. Instead, see
810 * transport.h and use jack_set_timebase_callback().
812 * @return ENOSYS, function not implemented.
814 int jack_engine_takeover_timebase (jack_client_t
*);
817 * @return the time in frames that has passed since the JACK server
818 * began the current process cycle.
820 jack_nframes_t
jack_frames_since_cycle_start (const jack_client_t
*);
823 * @return an estimate of the current time in frames. This is a
824 * running counter, no significance should be attached to its value,
825 * but it can be compared to a previously returned value.
827 jack_nframes_t
jack_frame_time (const jack_client_t
*);
830 * @return the frame_time after the last processing of the graph
831 * this is only to be used from the process callback.
833 * This function can be used to put timestamps generated by
834 * jack_frame_time() in correlation to the current process cycle.
836 jack_nframes_t
jack_last_frame_time (const jack_client_t
*client
);
839 * @return estimated time in microseconds of the specified frame time
841 jack_time_t
jack_frames_to_time(const jack_client_t
*client
, jack_nframes_t
);
844 * @return estimated time in frames for the specified system time.
846 jack_nframes_t
jack_time_to_frames(const jack_client_t
*client
, jack_time_t
);
849 * @return return JACK's current system time in microseconds,
850 * using JACK clock source.
852 * The value returned is guaranteed to be monotonic, but not linear.
854 * This function is a client version of @function jack_get_microseconds().
856 jack_time_t
jack_get_time();
859 * @return the current CPU load estimated by JACK. This is a running
860 * average of the time it takes to execute a full process cycle for
861 * all clients as a percentage of the real time available per cycle
862 * determined by the buffer size and sample rate.
864 float jack_cpu_load (jack_client_t
*client
);
867 * @return the pthread ID of the thread running the JACK client side
870 pthread_t
jack_client_thread_id (jack_client_t
*);
873 * Display JACK error message.
875 * Set via jack_set_error_function(), otherwise a JACK-provided
876 * default will print @a msg (plus a newline) to stderr.
878 * @param msg error message text (no newline at end).
880 extern void (*jack_error_callback
)(const char *msg
);
883 * Set the @ref jack_error_callback for error message display.
885 * The JACK library provides two built-in callbacks for this purpose:
886 * default_jack_error_callback() and silent_jack_error_callback().
888 void jack_set_error_function (void (*func
)(const char *));
891 * Display JACK info message.
893 * Set via jack_set_info_function(), otherwise a JACK-provided
894 * default will print @a msg (plus a newline) to stdout.
896 * @param msg info message text (no newline at end).
898 extern void (*jack_info_callback
)(const char *msg
);
901 * Set the @ref jack_info_callback for info message display.
903 void jack_set_info_function (void (*func
)(const char *));
909 #endif /* __jack_h__ */