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 <jack/systemdeps.h> 25 26 typedef uint64_t jack_uuid_t; 27 28 typedef int32_t jack_shmsize_t; 29 30 /** 31 * Type used to represent sample frame counts. 32 */ 33 typedef uint32_t jack_nframes_t; 34 35 /** 36 * Maximum value that can be stored in jack_nframes_t 37 */ 38 #define JACK_MAX_FRAMES (4294967295U) /* This should be UINT32_MAX, but C++ has a problem with that. */ 39 40 /** 41 * Type used to represent the value of free running 42 * monotonic clock with units of microseconds. 43 */ 44 typedef uint64_t jack_time_t; 45 46 /** 47 * Maximum size of @a load_init string passed to an internal client 48 * jack_initialize() function via jack_internal_client_load(). 49 */ 50 #define JACK_LOAD_INIT_LIMIT 1024 51 52 /** 53 * jack_intclient_t is an opaque type representing a loaded internal 54 * client. You may only access it using the API provided in @ref 55 * intclient.h "<jack/intclient.h>". 56 */ 57 typedef uint64_t jack_intclient_t; 58 59 /** 60 * jack_port_t is an opaque type. You may only access it using the 61 * API provided. 62 */ 63 typedef struct _jack_port jack_port_t; 64 65 /** 66 * jack_client_t is an opaque type. You may only access it using the 67 * API provided. 68 */ 69 typedef struct _jack_client jack_client_t; 70 71 /** 72 * Ports have unique ids. A port registration callback is the only 73 * place you ever need to know their value. 74 */ 75 typedef uint32_t jack_port_id_t; 76 77 typedef uint32_t jack_port_type_id_t; 78 79 /** 80 * @ref jack_options_t bits 81 */ 82 enum JackOptions { 83 84 /** 85 * Null value to use when no option bits are needed. 86 */ 87 JackNullOption = 0x00, 88 89 /** 90 * Do not automatically start the JACK server when it is not 91 * already running. This option is always selected if 92 * \$JACK_NO_START_SERVER is defined in the calling process 93 * environment. 94 */ 95 JackNoStartServer = 0x01, 96 97 /** 98 * Use the exact client name requested. Otherwise, JACK 99 * automatically generates a unique one, if needed. 100 */ 101 JackUseExactName = 0x02, 102 103 /** 104 * Open with optional <em>(char *) server_name</em> parameter. 105 */ 106 JackServerName = 0x04, 107 108 /** 109 * Load internal client from optional <em>(char *) 110 * load_name</em>. Otherwise use the @a client_name. 111 */ 112 JackLoadName = 0x08, 113 114 /** 115 * Pass optional <em>(char *) load_init</em> string to the 116 * jack_initialize() entry point of an internal client. 117 */ 118 JackLoadInit = 0x10, 119 120 /** 121 * pass a SessionID Token this allows the sessionmanager to identify the client again. 122 */ 123 JackSessionID = 0x20 124 }; 125 126 /** Valid options for opening an external client. */ 127 #define JackOpenOptions (JackSessionID|JackServerName|JackNoStartServer|JackUseExactName) 128 129 /** Valid options for loading an internal client. */ 130 #define JackLoadOptions (JackLoadInit|JackLoadName|JackUseExactName) 131 132 /** 133 * Options for several JACK operations, formed by OR-ing together the 134 * relevant @ref JackOptions bits. 135 */ 136 typedef enum JackOptions jack_options_t; 137 138 /** 139 * @ref jack_status_t bits 140 */ 141 enum JackStatus { 142 143 /** 144 * Overall operation failed. 145 */ 146 JackFailure = 0x01, 147 148 /** 149 * The operation contained an invalid or unsupported option. 150 */ 151 JackInvalidOption = 0x02, 152 153 /** 154 * The desired client name was not unique. With the @ref 155 * JackUseExactName option this situation is fatal. Otherwise, 156 * the name was modified by appending a dash and a two-digit 157 * number in the range "-01" to "-99". The 158 * jack_get_client_name() function will return the exact string 159 * that was used. If the specified @a client_name plus these 160 * extra characters would be too long, the open fails instead. 161 */ 162 JackNameNotUnique = 0x04, 163 164 /** 165 * The JACK server was started as a result of this operation. 166 * Otherwise, it was running already. In either case the caller 167 * is now connected to jackd, so there is no race condition. 168 * When the server shuts down, the client will find out. 169 */ 170 JackServerStarted = 0x08, 171 172 /** 173 * Unable to connect to the JACK server. 174 */ 175 JackServerFailed = 0x10, 176 177 /** 178 * Communication error with the JACK server. 179 */ 180 JackServerError = 0x20, 181 182 /** 183 * Requested client does not exist. 184 */ 185 JackNoSuchClient = 0x40, 186 187 /** 188 * Unable to load internal client 189 */ 190 JackLoadFailure = 0x80, 191 192 /** 193 * Unable to initialize client 194 */ 195 JackInitFailure = 0x100, 196 197 /** 198 * Unable to access shared memory 199 */ 200 JackShmFailure = 0x200, 201 202 /** 203 * Client's protocol version does not match 204 */ 205 JackVersionError = 0x400, 206 207 /** 208 * Backend error 209 */ 210 JackBackendError = 0x800, 211 212 /** 213 * Client zombified failure 214 */ 215 JackClientZombie = 0x1000 216 }; 217 218 /** 219 * Status word returned from several JACK operations, formed by 220 * OR-ing together the relevant @ref JackStatus bits. 221 */ 222 typedef enum JackStatus jack_status_t; 223 224 /** 225 * @ref jack_latency_callback_mode_t 226 */ 227 enum JackLatencyCallbackMode { 228 229 /** 230 * Latency Callback for Capture Latency. 231 * Input Ports have their latency value setup. 232 * In the Callback the client needs to set the latency of the output ports 233 */ 234 JackCaptureLatency, 235 236 /** 237 * Latency Callback for Playback Latency. 238 * Output Ports have their latency value setup. 239 * In the Callback the client needs to set the latency of the input ports 240 */ 241 JackPlaybackLatency 242 243 }; 244 245 /** 246 * Type of Latency Callback (Capture or Playback) 247 */ 248 typedef enum JackLatencyCallbackMode jack_latency_callback_mode_t; 249 250 /** 251 * Prototype for the client supplied function that is called 252 * by the engine when port latencies need to be recalculated 253 * 254 * @param mode playback or capture latency 255 * @param arg pointer to a client supplied data 256 * 257 * @return zero on success, non-zero on error 258 */ 259 typedef void (*JackLatencyCallback)(jack_latency_callback_mode_t mode, void *arg); 260 261 /** 262 * the new latency API operates on Ranges. 263 */ 264 PRE_PACKED_STRUCTURE 265 struct _jack_latency_range 266 { 267 /** 268 * minimum latency 269 */ 270 jack_nframes_t min; 271 /** 272 * maximum latency 273 */ 274 jack_nframes_t max; 275 } POST_PACKED_STRUCTURE; 276 277 typedef struct _jack_latency_range jack_latency_range_t; 278 279 /** 280 * Prototype for the client supplied function that is called 281 * by the engine anytime there is work to be done. 282 * 283 * @pre nframes == jack_get_buffer_size() 284 * @pre nframes == pow(2,x) 285 * 286 * @param nframes number of frames to process 287 * @param arg pointer to a client supplied structure 288 * 289 * @return zero on success, non-zero on error 290 */ 291 typedef int (*JackProcessCallback)(jack_nframes_t nframes, void *arg); 292 293 /** 294 * Prototype for the client thread routine called 295 * by the engine when the client is inserted in the graph. 296 * 297 * @param arg pointer to a client supplied structure 298 * 299 */ 300 typedef void *(*JackThreadCallback)(void* arg); 301 302 /** 303 * Prototype for the client supplied function that is called 304 * once after the creation of the thread in which other 305 * callbacks will be made. Special thread characteristics 306 * can be set from this callback, for example. This is a 307 * highly specialized callback and most clients will not 308 * and should not use it. 309 * 310 * @param arg pointer to a client supplied structure 311 * 312 * @return void 313 */ 314 typedef void (*JackThreadInitCallback)(void *arg); 315 316 /** 317 * Prototype for the client supplied function that is called 318 * whenever the processing graph is reordered. 319 * 320 * @param arg pointer to a client supplied structure 321 * 322 * @return zero on success, non-zero on error 323 */ 324 typedef int (*JackGraphOrderCallback)(void *arg); 325 326 /** 327 * Prototype for the client-supplied function that is called whenever 328 * an xrun has occurred. 329 * 330 * @see jack_get_xrun_delayed_usecs() 331 * 332 * @param arg pointer to a client supplied structure 333 * 334 * @return zero on success, non-zero on error 335 */ 336 typedef int (*JackXRunCallback)(void *arg); 337 338 /** 339 * Prototype for the @a bufsize_callback that is invoked whenever the 340 * JACK engine buffer size changes. Although this function is called 341 * in the JACK process thread, the normal process cycle is suspended 342 * during its operation, causing a gap in the audio flow. So, the @a 343 * bufsize_callback can allocate storage, touch memory not previously 344 * referenced, and perform other operations that are not realtime 345 * safe. 346 * 347 * @param nframes buffer size 348 * @param arg pointer supplied by jack_set_buffer_size_callback(). 349 * 350 * @return zero on success, non-zero on error 351 */ 352 typedef int (*JackBufferSizeCallback)(jack_nframes_t nframes, void *arg); 353 354 /** 355 * Prototype for the client supplied function that is called 356 * when the engine sample rate changes. 357 * 358 * @param nframes new engine sample rate 359 * @param arg pointer to a client supplied structure 360 * 361 * @return zero on success, non-zero on error 362 */ 363 typedef int (*JackSampleRateCallback)(jack_nframes_t nframes, void *arg); 364 365 /** 366 * Prototype for the client supplied function that is called 367 * whenever a port is registered or unregistered. 368 * 369 * @param port the ID of the port 370 * @param arg pointer to a client supplied data 371 * @param register non-zero if the port is being registered, 372 * zero if the port is being unregistered 373 */ 374 typedef void (*JackPortRegistrationCallback)(jack_port_id_t port, int /* register */, void *arg); 375 376 /** 377 * Prototype for the client supplied function that is called 378 * whenever a client is registered or unregistered. 379 * 380 * @param name a null-terminated string containing the client name 381 * @param register non-zero if the client is being registered, 382 * zero if the client is being unregistered 383 * @param arg pointer to a client supplied structure 384 */ 385 typedef void (*JackClientRegistrationCallback)(const char* name, int /* register */, void *arg); 386 387 /** 388 * Prototype for the client supplied function that is called 389 * whenever a port is connected or disconnected. 390 * 391 * @param a one of two ports connected or disconnected 392 * @param b one of two ports connected or disconnected 393 * @param connect non-zero if ports were connected 394 * zero if ports were disconnected 395 * @param arg pointer to a client supplied data 396 */ 397 typedef void (*JackPortConnectCallback)(jack_port_id_t a, jack_port_id_t b, int connect, void* arg); 398 399 /** 400 * Prototype for the client supplied function that is called 401 * whenever the port name has been changed. 402 * 403 * @param port the port that has been renamed 404 * @param new_name the new name 405 * @param arg pointer to a client supplied structure 406 */ 407 typedef void (*JackPortRenameCallback)(jack_port_id_t port, const char* old_name, const char* new_name, void *arg); 408 409 /** 410 * Prototype for the client supplied function that is called 411 * whenever jackd starts or stops freewheeling. 412 * 413 * @param starting non-zero if we start starting to freewheel, zero otherwise 414 * @param arg pointer to a client supplied structure 415 */ 416 typedef void (*JackFreewheelCallback)(int starting, void *arg); 417 418 /** 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 resources. Warning: jack_client_close() cannot be 424 * safely used inside the shutdown callback and has to be called outside of 425 * the callback context. 426 * 427 * @param arg pointer to a client supplied structure 428 */ 429 typedef void (*JackShutdownCallback)(void *arg); 430 431 /** 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 resources. Warning: jack_client_close() cannot be 437 * safely used inside the shutdown callback and has to be called outside of 438 * the callback context. 439 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 * Note that this string will not be available anymore after the callback returns, so possibly copy it. 443 * @param arg pointer to a client supplied structure 444 */ 445 typedef void (*JackInfoShutdownCallback)(jack_status_t code, const char* reason, void *arg); 446 447 /** 448 * Used for the type argument of jack_port_register() for default 449 * audio ports and midi ports. 450 */ 451 #define JACK_DEFAULT_AUDIO_TYPE "32 bit float mono audio" 452 #define JACK_DEFAULT_MIDI_TYPE "8 bit raw midi" 453 454 /** 455 * For convenience, use this typedef if you want to be able to change 456 * between float and double. You may want to typedef sample_t to 457 * jack_default_audio_sample_t in your application. 458 */ 459 typedef float jack_default_audio_sample_t; 460 461 /** 462 * A port has a set of flags that are formed by AND-ing together the 463 * desired values from the list below. The flags "JackPortIsInput" and 464 * "JackPortIsOutput" are mutually exclusive and it is an error to use 465 * them both. 466 */ 467 enum JackPortFlags { 468 469 /** 470 * if JackPortIsInput is set, then the port can receive 471 * data. 472 */ 473 JackPortIsInput = 0x1, 474 475 /** 476 * if JackPortIsOutput is set, then data can be read from 477 * the port. 478 */ 479 JackPortIsOutput = 0x2, 480 481 /** 482 * if JackPortIsPhysical is set, then the port corresponds 483 * to some kind of physical I/O connector. 484 */ 485 JackPortIsPhysical = 0x4, 486 487 /** 488 * if JackPortCanMonitor is set, then a call to 489 * jack_port_request_monitor() makes sense. 490 * 491 * Precisely what this means is dependent on the client. A typical 492 * result of it being called with TRUE as the second argument is 493 * that data that would be available from an output port (with 494 * JackPortIsPhysical set) is sent to a physical output connector 495 * as well, so that it can be heard/seen/whatever. 496 * 497 * Clients that do not control physical interfaces 498 * should never create ports with this bit set. 499 */ 500 JackPortCanMonitor = 0x8, 501 502 /** 503 * JackPortIsTerminal means: 504 * 505 * for an input port: the data received by the port 506 * will not be passed on or made 507 * available at any other port 508 * 509 * for an output port: the data available at the port 510 * does not originate from any other port 511 * 512 * Audio synthesizers, I/O hardware interface clients, HDR 513 * systems are examples of clients that would set this flag for 514 * their ports. 515 */ 516 JackPortIsTerminal = 0x10, 517 518 }; 519 520 /** 521 * Transport states. 522 */ 523 typedef enum { 524 525 /* the order matters for binary compatibility */ 526 JackTransportStopped = 0, /**< Transport halted */ 527 JackTransportRolling = 1, /**< Transport playing */ 528 JackTransportLooping = 2, /**< For OLD_TRANSPORT, now ignored */ 529 JackTransportStarting = 3, /**< Waiting for sync ready */ 530 JackTransportNetStarting = 4, /**< Waiting for sync ready on the network*/ 531 532 } jack_transport_state_t; 533 534 typedef uint64_t jack_unique_t; /**< Unique ID (opaque) */ 535 536 /** 537 * Optional struct jack_position_t fields. 538 */ 539 typedef enum { 540 541 JackPositionBBT = 0x10, /**< Bar, Beat, Tick */ 542 JackPositionTimecode = 0x20, /**< External timecode */ 543 JackBBTFrameOffset = 0x40, /**< Frame offset of BBT information */ 544 JackAudioVideoRatio = 0x80, /**< audio frames per video frame */ 545 JackVideoFrameOffset = 0x100 /**< frame offset of first video frame */ 546 547 } jack_position_bits_t; 548 549 /** all valid position bits */ 550 #define JACK_POSITION_MASK (JackPositionBBT|JackPositionTimecode) 551 #define EXTENDED_TIME_INFO 552 553 PRE_PACKED_STRUCTURE 554 struct _jack_position { 555 556 /* these four cannot be set from clients: the server sets them */ 557 jack_unique_t unique_1; /**< unique ID */ 558 jack_time_t usecs; /**< monotonic, free-rolling */ 559 jack_nframes_t frame_rate; /**< current frame rate (per second) */ 560 jack_nframes_t frame; /**< frame number, always present */ 561 562 jack_position_bits_t valid; /**< which other fields are valid */ 563 564 /* JackPositionBBT fields: */ 565 int32_t bar; /**< current bar */ 566 int32_t beat; /**< current beat-within-bar */ 567 int32_t tick; /**< current tick-within-beat */ 568 double bar_start_tick; 569 570 float beats_per_bar; /**< time signature "numerator" */ 571 float beat_type; /**< time signature "denominator" */ 572 double ticks_per_beat; 573 double beats_per_minute; 574 575 /* JackPositionTimecode fields: (EXPERIMENTAL: could change) */ 576 double frame_time; /**< current time in seconds */ 577 double next_time; /**< next sequential frame_time 578 (unless repositioned) */ 579 580 /* JackBBTFrameOffset fields: */ 581 jack_nframes_t bbt_offset; /**< frame offset for the BBT fields 582 (the given bar, beat, and tick 583 values actually refer to a time 584 frame_offset frames before the 585 start of the cycle), should 586 be assumed to be 0 if 587 JackBBTFrameOffset is not 588 set. If JackBBTFrameOffset is 589 set and this value is zero, the BBT 590 time refers to the first frame of this 591 cycle. If the value is positive, 592 the BBT time refers to a frame that 593 many frames before the start of the 594 cycle. */ 595 596 /* JACK video positional data (experimental) */ 597 598 float audio_frames_per_video_frame; /**< number of audio frames 599 per video frame. Should be assumed 600 zero if JackAudioVideoRatio is not 601 set. If JackAudioVideoRatio is set 602 and the value is zero, no video 603 data exists within the JACK graph */ 604 605 jack_nframes_t video_offset; /**< audio frame at which the first video 606 frame in this cycle occurs. Should 607 be assumed to be 0 if JackVideoFrameOffset 608 is not set. If JackVideoFrameOffset is 609 set, but the value is zero, there is 610 no video frame within this cycle. */ 611 612 /* For binary compatibility, new fields should be allocated from 613 * this padding area with new valid bits controlling access, so 614 * the existing structure size and offsets are preserved. */ 615 int32_t padding[7]; 616 617 /* When (unique_1 == unique_2) the contents are consistent. */ 618 jack_unique_t unique_2; /**< unique ID */ 619 620 } POST_PACKED_STRUCTURE; 621 622 typedef struct _jack_position jack_position_t; 623 624 /** 625 * Prototype for the @a sync_callback defined by slow-sync clients. 626 * When the client is active, this callback is invoked just before 627 * process() in the same thread. This occurs once after registration, 628 * then subsequently whenever some client requests a new position, or 629 * the transport enters the ::JackTransportStarting state. This 630 * realtime function must not wait. 631 * 632 * The transport @a state will be: 633 * 634 * - ::JackTransportStopped when a new position is requested; 635 * - ::JackTransportStarting when the transport is waiting to start; 636 * - ::JackTransportRolling when the timeout has expired, and the 637 * position is now a moving target. 638 * 639 * @param state current transport state. 640 * @param pos new transport position. 641 * @param arg the argument supplied by jack_set_sync_callback(). 642 * 643 * @return TRUE (non-zero) when ready to roll. 644 */ 645 typedef int (*JackSyncCallback)(jack_transport_state_t state, 646 jack_position_t *pos, 647 void *arg); 648 649 650 /** 651 * Prototype for the @a timebase_callback used to provide extended 652 * position information. Its output affects all of the following 653 * process cycle. This realtime function must not wait. 654 * 655 * This function is called immediately after process() in the same 656 * thread whenever the transport is rolling, or when any client has 657 * requested a new position in the previous cycle. The first cycle 658 * after jack_set_timebase_callback() is also treated as a new 659 * position, or the first cycle after jack_activate() if the client 660 * had been inactive. 661 * 662 * The timebase master may not use its @a pos argument to set @a 663 * pos->frame. To change position, use jack_transport_reposition() or 664 * jack_transport_locate(). These functions are realtime-safe, the @a 665 * timebase_callback can call them directly. 666 * 667 * @param state current transport state. 668 * @param nframes number of frames in current period. 669 * @param pos address of the position structure for the next cycle; @a 670 * pos->frame will be its frame number. If @a new_pos is FALSE, this 671 * structure contains extended position information from the current 672 * cycle. If TRUE, it contains whatever was set by the requester. 673 * The @a timebase_callback's task is to update the extended 674 * information here. 675 * @param new_pos TRUE (non-zero) for a newly requested @a pos, or for 676 * the first cycle after the @a timebase_callback is defined. 677 * @param arg the argument supplied by jack_set_timebase_callback(). 678 */ 679 typedef void (*JackTimebaseCallback)(jack_transport_state_t state, 680 jack_nframes_t nframes, 681 jack_position_t *pos, 682 int new_pos, 683 void *arg); 684 685 /********************************************************************* 686 * The following interfaces are DEPRECATED. They are only provided 687 * for compatibility with the earlier JACK transport implementation. 688 *********************************************************************/ 689 690 /** 691 * Optional struct jack_transport_info_t fields. 692 * 693 * @see jack_position_bits_t. 694 */ 695 typedef enum { 696 697 JackTransportState = 0x1, /**< Transport state */ 698 JackTransportPosition = 0x2, /**< Frame number */ 699 JackTransportLoop = 0x4, /**< Loop boundaries (ignored) */ 700 JackTransportSMPTE = 0x8, /**< SMPTE (ignored) */ 701 JackTransportBBT = 0x10 /**< Bar, Beat, Tick */ 702 703 } jack_transport_bits_t; 704 705 /** 706 * Deprecated struct for transport position information. 707 * 708 * @deprecated This is for compatibility with the earlier transport 709 * interface. Use the jack_position_t struct, instead. 710 */ 711 typedef struct { 712 713 /* these two cannot be set from clients: the server sets them */ 714 715 jack_nframes_t frame_rate; /**< current frame rate (per second) */ 716 jack_time_t usecs; /**< monotonic, free-rolling */ 717 718 jack_transport_bits_t valid; /**< which fields are legal to read */ 719 jack_transport_state_t transport_state; 720 jack_nframes_t frame; 721 jack_nframes_t loop_start; 722 jack_nframes_t loop_end; 723 724 long smpte_offset; /**< SMPTE offset (from frame 0) */ 725 float smpte_frame_rate; /**< 29.97, 30, 24 etc. */ 726 727 int bar; 728 int beat; 729 int tick; 730 double bar_start_tick; 731 732 float beats_per_bar; 733 float beat_type; 734 double ticks_per_beat; 735 double beats_per_minute; 736 737 } jack_transport_info_t; 738 739 740 #endif /* __jack_types_h__ */ 741