jackaudio
/
jack1
mirror of https://github.com/jackaudio/jack1
1
0
Fork 0
Code Releases 19 Activity
Browse Source

reorganize jack/jack.h to group related functions; add @defgroup to several headers files; update main ref doc page and use groups to provide an alternate way of exploring the API 

git-svn-id: svn+ssh://jackaudio.org/trunk/jack@3110 0c269be4-1314-0410-8aa9-9f06e86f4224
tags/0.115.6
paul 16 years ago
parent
e34eb55d49
commit
6e832670a0
5 changed files with 230 additions and 135 deletions
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +27
    -9
      doc/mainpage.dox
  2. +183
    -126
      jack/jack.h
  3. +7
    -0
      jack/midiport.h
  4. +7
    -0
      jack/thread.h
  5. +6
    -0
      jack/transport.h

+ 27
- 9
doc/mainpage.dox View File

@@ -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 <http://jackit.sourceforge.net>

@see <http://jackaudio.org>

@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 "<jack/jack.h>" is the main JACK interface.
- @ref statistics.h "<jack/statistics.h>" provides interfaces for
@@ -100,7 +116,7 @@ The JACK programming interfaces are described in several header files:
- @ref midiport.h "<jack/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


+ 183
- 126
jack/jack.h View File

@@ -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);

/**
* <b>THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN
* NEW JACK CLIENTS</b>
@@ -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
}


+ 7
- 0
jack/midiport.h View File

@@ -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
}


+ 7
- 0
jack/thread.h View File

@@ -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


+ 6
- 0
jack/transport.h View File

@@ -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


Write Preview
Loading…
Cancel
Save