transport.h File Reference

#include <jack/types.h>

Go to the source code of this file.

Data Structures

struct  jack_position_t
struct  jack_transport_info_t

Defines

#define JACK_POSITION_MASK   (JackPositionBBT|JackPositionTimecode|JackBBTFrameOffset|JackAudioVideoRatio|JackVideoFrameOffset)
#define EXTENDED_TIME_INFO

Typedefs

typedef uint64_t jack_unique_t
typedef int(*) JackSyncCallback (jack_transport_state_t state, jack_position_t *pos, void *arg)
typedef void(*) JackTimebaseCallback (jack_transport_state_t state, jack_nframes_t nframes, jack_position_t *pos, int new_pos, void *arg)

Enumerations

enum  jack_transport_state_t { JackTransportStopped = 0, JackTransportRolling = 1, JackTransportLooping = 2, JackTransportStarting = 3 }
enum  jack_position_bits_t {
  JackPositionBBT = 0x10, JackPositionTimecode = 0x20, JackBBTFrameOffset = 0x40, JackAudioVideoRatio = 0x80,
  JackVideoFrameOffset = 0x100
}
enum  jack_transport_bits_t {
  JackTransportState = 0x1, JackTransportPosition = 0x2, JackTransportLoop = 0x4, JackTransportSMPTE = 0x8,
  JackTransportBBT = 0x10
}

Functions

int jack_release_timebase (jack_client_t *client)
int jack_set_sync_callback (jack_client_t *client, JackSyncCallback sync_callback, void *arg)
int jack_set_sync_timeout (jack_client_t *client, jack_time_t timeout)
int jack_set_timebase_callback (jack_client_t *client, int conditional, JackTimebaseCallback timebase_callback, void *arg)
int jack_transport_locate (jack_client_t *client, jack_nframes_t frame)
jack_transport_state_t jack_transport_query (const jack_client_t *client, jack_position_t *pos)
jack_nframes_t jack_get_current_transport_frame (const jack_client_t *client)
int jack_transport_reposition (jack_client_t *client, jack_position_t *pos)
void jack_transport_start (jack_client_t *client)
void jack_transport_stop (jack_client_t *client)
void jack_get_transport_info (jack_client_t *client, jack_transport_info_t *tinfo)
void jack_set_transport_info (jack_client_t *client, jack_transport_info_t *tinfo)


Define Documentation

#define EXTENDED_TIME_INFO

#define JACK_POSITION_MASK   (JackPositionBBT|JackPositionTimecode|JackBBTFrameOffset|JackAudioVideoRatio|JackVideoFrameOffset)

all valid position bits


Typedef Documentation

typedef uint64_t jack_unique_t

Unique ID (opaque)

typedef int(*) JackSyncCallback(jack_transport_state_t state, jack_position_t *pos, void *arg)

Prototype for the sync_callback defined by slow-sync clients. When the client is active, this callback is invoked just before process() in the same thread. This occurs once after registration, then subsequently whenever some client requests a new position, or the transport enters the JackTransportStarting state. This realtime function must not wait.

The transport state will be:

Parameters:
state current transport state.
pos new transport position.
arg the argument supplied by jack_set_sync_callback().
Returns:
TRUE (non-zero) when ready to roll.

typedef void(*) JackTimebaseCallback(jack_transport_state_t state, jack_nframes_t nframes, jack_position_t *pos, int new_pos, void *arg)

Prototype for the timebase_callback used to provide extended position information. Its output affects all of the following process cycle. This realtime function must not wait.

This function is called immediately after process() in the same thread whenever the transport is rolling, or when any client has requested a new position in the previous cycle. The first cycle after jack_set_timebase_callback() is also treated as a new position, or the first cycle after jack_activate() if the client had been inactive.

The timebase master may not use its pos argument to set pos->frame. To change position, use jack_transport_reposition() or jack_transport_locate(). These functions are realtime-safe, the timebase_callback can call them directly.

Parameters:
state current transport state.
nframes number of frames in current period.
pos address of the position structure for the next cycle; pos->frame will be its frame number. If new_pos is FALSE, this structure contains extended position information from the current cycle. If TRUE, it contains whatever was set by the requester. The timebase_callback's task is to update the extended information here.
new_pos TRUE (non-zero) for a newly requested pos, or for the first cycle after the timebase_callback is defined.
arg the argument supplied by jack_set_timebase_callback().


Enumeration Type Documentation

enum jack_position_bits_t

Optional struct jack_position_t fields.

Enumerator:
JackPositionBBT  Bar, Beat, Tick
JackPositionTimecode  External timecode
JackBBTFrameOffset  Frame offset of BBT information
JackAudioVideoRatio  audio frames per video frame
JackVideoFrameOffset  frame offset of first video frame

enum jack_transport_bits_t

Optional struct jack_transport_info_t fields.

See also:
jack_position_bits_t.
Enumerator:
JackTransportState  Transport state
JackTransportPosition  Frame number
JackTransportLoop  Loop boundaries (ignored)
JackTransportSMPTE  SMPTE (ignored)
JackTransportBBT  Bar, Beat, Tick

enum jack_transport_state_t

Transport states.

Enumerator:
JackTransportStopped  Transport halted
JackTransportRolling  Transport playing
JackTransportLooping  For OLD_TRANSPORT, now ignored
JackTransportStarting  Waiting for sync ready


Function Documentation

jack_nframes_t jack_get_current_transport_frame ( const jack_client_t client  ) 

