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.
263
struct _jack_latency_range
273
} POST_PACKED_STRUCTURE;
275
typedef struct _jack_latency_range jack_latency_range_t;
278
* Prototype for the client supplied function that is called
279
* by the engine anytime there is work to be done.
281
* @pre nframes == jack_get_buffer_size()
282
* @pre nframes == pow(2,x)
284
* @param nframes number of frames to process
285
* @param arg pointer to a client supplied structure
287
* @return zero on success, non-zero on error
289
typedef int (*JackProcessCallback)(jack_nframes_t nframes, void *arg);
292
* Prototype for the client thread routine called
293
* by the engine when the client is inserted in the graph.
295
* @param arg pointer to a client supplied structure
298
typedef void *(*JackThreadCallback)(void* arg);
301
* Prototype for the client supplied function that is called
302
* once after the creation of the thread in which other
303
* callbacks will be made. Special thread characteristics
304
* can be set from this callback, for example. This is a
305
* highly specialized callback and most clients will not
306
* and should not use it.
308
* @param arg pointer to a client supplied structure
312
typedef void (*JackThreadInitCallback)(void *arg);
315
* Prototype for the client supplied function that is called
316
* whenever the processing graph is reordered.
318
* @param arg pointer to a client supplied structure
320
* @return zero on success, non-zero on error
322
typedef int (*JackGraphOrderCallback)(void *arg);
325
* Prototype for the client-supplied function that is called whenever
326
* an xrun has occured.
328
* @see jack_get_xrun_delayed_usecs()
330
* @param arg pointer to a client supplied structure
332
* @return zero on success, non-zero on error
334
typedef int (*JackXRunCallback)(void *arg);
337
* Prototype for the @a bufsize_callback that is invoked whenever the
338
* JACK engine buffer size changes. Although this function is called
339
* in the JACK process thread, the normal process cycle is suspended
340
* during its operation, causing a gap in the audio flow. So, the @a
341
* bufsize_callback can allocate storage, touch memory not previously
342
* referenced, and perform other operations that are not realtime
345
* @param nframes buffer size
346
* @param arg pointer supplied by jack_set_buffer_size_callback().
348
* @return zero on success, non-zero on error
350
typedef int (*JackBufferSizeCallback)(jack_nframes_t nframes, void *arg);
353
* Prototype for the client supplied function that is called
354
* when the engine sample rate changes.
356
* @param nframes new engine sample rate
357
* @param arg pointer to a client supplied structure
359
* @return zero on success, non-zero on error
361
typedef int (*JackSampleRateCallback)(jack_nframes_t nframes, void *arg);
364
* Prototype for the client supplied function that is called
365
* whenever a port is registered or unregistered.
367
* @param port the ID of the port
368
* @param arg pointer to a client supplied data
369
* @param register non-zero if the port is being registered,
370
* zero if the port is being unregistered
372
typedef void (*JackPortRegistrationCallback)(jack_port_id_t port, int register, void *arg);
375
* Prototype for the client supplied function that is called
376
* whenever a client is registered or unregistered.
378
* @param name a null-terminated string containing the client name
379
* @param register non-zero if the client is being registered,
380
* zero if the client is being unregistered
381
* @param arg pointer to a client supplied structure
383
typedef void (*JackClientRegistrationCallback)(const char* name, int register, void *arg);
386
* Prototype for the client supplied function that is called
387
* whenever a port is connected or disconnected.
389
* @param a one of two ports connected or disconnected
390
* @param b one of two ports connected or disconnected
391
* @param connect non-zero if ports were connected
392
* zero if ports were disconnected
393
* @param arg pointer to a client supplied data
395
typedef void (*JackPortConnectCallback)(jack_port_id_t a, jack_port_id_t b, int connect, void* arg);
398
* Prototype for the client supplied function that is called
399
* whenever the port name has been changed.
401
* @param port the port that has been renamed
402
* @param new_name the new name
403
* @param arg pointer to a client supplied structure
405
* @return zero on success, non-zero on error
407
typedef int (*JackPortRenameCallback)(jack_port_id_t port, const char* old_name, const char* new_name, void *arg);
410
* Prototype for the client supplied function that is called
411
* whenever jackd starts or stops freewheeling.
413
* @param starting non-zero if we start starting to freewheel, zero otherwise
414
* @param arg pointer to a client supplied structure
416
typedef void (*JackFreewheelCallback)(int starting, void *arg);
419
* Prototype for the client supplied function that is called
420
* whenever jackd is shutdown. Note that after server shutdown,
421
* the client pointer is *not* deallocated by libjack,
422
* the application is responsible to properly use jack_client_close()
423
* to release client ressources. Warning: jack_client_close() cannot be
424
* safely used inside the shutdown callback and has to be called outside of
425
* the callback context.
427
* @param arg pointer to a client supplied structure
429
typedef void (*JackShutdownCallback)(void *arg);
432
* Prototype for the client supplied function that is called
433
* whenever jackd is shutdown. Note that after server shutdown,
434
* the client pointer is *not* deallocated by libjack,
435
* the application is responsible to properly use jack_client_close()
436
* to release client ressources. Warning: jack_client_close() cannot be
437
* safely used inside the shutdown callback and has to be called outside of
438
* the callback context.
440
* @param code a status word, formed by OR-ing together the relevant @ref JackStatus bits.
441
* @param reason a string describing the shutdown reason (backend failure, server crash... etc...)
442
* @param arg pointer to a client supplied structure
444
typedef void (*JackInfoShutdownCallback)(jack_status_t code, const char* reason, void *arg);
447
* Used for the type argument of jack_port_register() for default
448
* audio ports and midi ports.
450
#define JACK_DEFAULT_AUDIO_TYPE "32 bit float mono audio"
451
#define JACK_DEFAULT_MIDI_TYPE "8 bit raw midi"
454
* For convenience, use this typedef if you want to be able to change
455
* between float and double. You may want to typedef sample_t to
456
* jack_default_audio_sample_t in your application.
458
typedef float jack_default_audio_sample_t;
461
* A port has a set of flags that are formed by AND-ing together the
462
* desired values from the list below. The flags "JackPortIsInput" and
463
* "JackPortIsOutput" are mutually exclusive and it is an error to use
469
* if JackPortIsInput is set, then the port can receive
472
JackPortIsInput = 0x1,
475
* if JackPortIsOutput is set, then data can be read from
478
JackPortIsOutput = 0x2,
481
* if JackPortIsPhysical is set, then the port corresponds
482
* to some kind of physical I/O connector.
484
JackPortIsPhysical = 0x4,
487
* if JackPortCanMonitor is set, then a call to
488
* jack_port_request_monitor() makes sense.
490
* Precisely what this means is dependent on the client. A typical
491
* result of it being called with TRUE as the second argument is
492
* that data that would be available from an output port (with
493
* JackPortIsPhysical set) is sent to a physical output connector
494
* as well, so that it can be heard/seen/whatever.
496
* Clients that do not control physical interfaces
497
* should never create ports with this bit set.
499
JackPortCanMonitor = 0x8,
502
* JackPortIsTerminal means:
504
* for an input port: the data received by the port
505
* will not be passed on or made
506
* available at any other port
508
* for an output port: the data available at the port
509
* does not originate from any other port
511
* Audio synthesizers, I/O hardware interface clients, HDR
512
* systems are examples of clients that would set this flag for
515
JackPortIsTerminal = 0x10,
524
/* the order matters for binary compatibility */
525
JackTransportStopped = 0, /**< Transport halted */
526
JackTransportRolling = 1, /**< Transport playing */
527
JackTransportLooping = 2, /**< For OLD_TRANSPORT, now ignored */
528
JackTransportStarting = 3, /**< Waiting for sync ready */
529
JackTransportNetStarting = 4, /**< Waiting for sync ready on the network*/
531
} jack_transport_state_t;
533
typedef uint64_t jack_unique_t; /**< Unique ID (opaque) */
536
* Optional struct jack_position_t fields.
540
JackPositionBBT = 0x10, /**< Bar, Beat, Tick */
541
JackPositionTimecode = 0x20, /**< External timecode */
542
JackBBTFrameOffset = 0x40, /**< Frame offset of BBT information */
543
JackAudioVideoRatio = 0x80, /**< audio frames per video frame */
544
JackVideoFrameOffset = 0x100 /**< frame offset of first video frame */
546
} jack_position_bits_t;
548
/** all valid position bits */
549
#define JACK_POSITION_MASK (JackPositionBBT|JackPositionTimecode)
550
#define EXTENDED_TIME_INFO
553
struct _jack_position {
555
/* these four cannot be set from clients: the server sets them */
556
jack_unique_t unique_1; /**< unique ID */
557
jack_time_t usecs; /**< monotonic, free-rolling */
558
jack_nframes_t frame_rate; /**< current frame rate (per second) */
559
jack_nframes_t frame; /**< frame number, always present */
561
jack_position_bits_t valid; /**< which other fields are valid */
563
/* JackPositionBBT fields: */
564
int32_t bar; /**< current bar */
565
int32_t beat; /**< current beat-within-bar */
566
int32_t tick; /**< current tick-within-beat */
567
double bar_start_tick;
569
float beats_per_bar; /**< time signature "numerator" */
570
float beat_type; /**< time signature "denominator" */
571
double ticks_per_beat;
572
double beats_per_minute;
574
/* JackPositionTimecode fields: (EXPERIMENTAL: could change) */
575
double frame_time; /**< current time in seconds */
576
double next_time; /**< next sequential frame_time
577
(unless repositioned) */
579
/* JackBBTFrameOffset fields: */
580
jack_nframes_t bbt_offset; /**< frame offset for the BBT fields
581
(the given bar, beat, and tick
582
values actually refer to a time
583
frame_offset frames before the
584
start of the cycle), should
585
be assumed to be 0 if
586
JackBBTFrameOffset is not
587
set. If JackBBTFrameOffset is
588
set and this value is zero, the BBT
589
time refers to the first frame of this
590
cycle. If the value is positive,
591
the BBT time refers to a frame that
592
many frames before the start of the
595
/* JACK video positional data (experimental) */
597
float audio_frames_per_video_frame; /**< number of audio frames
598
per video frame. Should be assumed
599
zero if JackAudioVideoRatio is not
600
set. If JackAudioVideoRatio is set
601
and the value is zero, no video
602
data exists within the JACK graph */
604
jack_nframes_t video_offset; /**< audio frame at which the first video
605
frame in this cycle occurs. Should
606
be assumed to be 0 if JackVideoFrameOffset
607
is not set. If JackVideoFrameOffset is
608
set, but the value is zero, there is
609
no video frame within this cycle. */
611
/* For binary compatibility, new fields should be allocated from
612
* this padding area with new valid bits controlling access, so
613
* the existing structure size and offsets are preserved. */
616
/* When (unique_1 == unique_2) the contents are consistent. */
617
jack_unique_t unique_2; /**< unique ID */
619
} POST_PACKED_STRUCTURE;
621
typedef struct _jack_position jack_position_t;
624
* Prototype for the @a sync_callback defined by slow-sync clients.
625
* When the client is active, this callback is invoked just before
626
* process() in the same thread. This occurs once after registration,
627
* then subsequently whenever some client requests a new position, or
628
* the transport enters the ::JackTransportStarting state. This
629
* realtime function must not wait.
631
* The transport @a state will be:
633
* - ::JackTransportStopped when a new position is requested;
634
* - ::JackTransportStarting when the transport is waiting to start;
635
* - ::JackTransportRolling when the timeout has expired, and the
636
* position is now a moving target.
638
* @param state current transport state.
639
* @param pos new transport position.
640
* @param arg the argument supplied by jack_set_sync_callback().
642
* @return TRUE (non-zero) when ready to roll.
644
typedef int (*JackSyncCallback)(jack_transport_state_t state,
645
jack_position_t *pos,
650
* Prototype for the @a timebase_callback used to provide extended
651
* position information. Its output affects all of the following
652
* process cycle. This realtime function must not wait.
654
* This function is called immediately after process() in the same
655
* thread whenever the transport is rolling, or when any client has
656
* requested a new position in the previous cycle. The first cycle
657
* after jack_set_timebase_callback() is also treated as a new
658
* position, or the first cycle after jack_activate() if the client
661
* The timebase master may not use its @a pos argument to set @a
662
* pos->frame. To change position, use jack_transport_reposition() or
663
* jack_transport_locate(). These functions are realtime-safe, the @a
664
* timebase_callback can call them directly.
666
* @param state current transport state.
667
* @param nframes number of frames in current period.
668
* @param pos address of the position structure for the next cycle; @a
669
* pos->frame will be its frame number. If @a new_pos is FALSE, this
670
* structure contains extended position information from the current
671
* cycle. If TRUE, it contains whatever was set by the requester.
672
* The @a timebase_callback's task is to update the extended
674
* @param new_pos TRUE (non-zero) for a newly requested @a pos, or for
675
* the first cycle after the @a timebase_callback is defined.
676
* @param arg the argument supplied by jack_set_timebase_callback().
678
typedef void (*JackTimebaseCallback)(jack_transport_state_t state,
679
jack_nframes_t nframes,
680
jack_position_t *pos,
684
/*********************************************************************
685
* The following interfaces are DEPRECATED. They are only provided
686
* for compatibility with the earlier JACK transport implementation.
687
*********************************************************************/
690
* Optional struct jack_transport_info_t fields.
692
* @see jack_position_bits_t.
696
JackTransportState = 0x1, /**< Transport state */
697
JackTransportPosition = 0x2, /**< Frame number */
698
JackTransportLoop = 0x4, /**< Loop boundaries (ignored) */
699
JackTransportSMPTE = 0x8, /**< SMPTE (ignored) */
700
JackTransportBBT = 0x10 /**< Bar, Beat, Tick */
702
} jack_transport_bits_t;
705
* Deprecated struct for transport position information.
707
* @deprecated This is for compatibility with the earlier transport
708
* interface. Use the jack_position_t struct, instead.
712
/* these two cannot be set from clients: the server sets them */
714
jack_nframes_t frame_rate; /**< current frame rate (per second) */
715
jack_time_t usecs; /**< monotonic, free-rolling */
717
jack_transport_bits_t valid; /**< which fields are legal to read */
718
jack_transport_state_t transport_state;
719
jack_nframes_t frame;
720
jack_nframes_t loop_start;
721
jack_nframes_t loop_end;
723
long smpte_offset; /**< SMPTE offset (from frame 0) */
724
float smpte_frame_rate; /**< 29.97, 30, 24 etc. */
729
double bar_start_tick;
733
double ticks_per_beat;
734
double beats_per_minute;
736
} jack_transport_info_t;
739
#endif /* __jack_types_h__ */
added
removed
os/win/include/jack/types.h
