jack/types.h

   1 /*
   2     Copyright (C) 2001 Paul Davis
   3     Copyright (C) 2004 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_types_h__
  22 #define __jack_types_h__
  23
  24 #include <inttypes.h>
  25
  26 typedef int32_t jack_shmsize_t;
  27
  28 /**
  29  * Type used to represent sample frame counts.
  30  */
  31 typedef uint32_t             jack_nframes_t;
  32
  33 /**
  34  * Maximum value that can be stored in jack_nframes_t
  35  */
  36 #define JACK_MAX_FRAMES (4294967295U)   /* This should be UINT32_MAX, but
  37                                            C++ has a problem with that. */
  38
  39 /**
  40  * Type used to represent the value of free running
  41  * monotonic clock with units of microseconds.
  42  */
  43 typedef uint64_t jack_time_t;
  44
  45 /**
  46  *  Maximum size of @a load_init string passed to an internal client
  47  *  jack_initialize() function via jack_internal_client_load().
  48  */
  49 #define JACK_LOAD_INIT_LIMIT 1024
  50
  51 /**
  52  *  jack_intclient_t is an opaque type representing a loaded internal
  53  *  client.  You may only access it using the API provided in @ref
  54  *  intclient.h "<jack/intclient.h>".
  55  */
  56 typedef uint64_t jack_intclient_t;
  57
  58 /**
  59  *  jack_port_t is an opaque type.  You may only access it using the
  60  *  API provided.
  61  */
  62 typedef struct _jack_port    jack_port_t;
  63
  64 /**
  65  *  jack_client_t is an opaque type.  You may only access it using the
  66  *  API provided.
  67  */
  68 typedef struct _jack_client  jack_client_t;
  69
  70 /**
  71  *  Ports have unique ids. A port registration callback is the only
  72  *  place you ever need to know their value.
  73  */
  74 typedef uint32_t             jack_port_id_t;
  75
  76 /**
  77  * Prototype for the client supplied function that is called
  78  * by the engine anytime there is work to be done.
  79  *
  80  * @pre nframes == jack_get_buffer_size()
  81  * @pre nframes == pow(2,x)
  82  *
  83  * @param nframes number of frames to process
  84  * @param arg pointer to a client supplied data
  85  *
  86  * @return zero on success, non-zero on error
  87  */
  88 typedef int  (*JackProcessCallback)(jack_nframes_t nframes, void *arg);
  89
  90 /**
  91  * Prototype for the client supplied function that is called
  92  * once after the creation of the thread in which other
  93  * callbacks will be made. Special thread characteristics
  94  * can be set from this callback, for example. This is a
  95  * highly specialized callback and most clients will not
  96  * and should not use it.
  97  *
  98  * @param arg pointer to a client supplied structure
  99  *
 100  * @return void
 101  */
 102 typedef void  (*JackThreadInitCallback)(void *arg);
 103
 104 /**
 105  * Prototype for the client supplied function that is called
 106  * whenever the processing graph is reordered.
 107  *
 108  * @param arg pointer to a client supplied data
 109  *
 110  * @return zero on success, non-zero on error
 111  */
 112 typedef int  (*JackGraphOrderCallback)(void *arg);
 113
 114 /**
 115  * Prototype for the client-supplied function that is called whenever
 116  * an xrun has occured.
 117  *
 118  * @see jack_get_xrun_delayed_usecs()
 119  *
 120  * @param arg pointer to a client supplied data
 121  *
 122  * @return zero on success, non-zero on error
 123  */
 124 typedef int  (*JackXRunCallback)(void *arg);
 125
 126 /**
 127  * Prototype for the @a bufsize_callback that is invoked whenever the
 128  * JACK engine buffer size changes.  Although this function is called
 129  * in the JACK process thread, the normal process cycle is suspended
 130  * during its operation, causing a gap in the audio flow.  So, the @a
 131  * bufsize_callback can allocate storage, touch memory not previously
 132  * referenced, and perform other operations that are not realtime
 133  * safe.
 134  *
 135  * @param nframes buffer size
 136  * @param arg pointer supplied by jack_set_buffer_size_callback().
 137  *
 138  * @return zero on success, non-zero on error
 139  */
 140 typedef int  (*JackBufferSizeCallback)(jack_nframes_t nframes, void *arg);
 141
 142 /**
 143  * Prototype for the client supplied function that is called
 144  * when the engine sample rate changes.
 145  *
 146  * @param nframes new engine sample rate
 147  * @param arg pointer to a client supplied data
 148  *
 149  * @return zero on success, non-zero on error
 150  */
 151 typedef int  (*JackSampleRateCallback)(jack_nframes_t nframes, void *arg);
 152
 153 /**
 154  * Prototype for the client supplied function that is called
 155  * whenever a port is registered or unregistered.
 156  *
 157  * @param port the ID of the port
 158  * @param arg pointer to a client supplied data
 159  * @param register non-zero if the port is being registered,
 160  *                     zero if the port is being unregistered
 161  */
 162 typedef void (*JackPortRegistrationCallback)(jack_port_id_t port, int register, void *arg);
 163
 164 /**
 165  * Prototype for the client supplied function that is called
 166  * whenever a client is registered or unregistered.
 167  *
 168  * @param name a null-terminated string containing the client name
 169  * @param register non-zero if the client is being registered,
 170  *                     zero if the client is being unregistered
 171  * @param arg pointer to a client supplied data
 172  */
 173 typedef void (*JackClientRegistrationCallback)(const char* name, int register, void *arg);
 174
 175 /**
 176  * Prototype for the client supplied function that is called
 177  * whenever a client is registered or unregistered.
 178  *
 179  * @param a one of two ports connected or disconnected
 180  * @param b one of two ports connected or disconnected
 181  * @param connect non-zero if ports were connected
 182  *                    zero if ports were disconnected
 183  * @param arg pointer to a client supplied data
 184  */
 185 typedef void (*JackPortConnectCallback)(jack_port_id_t a, jack_port_id_t b, int connect, void* arg);
 186
 187 /**
 188  * Prototype for the client supplied function that is called
 189  * whenever jackd starts or stops freewheeling.
 190  *
 191  * @param starting non-zero if we start starting to freewheel, zero otherwise
 192  * @param arg pointer to a client supplied structure
 193  */
 194 typedef void (*JackFreewheelCallback)(int starting, void *arg);
 195
 196 typedef void *(*JackThreadCallback)(void* arg);
 197
 198 /**
 199  * Used for the type argument of jack_port_register() for default
 200  * audio and midi ports.
 201  */
 202 #define JACK_DEFAULT_AUDIO_TYPE "32 bit float mono audio"
 203 #define JACK_DEFAULT_MIDI_TYPE "8 bit raw midi"
 204
 205 /**
 206  * For convenience, use this typedef if you want to be able to change
 207  * between float and double. You may want to typedef sample_t to
 208  * jack_default_audio_sample_t in your application.
 209  */
 210 typedef float jack_default_audio_sample_t;
 211
 212 /**
 213  *  A port has a set of flags that are formed by AND-ing together the
 214  *  desired values from the list below. The flags "JackPortIsInput" and
 215  *  "JackPortIsOutput" are mutually exclusive and it is an error to use
 216  *  them both.
 217  */
 218 enum JackPortFlags {
 219
 220      /**
 221       * if JackPortIsInput is set, then the port can receive
 222       * data.
 223       */
 224      JackPortIsInput = 0x1,
 225
 226      /**
 227       * if JackPortIsOutput is set, then data can be read from
 228       * the port.
 229       */
 230      JackPortIsOutput = 0x2,
 231
 232      /**
 233       * if JackPortIsPhysical is set, then the port corresponds
 234       * to some kind of physical I/O connector.
 235       */
 236      JackPortIsPhysical = 0x4,
 237
 238      /**
 239       * if JackPortCanMonitor is set, then a call to
 240       * jack_port_request_monitor() makes sense.
 241       *
 242       * Precisely what this means is dependent on the client. A typical
 243       * result of it being called with TRUE as the second argument is
 244       * that data that would be available from an output port (with
 245       * JackPortIsPhysical set) is sent to a physical output connector
 246       * as well, so that it can be heard/seen/whatever.
 247       *
 248       * Clients that do not control physical interfaces
 249       * should never create ports with this bit set.
 250       */
 251      JackPortCanMonitor = 0x8,
 252
 253      /**
 254       * JackPortIsTerminal means:
 255       *
 256       * for an input port: the data received by the port
 257       *                    will not be passed on or made
 258       *                    available at any other port
 259       *
 260       * for an output port: the data available at the port
 261       *                    does not originate from any other port
 262       *
 263       * Audio synthesizers, I/O hardware interface clients, HDR
 264       * systems are examples of clients that would set this flag for
 265       * their ports.
 266       */
 267      JackPortIsTerminal = 0x10
 268 };
 269
 270 /**
 271  *  @ref jack_options_t bits
 272  */
 273 enum JackOptions {
 274
 275      /**
 276       * Null value to use when no option bits are needed.
 277       */
 278      JackNullOption = 0x00,
 279
 280      /**
 281       * Do not automatically start the JACK server when it is not
 282       * already running.  This option is always selected if
 283       * \$JACK_NO_START_SERVER is defined in the calling process
 284       * environment.
 285       */
 286      JackNoStartServer = 0x01,
 287
 288      /**
 289       * Use the exact client name requested.  Otherwise, JACK
 290       * automatically generates a unique one, if needed.
 291       */
 292      JackUseExactName = 0x02,
 293
 294      /**
 295       * Open with optional <em>(char *) server_name</em> parameter.
 296       */
 297      JackServerName = 0x04,
 298
 299      /**
 300       * Load internal client from optional <em>(char *)
 301       * load_name</em>.  Otherwise use the @a client_name.
 302       */
 303      JackLoadName = 0x08,
 304
 305      /**
 306       * Pass optional <em>(char *) load_init</em> string to the
 307       * jack_initialize() entry point of an internal client.
 308       */
 309      JackLoadInit = 0x10
 310 };
 311
 312 /** Valid options for opening an external client. */
 313 #define JackOpenOptions (JackServerName|JackNoStartServer|JackUseExactName)
 314
 315 /** Valid options for loading an internal client. */
 316 #define JackLoadOptions (JackLoadInit|JackLoadName|JackUseExactName)
 317
 318 /**
 319  *  Options for several JACK operations, formed by OR-ing together the
 320  *  relevant @ref JackOptions bits.
 321  */
 322 typedef enum JackOptions jack_options_t;
 323
 324 /**
 325  *  @ref jack_status_t bits
 326  */
 327 enum JackStatus {
 328
 329      /**
 330       * Overall operation failed.
 331       */
 332      JackFailure = 0x01,
 333
 334      /**
 335       * The operation contained an invalid or unsupported option.
 336       */
 337      JackInvalidOption = 0x02,
 338
 339      /**
 340       * The desired client name was not unique.  With the @ref
 341       * JackUseExactName option this situation is fatal.  Otherwise,
 342       * the name was modified by appending a dash and a two-digit
 343       * number in the range "-01" to "-99".  The
 344       * jack_get_client_name() function will return the exact string
 345       * that was used.  If the specified @a client_name plus these
 346       * extra characters would be too long, the open fails instead.
 347       */
 348      JackNameNotUnique = 0x04,
 349
 350      /**
 351       * The JACK server was started as a result of this operation.
 352       * Otherwise, it was running already.  In either case the caller
 353       * is now connected to jackd, so there is no race condition.
 354       * When the server shuts down, the client will find out.
 355       */
 356      JackServerStarted = 0x08,
 357
 358      /**
 359       * Unable to connect to the JACK server.
 360       */
 361      JackServerFailed = 0x10,
 362
 363      /**
 364       * Communication error with the JACK server.
 365       */
 366      JackServerError = 0x20,
 367
 368      /**
 369       * Requested client does not exist.
 370       */
 371      JackNoSuchClient = 0x40,
 372
 373      /**
 374       * Unable to load internal client
 375       */
 376      JackLoadFailure = 0x80,
 377
 378      /**
 379       * Unable to initialize client
 380       */
 381      JackInitFailure = 0x100,
 382
 383      /**
 384       * Unable to access shared memory
 385       */
 386      JackShmFailure = 0x200,
 387
 388      /**
 389       * Client's protocol version does not match
 390       */
 391      JackVersionError = 0x400
 392 };
 393
 394 /**
 395  *  Status word returned from several JACK operations, formed by
 396  *  OR-ing together the relevant @ref JackStatus bits.
 397  */
 398 typedef enum JackStatus jack_status_t;
 399
 400 #endif /* __jack_types_h__ */