1 /* 2 Copyright (C) 2002 Paul Davis 3 Copyright (C) 2003 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 module jack.c.transport; 22 public import jack.c.types; 23 24 extern (C) { 25 26 /** 27 * @defgroup TransportControl Transport and Timebase control 28 * @{ 29 */ 30 31 /** 32 * Called by the timebase master to release itself from that 33 * responsibility. 34 * 35 * If the timebase master releases the timebase or leaves the JACK 36 * graph for any reason, the JACK engine takes over at the start of 37 * the next process cycle. The transport state does not change. If 38 * rolling, it continues to play, with frame numbers as the only 39 * available position information. 40 * 41 * @see jack_set_timebase_callback 42 * 43 * @param client the JACK client structure. 44 * 45 * @return 0 on success, otherwise a non-zero error code. 46 */ 47 int jack_release_timebase (jack_client_t *client) /* JACK_OPTIONAL_WEAK_EXPORT */; 48 49 /** 50 * Register (or unregister) as a slow-sync client, one that cannot 51 * respond immediately to transport position changes. 52 * 53 * The @a sync_callback will be invoked at the first available 54 * opportunity after its registration is complete. If the client is 55 * currently active this will be the following process cycle, 56 * otherwise it will be the first cycle after calling jack_activate(). 57 * After that, it runs according to the ::JackSyncCallback rules. 58 * Clients that don't set a @a sync_callback are assumed to be ready 59 * immediately any time the transport wants to start. 60 * 61 * @param client the JACK client structure. 62 * @param sync_callback is a realtime function that returns TRUE when 63 * the client is ready. Setting @a sync_callback to NULL declares that 64 * this client no longer requires slow-sync processing. 65 * @param arg an argument for the @a sync_callback function. 66 * 67 * @return 0 on success, otherwise a non-zero error code. 68 */ 69 int jack_set_sync_callback (jack_client_t *client, 70 JackSyncCallback sync_callback, 71 void *arg) /* JACK_OPTIONAL_WEAK_EXPORT */; 72 73 /** 74 * Set the timeout value for slow-sync clients. 75 * 76 * This timeout prevents unresponsive slow-sync clients from 77 * completely halting the transport mechanism. The default is two 78 * seconds. When the timeout expires, the transport starts rolling, 79 * even if some slow-sync clients are still unready. The @a 80 * sync_callbacks of these clients continue being invoked, giving them 81 * a chance to catch up. 82 * 83 * @see jack_set_sync_callback 84 * 85 * @param client the JACK client structure. 86 * @param timeout is delay (in microseconds) before the timeout expires. 87 * 88 * @return 0 on success, otherwise a non-zero error code. 89 */ 90 int jack_set_sync_timeout (jack_client_t *client, 91 jack_time_t timeout) /* JACK_OPTIONAL_WEAK_EXPORT */; 92 93 /** 94 * Register as timebase master for the JACK subsystem. 95 * 96 * The timebase master registers a callback that updates extended 97 * position information such as beats or timecode whenever necessary. 98 * Without this extended information, there is no need for this 99 * function. 100 * 101 * There is never more than one master at a time. When a new client 102 * takes over, the former @a timebase_callback is no longer called. 103 * Taking over the timebase may be done conditionally, so it fails if 104 * there was a master already. 105 * 106 * @param client the JACK client structure. 107 * @param conditional non-zero for a conditional request. 108 * @param timebase_callback is a realtime function that returns 109 * position information. 110 * @param arg an argument for the @a timebase_callback function. 111 * 112 * @return 113 * - 0 on success; 114 * - EBUSY if a conditional request fails because there was already a 115 * timebase master; 116 * - other non-zero error code. 117 */ 118 int jack_set_timebase_callback (jack_client_t *client, 119 int conditional, 120 JackTimebaseCallback timebase_callback, 121 void *arg) /* JACK_OPTIONAL_WEAK_EXPORT */; 122 123 /** 124 * Reposition the transport to a new frame number. 125 * 126 * May be called at any time by any client. The new position takes 127 * effect in two process cycles. If there are slow-sync clients and 128 * the transport is already rolling, it will enter the 129 * ::JackTransportStarting state and begin invoking their @a 130 * sync_callbacks until ready. This function is realtime-safe. 131 * 132 * @see jack_transport_reposition, jack_set_sync_callback 133 * 134 * @param client the JACK client structure. 135 * @param frame frame number of new transport position. 136 * 137 * @return 0 if valid request, non-zero otherwise. 138 */ 139 int jack_transport_locate (jack_client_t *client, 140 jack_nframes_t frame) /* JACK_OPTIONAL_WEAK_EXPORT */; 141 142 /** 143 * Query the current transport state and position. 144 * 145 * This function is realtime-safe, and can be called from any thread. 146 * If called from the process thread, @a pos corresponds to the first 147 * frame of the current cycle and the state returned is valid for the 148 * entire cycle. 149 * 150 * @param client the JACK client structure. 151 * @param pos pointer to structure for returning current transport 152 * position; @a pos->valid will show which fields contain valid data. 153 * If @a pos is NULL, do not return position information. 154 * 155 * @return Current transport state. 156 */ 157 jack_transport_state_t jack_transport_query (const(jack_client_t) *client, 158 jack_position_t *pos) /* JACK_OPTIONAL_WEAK_EXPORT */; 159 160 /** 161 * Return an estimate of the current transport frame, 162 * including any time elapsed since the last transport 163 * positional update. 164 * 165 * @param client the JACK client structure 166 */ 167 jack_nframes_t jack_get_current_transport_frame (const(jack_client_t) *client) /* JACK_OPTIONAL_WEAK_EXPORT */; 168 169 /** 170 * Request a new transport position. 171 * 172 * May be called at any time by any client. The new position takes 173 * effect in two process cycles. If there are slow-sync clients and 174 * the transport is already rolling, it will enter the 175 * ::JackTransportStarting state and begin invoking their @a 176 * sync_callbacks until ready. This function is realtime-safe. 177 * 178 * @see jack_transport_locate, jack_set_sync_callback 179 * 180 * @param client the JACK client structure. 181 * @param pos requested new transport position. 182 * 183 * @return 0 if valid request, EINVAL if position structure rejected. 184 */ 185 int jack_transport_reposition (jack_client_t *client, 186 const(jack_position_t) *pos) /* JACK_OPTIONAL_WEAK_EXPORT */; 187 188 /** 189 * Start the JACK transport rolling. 190 * 191 * Any client can make this request at any time. It takes effect no 192 * sooner than the next process cycle, perhaps later if there are 193 * slow-sync clients. This function is realtime-safe. 194 * 195 * @see jack_set_sync_callback 196 * 197 * @param client the JACK client structure. 198 */ 199 void jack_transport_start (jack_client_t *client) /* JACK_OPTIONAL_WEAK_EXPORT */; 200 201 /** 202 * Stop the JACK transport. 203 * 204 * Any client can make this request at any time. It takes effect on 205 * the next process cycle. This function is realtime-safe. 206 * 207 * @param client the JACK client structure. 208 */ 209 void jack_transport_stop (jack_client_t *client) /* JACK_OPTIONAL_WEAK_EXPORT */; 210 211 /** 212 * Gets the current transport info structure (deprecated). 213 * 214 * @param client the JACK client structure. 215 * @param tinfo current transport info structure. The "valid" field 216 * describes which fields contain valid data. 217 * 218 * @deprecated This is for compatibility with the earlier transport 219 * interface. Use jack_transport_query(), instead. 220 * 221 * @pre Must be called from the process thread. 222 */ 223 void jack_get_transport_info (jack_client_t *client, 224 jack_transport_info_t *tinfo) /* JACK_OPTIONAL_WEAK_EXPORT */; 225 226 /** 227 * Set the transport info structure (deprecated). 228 * 229 * @deprecated This function still exists for compatibility with the 230 * earlier transport interface, but it does nothing. Instead, define 231 * a ::JackTimebaseCallback. 232 */ 233 void jack_set_transport_info (jack_client_t *client, 234 jack_transport_info_t *tinfo) /* JACK_OPTIONAL_WEAK_EXPORT */; 235 236 /*@}*/ 237 238 }