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