common/transport_types.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_types.h,v 1.1.2.2 2006/06/20 14:44:00 letz Exp $
  20 */
  21
  22 #ifndef __jack_transport_aux_h__
  23 #define __jack_transport_aux_h__
  24
  25 #ifdef __cplusplus
  26 extern "C"
  27 {
  28 #endif
  29
  30 #include "types.h"
  31
  32     /**
  33      * Transport states.
  34      */
  35     typedef enum {
  36
  37         /* the order matters for binary compatibility */
  38         JackTransportStopped = 0,       /**< Transport halted */
  39         JackTransportRolling = 1,       /**< Transport playing */
  40         JackTransportLooping = 2,       /**< For OLD_TRANSPORT, now ignored */
  41         JackTransportStarting = 3,      /**< Waiting for sync ready */
  42         JackTransportSynching = 4       /**< temporary*/
  43
  44     } jack_transport_state_t;
  45
  46     typedef uint64_t jack_unique_t;             /**< Unique ID (opaque) */
  47
  48     /**
  49      * Optional struct jack_position_t fields.
  50      */
  51     typedef enum {
  52
  53         JackPositionBBT = 0x10,         /**< Bar, Beat, Tick */
  54         JackPositionTimecode = 0x20     /**< External timecode */
  55
  56     } jack_position_bits_t;
  57
  58     /** all valid position bits */
  59 #define JACK_POSITION_MASK (JackPositionBBT|JackPositionTimecode)
  60 #define EXTENDED_TIME_INFO
  61
  62     /**
  63      * Struct for transport position information.
  64      */
  65     typedef struct {
  66
  67         /* these four cannot be set from clients: the server sets them */
  68         jack_unique_t   unique_1;       /**< unique ID */
  69         jack_time_t     usecs;          /**< monotonic, free-rolling */
  70         jack_nframes_t  frame_rate;     /**< current frame rate (per second) */
  71         jack_nframes_t  frame;          /**< frame number, always present */
  72
  73         jack_position_bits_t valid;             /**< which other fields are valid */
  74
  75         /* JackPositionBBT fields: */
  76         int32_t bar;            /**< current bar */
  77         int32_t beat;           /**< current beat-within-bar */
  78         int32_t tick;           /**< current tick-within-beat */
  79         double  bar_start_tick;
  80
  81         float   beats_per_bar;  /**< time signature "numerator" */
  82         float   beat_type;      /**< time signature "denominator" */
  83         double  ticks_per_beat;
  84         double  beats_per_minute;
  85
  86         /* JackPositionTimecode fields: (EXPERIMENTAL: could change) */
  87         double  frame_time;     /**< current time in seconds */
  88         double  next_time;      /**< next sequential frame_time
  89                                                              (unless repositioned) */
  90
  91         /* For binary compatibility, new fields should be allocated from
  92          * this padding area with new valid bits controlling access, so
  93          * the existing structure size and offsets are preserved. */
  94         int32_t padding[10];
  95
  96         /* When (unique_1 == unique_2) the contents are consistent. */
  97         jack_unique_t   unique_2;       /**< unique ID */
  98
  99     }
 100     jack_position_t;
 101
 102     /**
 103         * Prototype for the @a sync_callback defined by slow-sync clients.
 104         * When the client is active, this callback is invoked just before
 105         * process() in the same thread.  This occurs once after registration,
 106         * then subsequently whenever some client requests a new position, or
 107         * the transport enters the ::JackTransportStarting state.  This
 108         * realtime function must not wait.
 109         *
 110         * The transport @a state will be:
 111         *
 112         *   - ::JackTransportStopped when a new position is requested;
 113         *   - ::JackTransportStarting when the transport is waiting to start;
 114         *   - ::JackTransportRolling when the timeout has expired, and the
 115         *   position is now a moving target.
 116         *
 117         * @param state current transport state.
 118         * @param pos new transport position.
 119         * @param arg the argument supplied by jack_set_sync_callback().
 120         *
 121         * @return TRUE (non-zero) when ready to roll.
 122         */
 123     typedef int (*JackSyncCallback)(jack_transport_state_t state,
 124                                     jack_position_t *pos,
 125                                     void *arg);
 126
 127
 128     /**
 129       * Prototype for the @a timebase_callback used to provide extended
 130       * position information.  Its output affects all of the following
 131       * process cycle.  This realtime function must not wait.
 132       *
 133       * This function is called immediately after process() in the same
 134       * thread whenever the transport is rolling, or when any client has
 135       * requested a new position in the previous cycle.  The first cycle
 136       * after jack_set_timebase_callback() is also treated as a new
 137       * position, or the first cycle after jack_activate() if the client
 138       * had been inactive.
 139       *
 140       * The timebase master may not use its @a pos argument to set @a
 141       * pos->frame.  To change position, use jack_transport_reposition() or
 142       * jack_transport_locate().  These functions are realtime-safe, the @a
 143       * timebase_callback can call them directly.
 144       *
 145       * @param state current transport state.
 146       * @param nframes number of frames in current period.
 147       * @param pos address of the position structure for the next cycle; @a
 148       * pos->frame will be its frame number.  If @a new_pos is FALSE, this
 149       * structure contains extended position information from the current
 150       * cycle.  If TRUE, it contains whatever was set by the requester.
 151       * The @a timebase_callback's task is to update the extended
 152       * information here.
 153       * @param new_pos TRUE (non-zero) for a newly requested @a pos, or for
 154       * the first cycle after the @a timebase_callback is defined.
 155       * @param arg the argument supplied by jack_set_timebase_callback().
 156       */
 157     typedef void (*JackTimebaseCallback)(jack_transport_state_t state,
 158                                          jack_nframes_t nframes,
 159                                          jack_position_t *pos,
 160                                          int new_pos,
 161                                          void *arg);
 162
 163     /*********************************************************************
 164         * The following interfaces are DEPRECATED.  They are only provided
 165         * for compatibility with the earlier JACK transport implementation.
 166         *********************************************************************/
 167
 168     /**
 169      * Optional struct jack_transport_info_t fields.
 170      *
 171      * @see jack_position_bits_t.
 172      */
 173     typedef enum {
 174
 175         JackTransportState = 0x1,       /**< Transport state */
 176         JackTransportPosition = 0x2,    /**< Frame number */
 177         JackTransportLoop = 0x4,        /**< Loop boundaries (ignored) */
 178         JackTransportSMPTE = 0x8,       /**< SMPTE (ignored) */
 179         JackTransportBBT = 0x10 /**< Bar, Beat, Tick */
 180
 181     } jack_transport_bits_t;
 182
 183     /**
 184      * Deprecated struct for transport position information.
 185      *
 186      * @deprecated This is for compatibility with the earlier transport
 187      * interface.  Use the jack_position_t struct, instead.
 188      */
 189     typedef struct {
 190
 191         /* these two cannot be set from clients: the server sets them */
 192
 193         jack_nframes_t frame_rate;              /**< current frame rate (per second) */
 194         jack_time_t usecs;              /**< monotonic, free-rolling */
 195
 196         jack_transport_bits_t valid;    /**< which fields are legal to read */
 197         jack_transport_state_t transport_state;
 198         jack_nframes_t frame;
 199         jack_nframes_t loop_start;
 200         jack_nframes_t loop_end;
 201
 202         long smpte_offset;      /**< SMPTE offset (from frame 0) */
 203         float smpte_frame_rate; /**< 29.97, 30, 24 etc. */
 204
 205         int bar;
 206         int beat;
 207         int tick;
 208         double bar_start_tick;
 209
 210         float beats_per_bar;
 211         float beat_type;
 212         double ticks_per_beat;
 213         double beats_per_minute;
 214
 215     }
 216     jack_transport_info_t;
 217
 218 #ifdef __cplusplus
 219 }
 220 #endif
 221
 222 #endif /* __jack_transport_aux_h__ */