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