2
Copyright (C) 2001 Paul Davis
3
Copyright (C) 2004 Jack O'Quin
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.
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.
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.
21
#ifndef __jack_types_h__
22
#define __jack_types_h__
24
#include <jack/systemdeps.h>
26
typedef int32_t jack_shmsize_t;
29
* Type used to represent sample frame counts.
31
typedef uint32_t jack_nframes_t;
34
* Maximum value that can be stored in jack_nframes_t
36
#define JACK_MAX_FRAMES (4294967295U) /* This should be UINT32_MAX, but C++ has a problem with that. */
39
* Type used to represent the value of free running
40
* monotonic clock with units of microseconds.
42
typedef uint64_t jack_time_t;
45
* Maximum size of @a load_init string passed to an internal client
46
* jack_initialize() function via jack_internal_client_load().
48
#define JACK_LOAD_INIT_LIMIT 1024
51
* jack_intclient_t is an opaque type representing a loaded internal
52
* client. You may only access it using the API provided in @ref
53
* intclient.h "<jack/intclient.h>".
55
typedef uint64_t jack_intclient_t;
58
* jack_port_t is an opaque type. You may only access it using the
61
typedef struct _jack_port jack_port_t;
64
* jack_client_t is an opaque type. You may only access it using the
67
typedef struct _jack_client jack_client_t;
70
* Ports have unique ids. A port registration callback is the only
71
* place you ever need to know their value.
73
typedef uint32_t jack_port_id_t;
75
typedef uint32_t jack_port_type_id_t;
78
* @ref jack_options_t bits
83
* Null value to use when no option bits are needed.
85
JackNullOption = 0x00,
88
* Do not automatically start the JACK server when it is not
89
* already running. This option is always selected if
90
* \$JACK_NO_START_SERVER is defined in the calling process
93
JackNoStartServer = 0x01,
96
* Use the exact client name requested. Otherwise, JACK
97
* automatically generates a unique one, if needed.
99
JackUseExactName = 0x02,
102
* Open with optional <em>(char *) server_name</em> parameter.
104
JackServerName = 0x04,
107
* Load internal client from optional <em>(char *)
108
* load_name</em>. Otherwise use the @a client_name.
113
* Pass optional <em>(char *) load_init</em> string to the
114
* jack_initialize() entry point of an internal client.
119
* pass a SessionID Token this allows the sessionmanager to identify the client again.
124
/** Valid options for opening an external client. */
125
#define JackOpenOptions (JackSessionID|JackServerName|JackNoStartServer|JackUseExactName)
127
/** Valid options for loading an internal client. */
128
#define JackLoadOptions (JackLoadInit|JackLoadName|JackUseExactName)
131
* Options for several JACK operations, formed by OR-ing together the
132
* relevant @ref JackOptions bits.
134
typedef enum JackOptions jack_options_t;
137
* @ref jack_status_t bits
142
* Overall operation failed.
147
* The operation contained an invalid or unsupported option.
149
JackInvalidOption = 0x02,
152
* The desired client name was not unique. With the @ref
153
* JackUseExactName option this situation is fatal. Otherwise,
154
* the name was modified by appending a dash and a two-digit
155
* number in the range "-01" to "-99". The
156
* jack_get_client_name() function will return the exact string
157
* that was used. If the specified @a client_name plus these
158
* extra characters would be too long, the open fails instead.
160
JackNameNotUnique = 0x04,
163
* The JACK server was started as a result of this operation.
164
* Otherwise, it was running already. In either case the caller
165
* is now connected to jackd, so there is no race condition.
166
* When the server shuts down, the client will find out.
168
JackServerStarted = 0x08,
171
* Unable to connect to the JACK server.
173
JackServerFailed = 0x10,
176
* Communication error with the JACK server.
178
JackServerError = 0x20,
181
* Requested client does not exist.
183
JackNoSuchClient = 0x40,
186
* Unable to load internal client
188
JackLoadFailure = 0x80,
191
* Unable to initialize client
193
JackInitFailure = 0x100,
196
* Unable to access shared memory
198
JackShmFailure = 0x200,
201
* Client's protocol version does not match
203
JackVersionError = 0x400,
208
JackBackendError = 0x800,
211
* Client zombified failure
213
JackClientZombie = 0x1000
217
* Status word returned from several JACK operations, formed by
218
* OR-ing together the relevant @ref JackStatus bits.
220
typedef enum JackStatus jack_status_t;
223
* @ref jack_latency_callback_mode_t
225
enum JackLatencyCallbackMode {
228
* Latency Callback for Capture Latency.
229
* Input Ports have their latency value setup.
230
* In the Callback the client needs to set the latency of the output ports
235
* Latency Callback for Playback Latency.
236
* Output Ports have their latency value setup.
237
* In the Callback the client needs to set the latency of the input ports
244
* Type of Latency Callback (Capture or Playback)
246
typedef enum JackLatencyCallbackMode jack_latency_callback_mode_t;
249
* Prototype for the client supplied function that is called
250
* by the engine when port latencies need to be recalculated
252
* @param mode playback or capture latency
253
* @param arg pointer to a client supplied data
255
* @return zero on success, non-zero on error
257
typedef void (*JackLatencyCallback)(jack_latency_callback_mode_t mode, void *arg);
260
* the new latency API operates on Ranges.
262
struct _jack_latency_range
274
typedef struct _jack_latency_range jack_latency_range_t;
277
* Prototype for the client supplied function that is called
278
* by the engine anytime there is work to be done.
280
* @pre nframes == jack_get_buffer_size()
281
* @pre nframes == pow(2,x)
283
* @param nframes number of frames to process
284
* @param arg pointer to a client supplied structure
286
* @return zero on success, non-zero on error
288
typedef int (*JackProcessCallback)(jack_nframes_t nframes, void *arg);
291
* Prototype for the client thread routine called
292
* by the engine when the client is inserted in the graph.
294
* @param arg pointer to a client supplied structure
297
typedef void *(*JackThreadCallback)(void* arg);
300
* Prototype for the client supplied function that is called
301
* once after the creation of the thread in which other
302
* callbacks will be made. Special thread characteristics
303
* can be set from this callback, for example. This is a
304
* highly specialized callback and most clients will not
305
* and should not use it.
307
* @param arg pointer to a client supplied structure
311
typedef void (*JackThreadInitCallback)(void *arg);
314
* Prototype for the client supplied function that is called
315
* whenever the processing graph is reordered.
317
* @param arg pointer to a client supplied structure
319
* @return zero on success, non-zero on error
321
typedef int (*JackGraphOrderCallback)(void *arg);
324
* Prototype for the client-supplied function that is called whenever
325
* an xrun has occured.
327
* @see jack_get_xrun_delayed_usecs()
329
* @param arg pointer to a client supplied structure
331
* @return zero on success, non-zero on error
333
typedef int (*JackXRunCallback)(void *arg);
336
* Prototype for the @a bufsize_callback that is invoked whenever the
337
* JACK engine buffer size changes. Although this function is called
338
* in the JACK process thread, the normal process cycle is suspended
339
* during its operation, causing a gap in the audio flow. So, the @a
340
* bufsize_callback can allocate storage, touch memory not previously
341
* referenced, and perform other operations that are not realtime
344
* @param nframes buffer size
345
* @param arg pointer supplied by jack_set_buffer_size_callback().
347
* @return zero on success, non-zero on error
349
typedef int (*JackBufferSizeCallback)(jack_nframes_t nframes, void *arg);
352
* Prototype for the client supplied function that is called
353
* when the engine sample rate changes.
355
* @param nframes new engine sample rate
356
* @param arg pointer to a client supplied structure
358
* @return zero on success, non-zero on error
360
typedef int (*JackSampleRateCallback)(jack_nframes_t nframes, void *arg);
363
* Prototype for the client supplied function that is called
364
* whenever a port is registered or unregistered.
366
* @param port the ID of the port
367
* @param arg pointer to a client supplied data
368
* @param register non-zero if the port is being registered,
369
* zero if the port is being unregistered
371
typedef void (*JackPortRegistrationCallback)(jack_port_id_t port, int register, void *arg);
374
* Prototype for the client supplied function that is called
375
* whenever a client is registered or unregistered.
377
* @param name a null-terminated string containing the client name
378
* @param register non-zero if the client is being registered,
379
* zero if the client is being unregistered
380
* @param arg pointer to a client supplied structure
382
typedef void (*JackClientRegistrationCallback)(const char* name, int register, void *arg);
385
* Prototype for the client supplied function that is called
386
* whenever a port is connected or disconnected.
388
* @param a one of two ports connected or disconnected
389
* @param b one of two ports connected or disconnected
390
* @param connect non-zero if ports were connected
391
* zero if ports were disconnected
392
* @param arg pointer to a client supplied data
394
typedef void (*JackPortConnectCallback)(jack_port_id_t a, jack_port_id_t b, int connect, void* arg);
397
* Prototype for the client supplied function that is called
398
* whenever the port name has been changed.
400
* @param port the port that has been renamed
401
* @param new_name the new name
402
* @param arg pointer to a client supplied structure
404
* @return zero on success, non-zero on error
406
typedef int (*JackPortRenameCallback)(jack_port_id_t port, const char* old_name, const char* new_name, void *arg);
409
* Prototype for the client supplied function that is called
410
* whenever jackd starts or stops freewheeling.
412
* @param starting non-zero if we start starting to freewheel, zero otherwise
413
* @param arg pointer to a client supplied structure
415
typedef void (*JackFreewheelCallback)(int starting, void *arg);
418
* Prototype for the client supplied function that is called
419
* whenever jackd is shutdown. Note that after server shutdown,
420
* the client pointer is *not* deallocated by libjack,
421
* the application is responsible to properly use jack_client_close()
422
* to release client ressources. Warning: jack_client_close() cannot be
423
* safely used inside the shutdown callback and has to be called outside of
424
* the callback context.
426
* @param arg pointer to a client supplied structure
428
typedef void (*JackShutdownCallback)(void *arg);
431
* Prototype for the client supplied function that is called
432
* whenever jackd is shutdown. Note that after server shutdown,
433
* the client pointer is *not* deallocated by libjack,
434
* the application is responsible to properly use jack_client_close()
435
* to release client ressources. Warning: jack_client_close() cannot be
436
* safely used inside the shutdown callback and has to be called outside of
437
* the callback context.
439
* @param code a status word, formed by OR-ing together the relevant @ref JackStatus bits.
440
* @param reason a string describing the shutdown reason (backend failure, server crash... etc...)
441
* @param arg pointer to a client supplied structure
443
typedef void (*JackInfoShutdownCallback)(jack_status_t code, const char* reason, void *arg);
446
* Used for the type argument of jack_port_register() for default
447
* audio ports and midi ports.
449
#define JACK_DEFAULT_AUDIO_TYPE "32 bit float mono audio"
450
#define JACK_DEFAULT_MIDI_TYPE "8 bit raw midi"
453
* For convenience, use this typedef if you want to be able to change
454
* between float and double. You may want to typedef sample_t to
455
* jack_default_audio_sample_t in your application.
457
typedef float jack_default_audio_sample_t;
460
* A port has a set of flags that are formed by AND-ing together the
461
* desired values from the list below. The flags "JackPortIsInput" and
462
* "JackPortIsOutput" are mutually exclusive and it is an error to use
468
* if JackPortIsInput is set, then the port can receive
471
JackPortIsInput = 0x1,
474
* if JackPortIsOutput is set, then data can be read from
477
JackPortIsOutput = 0x2,
480
* if JackPortIsPhysical is set, then the port corresponds
481
* to some kind of physical I/O connector.
483
JackPortIsPhysical = 0x4,
486
* if JackPortCanMonitor is set, then a call to
487
* jack_port_request_monitor() makes sense.
489
* Precisely what this means is dependent on the client. A typical
490
* result of it being called with TRUE as the second argument is
491
* that data that would be available from an output port (with
492
* JackPortIsPhysical set) is sent to a physical output connector
493
* as well, so that it can be heard/seen/whatever.
495
* Clients that do not control physical interfaces
496
* should never create ports with this bit set.
498
JackPortCanMonitor = 0x8,
501
* JackPortIsTerminal means:
503
* for an input port: the data received by the port
504
* will not be passed on or made
505
* available at any other port
507
* for an output port: the data available at the port
508
* does not originate from any other port
510
* Audio synthesizers, I/O hardware interface clients, HDR
511
* systems are examples of clients that would set this flag for
514
JackPortIsTerminal = 0x10,
523
/* the order matters for binary compatibility */
524
JackTransportStopped = 0, /**< Transport halted */
525
JackTransportRolling = 1, /**< Transport playing */
526
JackTransportLooping = 2, /**< For OLD_TRANSPORT, now ignored */
527
JackTransportStarting = 3, /**< Waiting for sync ready */
528
JackTransportNetStarting = 4, /**< Waiting for sync ready on the network*/
530
} jack_transport_state_t;
532
typedef uint64_t jack_unique_t; /**< Unique ID (opaque) */
535
* Optional struct jack_position_t fields.
539
JackPositionBBT = 0x10, /**< Bar, Beat, Tick */
540
JackPositionTimecode = 0x20, /**< External timecode */
541
JackBBTFrameOffset = 0x40, /**< Frame offset of BBT information */
542
JackAudioVideoRatio = 0x80, /**< audio frames per video frame */
543
JackVideoFrameOffset = 0x100 /**< frame offset of first video frame */
545
} jack_position_bits_t;
547
/** all valid position bits */
548
#define JACK_POSITION_MASK (JackPositionBBT|JackPositionTimecode)
549
#define EXTENDED_TIME_INFO
553
/* these four cannot be set from clients: the server sets them */
554
jack_unique_t unique_1; /**< unique ID */
555
jack_time_t usecs; /**< monotonic, free-rolling */
556
jack_nframes_t frame_rate; /**< current frame rate (per second) */
557
jack_nframes_t frame; /**< frame number, always present */
559
jack_position_bits_t valid; /**< which other fields are valid */
561
/* JackPositionBBT fields: */
562
int32_t bar; /**< current bar */
563
int32_t beat; /**< current beat-within-bar */
564
int32_t tick; /**< current tick-within-beat */
565
double bar_start_tick;
567
float beats_per_bar; /**< time signature "numerator" */
568
float beat_type; /**< time signature "denominator" */
569
double ticks_per_beat;
570
double beats_per_minute;
572
/* JackPositionTimecode fields: (EXPERIMENTAL: could change) */
573
double frame_time; /**< current time in seconds */
574
double next_time; /**< next sequential frame_time
575
(unless repositioned) */
577
/* JackBBTFrameOffset fields: */
578
jack_nframes_t bbt_offset; /**< frame offset for the BBT fields
579
(the given bar, beat, and tick
580
values actually refer to a time
581
frame_offset frames before the
582
start of the cycle), should
583
be assumed to be 0 if
584
JackBBTFrameOffset is not
585
set. If JackBBTFrameOffset is
586
set and this value is zero, the BBT
587
time refers to the first frame of this
588
cycle. If the value is positive,
589
the BBT time refers to a frame that
590
many frames before the start of the
593
/* JACK video positional data (experimental) */
595
float audio_frames_per_video_frame; /**< number of audio frames
596
per video frame. Should be assumed
597
zero if JackAudioVideoRatio is not
598
set. If JackAudioVideoRatio is set
599
and the value is zero, no video
600
data exists within the JACK graph */
602
jack_nframes_t video_offset; /**< audio frame at which the first video
603
frame in this cycle occurs. Should
604
be assumed to be 0 if JackVideoFrameOffset
605
is not set. If JackVideoFrameOffset is
606
set, but the value is zero, there is
607
no video frame within this cycle. */
609
/* For binary compatibility, new fields should be allocated from
610
* this padding area with new valid bits controlling access, so
611
* the existing structure size and offsets are preserved. */
614
/* When (unique_1 == unique_2) the contents are consistent. */
615
jack_unique_t unique_2; /**< unique ID */
620
* Prototype for the @a sync_callback defined by slow-sync clients.
621
* When the client is active, this callback is invoked just before
622
* process() in the same thread. This occurs once after registration,
623
* then subsequently whenever some client requests a new position, or
624
* the transport enters the ::JackTransportStarting state. This
625
* realtime function must not wait.
627
* The transport @a state will be:
629
* - ::JackTransportStopped when a new position is requested;
630
* - ::JackTransportStarting when the transport is waiting to start;
631
* - ::JackTransportRolling when the timeout has expired, and the
632
* position is now a moving target.
634
* @param state current transport state.
635
* @param pos new transport position.
636
* @param arg the argument supplied by jack_set_sync_callback().
638
* @return TRUE (non-zero) when ready to roll.
640
typedef int (*JackSyncCallback)(jack_transport_state_t state,
641
jack_position_t *pos,
646
* Prototype for the @a timebase_callback used to provide extended
647
* position information. Its output affects all of the following
648
* process cycle. This realtime function must not wait.
650
* This function is called immediately after process() in the same
651
* thread whenever the transport is rolling, or when any client has
652
* requested a new position in the previous cycle. The first cycle
653
* after jack_set_timebase_callback() is also treated as a new
654
* position, or the first cycle after jack_activate() if the client
657
* The timebase master may not use its @a pos argument to set @a
658
* pos->frame. To change position, use jack_transport_reposition() or
659
* jack_transport_locate(). These functions are realtime-safe, the @a
660
* timebase_callback can call them directly.
662
* @param state current transport state.
663
* @param nframes number of frames in current period.
664
* @param pos address of the position structure for the next cycle; @a
665
* pos->frame will be its frame number. If @a new_pos is FALSE, this
666
* structure contains extended position information from the current
667
* cycle. If TRUE, it contains whatever was set by the requester.
668
* The @a timebase_callback's task is to update the extended
670
* @param new_pos TRUE (non-zero) for a newly requested @a pos, or for
671
* the first cycle after the @a timebase_callback is defined.
672
* @param arg the argument supplied by jack_set_timebase_callback().
674
typedef void (*JackTimebaseCallback)(jack_transport_state_t state,
675
jack_nframes_t nframes,
676
jack_position_t *pos,
680
/*********************************************************************
681
* The following interfaces are DEPRECATED. They are only provided
682
* for compatibility with the earlier JACK transport implementation.
683
*********************************************************************/
686
* Optional struct jack_transport_info_t fields.
688
* @see jack_position_bits_t.
692
JackTransportState = 0x1, /**< Transport state */
693
JackTransportPosition = 0x2, /**< Frame number */
694
JackTransportLoop = 0x4, /**< Loop boundaries (ignored) */
695
JackTransportSMPTE = 0x8, /**< SMPTE (ignored) */
696
JackTransportBBT = 0x10 /**< Bar, Beat, Tick */
698
} jack_transport_bits_t;
701
* Deprecated struct for transport position information.
703
* @deprecated This is for compatibility with the earlier transport
704
* interface. Use the jack_position_t struct, instead.
708
/* these two cannot be set from clients: the server sets them */
710
jack_nframes_t frame_rate; /**< current frame rate (per second) */
711
jack_time_t usecs; /**< monotonic, free-rolling */
713
jack_transport_bits_t valid; /**< which fields are legal to read */
714
jack_transport_state_t transport_state;
715
jack_nframes_t frame;
716
jack_nframes_t loop_start;
717
jack_nframes_t loop_end;
719
long smpte_offset; /**< SMPTE offset (from frame 0) */
720
float smpte_frame_rate; /**< 29.97, 30, 24 etc. */
725
double bar_start_tick;
729
double ticks_per_beat;
730
double beats_per_minute;
732
} jack_transport_info_t;
735
#endif /* __jack_types_h__ */
added
removed
os/mac/include/jack/types.h