Return an estimate of the current transport frame, including any time elapsed since the last transport positional update.

Parameters:
client the JACK client structure

void jack_get_transport_info ( jack_client_t client,
jack_transport_info_t tinfo 
)

Gets the current transport info structure (deprecated).

Parameters:
client the JACK client structure.
tinfo current transport info structure. The "valid" field describes which fields contain valid data.
Deprecated:
This is for compatibility with the earlier transport interface. Use jack_transport_query(), instead.
Precondition:
Must be called from the process thread.

int jack_release_timebase ( jack_client_t client  ) 

Called by the timebase master to release itself from that responsibility.

If the timebase master releases the timebase or leaves the JACK graph for any reason, the JACK engine takes over at the start of the next process cycle. The transport state does not change. If rolling, it continues to play, with frame numbers as the only available position information.

See also:
jack_set_timebase_callback
Parameters:
client the JACK client structure.
Returns:
0 on success, otherwise a non-zero error code.

int jack_set_sync_callback ( jack_client_t client,
JackSyncCallback  sync_callback,
void *  arg 
)

Register (or unregister) as a slow-sync client, one that cannot respond immediately to transport position changes.

The sync_callback will be invoked at the first available opportunity after its registration is complete. If the client is currently active this will be the following process cycle, otherwise it will be the first cycle after calling jack_activate(). After that, it runs according to the JackSyncCallback rules. Clients that don't set a sync_callback are assumed to be ready immediately any time the transport wants to start.

Parameters:
client the JACK client structure.
sync_callback is a realtime function that returns TRUE when the client is ready. Setting sync_callback to NULL declares that this client no longer requires slow-sync processing.
arg an argument for the sync_callback function.
Returns:
0 on success, otherwise a non-zero error code.

int jack_set_sync_timeout ( jack_client_t client,
jack_time_t  timeout 
)

Set the timeout value for slow-sync clients.

This timeout prevents unresponsive slow-sync clients from completely halting the transport mechanism. The default is two seconds. When the timeout expires, the transport starts rolling, even if some slow-sync clients are still unready. The sync_callbacks of these clients continue being invoked, giving them a chance to catch up.

See also:
jack_set_sync_callback
Parameters:
client the JACK client structure.
timeout is delay (in microseconds) before the timeout expires.
Returns:
0 on success, otherwise a non-zero error code.

int jack_set_timebase_callback ( jack_client_t client,
int  conditional,
JackTimebaseCallback  timebase_callback,
void *  arg 
)

Register as timebase master for the JACK subsystem.

The timebase master registers a callback that updates extended position information such as beats or timecode whenever necessary. Without this extended information, there is no need for this function.

There is never more than one master at a time. When a new client takes over, the former timebase_callback is no longer called. Taking over the timebase may be done conditionally, so it fails if there was a master already.

Parameters:
client the JACK client structure.
conditional non-zero for a conditional request.
timebase_callback is a realtime function that returns position information.
arg an argument for the timebase_callback function.
Returns:
  • 0 on success;
  • EBUSY if a conditional request fails because there was already a timebase master;
  • other non-zero error code.

void jack_set_transport_info ( jack_client_t client,
jack_transport_info_t tinfo 
)

Set the transport info structure (deprecated).

Deprecated:
This function still exists for compatibility with the earlier transport interface, but it does nothing. Instead, define a JackTimebaseCallback.

int jack_transport_locate ( jack_client_t client,
jack_nframes_t  frame 
)

Reposition the transport to a new frame number.

May be called at any time by any client. The new position takes effect in two process cycles. If there are slow-sync clients and the transport is already rolling, it will enter the JackTransportStarting state and begin invoking their sync_callbacks until ready. This function is realtime-safe.

See also:
jack_transport_reposition, jack_set_sync_callback
Parameters:
client the JACK client structure.
frame frame number of new transport position.
Returns:
0 if valid request, non-zero otherwise.

jack_transport_state_t jack_transport_query ( const jack_client_t client,
jack_position_t pos 
)

Query the current transport state and position.

This function is realtime-safe, and can be called from any thread. If called from the process thread, pos corresponds to the first frame of the current cycle and the state returned is valid for the entire cycle.

Parameters:
client the JACK client structure.
pos pointer to structure for returning current transport position; pos->valid will show which fields contain valid data. If pos is NULL, do not return position information.
Returns:
Current transport state.

int jack_transport_reposition ( jack_client_t client,
jack_position_t pos 
)

Request a new transport position.

May be called at any time by any client. The new position takes effect in two process cycles. If there are slow-sync clients and the transport is already rolling, it will enter the JackTransportStarting state and begin invoking their sync_callbacks until ready. This function is realtime-safe.

See also:
jack_transport_locate, jack_set_sync_callback
Parameters:
client the JACK client structure.
pos requested new transport position.
Returns:
0 if valid request, EINVAL if position structure rejected.

void jack_transport_start ( jack_client_t client  ) 

Start the JACK transport rolling.

Any client can make this request at any time. It takes effect no sooner than the next process cycle, perhaps later if there are slow-sync clients. This function is realtime-safe.

See also:
jack_set_sync_callback
Parameters:
client the JACK client structure.

void jack_transport_stop ( jack_client_t client  ) 

Stop the JACK transport.

Any client can make this request at any time. It takes effect on the next process cycle. This function is realtime-safe.

Parameters:
client the JACK client structure.


Generated on Sun Sep 23 09:46:50 2007 for JACK-AUDIO-CONNECTION-KIT by  doxygen 1.4.7