Audio Processing Framework (APF)  version 0.3.0
Classes | Public Types | Public Member Functions | List of all members
apf::JackClient Class Reference

C++ wrapper for a JACK client. More...

#include <apf/jackclient.h>

Inheritance diagram for apf::JackClient:
Inheritance graph
[legend]

Classes

struct  jack_error
 exception to be thrown at various occasions. More...
 

Public Types

enum  callback_usage_t { dont_use_jack_process_callback = 0, use_jack_process_callback }
 Select if JACK's audio callback function shall be called. More...
 
typedef jack_default_audio_sample_t sample_t
 
typedef jack_nframes_t nframes_t
 
typedef jack_port_t port_t
 

Public Member Functions

 JackClient (const std::string &name="JackClient", callback_usage_t callback_usage=dont_use_jack_process_callback)
 Constructor. More...
 
bool activate () const
 Activate JACK client. More...
 
bool deactivate () const
 Deactivate JACK client. More...
 
bool set_freewheel (int onoff) const
 Set JACK freewheeling mode. More...
 
std::string client_name () const
 
nframes_t sample_rate () const
 
nframes_t buffer_size () const
 
bool is_realtime () const
 
int get_real_time_priority () const
 
float get_cpu_load () const
 
pthread_t client_thread_id () const
 
manage JACK ports
port_t * register_in_port (const std::string &name) const
 Register JACK input port. More...
 
port_t * register_out_port (const std::string &name) const
 Register JACK output port. More...
 
port_t * register_port (const std::string &name, unsigned long flags) const
 Register JACK port (input or output). More...
 
bool unregister_port (port_t *port) const
 Unregister JACK port. More...
 
bool connect_ports (const std::string &source, const std::string &destination) const
 Connect two JACK ports. More...
 
bool disconnect_ports (const std::string &source, const std::string &destination) const
 Disconnect two JACK ports. More...
 
bool connect_pending_connections () const
 Make connections which are still pending from a previous call to connect_ports(). More...
 
manage JACK transport
void transport_start () const
 Start JACK transport. More...
 
void transport_stop () const
 Stop JACK transport. More...
 
bool transport_locate (nframes_t frame) const
 Set JACK transport location. More...
 
std::pair< bool, nframes_t > get_transport_state () const
 Get JACK transport state. More...
 

Protected Member Functions

callback functions

can be overwritten in derived classes

virtual int jack_process_callback (nframes_t nframes)
 JACK process callback function. More...
 
virtual void jack_shutdown_callback (jack_status_t code, const char *reason)
 JACK shutdown callback. More...
 
virtual int jack_sample_rate_callback (nframes_t sr)
 JACK sample rate callback. More...
 
virtual int jack_buffer_size_callback (nframes_t bs)
 JACK buffer size callback. More...
 
virtual int jack_xrun_callback ()
 JACK xrun callback. More...
 

Detailed Description

C++ wrapper for a JACK client.

Warning
When several JACK clients are running and one of them is closed, this can lead to a segmentation fault in the callback function (jack_port_get_buffer() delivers bad data). We couldn't really track down the error, but to be on the sure side, delete your JackClients only on the very end.
A related issue may be that after calling jack_client_close() the corresponding thread is not closed, in the end it becomes a "zombie thread". But maybe this is a different story ...
Any comments on this topic are very welcome!

Definition at line 68 of file jackclient.h.

Member Enumeration Documentation

Select if JACK's audio callback function shall be called.

Enumerator
dont_use_jack_process_callback 

JACK audio callback is never called.

use_jack_process_callback 

JACK audio callback (jack_process_callback()) is called after activate()

Definition at line 76 of file jackclient.h.

Constructor & Destructor Documentation

apf::JackClient::JackClient ( const std::string &  name = "JackClient",
callback_usage_t  callback_usage = dont_use_jack_process_callback 
)
inlineexplicit

Constructor.

Parameters
nameclient name of the JACK client to be created.
callback_usageif use_jack_process_callback, the member function jack_process_callback() is called by JACK in each audio cycle.
Warning
name should not include a colon. This doesn't cause an error directly, but it messes up the JACK client- and portnames.
Exceptions
jack_errorif something goes wrong

Definition at line 464 of file jackclient.h.

References use_jack_process_callback.

Referenced by jack_xrun_callback().

Member Function Documentation

bool apf::JackClient::activate ( ) const
inline

Activate JACK client.

Returns
true on success
See also
jack_activate()

Definition at line 127 of file jackclient.h.

References connect_pending_connections().

bool apf::JackClient::deactivate ( ) const
inline

Deactivate JACK client.

Returns
true on success
See also
jack_deactivate()

Definition at line 141 of file jackclient.h.

port_t* apf::JackClient::register_in_port ( const std::string &  name) const
inline

Register JACK input port.

Parameters
namedesired port name
Returns
JACK port
See also
register_port()

Definition at line 155 of file jackclient.h.

References register_port().

Referenced by apf::jack_policy::jack_policy().

port_t* apf::JackClient::register_out_port ( const std::string &  name) const
inline

Register JACK output port.

