jack/transport.h

   1 /*
   2     Copyright (C) 2002 Paul Davis
   3     Copyright (C) 2003 Jack O'Quin
   4
   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.
   9
  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.
  14
  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.
  18
  19 */
  20
  21 #ifndef __jack_transport_h__
  22 #define __jack_transport_h__
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 #include <jack/types.h>
  29
  30 /**
  31  * Transport states.
  32  */
  33 typedef enum {
  34
  35         /* the order matters for binary compatibility */
  36         JackTransportStopped = 0,       /**< Transport halted */
  37         JackTransportRolling = 1,       /**< Transport playing */
  38         JackTransportLooping = 2,       /**< For OLD_TRANSPORT, now ignored */
  39         JackTransportStarting = 3       /**< Waiting for sync ready */
  40
  41 } jack_transport_state_t;
  42
  43 typedef uint64_t jack_unique_t;         /**< Unique ID (opaque) */
  44
  45 /**
  46  * Optional struct jack_position_t fields.
  47  */
  48 typedef enum {
  49
  50         JackPositionBBT =         0x10, /**< Bar, Beat, Tick */
  51         JackPositionTimecode =    0x20, /**< External timecode */
  52         JackBBTFrameOffset =      0x40, /**< Frame offset of BBT information */
  53         JackAudioVideoRatio =     0x80, /**< audio frames per video frame */
  54         JackVideoFrameOffset =   0x100  /**< frame offset of first video frame */
  55 } jack_position_bits_t;
  56
  57 /** all valid position bits */
  58 #define JACK_POSITION_MASK (JackPositionBBT|JackPositionTimecode|JackBBTFrameOffset|JackAudioVideoRatio|JackVideoFrameOffset)
  59 #define EXTENDED_TIME_INFO
  60
  61 /**
  62  * Struct for transport position information.
  63  */
  64 typedef struct {
  65
  66     /* these four cannot be set from clients: the server sets them */
  67     jack_unique_t       unique_1;       /**< unique ID */
  68     jack_time_t         usecs;          /**< monotonic, free-rolling */
  69     jack_nframes_t      frame_rate;     /**< current frame rate (per second) */
  70     jack_nframes_t      frame;          /**< frame number, always present */
  71
  72     jack_position_bits_t valid;         /**< which other fields are valid */
  73
  74     /* JackPositionBBT fields: */
  75     int32_t             bar;            /**< current bar */
  76     int32_t             beat;           /**< current beat-within-bar */
  77     int32_t             tick;           /**< current tick-within-beat */
  78     double              bar_start_tick;
  79
  80     float               beats_per_bar;  /**< time signature "numerator" */
  81     float               beat_type;      /**< time signature "denominator" */
  82     double              ticks_per_beat;
  83     double              beats_per_minute;
  84
  85     /* JackPositionTimecode fields:     (EXPERIMENTAL: could change) */
  86     double              frame_time;     /**< current time in seconds */
  87     double              next_time;      /**< next sequential frame_time
  88                                              (unless repositioned) */
  89
  90     /* JackBBTFrameOffset fields: */
  91     jack_nframes_t      bbt_offset;     /**< frame offset for the BBT fields
  92                                              (the given bar, beat, and tick
  93                                              values actually refer to a time
  94                                              frame_offset frames before the
  95                                              start of the cycle), should
  96                                              be assumed to be 0 if
  97                                              JackBBTFrameOffset is not
  98                                              set. If JackBBTFrameOffset is
  99                                              set and this value is zero, the BBT
 100                                              time refers to the first frame of this
 101                                              cycle. If the value is positive,
 102                                              the BBT time refers to a frame that
 103                                              many frames before the start of the
 104                                              cycle. */
 105
 106     /* JACK video positional data (experimental) */
 107
 108     float               audio_frames_per_video_frame; /**< number of audio frames
 109                                              per video frame. Should be assumed
 110                                              zero if JackAudioVideoRatio is not
 111                                              set. If JackAudioVideoRatio is set
 112                                              and the value is zero, no video
 113                                              data exists within the JACK graph */
 114
 115     jack_nframes_t      video_offset;   /**< audio frame at which the first video
 116                                              frame in this cycle occurs. Should
 117                                              be assumed to be 0 if JackVideoFrameOffset
 118                                              is not set. If JackVideoFrameOffset is
 119                                              set, but the value is zero, there is
 120                                              no video frame within this cycle. */
 121
 122     /* For binary compatibility, new fields should be allocated from
 123      * this padding area with new valid bits controlling access, so
 124      * the existing structure size and offsets are preserved. */
 125     int32_t             padding[7];
 126
 127     /* When (unique_1 == unique_2) the contents are consistent. */
 128     jack_unique_t       unique_2;       /**< unique ID */
 129
 130 } jack_position_t;
 131
 132 /**
 133  * Called by the timebase master to release itself from that
 134  * responsibility.
 135  *
 136  * If the timebase master releases the timebase or leaves the JACK
 137  * graph for any reason, the JACK engine takes over at the start of
 138  * the next process cycle.  The transport state does not change.  If
 139  * rolling, it continues to play, with frame numbers as the only
 140  * available position information.
 141  *
 142  * @see jack_set_timebase_callback
 143  *
 144  * @param client the JACK client structure.
 145  *
 146  * @return 0 on success, otherwise a non-zero error code.
 147  */
 148 int  jack_release_timebase (jack_client_t *client);
 149
 150 /**
 151  * Prototype for the @a sync_callback defined by slow-sync clients.
 152  * When the client is active, this callback is invoked just before
 153  * process() in the same thread.  This occurs once after registration,
 154  * then subsequently whenever some client requests a new position, or
 155  * the transport enters the ::JackTransportStarting state.  This
 156  * realtime function must not wait.
 157  *
 158  * The transport @a state will be:
 159  *
 160  *   - ::JackTransportStopped when a new position is requested;
 161  *   - ::JackTransportStarting when the transport is waiting to start;
 162  *   - ::JackTransportRolling when the timeout has expired, and the
 163  *   position is now a moving target.
 164  *
 165  * @param state current transport state.
 166  * @param pos new transport position.
 167  * @param arg the argument supplied by jack_set_sync_callback().
 168  *
 169  * @return TRUE (non-zero) when ready to roll.
 170  */
 171 typedef int  (*JackSyncCallback)(jack_transport_state_t state,
 172                                  jack_position_t *pos,
 173                                  void *arg);
 174
 175 /**
 176  * Register (or unregister) as a slow-sync client, one that cannot
 177  * respond immediately to transport position changes.
 178  *
 179  * The @a sync_callback will be invoked at the first available
 180  * opportunity after its registration is complete.  If the client is
 181  * currently active this will be the following process cycle,
 182  * otherwise it will be the first cycle after calling jack_activate().
 183  * After that, it runs according to the ::JackSyncCallback rules.
 184  * Clients that don't set a @a sync_callback are assumed to be ready
 185  * immediately any time the transport wants to start.
 186  *
 187  * @param client the JACK client structure.
 188  * @param sync_callback is a realtime function that returns TRUE when
 189  * the client is ready.  Setting @a sync_callback to NULL declares that
 190  * this client no longer requires slow-sync processing.
 191  * @param arg an argument for the @a sync_callback function.
 192  *
 193  * @return 0 on success, otherwise a non-zero error code.
 194  */
 195 int  jack_set_sync_callback (jack_client_t *client,
 196                              JackSyncCallback sync_callback,
 197                              void *arg);
 198
 199 /**
 200  * Set the timeout value for slow-sync clients.
 201  *
 202  * This timeout prevents unresponsive slow-sync clients from
 203  * completely halting the transport mechanism.  The default is two
 204  * seconds.  When the timeout expires, the transport starts rolling,
 205  * even if some slow-sync clients are still unready.  The @a
 206  * sync_callbacks of these clients continue being invoked, giving them
 207  * a chance to catch up.
 208  *
 209  * @see jack_set_sync_callback
 210  *
 211  * @param client the JACK client structure.
 212  * @param timeout is delay (in microseconds) before the timeout expires.
 213  *
 214  * @return 0 on success, otherwise a non-zero error code.
 215  */
 216 int  jack_set_sync_timeout (jack_client_t *client,
 217                             jack_time_t timeout);
 218
 219 /**
 220  * Prototype for the @a timebase_callback used to provide extended
 221  * position information.  Its output affects all of the following
 222  * process cycle.  This realtime function must not wait.
 223  *
 224  * This function is called immediately after process() in the same
 225  * thread whenever the transport is rolling, or when any client has
 226  * requested a new position in the previous cycle.  The first cycle
 227  * after jack_set_timebase_callback() is also treated as a new
 228  * position, or the first cycle after jack_activate() if the client
 229  * had been inactive.
 230  *
 231  * The timebase master may not use its @a pos argument to set @a
 232  * pos->frame.  To change position, use jack_transport_reposition() or
 233  * jack_transport_locate().  These functions are realtime-safe, the @a
 234  * timebase_callback can call them directly.
 235  *
 236  * @param state current transport state.
 237  * @param nframes number of frames in current period.
 238  * @param pos address of the position structure for the next cycle; @a
 239  * pos->frame will be its frame number.  If @a new_pos is FALSE, this
 240  * structure contains extended position information from the current
 241  * cycle.  If TRUE, it contains whatever was set by the requester.
 242  * The @a timebase_callback's task is to update the extended
 243  * information here.
 244  * @param new_pos TRUE (non-zero) for a newly requested @a pos, or for
 245  * the first cycle after the @a timebase_callback is defined.
 246  * @param arg the argument supplied by jack_set_timebase_callback().
 247  */
 248 typedef void (*JackTimebaseCallback)(jack_transport_state_t state,
 249                                      jack_nframes_t nframes,
 250                                      jack_position_t *pos,
 251                                      int new_pos,
 252                                      void *arg);
 253
 254 /**
 255  * Register as timebase master for the JACK subsystem.
 256  *
 257  * The timebase master registers a callback that updates extended
 258  * position information such as beats or timecode whenever necessary.
 259  * Without this extended information, there is no need for this
 260  * function.
 261  *
 262  * There is never more than one master at a time.  When a new client
 263  * takes over, the former @a timebase_callback is no longer called.
 264  * Taking over the timebase may be done conditionally, so it fails if
 265  * there was a master already.
 266  *
 267  * @param client the JACK client structure.
 268  * @param conditional non-zero for a conditional request.
 269  * @param timebase_callback is a realtime function that returns
 270  * position information.
 271  * @param arg an argument for the @a timebase_callback function.
 272  *
 273  * @return
 274  *   - 0 on success;
 275  *   - EBUSY if a conditional request fails because there was already a
 276  *   timebase master;
 277  *   - other non-zero error code.
 278  */
 279 int  jack_set_timebase_callback (jack_client_t *client,
 280                                  int conditional,
 281                                  JackTimebaseCallback timebase_callback,
 282                                  void *arg);
 283
 284 /**
 285  * Reposition the transport to a new frame number.
 286  *
 287  * May be called at any time by any client.  The new position takes
 288  * effect in two process cycles.  If there are slow-sync clients and
 289  * the transport is already rolling, it will enter the
 290  * ::JackTransportStarting state and begin invoking their @a
 291  * sync_callbacks until ready.  This function is realtime-safe.
 292  *
 293  * @see jack_transport_reposition, jack_set_sync_callback
 294  *
 295  * @param client the JACK client structure.
 296  * @param frame frame number of new transport position.
 297  *
 298  * @return 0 if valid request, non-zero otherwise.
 299  */
 300 int  jack_transport_locate (jack_client_t *client,
 301                             jack_nframes_t frame);
 302
 303 /**
 304  * Query the current transport state and position.
 305  *
 306  * This function is realtime-safe, and can be called from any thread.
 307  * If called from the process thread, @a pos corresponds to the first
 308  * frame of the current cycle and the state returned is valid for the
 309  * entire cycle.
 310  *
 311  * @param client the JACK client structure.
 312  * @param pos pointer to structure for returning current transport
 313  * position; @a pos->valid will show which fields contain valid data.
 314  * If @a pos is NULL, do not return position information.
 315  *
 316  * @return Current transport state.
 317  */
 318 jack_transport_state_t jack_transport_query (const jack_client_t *client,
 319                                              jack_position_t *pos);
 320
 321 /**
 322  * Return an estimate of the current transport frame,
 323  * including any time elapsed since the last transport
 324  * positional update.
 325  *
 326  * @param client the JACK client structure
 327  */
 328 jack_nframes_t jack_get_current_transport_frame (const jack_client_t *client);
 329
 330 /**
 331  * Request a new transport position.
 332  *
 333  * May be called at any time by any client.  The new position takes
 334  * effect in two process cycles.  If there are slow-sync clients and
 335  * the transport is already rolling, it will enter the
 336  * ::JackTransportStarting state and begin invoking their @a
 337  * sync_callbacks until ready.  This function is realtime-safe.
 338  *
 339  * @see jack_transport_locate, jack_set_sync_callback
 340  *
 341  * @param client the JACK client structure.
 342  * @param pos requested new transport position.
 343  *
 344  * @return 0 if valid request, EINVAL if position structure rejected.
 345  */
 346 int  jack_transport_reposition (jack_client_t *client,
 347                                 jack_position_t *pos);
 348
 349 /**
 350  * Start the JACK transport rolling.
 351  *
 352  * Any client can make this request at any time.  It takes effect no
 353  * sooner than the next process cycle, perhaps later if there are
 354  * slow-sync clients.  This function is realtime-safe.
 355  *
 356  * @see jack_set_sync_callback
 357  *
 358  * @param client the JACK client structure.
 359  */
 360 void jack_transport_start (jack_client_t *client);
 361
 362 /**
 363  * Stop the JACK transport.
 364  *
 365  * Any client can make this request at any time.  It takes effect on
 366  * the next process cycle.  This function is realtime-safe.
 367  *
 368  * @param client the JACK client structure.
 369  */
 370 void jack_transport_stop (jack_client_t *client);
 371
 372
 373 /*********************************************************************
 374  * The following interfaces are DEPRECATED.  They are only provided
 375  * for compatibility with the earlier JACK transport implementation.
 376  *********************************************************************/
 377
 378 /**
 379  * Optional struct jack_transport_info_t fields.
 380  *
 381  * @see jack_position_bits_t.
 382  */
 383 typedef enum {
 384
 385         JackTransportState =    0x1,    /**< Transport state */
 386         JackTransportPosition = 0x2,    /**< Frame number */
 387         JackTransportLoop =     0x4,    /**< Loop boundaries (ignored) */
 388         JackTransportSMPTE =    0x8,    /**< SMPTE (ignored) */
 389         JackTransportBBT =      0x10    /**< Bar, Beat, Tick */
 390
 391 } jack_transport_bits_t;
 392
 393 /**
 394  * Deprecated struct for transport position information.
 395  *
 396  * @deprecated This is for compatibility with the earlier transport
 397  * interface.  Use the jack_position_t struct, instead.
 398  */
 399 typedef struct {
 400
 401     /* these two cannot be set from clients: the server sets them */
 402
 403     jack_nframes_t frame_rate;          /**< current frame rate (per second) */
 404     jack_time_t    usecs;               /**< monotonic, free-rolling */
 405
 406     jack_transport_bits_t  valid;       /**< which fields are legal to read */
 407     jack_transport_state_t transport_state;
 408     jack_nframes_t         frame;
 409     jack_nframes_t         loop_start;
 410     jack_nframes_t         loop_end;
 411
 412     long           smpte_offset;        /**< SMPTE offset (from frame 0) */
 413     float          smpte_frame_rate;    /**< 29.97, 30, 24 etc. */
 414
 415     int            bar;
 416     int            beat;
 417     int            tick;
 418     double         bar_start_tick;
 419
 420     float          beats_per_bar;
 421     float          beat_type;
 422     double         ticks_per_beat;
 423     double         beats_per_minute;
 424
 425 } jack_transport_info_t;
 426
 427 /**
 428  * Gets the current transport info structure (deprecated).
 429  *
 430  * @param client the JACK client structure.
 431  * @param tinfo current transport info structure.  The "valid" field
 432  * describes which fields contain valid data.
 433  *
 434  * @deprecated This is for compatibility with the earlier transport
 435  * interface.  Use jack_transport_query(), instead.
 436  *
 437  * @pre Must be called from the process thread.
 438  */
 439 void jack_get_transport_info (jack_client_t *client,
 440                               jack_transport_info_t *tinfo);
 441
 442 /**
 443  * Set the transport info structure (deprecated).
 444  *
 445  * @deprecated This function still exists for compatibility with the
 446  * earlier transport interface, but it does nothing.  Instead, define
 447  * a ::JackTimebaseCallback.
 448  */
 449 void jack_set_transport_info (jack_client_t *client,
 450                               jack_transport_info_t *tinfo);
 451
 452 #ifdef __cplusplus
 453 }
 454 #endif
 455
 456 #endif /* __jack_transport_h__ */