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 structure
  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 structure
 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 structure
 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 structure
 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  * @parm  port the ID of the port
 158  * @param arg pointer to a client supplied structure
 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 structure
 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 jackd starts or stops freewheeling.
 178  *
 179  * @param starting non-zero if we start starting to freewheel, zero otherwise
 180  * @param arg pointer to a client supplied structure
 181  */
 182 typedef void (*JackFreewheelCallback)(int starting, void *arg);
 183
 184 /**
 185  * Used for the type argument of jack_port_register() for default
 186  * audio and midi ports.
 187  */
 188 #define JACK_DEFAULT_AUDIO_TYPE "32 bit float mono audio"
 189 #define JACK_DEFAULT_MIDI_TYPE "8 bit raw midi"
 190
 191 /**
 192  * For convenience, use this typedef if you want to be able to change
 193  * between float and double. You may want to typedef sample_t to
 194  * jack_default_audio_sample_t in your application.
 195  */
 196 typedef float jack_default_audio_sample_t;
 197
 198 /**
 199  *  A port has a set of flags that are formed by AND-ing together the
 200  *  desired values from the list below. The flags "JackPortIsInput" and
 201  *  "JackPortIsOutput" are mutually exclusive and it is an error to use
 202  *  them both.
 203  */
 204 enum JackPortFlags {
 205
 206      /**
 207       * if JackPortIsInput is set, then the port can receive
 208       * data.
 209       */
 210      JackPortIsInput = 0x1,
 211
 212      /**
 213       * if JackPortIsOutput is set, then data can be read from
 214       * the port.
 215       */
 216      JackPortIsOutput = 0x2,
 217
 218      /**
 219       * if JackPortIsPhysical is set, then the port corresponds
 220       * to some kind of physical I/O connector.
 221       */
 222      JackPortIsPhysical = 0x4,
 223
 224      /**
 225       * if JackPortCanMonitor is set, then a call to
 226       * jack_port_request_monitor() makes sense.
 227       *
 228       * Precisely what this means is dependent on the client. A typical
 229       * result of it being called with TRUE as the second argument is
 230       * that data that would be available from an output port (with
 231       * JackPortIsPhysical set) is sent to a physical output connector
 232       * as well, so that it can be heard/seen/whatever.
 233       *
 234       * Clients that do not control physical interfaces
 235       * should never create ports with this bit set.
 236       */
 237      JackPortCanMonitor = 0x8,
 238
 239      /**
 240       * JackPortIsTerminal means:
 241       *
 242       * for an input port: the data received by the port
 243       *                    will not be passed on or made
 244       *                    available at any other port
 245       *
 246       * for an output port: the data available at the port
 247       *                    does not originate from any other port
 248       *
 249       * Audio synthesizers, I/O hardware interface clients, HDR
 250       * systems are examples of clients that would set this flag for
 251       * their ports.
 252       */
 253      JackPortIsTerminal = 0x10
 254 };
 255
 256 /**
 257  *  @ref jack_options_t bits
 258  */
 259 enum JackOptions {
 260
 261      /**
 262       * Null value to use when no option bits are needed.
 263       */
 264      JackNullOption = 0x00,
 265
 266      /**
 267       * Do not automatically start the JACK server when it is not
 268       * already running.  This option is always selected if
 269       * \$JACK_NO_START_SERVER is defined in the calling process
 270       * environment.
 271       */
 272      JackNoStartServer = 0x01,
 273
 274      /**
 275       * Use the exact client name requested.  Otherwise, JACK
 276       * automatically generates a unique one, if needed.
 277       */
 278      JackUseExactName = 0x02,
 279
 280      /**
 281       * Open with optional <em>(char *) server_name</em> parameter.
 282       */
 283      JackServerName = 0x04,
 284
 285      /**
 286       * Load internal client from optional <em>(char *)
 287       * load_name</em>.  Otherwise use the @a client_name.
 288       */
 289      JackLoadName = 0x08,
 290
 291      /**
 292       * Pass optional <em>(char *) load_init</em> string to the
 293       * jack_initialize() entry point of an internal client.
 294       */
 295      JackLoadInit = 0x10
 296 };
 297
 298 /** Valid options for opening an external client. */
 299 #define JackOpenOptions (JackServerName|JackNoStartServer|JackUseExactName)
 300
 301 /** Valid options for loading an internal client. */
 302 #define JackLoadOptions (JackLoadInit|JackLoadName|JackUseExactName)
 303
 304 /**
 305  *  Options for several JACK operations, formed by OR-ing together the
 306  *  relevant @ref JackOptions bits.
 307  */
 308 typedef enum JackOptions jack_options_t;
 309
 310 /**
 311  *  @ref jack_status_t bits
 312  */
 313 enum JackStatus {
 314
 315      /**
 316       * Overall operation failed.
 317       */
 318      JackFailure = 0x01,
 319
 320      /**
 321       * The operation contained an invalid or unsupported option.
 322       */
 323      JackInvalidOption = 0x02,
 324
 325      /**
 326       * The desired client name was not unique.  With the @ref
 327       * JackUseExactName option this situation is fatal.  Otherwise,
 328       * the name was modified by appending a dash and a two-digit
 329       * number in the range "-01" to "-99".  The
 330       * jack_get_client_name() function will return the exact string
 331       * that was used.  If the specified @a client_name plus these
 332       * extra characters would be too long, the open fails instead.
 333       */
 334      JackNameNotUnique = 0x04,
 335
 336      /**
 337       * The JACK server was started as a result of this operation.
 338       * Otherwise, it was running already.  In either case the caller
 339       * is now connected to jackd, so there is no race condition.
 340       * When the server shuts down, the client will find out.
 341       */
 342      JackServerStarted = 0x08,
 343
 344      /**
 345       * Unable to connect to the JACK server.
 346       */
 347      JackServerFailed = 0x10,
 348
 349      /**
 350       * Communication error with the JACK server.
 351       */
 352      JackServerError = 0x20,
 353
 354      /**
 355       * Requested client does not exist.
 356       */
 357      JackNoSuchClient = 0x40,
 358
 359      /**
 360       * Unable to load internal client
 361       */
 362      JackLoadFailure = 0x80,
 363
 364      /**
 365       * Unable to initialize client
 366       */
 367      JackInitFailure = 0x100,
 368
 369      /**
 370       * Unable to access shared memory
 371       */
 372      JackShmFailure = 0x200,
 373
 374      /**
 375       * Client's protocol version does not match
 376       */
 377      JackVersionError = 0x400
 378 };
 379
 380 /**
 381  *  Status word returned from several JACK operations, formed by
 382  *  OR-ing together the relevant @ref JackStatus bits.
 383  */
 384 typedef enum JackStatus jack_status_t;
 385
 386 #endif /* __jack_types_h__ */