Parameters
namedesired port name
Returns
JACK port
See also
register_port()

Definition at line 164 of file jackclient.h.

References register_port().

Referenced by apf::jack_policy::jack_policy().

port_t* apf::JackClient::register_port ( const std::string &  name,
unsigned long  flags 
) const
inline

Register JACK port (input or output).

Parameters
namedesired port name
flagsJACK port flags
Returns
JACK port
See also
jack_port_register()

Definition at line 174 of file jackclient.h.

Referenced by register_in_port(), and register_out_port().

bool apf::JackClient::unregister_port ( port_t *  port) const
inline

Unregister JACK port.

Parameters
portJACK port
Returns
true on success
See also
jack_port_unregister()

Definition at line 184 of file jackclient.h.

bool apf::JackClient::connect_ports ( const std::string &  source,
const std::string &  destination 
) const
inline

Connect two JACK ports.

Parameters
sourcesource port name
destinationdestination port name
Returns
true on success

Definition at line 201 of file jackclient.h.

bool apf::JackClient::disconnect_ports ( const std::string &  source,
const std::string &  destination 
) const
inline

Disconnect two JACK ports.

Parameters
sourcesource port name
destinationdestination port name
Returns
true on success

Definition at line 211 of file jackclient.h.

bool apf::JackClient::connect_pending_connections ( ) const
inline

Make connections which are still pending from a previous call to connect_ports().

This is needed if connect_ports() has been called while the JackClient wasn't activated yet.

Definition at line 220 of file jackclient.h.

Referenced by activate().

void apf::JackClient::transport_start ( ) const
inline

Start JACK transport.

Definition at line 245 of file jackclient.h.

void apf::JackClient::transport_stop ( ) const
inline

Stop JACK transport.

Definition at line 251 of file jackclient.h.

bool apf::JackClient::transport_locate ( nframes_t  frame) const
inline

Set JACK transport location.

Parameters
framelocation
Returns
true on success
See also
get_transport_state(), jack_transport_locate()

Definition at line 260 of file jackclient.h.

std::pair<bool, nframes_t> apf::JackClient::get_transport_state ( ) const
inline

Get JACK transport state.

Returns
a pair: first element is true if transport is rolling, second is the current position.

Definition at line 268 of file jackclient.h.

bool apf::JackClient::set_freewheel ( int  onoff) const
inline

Set JACK freewheeling mode.

Parameters
onoffnon-zero: start; zero: stop
Returns
true on success

Definition at line 287 of file jackclient.h.

std::string apf::JackClient::client_name ( ) const
inline
Returns
JACK client name

Definition at line 293 of file jackclient.h.

nframes_t apf::JackClient::sample_rate ( ) const
inline
Returns
JACK sample rate

Definition at line 295 of file jackclient.h.

nframes_t apf::JackClient::buffer_size ( ) const
inline
Returns
JACK buffer size

Definition at line 297 of file jackclient.h.

virtual int apf::JackClient::jack_process_callback ( nframes_t  nframes)
inlineprotectedvirtual

JACK process callback function.

This function is empty in the JackClient base class. Derived classes should overwrite it if needed.

Parameters
nframesNumber of frames (~samples) in the current block. This value is delivered by the JACK server.
Returns
message to JACK: 0 means call me again, 1 don't call me anymore.
Exceptions
jack_errorif not implemented
See also
callback_usage_t

Definition at line 337 of file jackclient.h.

Referenced by jack_xrun_callback().

virtual void apf::JackClient::jack_shutdown_callback ( jack_status_t  code,
const char *  reason 
)
inlineprotectedvirtual

JACK shutdown callback.

By default, this is throwing a jack_error exception. If you don't like this, you can overwrite this function in your derived class.

Parameters
codestatus code, see JackInfoShutdownCallback
reasona string describing the shutdown reason
See also
JackInfoShutdownCallback and jack_on_info_shutdown()
Note
There is also JackShutdownCallback and jack_on_shutdown(), but this one is more useful.

Definition at line 351 of file jackclient.h.

Referenced by jack_xrun_callback().

virtual int apf::JackClient::jack_sample_rate_callback ( nframes_t  sr)
inlineprotectedvirtual

JACK sample rate callback.

Parameters
srnew sample rate delivered by JACK
Exceptions
jack_errorif not implemented
Returns
0 on success.

Definition at line 361 of file jackclient.h.

Referenced by jack_xrun_callback().

virtual int apf::JackClient::jack_buffer_size_callback ( nframes_t  bs)
inlineprotectedvirtual

JACK buffer size callback.

Exceptions
jack_errorif not implemented
Returns
0 on success.

Definition at line 370 of file jackclient.h.

Referenced by jack_xrun_callback().

virtual int apf::JackClient::jack_xrun_callback ( )
inlineprotectedvirtual

JACK xrun callback.

Returns
zero on success, non-zero on error

Definition at line 378 of file jackclient.h.

References jack_buffer_size_callback(), jack_process_callback(), jack_sample_rate_callback(), jack_shutdown_callback(), and JackClient().


The documentation for this class was generated from the following file: