diff --git a/doc/mainpage.dox b/doc/mainpage.dox index fce92d6..e3f009d 100644 --- a/doc/mainpage.dox +++ b/doc/mainpage.dox @@ -8,18 +8,18 @@ @section intro Introduction -JACK is a low-latency audio server, written for POSIX conformant -operating systems such as GNU/Linux and Apple's OS X. It can connect -several client applications to an audio device, and allow them to -share audio with each other. Clients can run as separate processes -like normal applications, or within the JACK server as "plugins". +JACK is a low-latency audio server, written for any operating system +that is reasonably POSIX compliant. It currently exists for Linux, OS +X, Solaris, FreeBSD and Windows. It can connect several client +applications to an audio device, and allow them to share audio with +each other. Clients can run as separate processes like normal +applications, or within the JACK server as "plugins". JACK was designed from the ground up for professional audio work, and its design focuses on two key areas: synchronous execution of all clients, and low latency operation. -@see - +@see @section jack_overview JACK Overview @@ -80,7 +80,23 @@ internal client "plugin" that runs within the JACK server process. @section reference Reference -The JACK programming interfaces are described in several header files: +The JACK programming interfaces are described in several header files. +We present them here broken into useful categories to make the API a +little clearer: + + - @ref ClientFunctions + - @ref ClientCallbacks + - @ref ClientThreads + - @ref ServerControl + - @ref PortFunctions + - @ref PortSearching + - @ref TimeFunctions + - @ref TransportControl + - @ref ErrorOutput + - @ref NonCallbackAPI + - @ref MIDIAPI + +The full API is described in: - @ref jack.h "" is the main JACK interface. - @ref statistics.h "" provides interfaces for @@ -100,7 +116,7 @@ The JACK programming interfaces are described in several header files: - @ref midiport.h "" functions to handle reading and writing of MIDI data to a port -In addition, the example-clients directory provides numerous examples +In addition, the tools directory provides numerous examples of simple JACK clients that nevertheless use the API to do something useful. It includes @@ -112,6 +128,8 @@ useful. It includes - commands to load and unload JACK internal clients. - tools for checking the status of a running JACK system. +and many more. + @section porting Porting JACK is designed to be portable to any system supporting the relevant diff --git a/jack/jack.h b/jack/jack.h index 770da94..ff940cd 100644 --- a/jack/jack.h +++ b/jack/jack.h @@ -34,6 +34,11 @@ extern "C" { * Note: More documentation can be found in jack/types.h. */ +/** + * @defgroup ClientFunctions Creating & manipulating clients + * @{ + */ + /** * Open an external client session with a JACK server. This interface * is more complex but more powerful than jack_client_new(). With it, @@ -132,53 +137,44 @@ int jack_internal_client_new (const char *client_name, void jack_internal_client_close (const char *client_name); /** - * @param client pointer to JACK client structure. + * Tell the Jack server that the program is ready to start processing + * audio. * - * Check if the JACK subsystem is running with -R (--realtime). + * @return 0 on success, otherwise a non-zero error code + */ +int jack_activate (jack_client_t *client); + +/** + * Tell the Jack server to remove this @a client from the process + * graph. Also, disconnect all ports belonging to it, since inactive + * clients have no port connections. * - * @return 1 if JACK is running realtime, 0 otherwise + * @return 0 on success, otherwise a non-zero error code */ -int jack_is_realtime (jack_client_t *client); +int jack_deactivate (jack_client_t *client); -/** +/** + * @return the pthread ID of the thread running the JACK client side + * code. + */ +pthread_t jack_client_thread_id (jack_client_t *); + +/*@}*/ + +/** * @param client pointer to JACK client structure. - * @param function The jack_shutdown function pointer. - * @param arg The arguments for the jack_shutdown function. * - * Register a function (and argument) to be called if and when the - * JACK server shuts down the client thread. The function must - * be written as if it were an asynchonrous POSIX signal - * handler --- use only async-safe functions, and remember that it - * is executed from another thread. A typical function might - * set a flag or write to a pipe so that the rest of the - * application knows that the JACK client thread has shut - * down. + * Check if the JACK subsystem is running with -R (--realtime). * - * NOTE: clients do not need to call this. It exists only - * to help more complex clients understand what is going - * on. It should be called before jack_client_activate(). + * @return 1 if JACK is running realtime, 0 otherwise */ -void jack_on_shutdown (jack_client_t *client, - void (*function)(void *arg), void *arg); +int jack_is_realtime (jack_client_t *client); /** - * Tell the Jack server to call @a process_callback whenever there is - * work be done, passing @a arg as the second argument. - * - * The code in the supplied function must be suitable for real-time - * execution. That means that it cannot call functions that might - * block for a long time. This includes malloc, free, printf, - * pthread_mutex_lock, sleep, wait, poll, select, pthread_join, - * pthread_cond_wait, etc, etc. See - * http://jackit.sourceforge.net/docs/design/design.html#SECTION00411000000000000000 - * for more information. - * - * @return 0 on success, otherwise a non-zero error code, causing JACK - * to remove that client from the process() graph. + * @defgroup NonCallbackAPI The non-callback API + * @{ */ -int jack_set_process_callback (jack_client_t *client, - JackProcessCallback process_callback, - void *arg); + /** * THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN * NEW JACK CLIENTS @@ -220,6 +216,13 @@ void jack_cycle_signal (jack_client_t* client, int status); */ int jack_set_process_thread(jack_client_t* client, JackThreadCallback fun, void *arg); +/*@}*/ + +/** + * @defgroup ClientCallbacks Setting Client Callbacks + * @{ + */ + /** * Tell JACK to call @a thread_init_callback once just after * the creation of the thread in which all other callbacks @@ -235,6 +238,46 @@ int jack_set_thread_init_callback (jack_client_t *client, JackThreadInitCallback thread_init_callback, void *arg); +/** + * @param client pointer to JACK client structure. + * @param function The jack_shutdown function pointer. + * @param arg The arguments for the jack_shutdown function. + * + * Register a function (and argument) to be called if and when the + * JACK server shuts down the client thread. The function must + * be written as if it were an asynchonrous POSIX signal + * handler --- use only async-safe functions, and remember that it + * is executed from another thread. A typical function might + * set a flag or write to a pipe so that the rest of the + * application knows that the JACK client thread has shut + * down. + * + * NOTE: clients do not need to call this. It exists only + * to help more complex clients understand what is going + * on. It should be called before jack_client_activate(). + */ +void jack_on_shutdown (jack_client_t *client, + void (*function)(void *arg), void *arg); + +/** + * Tell the Jack server to call @a process_callback whenever there is + * work be done, passing @a arg as the second argument. + * + * The code in the supplied function must be suitable for real-time + * execution. That means that it cannot call functions that might + * block for a long time. This includes malloc, free, printf, + * pthread_mutex_lock, sleep, wait, poll, select, pthread_join, + * pthread_cond_wait, etc, etc. See + * http://jackit.sourceforge.net/docs/design/design.html#SECTION00411000000000000000 + * for more information. + * + * @return 0 on success, otherwise a non-zero error code, causing JACK + * to remove that client from the process() graph. + */ +int jack_set_process_callback (jack_client_t *client, + JackProcessCallback process_callback, + void *arg); + /** * Tell the Jack server to call @a freewheel_callback * whenever we enter or leave "freewheel" mode, passing @a @@ -248,49 +291,6 @@ int jack_set_freewheel_callback (jack_client_t *client, JackFreewheelCallback freewheel_callback, void *arg); -/** - * Start/Stop JACK's "freewheel" mode. - * - * When in "freewheel" mode, JACK no longer waits for - * any external event to begin the start of the next process - * cycle. - * - * As a result, freewheel mode causes "faster than realtime" - * execution of a JACK graph. If possessed, real-time - * scheduling is dropped when entering freewheel mode, and - * if appropriate it is reacquired when stopping. - * - * IMPORTANT: on systems using capabilities to provide real-time - * scheduling (i.e. Linux kernel 2.4), if onoff is zero, this function - * must be called from the thread that originally called jack_activate(). - * This restriction does not apply to other systems (e.g. Linux kernel 2.6 - * or OS X). - * - * @param client pointer to JACK client structure - * @param onoff if non-zero, freewheel mode starts. Otherwise - * freewheel mode ends. - * - * @return 0 on success, otherwise a non-zero error code. - */ -int jack_set_freewheel(jack_client_t* client, int onoff); - -/** - * Change the buffer size passed to the @a process_callback. - * - * This operation stops the JACK engine process cycle, then calls all - * registered @a bufsize_callback functions before restarting the - * process cycle. This will cause a gap in the audio flow, so it - * should only be done at appropriate stopping points. - * - * @see jack_set_buffer_size_callback() - * - * @param client pointer to JACK client structure. - * @param nframes new buffer size. Must be a power of two. - * - * @return 0 on success, otherwise a non-zero error code - */ -int jack_set_buffer_size (jack_client_t *client, jack_nframes_t nframes); - /** * Tell JACK to call @a bufsize_callback whenever the size of the the * buffer that will be passed to the @a process_callback is about to @@ -365,22 +365,100 @@ int jack_set_graph_order_callback (jack_client_t *, int jack_set_xrun_callback (jack_client_t *, JackXRunCallback xrun_callback, void *arg); +/*@}*/ + /** - * Tell the Jack server that the program is ready to start processing - * audio. + * @defgroup ServerControl Controlling & querying JACK server operation + * @{ + */ + +/** + * Start/Stop JACK's "freewheel" mode. * - * @return 0 on success, otherwise a non-zero error code + * When in "freewheel" mode, JACK no longer waits for + * any external event to begin the start of the next process + * cycle. + * + * As a result, freewheel mode causes "faster than realtime" + * execution of a JACK graph. If possessed, real-time + * scheduling is dropped when entering freewheel mode, and + * if appropriate it is reacquired when stopping. + * + * IMPORTANT: on systems using capabilities to provide real-time + * scheduling (i.e. Linux kernel 2.4), if onoff is zero, this function + * must be called from the thread that originally called jack_activate(). + * This restriction does not apply to other systems (e.g. Linux kernel 2.6 + * or OS X). + * + * @param client pointer to JACK client structure + * @param onoff if non-zero, freewheel mode starts. Otherwise + * freewheel mode ends. + * + * @return 0 on success, otherwise a non-zero error code. */ -int jack_activate (jack_client_t *client); +int jack_set_freewheel(jack_client_t* client, int onoff); /** - * Tell the Jack server to remove this @a client from the process - * graph. Also, disconnect all ports belonging to it, since inactive - * clients have no port connections. + * Change the buffer size passed to the @a process_callback. + * + * This operation stops the JACK engine process cycle, then calls all + * registered @a bufsize_callback functions before restarting the + * process cycle. This will cause a gap in the audio flow, so it + * should only be done at appropriate stopping points. + * + * @see jack_set_buffer_size_callback() + * + * @param client pointer to JACK client structure. + * @param nframes new buffer size. Must be a power of two. * * @return 0 on success, otherwise a non-zero error code */ -int jack_deactivate (jack_client_t *client); +int jack_set_buffer_size (jack_client_t *client, jack_nframes_t nframes); + +/** + * @return the sample rate of the jack system, as set by the user when + * jackd was started. + */ +jack_nframes_t jack_get_sample_rate (jack_client_t *); + +/** + * @return the current maximum size that will ever be passed to the @a + * process_callback. It should only be used *before* the client has + * been activated. This size may change, clients that depend on it + * must register a @a bufsize_callback so they will be notified if it + * does. + * + * @see jack_set_buffer_size_callback() + */ +jack_nframes_t jack_get_buffer_size (jack_client_t *); + +/** + * Old-style interface to become the timebase for the entire JACK + * subsystem. + * + * @deprecated This function still exists for compatibility with the + * earlier transport interface, but it does nothing. Instead, see + * transport.h and use jack_set_timebase_callback(). + * + * @return ENOSYS, function not implemented. + */ +int jack_engine_takeover_timebase (jack_client_t *); + +/** + * @return the current CPU load estimated by JACK. This is a running + * average of the time it takes to execute a full process cycle for + * all clients as a percentage of the real time available per cycle + * determined by the buffer size and sample rate. + */ +float jack_cpu_load (jack_client_t *client); + + +/*@}*/ + +/** + * @defgroup PortFunctions Creating & manipulating ports + * @{ + */ /** * Create a new port for the client. This is an object used for moving @@ -588,10 +666,10 @@ void jack_port_set_latency (jack_port_t *, jack_nframes_t); /** * Request a complete recomputation of a port's total latency. This * can be called by a client that has just changed the internal - * latency of its port using jack_port_set_latency() + * latency of its port using jack_port_set_latency * and wants to ensure that all signal pathways in the graph * are updated with respect to the values that will be returned - * by jack_port_get_total_latency(). + * by jack_port_get_total_latency. * * @return zero for successful execution of the request. non-zero * otherwise. @@ -601,10 +679,10 @@ int jack_recompute_total_latency (jack_client_t*, jack_port_t* port); /** * Request a complete recomputation of all port latencies. This * can be called by a client that has just changed the internal - * latency of its port using jack_port_set_latency() + * latency of its port using jack_port_set_latency * and wants to ensure that all signal pathways in the graph * are updated with respect to the values that will be returned - * by jack_port_get_total_latency(). It allows a client + * by jack_port_get_total_latency. It allows a client * to change multiple port latencies without triggering a * recompute for each change. * @@ -627,7 +705,7 @@ int jack_port_set_name (jack_port_t *port, const char *port_name); * If the alias is longer than jack_port_name_size(), it will be truncated. * * After a successful call, and until JACK exits or - * jack_port_unset_alias() is called, @a alias may be + * jack_port_unset_alias() is called, may be * used as a alternate name for the port. * * Ports can have up to two aliases - if both are already @@ -749,23 +827,12 @@ int jack_port_name_size(void); * including the final NULL character. This value is a constant. */ int jack_port_type_size(void); +/*@}*/ /** - * @return the sample rate of the jack system, as set by the user when - * jackd was started. - */ -jack_nframes_t jack_get_sample_rate (jack_client_t *); - -/** - * @return the current maximum size that will ever be passed to the @a - * process_callback. It should only be used *before* the client has - * been activated. This size may change, clients that depend on it - * must register a @a bufsize_callback so they will be notified if it - * does. - * - * @see jack_set_buffer_size_callback() + * @defgroup PortSearching Looking up ports + * @{ */ -jack_nframes_t jack_get_buffer_size (jack_client_t *); /** * @param port_name_pattern A regular expression used to select @@ -801,17 +868,13 @@ jack_port_t *jack_port_by_name (jack_client_t *, const char *port_name); jack_port_t *jack_port_by_id (jack_client_t *client, jack_port_id_t port_id); +/*@}*/ + + /** - * Old-style interface to become the timebase for the entire JACK - * subsystem. - * - * @deprecated This function still exists for compatibility with the - * earlier transport interface, but it does nothing. Instead, see - * transport.h and use jack_set_timebase_callback(). - * - * @return ENOSYS, function not implemented. + * @defgroup TimeFunctions Handling time + * @{ */ -int jack_engine_takeover_timebase (jack_client_t *); /** * @return the time in frames that has passed since the JACK server @@ -855,19 +918,12 @@ jack_nframes_t jack_time_to_frames(const jack_client_t *client, jack_time_t); */ jack_time_t jack_get_time(); +/*@}*/ + /** - * @return the current CPU load estimated by JACK. This is a running - * average of the time it takes to execute a full process cycle for - * all clients as a percentage of the real time available per cycle - * determined by the buffer size and sample rate. - */ -float jack_cpu_load (jack_client_t *client); - -/** - * @return the pthread ID of the thread running the JACK client side - * code. + * @defgroup ErrorOutput Controlling error/information output */ -pthread_t jack_client_thread_id (jack_client_t *); +/*@{*/ /** * Display JACK error message. @@ -901,6 +957,7 @@ extern void (*jack_info_callback)(const char *msg); * Set the @ref jack_info_callback for info message display. */ void jack_set_info_function (void (*func)(const char *)); +/*@}*/ #ifdef __cplusplus } diff --git a/jack/midiport.h b/jack/midiport.h index da574f8..69f1afb 100644 --- a/jack/midiport.h +++ b/jack/midiport.h @@ -42,6 +42,11 @@ typedef struct _jack_midi_event } jack_midi_event_t; +/** + * @defgroup MIDIAPI Reading and writing MIDI data + * @{ + */ + /* Get number of events in a port buffer. * * @param port_buffer Port buffer from which to retrieve event. @@ -142,6 +147,8 @@ jack_midi_event_write(void *port_buffer, jack_nframes_t jack_midi_get_lost_event_count(void *port_buffer); +/*@}*/ + #ifdef __cplusplus } diff --git a/jack/thread.h b/jack/thread.h index 26e5065..4c80b89 100644 --- a/jack/thread.h +++ b/jack/thread.h @@ -37,6 +37,11 @@ extern "C" { * handling of realtime scheduling and associated privileges. */ +/** + * @defgroup ClientThreads Creating and managing client threads + * @{ + */ + /** * @returns if JACK is running with realtime scheduling, this returns * the priority that any JACK-created client threads will run at. @@ -97,6 +102,8 @@ int jack_client_create_thread (jack_client_t* client, */ int jack_drop_real_time_scheduling (pthread_t thread); +/* @} */ + #ifdef __cplusplus } #endif diff --git a/jack/transport.h b/jack/transport.h index de9a9cd..69e70e2 100644 --- a/jack/transport.h +++ b/jack/transport.h @@ -145,6 +145,11 @@ typedef struct { } POST_PACKED_STRUCTURE jack_position_t; +/** + * @defgroup TransportControl Transport and Timebase control + * @{ + */ + /** * Called by the timebase master to release itself from that * responsibility. @@ -385,6 +390,7 @@ void jack_transport_start (jack_client_t *client); */ void jack_transport_stop (jack_client_t *client); +/*@}*/ /********************************************************************* * The following interfaces are DEPRECATED. They are only provided