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_h__ 22 #define __jack_h__ 23 24 #ifdef __cplusplus 25 extern "C" 26 { 27 #endif 28 29 #include <jack/systemdeps.h> 30 #include <jack/types.h> 31 #include <jack/transport.h> 32 33 /** 34 * Note: More documentation can be found in jack/types.h. 35 */ 36 37 /************************************************************* 38 * NOTE: JACK_WEAK_EXPORT ***MUST*** be used on every function 39 * added to the JACK API after the 0.116.2 release. 40 * 41 * Functions that predate this release are marked with 42 * JACK_WEAK_OPTIONAL_EXPORT which can be defined at compile 43 * time in a variety of ways. The default definition is empty, 44 * so that these symbols get normal linkage. If you wish to 45 * use all JACK symbols with weak linkage, include 46 * <jack/weakjack.h> before jack.h. 47 *************************************************************/ 48 49 #include <jack/weakmacros.h> 50 51 /** 52 * Call this function to get version of the JACK, in form of several numbers 53 * 54 * @param major_ptr pointer to variable receiving major version of JACK. 55 * 56 * @param minor_ptr pointer to variable receiving minor version of JACK. 57 * 58 * @param major_ptr pointer to variable receiving micro version of JACK. 59 * 60 * @param major_ptr pointer to variable receiving protocol version of JACK. 61 * 62 */ 63 void 64 jack_get_version( 65 int *major_ptr, 66 int *minor_ptr, 67 int *micro_ptr, 68 int *proto_ptr) JACK_OPTIONAL_WEAK_EXPORT; 69 70 /** 71 * Call this function to get version of the JACK, in form of a string 72 * 73 * @return Human readable string describing JACK version being used. 74 * 75 */ 76 const char * 77 jack_get_version_string(void) JACK_OPTIONAL_WEAK_EXPORT; 78 79 /** 80 * @defgroup ClientFunctions Creating & manipulating clients 81 * @{ 82 */ 83 84 /** 85 * Open an external client session with a JACK server. This interface 86 * is more complex but more powerful than jack_client_new(). With it, 87 * clients may choose which of several servers to connect, and control 88 * whether and how to start the server automatically, if it was not 89 * already running. There is also an option for JACK to generate a 90 * unique client name, when necessary. 91 * 92 * @param client_name of at most jack_client_name_size() characters. 93 * The name scope is local to each server. Unless forbidden by the 94 * @ref JackUseExactName option, the server will modify this name to 95 * create a unique variant, if needed. 96 * 97 * @param options formed by OR-ing together @ref JackOptions bits. 98 * Only the @ref JackOpenOptions bits are allowed. 99 * 100 * @param status (if non-NULL) an address for JACK to return 101 * information from the open operation. This status word is formed by 102 * OR-ing together the relevant @ref JackStatus bits. 103 * 104 * 105 * <b>Optional parameters:</b> depending on corresponding [@a options 106 * bits] additional parameters may follow @a status (in this order). 107 * 108 * @arg [@ref JackServerName] <em>(char *) server_name</em> selects 109 * from among several possible concurrent server instances. Server 110 * names are unique to each user. If unspecified, use "default" 111 * unless \$JACK_DEFAULT_SERVER is defined in the process environment. 112 * 113 * @return Opaque client handle if successful. If this is NULL, the 114 * open operation failed, @a *status includes @ref JackFailure and the 115 * caller is not a JACK client. 116 */ 117 jack_client_t * jack_client_open (const char *client_name, 118 jack_options_t options, 119 jack_status_t *status, ...) JACK_OPTIONAL_WEAK_EXPORT; 120 121 /** 122 * \bold THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN 123 * NEW JACK CLIENTS 124 * 125 * @deprecated Please use jack_client_open(). 126 */ 127 jack_client_t * jack_client_new (const char *client_name) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT; 128 129 /** 130 * Disconnects an external client from a JACK server. 131 * 132 * @return 0 on success, otherwise a non-zero error code 133 */ 134 int jack_client_close (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT; 135 136 /** 137 * @return the maximum number of characters in a JACK client name 138 * including the final NULL character. This value is a constant. 139 */ 140 int jack_client_name_size (void) JACK_OPTIONAL_WEAK_EXPORT; 141 142 /** 143 * @return pointer to actual client name. This is useful when @ref 144 * JackUseExactName is not specified on open and @ref 145 * JackNameNotUnique status was returned. In that case, the actual 146 * name will differ from the @a client_name requested. 147 */ 148 char * jack_get_client_name (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT; 149 150 /** 151 * Get the session ID for a client name. 152 * 153 * The session manager needs this to reassociate a client name to the session_id. 154 * 155 * The caller is responsible for calling jack_free(3) on any non-NULL 156 * returned value. 157 */ 158 char *jack_get_uuid_for_client_name (jack_client_t *client, 159 const char *client_name) JACK_WEAK_EXPORT; 160 161 /** 162 * Get the client name for a session_id. 163 * 164 * In order to snapshot the graph connections, the session manager needs to map 165 * session_ids to client names. 166 * 167 * The caller is responsible for calling jack_free(3) on any non-NULL 168 * returned value. 169 */ 170 char *jack_get_client_name_by_uuid (jack_client_t *client, 171 const char *client_uuid ) JACK_WEAK_EXPORT; 172 173 /** 174 * Load an internal client into the Jack server. 175 * 176 * Internal clients run inside the JACK server process. They can use 177 * most of the same functions as external clients. Each internal 178 * client must declare jack_initialize() and jack_finish() entry 179 * points, called at load and unload times. See inprocess.c for an 180 * example of how to write an internal client. 181 * 182 * @deprecated Please use jack_internal_client_load(). 183 * 184 * @param client_name of at most jack_client_name_size() characters. 185 * 186 * @param load_name of a shared object file containing the code for 187 * the new client. 188 * 189 * @param load_init an arbitrary string passed to the jack_initialize() 190 * routine of the new client (may be NULL). 191 * 192 * @return 0 if successful. 193 */ 194 int jack_internal_client_new (const char *client_name, 195 const char *load_name, 196 const char *load_init) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT; 197 198 /** 199 * Remove an internal client from a JACK server. 200 * 201 * @deprecated Please use jack_internal_client_unload(). 202 */ 203 void jack_internal_client_close (const char *client_name) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT; 204 205 /** 206 * Tell the Jack server that the program is ready to start processing 207 * audio. 208 * 209 * @return 0 on success, otherwise a non-zero error code 210 */ 211 int jack_activate (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT; 212 213 /** 214 * Tell the Jack server to remove this @a client from the process 215 * graph. Also, disconnect all ports belonging to it, since inactive 216 * clients have no port connections. 217 * 218 * @return 0 on success, otherwise a non-zero error code 219 */ 220 int jack_deactivate (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT; 221 222 /** 223 * @return pid of client. If not available, 0 will be returned. 224 */ 225 int jack_get_client_pid (const char *name) JACK_OPTIONAL_WEAK_EXPORT; 226 227 /** 228 * @return the pthread ID of the thread running the JACK client side 229 * real-time code. 230 */ 231 jack_native_thread_t jack_client_thread_id (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT; 232 233 /*@}*/ 234 235 /** 236 * @param client pointer to JACK client structure. 237 * 238 * Check if the JACK subsystem is running with -R (--realtime). 239 * 240 * @return 1 if JACK is running realtime, 0 otherwise 241 */ 242 int jack_is_realtime (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT; 243 244 /** 245 * @defgroup NonCallbackAPI The non-callback API 246 * @{ 247 */ 248 249 /** 250 * \bold THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN 251 * NEW JACK CLIENTS. 252 * 253 * @deprecated Please use jack_cycle_wait() and jack_cycle_signal() functions. 254 */ 255 jack_nframes_t jack_thread_wait (jack_client_t *client, int status) JACK_OPTIONAL_WEAK_EXPORT; 256 257 /** 258 * Wait until this JACK client should process data. 259 * 260 * @param client - pointer to a JACK client structure 261 * 262 * @return the number of frames of data to process 263 */ 264 jack_nframes_t jack_cycle_wait (jack_client_t* client) JACK_OPTIONAL_WEAK_EXPORT; 265 266 /** 267 * Signal next clients in the graph. 268 * 269 * @param client - pointer to a JACK client structure 270 * @param status - if non-zero, calling thread should exit 271 */ 272 void jack_cycle_signal (jack_client_t* client, int status) JACK_OPTIONAL_WEAK_EXPORT; 273 274 /** 275 * Tell the Jack server to call @a thread_callback in the RT thread. 276 * Typical use are in conjunction with @a jack_cycle_wait and @a jack_cycle_signal functions. 277 * The code in the supplied function must be suitable for real-time 278 * execution. That means that it cannot call functions that might 279 * block for a long time. This includes malloc, free, printf, 280 * pthread_mutex_lock, sleep, wait, poll, select, pthread_join, 281 * pthread_cond_wait, etc, etc. See 282 * http://jackit.sourceforge.net/docs/design/design.html#SECTION00411000000000000000 283 * for more information. 284 * 285 * NOTE: this function cannot be called while the client is activated 286 * (after jack_activate has been called.) 287 * 288 * @return 0 on success, otherwise a non-zero error code. 289 */ 290 int jack_set_process_thread(jack_client_t* client, JackThreadCallback thread_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT; 291 292 /*@}*/ 293 294 /** 295 * @defgroup ClientCallbacks Setting Client Callbacks 296 * @{ 297 */ 298 299 /** 300 * Tell JACK to call @a thread_init_callback once just after 301 * the creation of the thread in which all other callbacks 302 * will be handled. 303 * 304 * The code in the supplied function does not need to be 305 * suitable for real-time execution. 306 * 307 * NOTE: this function cannot be called while the client is activated 308 * (after jack_activate has been called.) 309 * 310 * @return 0 on success, otherwise a non-zero error code, causing JACK 311 * to remove that client from the process() graph. 312 */ 313 int jack_set_thread_init_callback (jack_client_t *client, 314 JackThreadInitCallback thread_init_callback, 315 void *arg) JACK_OPTIONAL_WEAK_EXPORT; 316 317 /** 318 * @param client pointer to JACK client structure. 319 * @param function The jack_shutdown function pointer. 320 * @param arg The arguments for the jack_shutdown function. 321 * 322 * Register a function (and argument) to be called if and when the 323 * JACK server shuts down the client thread. The function must 324 * be written as if it were an asynchonrous POSIX signal 325 * handler --- use only async-safe functions, and remember that it 326 * is executed from another thread. A typical function might 327 * set a flag or write to a pipe so that the rest of the 328 * application knows that the JACK client thread has shut 329 * down. 330 * 331 * NOTE: clients do not need to call this. It exists only 332 * to help more complex clients understand what is going 333 * on. It should be called before jack_client_activate(). 334 * 335 * NOTE: if a client calls this AND jack_on_info_shutdown(), then 336 * in case of a client thread shutdown, the callback 337 * passed to this function will not be called, and the one passed to 338 * jack_on_info_shutdown() will. 339 * 340 * NOTE: application should typically signal another thread to correctly 341 * finish cleanup, that is by calling "jack_client_close" 342 * (since "jack_client_close" cannot be called directly in the context 343 * of the thread that calls the shutdown callback). 344 */ 345 void jack_on_shutdown (jack_client_t *client, 346 JackShutdownCallback shutdown_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT; 347 348 /** 349 * @param client pointer to JACK client structure. 350 * @param function The jack_info_shutdown function pointer. 351 * @param arg The arguments for the jack_info_shutdown function. 352 * 353 * Register a function (and argument) to be called if and when the 354 * JACK server shuts down the client thread. The function must 355 * be written as if it were an asynchonrous POSIX signal 356 * handler --- use only async-safe functions, and remember that it 357 * is executed from another thread. A typical function might 358 * set a flag or write to a pipe so that the rest of the 359 * application knows that the JACK client thread has shut 360 * down. 361 * 362 * NOTE: clients do not need to call this. It exists only 363 * to help more complex clients understand what is going 364 * on. It should be called before jack_client_activate(). 365 * 366 * NOTE: if a client calls this AND jack_on_shutdown(), then 367 * in case of a client thread shutdown, the callback passed to 368 * jack_on_info_shutdown() will be called. 369 * 370 * NOTE: application should typically signal another thread to correctly 371 * finish cleanup, that is by calling "jack_client_close" 372 * (since "jack_client_close" cannot be called directly in the context 373 * of the thread that calls the shutdown callback). 374 */ 375 void jack_on_info_shutdown (jack_client_t *client, 376 JackInfoShutdownCallback shutdown_callback, void *arg) JACK_WEAK_EXPORT; 377 378 /** 379 * Tell the Jack server to call @a process_callback whenever there is 380 * work be done, passing @a arg as the second argument. 381 * 382 * The code in the supplied function must be suitable for real-time 383 * execution. That means that it cannot call functions that might 384 * block for a long time. This includes malloc, free, printf, 385 * pthread_mutex_lock, sleep, wait, poll, select, pthread_join, 386 * pthread_cond_wait, etc, etc. See 387 * http://jackit.sourceforge.net/docs/design/design.html#SECTION00411000000000000000 388 * for more information. 389 * 390 * NOTE: this function cannot be called while the client is activated 391 * (after jack_activate has been called.) 392 * 393 * @return 0 on success, otherwise a non-zero error code. 394 */ 395 int jack_set_process_callback (jack_client_t *client, 396 JackProcessCallback process_callback, 397 void *arg) JACK_OPTIONAL_WEAK_EXPORT; 398 399 /** 400 * Tell the Jack server to call @a freewheel_callback 401 * whenever we enter or leave "freewheel" mode, passing @a 402 * arg as the second argument. The first argument to the 403 * callback will be non-zero if JACK is entering freewheel 404 * mode, and zero otherwise. 405 * 406 * All "notification events" are received in a separated non RT thread, 407 * the code in the supplied function does not need to be 408 * suitable for real-time execution. 409 * 410 * NOTE: this function cannot be called while the client is activated 411 * (after jack_activate has been called.) 412 * 413 * @return 0 on success, otherwise a non-zero error code. 414 */ 415 int jack_set_freewheel_callback (jack_client_t *client, 416 JackFreewheelCallback freewheel_callback, 417 void *arg) JACK_OPTIONAL_WEAK_EXPORT; 418 419 /** 420 * Tell JACK to call @a bufsize_callback whenever the size of the the 421 * buffer that will be passed to the @a process_callback is about to 422 * change. Clients that depend on knowing the buffer size must supply 423 * a @a bufsize_callback before activating themselves. 424 * 425 * All "notification events" are received in a separated non RT thread, 426 * the code in the supplied function does not need to be 427 * suitable for real-time execution. 428 * 429 * NOTE: this function cannot be called while the client is activated 430 * (after jack_activate has been called.) 431 * 432 * @param client pointer to JACK client structure. 433 * @param bufsize_callback function to call when the buffer size changes. 434 * @param arg argument for @a bufsize_callback. 435 * 436 * @return 0 on success, otherwise a non-zero error code 437 */ 438 int jack_set_buffer_size_callback (jack_client_t *client, 439 JackBufferSizeCallback bufsize_callback, 440 void *arg) JACK_OPTIONAL_WEAK_EXPORT; 441 442 /** 443 * Tell the Jack server to call @a srate_callback whenever the system 444 * sample rate changes. 445 * 446 * All "notification events" are received in a separated non RT thread, 447 * the code in the supplied function does not need to be 448 * suitable for real-time execution. 449 * 450 * NOTE: this function cannot be called while the client is activated 451 * (after jack_activate has been called.) 452 * 453 * @return 0 on success, otherwise a non-zero error code 454 */ 455 int jack_set_sample_rate_callback (jack_client_t *client, 456 JackSampleRateCallback srate_callback, 457 void *arg) JACK_OPTIONAL_WEAK_EXPORT; 458 459 /** 460 * Tell the JACK server to call @a client_registration_callback whenever a 461 * client is registered or unregistered, passing @a arg as a parameter. 462 * 463 * All "notification events" are received in a separated non RT thread, 464 * the code in the supplied function does not need to be 465 * suitable for real-time execution. 466 * 467 * NOTE: this function cannot be called while the client is activated 468 * (after jack_activate has been called.) 469 * 470 * @return 0 on success, otherwise a non-zero error code 471 */ 472 int jack_set_client_registration_callback (jack_client_t *client, 473 JackClientRegistrationCallback 474 registration_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT; 475 476 /** 477 * Tell the JACK server to call @a registration_callback whenever a 478 * port is registered or unregistered, passing @a arg as a parameter. 479 * 480 * All "notification events" are received in a separated non RT thread, 481 * the code in the supplied function does not need to be 482 * suitable for real-time execution. 483 * 484 * NOTE: this function cannot be called while the client is activated 485 * (after jack_activate has been called.) 486 * 487 * @return 0 on success, otherwise a non-zero error code 488 */ 489 int jack_set_port_registration_callback (jack_client_t *client, 490 JackPortRegistrationCallback 491 registration_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT; 492 493 /** 494 * Tell the JACK server to call @a connect_callback whenever a 495 * port is connected or disconnected, passing @a arg as a parameter. 496 * 497 * All "notification events" are received in a separated non RT thread, 498 * the code in the supplied function does not need to be 499 * suitable for real-time execution. 500 * 501 * NOTE: this function cannot be called while the client is activated 502 * (after jack_activate has been called.) 503 * 504 * @return 0 on success, otherwise a non-zero error code 505 */ 506 int jack_set_port_connect_callback (jack_client_t *client, 507 JackPortConnectCallback 508 connect_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT; 509 510 /** 511 * Tell the JACK server to call @a rename_callback whenever a 512 * port is renamed, passing @a arg as a parameter. 513 * 514 * All "notification events" are received in a separated non RT thread, 515 * the code in the supplied function does not need to be 516 * suitable for real-time execution. 517 * 518 * NOTE: this function cannot be called while the client is activated 519 * (after jack_activate has been called.) 520 * 521 * @return 0 on success, otherwise a non-zero error code 522 */ 523 int jack_set_port_rename_callback (jack_client_t *client, 524 JackPortRenameCallback 525 rename_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT; 526 527 /** 528 * Tell the JACK server to call @a graph_callback whenever the 529 * processing graph is reordered, passing @a arg as a parameter. 530 * 531 * All "notification events" are received in a separated non RT thread, 532 * the code in the supplied function does not need to be 533 * suitable for real-time execution. 534 * 535 * NOTE: this function cannot be called while the client is activated 536 * (after jack_activate has been called.) 537 * 538 * @return 0 on success, otherwise a non-zero error code 539 */ 540 int jack_set_graph_order_callback (jack_client_t *client, 541 JackGraphOrderCallback graph_callback, 542 void *) JACK_OPTIONAL_WEAK_EXPORT; 543 544 /** 545 * Tell the JACK server to call @a xrun_callback whenever there is a 546 * xrun, passing @a arg as a parameter. 547 * 548 * All "notification events" are received in a separated non RT thread, 549 * the code in the supplied function does not need to be 550 * suitable for real-time execution. 551 * 552 * NOTE: this function cannot be called while the client is activated 553 * (after jack_activate has been called.) 554 * 555 * @return 0 on success, otherwise a non-zero error code 556 */ 557 int jack_set_xrun_callback (jack_client_t *client, 558 JackXRunCallback xrun_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT; 559 560 /*@}*/ 561 562 /** 563 * Tell the Jack server to call @a latency_callback whenever it 564 * is necessary to recompute the latencies for some or all 565 * Jack ports. 566 * 567 * @a latency_callback will be called twice each time it is 568 * needed, once being passed JackCaptureLatency and once 569 * JackPlaybackLatency. See @ref LatencyFunctions for 570 * the definition of each type of latency and related functions. 571 * 572 * <b>IMPORTANT: Most JACK clients do NOT need to register a latency 573 * callback.</b> 574 * 575 * Clients that meet any of the following conditions do NOT 576 * need to register a latency callback: 577 * 578 * - have only input ports 579 * - have only output ports 580 * - their output is totally unrelated to their input 581 * - their output is not delayed relative to their input 582 * (i.e. data that arrives in a given process() 583 * callback is processed and output again in the 584 * same callback) 585 * 586 * Clients NOT registering a latency callback MUST also 587 * satisfy this condition: 588 * 589 * - have no multiple distinct internal signal pathways 590 * 591 * This means that if your client has more than 1 input and 592 * output port, and considers them always "correlated" 593 * (e.g. as a stereo pair), then there is only 1 (e.g. stereo) 594 * signal pathway through the client. This would be true, 595 * for example, of a stereo FX rack client that has a 596 * left/right input pair and a left/right output pair. 597 * 598 * However, this is somewhat a matter of perspective. The 599 * same FX rack client could be connected so that its 600 * two input ports were connected to entirely separate 601 * sources. Under these conditions, the fact that the client 602 * does not register a latency callback MAY result 603 * in port latency values being incorrect. 604 * 605 * Clients that do not meet any of those conditions SHOULD 606 * register a latency callback. 607 * 608 * Another case is when a client wants to use 609 * @ref jack_port_get_latency_range(), which only returns meaninful 610 * values when ports get connected and latency values change. 611 * 612 * See the documentation for @ref jack_port_set_latency_range() 613 * on how the callback should operate. Remember that the @a mode 614 * argument given to the latency callback will need to be 615 * passed into @ref jack_port_set_latency_range() 616 * 617 * @return 0 on success, otherwise a non-zero error code 618 */ 619 int jack_set_latency_callback (jack_client_t *client, 620 JackLatencyCallback latency_callback, 621 void *) JACK_WEAK_EXPORT; 622 /*@}*/ 623 624 /** 625 * @defgroup ServerClientControl Controlling & querying JACK server operation 626 * @{ 627 */ 628 629 /** 630 * Start/Stop JACK's "freewheel" mode. 631 * 632 * When in "freewheel" mode, JACK no longer waits for 633 * any external event to begin the start of the next process 634 * cycle. 635 * 636 * As a result, freewheel mode causes "faster than realtime" 637 * execution of a JACK graph. If possessed, real-time 638 * scheduling is dropped when entering freewheel mode, and 639 * if appropriate it is reacquired when stopping. 640 * 641 * IMPORTANT: on systems using capabilities to provide real-time 642 * scheduling (i.e. Linux kernel 2.4), if onoff is zero, this function 643 * must be called from the thread that originally called jack_activate(). 644 * This restriction does not apply to other systems (e.g. Linux kernel 2.6 645 * or OS X). 646 * 647 * @param client pointer to JACK client structure 648 * @param onoff if non-zero, freewheel mode starts. Otherwise 649 * freewheel mode ends. 650 * 651 * @return 0 on success, otherwise a non-zero error code. 652 */ 653 int jack_set_freewheel(jack_client_t* client, int onoff) JACK_OPTIONAL_WEAK_EXPORT; 654 655 /** 656 * Change the buffer size passed to the @a process_callback. 657 * 658 * This operation stops the JACK engine process cycle, then calls all 659 * registered @a bufsize_callback functions before restarting the 660 * process cycle. This will cause a gap in the audio flow, so it 661 * should only be done at appropriate stopping points. 662 * 663 * @see jack_set_buffer_size_callback() 664 * 665 * @param client pointer to JACK client structure. 666 * @param nframes new buffer size. Must be a power of two. 667 * 668 * @return 0 on success, otherwise a non-zero error code 669 */ 670 int jack_set_buffer_size (jack_client_t *client, jack_nframes_t nframes) JACK_OPTIONAL_WEAK_EXPORT; 671 672 /** 673 * @return the sample rate of the jack system, as set by the user when 674 * jackd was started. 675 */ 676 jack_nframes_t jack_get_sample_rate (jack_client_t *) JACK_OPTIONAL_WEAK_EXPORT; 677 678 /** 679 * @return the current maximum size that will ever be passed to the @a 680 * process_callback. It should only be used *before* the client has 681 * been activated. This size may change, clients that depend on it 682 * must register a @a bufsize_callback so they will be notified if it 683 * does. 684 * 685 * @see jack_set_buffer_size_callback() 686 */ 687 jack_nframes_t jack_get_buffer_size (jack_client_t *) JACK_OPTIONAL_WEAK_EXPORT; 688 689 /** 690 * Old-style interface to become the timebase for the entire JACK 691 * subsystem. 692 * 693 * @deprecated This function still exists for compatibility with the 694 * earlier transport interface, but it does nothing. Instead, see 695 * transport.h and use jack_set_timebase_callback(). 696 * 697 * @return ENOSYS, function not implemented. 698 */ 699 int jack_engine_takeover_timebase (jack_client_t *) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT; 700 701 /** 702 * @return the current CPU load estimated by JACK. This is a running 703 * average of the time it takes to execute a full process cycle for 704 * all clients as a percentage of the real time available per cycle 705 * determined by the buffer size and sample rate. 706 */ 707 float jack_cpu_load (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT; 708 709 /*@}*/ 710 711 /** 712 * @defgroup PortFunctions Creating & manipulating ports 713 * @{ 714 */ 715 716 /** 717 * Create a new port for the client. This is an object used for moving 718 * data of any type in or out of the client. Ports may be connected 719 * in various ways. 720 * 721 * Each port has a short name. The port's full name contains the name 722 * of the client concatenated with a colon (:) followed by its short 723 * name. The jack_port_name_size() is the maximum length of this full 724 * name. Exceeding that will cause the port registration to fail and 725 * return NULL. 726 * 727 * The @a port_name must be unique among all ports owned by this client. 728 * If the name is not unique, the registration will fail. 729 * 730 * All ports have a type, which may be any non-NULL and non-zero 731 * length string, passed as an argument. Some port types are built 732 * into the JACK API, currently only JACK_DEFAULT_AUDIO_TYPE. 733 * 734 * @param client pointer to JACK client structure. 735 * @param port_name non-empty short name for the new port (not 736 * including the leading @a "client_name:"). Must be unique. 737 * @param port_type port type name. If longer than 738 * jack_port_type_size(), only that many characters are significant. 739 * @param flags @ref JackPortFlags bit mask. 740 * @param buffer_size must be non-zero if this is not a built-in @a 741 * port_type. Otherwise, it is ignored. 742 * 743 * @return jack_port_t pointer on success, otherwise NULL. 744 */ 745 jack_port_t * jack_port_register (jack_client_t *client, 746 const char *port_name, 747 const char *port_type, 748 unsigned long flags, 749 unsigned long buffer_size) JACK_OPTIONAL_WEAK_EXPORT; 750 751 /** 752 * Remove the port from the client, disconnecting any existing 753 * connections. 754 * 755 * @return 0 on success, otherwise a non-zero error code 756 */ 757 int jack_port_unregister (jack_client_t *client, jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT; 758 759 /** 760 * This returns a pointer to the memory area associated with the 761 * specified port. For an output port, it will be a memory area 762 * that can be written to; for an input port, it will be an area 763 * containing the data from the port's connection(s), or 764 * zero-filled. if there are multiple inbound connections, the data 765 * will be mixed appropriately. 766 * 767 * FOR OUTPUT PORTS ONLY : DEPRECATED in Jack 2.0 !! 768 * --------------------------------------------------- 769 * You may cache the value returned, but only between calls to 770 * your "blocksize" callback. For this reason alone, you should 771 * either never cache the return value or ensure you have 772 * a "blocksize" callback and be sure to invalidate the cached 773 * address from there. 774 * 775 * Caching output ports is DEPRECATED in Jack 2.0, due to some new optimization (like "pipelining"). 776 * Port buffers have to be retrieved in each callback for proper functioning. 777 */ 778 void * jack_port_get_buffer (jack_port_t *port, jack_nframes_t) JACK_OPTIONAL_WEAK_EXPORT; 779 780 /** 781 * @return the UUID of the jack_port_t 782 * 783 * @see jack_uuid_to_string() to convert into a string representation 784 */ 785 jack_uuid_t jack_port_uuid (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT; 786 787 /** 788 * @return the full name of the jack_port_t (including the @a 789 * "client_name:" prefix). 790 * 791 * @see jack_port_name_size(). 792 */ 793 const char * jack_port_name (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT; 794 795 /** 796 * @return the short name of the jack_port_t (not including the @a 797 * "client_name:" prefix). 798 * 799 * @see jack_port_name_size(). 800 */ 801 const char * jack_port_short_name (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT; 802 803 /** 804 * @return the @ref JackPortFlags of the jack_port_t. 805 */ 806 int jack_port_flags (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT; 807 808 /** 809 * @return the @a port type, at most jack_port_type_size() characters 810 * including a final NULL. 811 */ 812 const char * jack_port_type (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT; 813 814 /** 815 * @return the @a port type id. 816 */ 817 jack_port_type_id_t jack_port_type_id (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT; 818 819 /** 820 * @return TRUE if the jack_port_t belongs to the jack_client_t. 821 */ 822 int jack_port_is_mine (const jack_client_t *client, const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT; 823 824 /** 825 * @return number of connections to or from @a port. 826 * 827 * @pre The calling client must own @a port. 828 */ 829 int jack_port_connected (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT; 830 831 /** 832 * @return TRUE if the locally-owned @a port is @b directly connected 833 * to the @a port_name. 834 * 835 * @see jack_port_name_size() 836 */ 837 int jack_port_connected_to (const jack_port_t *port, 838 const char *port_name) JACK_OPTIONAL_WEAK_EXPORT; 839 840 /** 841 * @return a null-terminated array of full port names to which the @a 842 * port is connected. If none, returns NULL. 843 * 844 * The caller is responsible for calling jack_free() on any non-NULL 845 * returned value. 846 * 847 * @param port locally owned jack_port_t pointer. 848 * 849 * @see jack_port_name_size(), jack_port_get_all_connections() 850 */ 851 const char ** jack_port_get_connections (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT; 852 853 /** 854 * @return a null-terminated array of full port names to which the @a 855 * port is connected. If none, returns NULL. 856 * 857 * The caller is responsible for calling jack_free() on any non-NULL 858 * returned value. 859 * 860 * This differs from jack_port_get_connections() in two important 861 * respects: 862 * 863 * 1) You may not call this function from code that is 864 * executed in response to a JACK event. For example, 865 * you cannot use it in a GraphReordered handler. 866 * 867 * 2) You need not be the owner of the port to get information 868 * about its connections. 869 * 870 * @see jack_port_name_size() 871 */ 872 const char ** jack_port_get_all_connections (const jack_client_t *client, 873 const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT; 874 875 /** 876 * 877 * @deprecated This function will be removed from a future version 878 * of JACK. Do not use it. There is no replacement. It has 879 * turned out to serve essentially no purpose in real-life 880 * JACK clients. 881 */ 882 int jack_port_tie (jack_port_t *src, jack_port_t *dst) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT; 883 884 /** 885 * 886 * @deprecated This function will be removed from a future version 887 * of JACK. Do not use it. There is no replacement. It has 888 * turned out to serve essentially no purpose in real-life 889 * JACK clients. 890 */ 891 int jack_port_untie (jack_port_t *port) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT; 892 893 /** 894 * \bold THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN 895 * NEW JACK CLIENTS 896 * 897 * Modify a port's short name. May be called at any time. If the 898 * resulting full name (including the @a "client_name:" prefix) is 899 * longer than jack_port_name_size(), it will be truncated. 900 * 901 * @return 0 on success, otherwise a non-zero error code. 902 */ 903 int jack_port_set_name (jack_port_t *port, const char *port_name) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT; 904 905 /** 906 * Modify a port's short name. May NOT be called from a callback handling a server event. 907 * If the resulting full name (including the @a "client_name:" prefix) is 908 * longer than jack_port_name_size(), it will be truncated. 909 * 910 * @return 0 on success, otherwise a non-zero error code. 911 * 912 * This differs from jack_port_set_name() by triggering PortRename notifications to 913 * clients that have registered a port rename handler. 914 */ 915 int jack_port_rename (jack_client_t* client, jack_port_t *port, const char *port_name) JACK_OPTIONAL_WEAK_EXPORT; 916 917 /** 918 * Set @a alias as an alias for @a port. May be called at any time. 919 * If the alias is longer than jack_port_name_size(), it will be truncated. 920 * 921 * After a successful call, and until JACK exits or 922 * @function jack_port_unset_alias() is called, @alias may be 923 * used as a alternate name for the port. 924 * 925 * Ports can have up to two aliases - if both are already 926 * set, this function will return an error. 927 * 928 * @return 0 on success, otherwise a non-zero error code. 929 */ 930 int jack_port_set_alias (jack_port_t *port, const char *alias) JACK_OPTIONAL_WEAK_EXPORT; 931 932 /** 933 * Remove @a alias as an alias for @a port. May be called at any time. 934 * 935 * After a successful call, @a alias can no longer be 936 * used as a alternate name for the port. 937 * 938 * @return 0 on success, otherwise a non-zero error code. 939 */ 940 int jack_port_unset_alias (jack_port_t *port, const char *alias) JACK_OPTIONAL_WEAK_EXPORT; 941 942 /** 943 * Get any aliases known for @port. 944 * 945 * @return the number of aliases discovered for the port 946 */ 947 int jack_port_get_aliases (const jack_port_t *port, char* const aliases[2]) JACK_OPTIONAL_WEAK_EXPORT; 948 949 /** 950 * If @ref JackPortCanMonitor is set for this @a port, turn input 951 * monitoring on or off. Otherwise, do nothing. 952 */ 953 int jack_port_request_monitor (jack_port_t *port, int onoff) JACK_OPTIONAL_WEAK_EXPORT; 954 955 /** 956 * If @ref JackPortCanMonitor is set for this @a port_name, turn input 957 * monitoring on or off. Otherwise, do nothing. 958 * 959 * @return 0 on success, otherwise a non-zero error code. 960 * 961 * @see jack_port_name_size() 962 */ 963 int jack_port_request_monitor_by_name (jack_client_t *client, 964 const char *port_name, int onoff) JACK_OPTIONAL_WEAK_EXPORT; 965 966 /** 967 * If @ref JackPortCanMonitor is set for a port, this function turns 968 * on input monitoring if it was off, and turns it off if only one 969 * request has been made to turn it on. Otherwise it does nothing. 970 * 971 * @return 0 on success, otherwise a non-zero error code 972 */ 973 int jack_port_ensure_monitor (jack_port_t *port, int onoff) JACK_OPTIONAL_WEAK_EXPORT; 974 975 /** 976 * @return TRUE if input monitoring has been requested for @a port. 977 */ 978 int jack_port_monitoring_input (jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT; 979 980 /** 981 * Establish a connection between two ports. 982 * 983 * When a connection exists, data written to the source port will 984 * be available to be read at the destination port. 985 * 986 * @pre The port types must be identical. 987 * 988 * @pre The @ref JackPortFlags of the @a source_port must include @ref 989 * JackPortIsOutput. 990 * 991 * @pre The @ref JackPortFlags of the @a destination_port must include 992 * @ref JackPortIsInput. 993 * 994 * @return 0 on success, EEXIST if the connection is already made, 995 * otherwise a non-zero error code 996 */ 997 int jack_connect (jack_client_t *client, 998 const char *source_port, 999 const char *destination_port) JACK_OPTIONAL_WEAK_EXPORT; 1000 1001 /** 1002 * Remove a connection between two ports. 1003 * 1004 * @pre The port types must be identical. 1005 * 1006 * @pre The @ref JackPortFlags of the @a source_port must include @ref 1007 * JackPortIsOutput. 1008 * 1009 * @pre The @ref JackPortFlags of the @a destination_port must include 1010 * @ref JackPortIsInput. 1011 * 1012 * @return 0 on success, otherwise a non-zero error code 1013 */ 1014 int jack_disconnect (jack_client_t *client, 1015 const char *source_port, 1016 const char *destination_port) JACK_OPTIONAL_WEAK_EXPORT; 1017 1018 /** 1019 * Perform the same function as jack_disconnect() using port handles 1020 * rather than names. This avoids the name lookup inherent in the 1021 * name-based version. 1022 * 1023 * Clients connecting their own ports are likely to use this function, 1024 * while generic connection clients (e.g. patchbays) would use 1025 * jack_disconnect(). 1026 */ 1027 int jack_port_disconnect (jack_client_t *client, jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT; 1028 1029 /** 1030 * @return the maximum number of characters in a full JACK port name 1031 * including the final NULL character. This value is a constant. 1032 * 1033 * A port's full name contains the owning client name concatenated 1034 * with a colon (:) followed by its short name and a NULL 1035 * character. 1036 */ 1037 int jack_port_name_size(void) JACK_OPTIONAL_WEAK_EXPORT; 1038 1039 /** 1040 * @return the maximum number of characters in a JACK port type name 1041 * including the final NULL character. This value is a constant. 1042 */ 1043 int jack_port_type_size(void) JACK_OPTIONAL_WEAK_EXPORT; 1044 1045 /** 1046 * @return the buffersize of a port of type @arg port_type. 1047 * 1048 * this function may only be called in a buffer_size callback. 1049 */ 1050 size_t jack_port_type_get_buffer_size (jack_client_t *client, const char *port_type) JACK_WEAK_EXPORT; 1051 1052 /*@}*/ 1053 1054 /** 1055 * @defgroup LatencyFunctions Managing and determining latency 1056 * 1057 * The purpose of JACK's latency API is to allow clients to 1058 * easily answer two questions: 1059 * 1060 * - How long has it been since the data read from a port arrived 1061 * at the edge of the JACK graph (either via a physical port 1062 * or being synthesized from scratch)? 1063 * 1064 * - How long will it be before the data written to a port arrives 1065 * at the edge of a JACK graph? 1066 1067 * To help answering these two questions, all JACK ports have two 1068 * latency values associated with them, both measured in frames: 1069 * 1070 * <b>capture latency</b>: how long since the data read from 1071 * the buffer of a port arrived at 1072 * a port marked with JackPortIsTerminal. 1073 * The data will have come from the "outside 1074 * world" if the terminal port is also 1075 * marked with JackPortIsPhysical, or 1076 * will have been synthesized by the client 1077 * that owns the terminal port. 1078 * 1079 * <b>playback latency</b>: how long until the data 1080 * written to the buffer of port will reach a port 1081 * marked with JackPortIsTerminal. 1082 * 1083 * Both latencies might potentially have more than one value 1084 * because there may be multiple pathways to/from a given port 1085 * and a terminal port. Latency is therefore generally 1086 * expressed a min/max pair. 1087 * 1088 * In most common setups, the minimum and maximum latency 1089 * are the same, but this design accommodates more complex 1090 * routing, and allows applications (and thus users) to 1091 * detect cases where routing is creating an anomalous 1092 * situation that may either need fixing or more 1093 * sophisticated handling by clients that care about 1094 * latency. 1095 * 1096 * See also @ref jack_set_latency_callback for details on how 1097 * clients that add latency to the signal path should interact 1098 * with JACK to ensure that the correct latency figures are 1099 * used. 1100 * @{ 1101 */ 1102 1103 /** 1104 * The port latency is zero by default. Clients that control 1105 * physical hardware with non-zero latency should call this 1106 * to set the latency to its correct value. Note that the value 1107 * should include any systemic latency present "outside" the 1108 * physical hardware controlled by the client. For example, 1109 * for a client controlling a digital audio interface connected 1110 * to an external digital converter, the latency setting should 1111 * include both buffering by the audio interface *and* the converter. 1112 * 1113 * @deprecated This method will be removed in the next major 1114 * release of JACK. It should not be used in new code, and should 1115 * be replaced by a latency callback that calls @ref 1116 * jack_port_set_latency_range(). 1117 */ 1118 void jack_port_set_latency (jack_port_t *port, jack_nframes_t) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT; 1119 1120 /** 1121 * return the latency range defined by @a mode for 1122 * @a port, in frames. 1123 * 1124 * See @ref LatencyFunctions for the definition of each latency value. 1125 * 1126 * This function is best used from callbacks, specifically the latency callback. 1127 * Before a port is connected, this returns the default latency: zero. 1128 * Therefore it only makes sense to call jack_port_get_latency_range() when 1129 * the port is connected, and that gets signalled by the latency callback. 1130 * See @ref jack_set_latency_callback() for details. 1131 */ 1132 void jack_port_get_latency_range (jack_port_t *port, jack_latency_callback_mode_t mode, jack_latency_range_t *range) JACK_WEAK_EXPORT; 1133 1134 /** 1135 * set the minimum and maximum latencies defined by 1136 * @a mode for @a port, in frames. 1137 * 1138 * See @ref LatencyFunctions for the definition of each latency value. 1139 * 1140 * This function should ONLY be used inside a latency 1141 * callback. The client should determine the current 1142 * value of the latency using @ref jack_port_get_latency_range() 1143 * (called using the same mode as @a mode) 1144 * and then add some number of frames to that reflects 1145 * latency added by the client. 1146 * 1147 * How much latency a client adds will vary 1148 * dramatically. For most clients, the answer is zero 1149 * and there is no reason for them to register a latency 1150 * callback and thus they should never call this 1151 * function. 1152 * 1153 * More complex clients that take an input signal, 1154 * transform it in some way and output the result but 1155 * not during the same process() callback will 1156 * generally know a single constant value to add 1157 * to the value returned by @ref jack_port_get_latency_range(). 1158 * 1159 * Such clients would register a latency callback (see 1160 * @ref jack_set_latency_callback) and must know what input 1161 * ports feed which output ports as part of their 1162 * internal state. Their latency callback will update 1163 * the ports' latency values appropriately. 1164 * 1165 * A pseudo-code example will help. The @a mode argument to the latency 1166 * callback will determine whether playback or capture 1167 * latency is being set. The callback will use 1168 * @ref jack_port_set_latency_range() as follows: 1169 * 1170 * \code 1171 * jack_latency_range_t range; 1172 * if (mode == JackPlaybackLatency) { 1173 * foreach input_port in (all self-registered port) { 1174 * jack_port_get_latency_range (port_feeding_input_port, JackPlaybackLatency, &range); 1175 * range.min += min_delay_added_as_signal_flows_from port_feeding to input_port; 1176 * range.max += max_delay_added_as_signal_flows_from port_feeding to input_port; 1177 * jack_port_set_latency_range (input_port, JackPlaybackLatency, &range); 1178 * } 1179 * } else if (mode == JackCaptureLatency) { 1180 * foreach output_port in (all self-registered port) { 1181 * jack_port_get_latency_range (port_fed_by_output_port, JackCaptureLatency, &range); 1182 * range.min += min_delay_added_as_signal_flows_from_output_port_to_fed_by_port; 1183 * range.max += max_delay_added_as_signal_flows_from_output_port_to_fed_by_port; 1184 * jack_port_set_latency_range (output_port, JackCaptureLatency, &range); 1185 * } 1186 * } 1187 * \endcode 1188 * 1189 * In this relatively simple pseudo-code example, it is assumed that 1190 * each input port or output is connected to only 1 output or input 1191 * port respectively. 1192 * 1193 * If a port is connected to more than 1 other port, then the 1194 * range.min and range.max values passed to @ref 1195 * jack_port_set_latency_range() should reflect the minimum and 1196 * maximum values across all connected ports. 1197 * 1198 * See the description of @ref jack_set_latency_callback for more 1199 * information. 1200 */ 1201 void jack_port_set_latency_range (jack_port_t *port, jack_latency_callback_mode_t mode, jack_latency_range_t *range) JACK_WEAK_EXPORT; 1202 1203 /** 1204 * Request a complete recomputation of all port latencies. This 1205 * can be called by a client that has just changed the internal 1206 * latency of its port using jack_port_set_latency 1207 * and wants to ensure that all signal pathways in the graph 1208 * are updated with respect to the values that will be returned 1209 * by jack_port_get_total_latency. It allows a client 1210 * to change multiple port latencies without triggering a 1211 * recompute for each change. 1212 * 1213 * @return zero for successful execution of the request. non-zero 1214 * otherwise. 1215 */ 1216 int jack_recompute_total_latencies (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT; 1217 1218 /** 1219 * @return the time (in frames) between data being available or 1220 * delivered at/to a port, and the time at which it arrived at or is 1221 * delivered to the "other side" of the port. E.g. for a physical 1222 * audio output port, this is the time between writing to the port and 1223 * when the signal will leave the connector. For a physical audio 1224 * input port, this is the time between the sound arriving at the 1225 * connector and the corresponding frames being readable from the 1226 * port. 1227 * 1228 * @deprecated This method will be removed in the next major 1229 * release of JACK. It should not be used in new code, and should 1230 * be replaced by jack_port_get_latency_range() in any existing 1231 * use cases. 1232 */ 1233 jack_nframes_t jack_port_get_latency (jack_port_t *port) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT; 1234 1235 /** 1236 * The maximum of the sum of the latencies in every 1237 * connection path that can be drawn between the port and other 1238 * ports with the @ref JackPortIsTerminal flag set. 1239 * 1240 * @deprecated This method will be removed in the next major 1241 * release of JACK. It should not be used in new code, and should 1242 * be replaced by jack_port_get_latency_range() in any existing 1243 * use cases. 1244 */ 1245 jack_nframes_t jack_port_get_total_latency (jack_client_t *client, 1246 jack_port_t *port) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT; 1247 1248 /** 1249 * Request a complete recomputation of a port's total latency. This 1250 * can be called by a client that has just changed the internal 1251 * latency of its port using jack_port_set_latency 1252 * and wants to ensure that all signal pathways in the graph 1253 * are updated with respect to the values that will be returned 1254 * by jack_port_get_total_latency. 1255 * 1256 * @return zero for successful execution of the request. non-zero 1257 * otherwise. 1258 * 1259 * @deprecated This method will be removed in the next major 1260 * release of JACK. It should not be used in new code, and should 1261 * be replaced by jack_recompute_total_latencies() in any existing 1262 * use cases. 1263 */ 1264 int jack_recompute_total_latency (jack_client_t*, jack_port_t* port) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT; 1265 1266 /*@}*/ 1267 1268 /** 1269 * @defgroup PortSearching Looking up ports 1270 * @{ 1271 */ 1272 1273 /** 1274 * @param port_name_pattern A regular expression used to select 1275 * ports by name. If NULL or of zero length, no selection based 1276 * on name will be carried out. 1277 * @param type_name_pattern A regular expression used to select 1278 * ports by type. If NULL or of zero length, no selection based 1279 * on type will be carried out. 1280 * @param flags A value used to select ports by their flags. 1281 * If zero, no selection based on flags will be carried out. 1282 * 1283 * @return a NULL-terminated array of ports that match the specified 1284 * arguments. The caller is responsible for calling jack_free() any 1285 * non-NULL returned value. 1286 * 1287 * @see jack_port_name_size(), jack_port_type_size() 1288 */ 1289 const char ** jack_get_ports (jack_client_t *client, 1290 const char *port_name_pattern, 1291 const char *type_name_pattern, 1292 unsigned long flags) JACK_OPTIONAL_WEAK_EXPORT; 1293 1294 /** 1295 * @return address of the jack_port_t named @a port_name. 1296 * 1297 * @see jack_port_name_size() 1298 */ 1299 jack_port_t * jack_port_by_name (jack_client_t *client, const char *port_name) JACK_OPTIONAL_WEAK_EXPORT; 1300 1301 /** 1302 * @return address of the jack_port_t of a @a port_id. 1303 */ 1304 jack_port_t * jack_port_by_id (jack_client_t *client, 1305 jack_port_id_t port_id) JACK_OPTIONAL_WEAK_EXPORT; 1306 1307 /*@}*/ 1308 1309 /** 1310 * @defgroup TimeFunctions Handling time 1311 * @{ 1312 * 1313 * JACK time is in units of 'frames', according to the current sample rate. 1314 * The absolute value of frame times is meaningless, frame times have meaning 1315 * only relative to each other. 1316 */ 1317 1318 /** 1319 * @return the estimated time in frames that has passed since the JACK 1320 * server began the current process cycle. 1321 */ 1322 jack_nframes_t jack_frames_since_cycle_start (const jack_client_t *) JACK_OPTIONAL_WEAK_EXPORT; 1323 1324 /** 1325 * @return the estimated current time in frames. 1326 * This function is intended for use in other threads (not the process 1327 * callback). The return value can be compared with the value of 1328 * jack_last_frame_time to relate time in other threads to JACK time. 1329 */ 1330 jack_nframes_t jack_frame_time (const jack_client_t *) JACK_OPTIONAL_WEAK_EXPORT; 1331 1332 /** 1333 * @return the precise time at the start of the current process cycle. 1334 * This function may only be used from the process callback, and can 1335 * be used to interpret timestamps generated by jack_frame_time() in 1336 * other threads with respect to the current process cycle. 1337 * 1338 * This is the only jack time function that returns exact time: 1339 * when used during the process callback it always returns the same 1340 * value (until the next process callback, where it will return 1341 * that value + nframes, etc). The return value is guaranteed to be 1342 * monotonic and linear in this fashion unless an xrun occurs. 1343 * If an xrun occurs, clients must check this value again, as time 1344 * may have advanced in a non-linear way (e.g. cycles may have been skipped). 1345 */ 1346 jack_nframes_t jack_last_frame_time (const jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT; 1347 1348 /** 1349 * This function may only be used from the process callback. 1350 * It provides the internal cycle timing information as used by 1351 * most of the other time related functions. This allows the 1352 * caller to map between frame counts and microseconds with full 1353 * precision (i.e. without rounding frame times to integers), 1354 * and also provides e.g. the microseconds time of the start of 1355 * the current cycle directly (it has to be computed otherwise). 1356 * 1357 * If the return value is zero, the following information is 1358 * provided in the variables pointed to by the arguments: 1359 * 1360 * current_frames: the frame time counter at the start of the 1361 * current cycle, same as jack_last_frame_time(). 1362 * current_usecs: the microseconds time at the start of the 1363 * current cycle. 1364 * next_usecs: the microseconds time of the start of the next 1365 * next cycle as computed by the DLL. 1366 * period_usecs: the current best estimate of the period time in 1367 * microseconds. 1368 * 1369 * NOTES: 1370 * 1371 * Because of the types used, all the returned values except period_usecs 1372 * are unsigned. In computations mapping between frames and microseconds 1373 * *signed* differences are required. The easiest way is to compute those 1374 * separately and assign them to the appropriate signed variables, 1375 * int32_t for frames and int64_t for usecs. See the implementation of 1376 * jack_frames_to_time() and Jack_time_to_frames() for an example. 1377 * 1378 * Unless there was an xrun, skipped cycles, or the current cycle is the 1379 * first after freewheeling or starting Jack, the value of current_usecs 1380 * will always be the value of next_usecs of the previous cycle. 1381 * 1382 * The value of period_usecs will in general NOT be exactly equal to 1383 * the difference of next_usecs and current_usecs. This is because to 1384 * ensure stability of the DLL and continuity of the mapping, a fraction 1385 * of the loop error must be included in next_usecs. For an accurate 1386 * mapping between frames and microseconds, the difference of next_usecs 1387 * and current_usecs should be used, and not period_usecs. 1388 * 1389 * @return zero if OK, non-zero otherwise. 1390 */ 1391 int jack_get_cycle_times(const jack_client_t *client, 1392 jack_nframes_t *current_frames, 1393 jack_time_t *current_usecs, 1394 jack_time_t *next_usecs, 1395 float *period_usecs) JACK_OPTIONAL_WEAK_EXPORT; 1396 1397 /** 1398 * @return the estimated time in microseconds of the specified frame time 1399 */ 1400 jack_time_t jack_frames_to_time(const jack_client_t *client, jack_nframes_t) JACK_OPTIONAL_WEAK_EXPORT; 1401 1402 /** 1403 * @return the estimated time in frames for the specified system time. 1404 */ 1405 jack_nframes_t jack_time_to_frames(const jack_client_t *client, jack_time_t) JACK_OPTIONAL_WEAK_EXPORT; 1406 1407 /** 1408 * @return return JACK's current system time in microseconds, 1409 * using the JACK clock source. 1410 * 1411 * The value returned is guaranteed to be monotonic, but not linear. 1412 */ 1413 jack_time_t jack_get_time(void) JACK_OPTIONAL_WEAK_EXPORT; 1414 1415 /*@}*/ 1416 1417 /** 1418 * @defgroup ErrorOutput Controlling error/information output 1419 */ 1420 /*@{*/ 1421 1422 /** 1423 * Display JACK error message. 1424 * 1425 * Set via jack_set_error_function(), otherwise a JACK-provided 1426 * default will print @a msg (plus a newline) to stderr. 1427 * 1428 * @param msg error message text (no newline at end). 1429 */ 1430 extern void (*jack_error_callback)(const char *msg) JACK_OPTIONAL_WEAK_EXPORT; 1431 1432 /** 1433 * Set the @ref jack_error_callback for error message display. 1434 * Set it to NULL to restore default_jack_error_callback function. 1435 * 1436 * The JACK library provides two built-in callbacks for this purpose: 1437 * default_jack_error_callback() and silent_jack_error_callback(). 1438 */ 1439 void jack_set_error_function (void (*func)(const char *)) JACK_OPTIONAL_WEAK_EXPORT; 1440 1441 /** 1442 * Display JACK info message. 1443 * 1444 * Set via jack_set_info_function(), otherwise a JACK-provided 1445 * default will print @a msg (plus a newline) to stdout. 1446 * 1447 * @param msg info message text (no newline at end). 1448 */ 1449 extern void (*jack_info_callback)(const char *msg) JACK_OPTIONAL_WEAK_EXPORT; 1450 1451 /** 1452 * Set the @ref jack_info_callback for info message display. 1453 * Set it to NULL to restore default_jack_info_callback function. 1454 * 1455 * The JACK library provides two built-in callbacks for this purpose: 1456 * default_jack_info_callback() and silent_jack_info_callback(). 1457 */ 1458 void jack_set_info_function (void (*func)(const char *)) JACK_OPTIONAL_WEAK_EXPORT; 1459 1460 /*@}*/ 1461 1462 /** 1463 * The free function to be used on memory returned by jack_port_get_connections, 1464 * jack_port_get_all_connections, jack_get_ports and jack_get_internal_client_name functions. 1465 * This is MANDATORY on Windows when otherwise all nasty runtime version related crashes can occur. 1466 * Developers are strongly encouraged to use this function instead of the standard "free" function in new code. 1467 * 1468 * @param ptr the memory pointer to be deallocated. 1469 */ 1470 void jack_free(void* ptr) JACK_OPTIONAL_WEAK_EXPORT; 1471 1472 1473 #ifdef __cplusplus 1474 } 1475 #endif 1476 1477 #endif /* __jack_h__ */ 1478