** Warning: Cannot open xref database.
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 $Id: transport.h,v 1.18 2003/12/18 04:03:28 joq Exp $
20 */
21
22 #ifndef __jack_transport_h__
23 #define __jack_transport_h__
24
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28
29 #include <jack/types.h>
30
31 /**
32 * Transport states.
33 */
34 typedef enum {
35
36 /* the order matters for binary compatibility */
37 JackTransportStopped = 0, /**< Transport halted */
38 JackTransportRolling = 1, /**< Transport playing */
39 JackTransportLooping = 2, /**< For OLD_TRANSPORT, now ignored */
40 JackTransportStarting = 3 /**< Waiting for sync ready */
41
42 } jack_transport_state_t;
43
44 typedef uint64_t jack_unique_t; /**< Unique ID (opaque) */
45
46 /**
47 * Optional struct jack_position_t fields.
48 */
49 typedef enum {
50
51 JackPositionBBT = 0x10, /**< Bar, Beat, Tick */
52 JackPositionTimecode = 0x20 /**< External timecode */
53
54 } jack_position_bits_t;
55
56 /** all valid position bits */
57 #define JACK_POSITION_MASK (JackPositionBBT|JackPositionTimecode)
58 #define EXTENDED_TIME_INFO
59
60 /**
61 * Struct for transport position information.
62 */
63 typedef struct {
64
65 /* these four cannot be set from clients: the server sets them */
66 jack_unique_t unique_1; /**< unique ID */
67 jack_time_t usecs; /**< monotonic, free-rolling */
68 jack_nframes_t frame_rate; /**< current frame rate (per second) */
69 jack_nframes_t frame; /**< frame number, always present */
70
71 jack_position_bits_t valid; /**< which other fields are valid */
72
73 /* JackPositionBBT fields: */
74 int32_t bar; /**< current bar */
75 int32_t beat; /**< current beat-within-bar */
76 int32_t tick; /**< current tick-within-beat */
77 double bar_start_tick;
78
79 float beats_per_bar;
80 float beat_type;
81 double ticks_per_beat;
82 double beats_per_minute;
83
84 /* JackPositionTimecode fields: (EXPERIMENTAL: could change) */
85 double frame_time; /**< current time in seconds */
86 double next_time; /**< next sequential frame_time
87 (unless repositioned) */
88
89 /* For binary compatibility, new fields should be allocated from
90 * this padding area with new valid bits controlling access, so
91 * the existing structure size and offsets are preserved. */
92 int32_t padding[10];
93
94 /* When (unique_1 == unique_2) the contents are consistent. */
95 jack_unique_t unique_2; /**< unique ID */
96
97 } jack_position_t;
98
99 /**
100 * Called by the timebase master to release itself from that
101 * responsibility.
102 *
103 * If the timebase master releases the timebase or leaves the JACK
104 * graph for any reason, the JACK engine takes over at the start of
105 * the next process cycle. The transport state does not change. If
106 * rolling, it continues to play, with frame numbers as the only
107 * available position information.
108 *
109 * @see jack_set_timebase_callback
110 *
111 * @param client the JACK client structure.
112 *
113 * @return 0 on success, otherwise a non-zero error code.
114 */
115 int jack_release_timebase (jack_client_t *client);
116
117 /**
118 * Prototype for the @a sync_callback defined by slow-sync clients.
119 * Called just before process() in the same thread on the first cycle
120 * after being registered, whenever some client requests a new
121 * position, or when the transport enters the ::JackTransportStarting
122 * state. This realtime function must not wait.
123 *
124 * The transport @a state will be:
125 *
126 * - ::JackTransportStopped when a new position is requested;
127 * - ::JackTransportStarting when the transport is waiting to start;
128 * - ::JackTransportRolling when the timeout has expired, and the
129 * position is now a moving target.
130 *
131 * @param state current transport state.
132 * @param pos new transport position.
133 * @param arg the argument supplied by jack_set_sync_callback().
134 *
135 * @return TRUE (non-zero) when ready to roll.
136 */
137 typedef int (*JackSyncCallback)(jack_transport_state_t state,
138 jack_position_t *pos,
139 void *arg);
140
141 /**
142 * Register (or unregister) as a slow-sync client, one that cannot
143 * respond immediately to transport position changes.
144 *
145 * The @a sync_callback will be invoked in the first process cycle
146 * after its registration is complete, or in the first cycle after
147 * jack_activate() if the client had been inactive. After that, it
148 * runs according to the ::JackSyncCallback rules. Clients that don't
149 * set a @a sync_callback are assumed to be ready immediately any time
150 * the transport wants to start.
151 *
152 * @param client the JACK client structure.
153 * @param sync_callback is a realtime function that returns TRUE when
154 * the client is ready. Setting @a sync_callback to NULL declares that
155 * this client no longer requires slow-sync processing.
156 * @param arg an argument for the @a sync_callback function.
157 *
158 * @return 0 on success, otherwise a non-zero error code.
159 */
160 int jack_set_sync_callback (jack_client_t *client,
161 JackSyncCallback sync_callback,
162 void *arg);
163
164 /**
165 * Set the timeout value for slow-sync clients.
166 *
167 * This timeout prevents unresponsive slow-sync clients from
168 * completely halting the transport mechanism. The default is two
169 * seconds. When the timeout expires, the transport starts rolling,
170 * even if some slow-sync clients are still unready. The @a
171 * sync_callbacks of these clients continue being invoked, giving them
172 * a chance to catch up.
173 *
174 * @see jack_set_sync_callback
175 *
176 * @param client the JACK client structure.
177 * @param timeout is delay (in microseconds) before the timeout expires.
178 *
179 * @return 0 on success, otherwise a non-zero error code.
180 */
181 int jack_set_sync_timeout (jack_client_t *client,
182 jack_time_t timeout);
183
184 /**
185 * Prototype for the @a timebase_callback used to provide extended
186 * position information. Its output affects all of the following
187 * process cycle. This realtime function must not wait.
188 *
189 * This function is called immediately after process() in the same
190 * thread whenever the transport is rolling, or when any client has
191 * requested a new position in the previous cycle. The first cycle
192 * after jack_set_timebase_callback() is also treated as a new
193 * position, or the first cycle after jack_activate() if the client
194 * had been inactive.
195 *
196 * The timebase master may not use its @a pos argument to set @a
197 * pos->frame. To change position, use jack_transport_reposition() or
198 * jack_transport_locate(). These functions are realtime-safe, the @a
199 * timebase_callback can call them directly.
200 *
201 * @param state current transport state.
202 * @param nframes number of frames in current period.
203 * @param pos address of the position structure for the next cycle; @a
204 * pos->frame will be its frame number. If @a new_pos is FALSE, this
205 * structure contains extended position information from the current
206 * cycle. If TRUE, it contains whatever was set by the requester.
207 * The @a timebase_callback's task is to update the extended
208 * information here.
209 * @param new_pos TRUE (non-zero) for a newly requested @a pos, or for
210 * the first cycle after the @a timebase_callback is defined.
211 * @param arg the argument supplied by jack_set_timebase_callback().
212 */
213 typedef void (*JackTimebaseCallback)(jack_transport_state_t state,
214 jack_nframes_t nframes,
215 jack_position_t *pos,
216 int new_pos,
217 void *arg);
218
219 /**
220 * Register as timebase master for the JACK subsystem.
221 *
222 * The timebase master registers a callback that updates extended
223 * position information such as beats or timecode whenever necessary.
224 * Without this extended information, there is no need for this
225 * function.
226 *
227 * There is never more than one master at a time. When a new client
228 * takes over, the former @a timebase_callback is no longer called.
229 * Taking over the timebase may be done conditionally, so it fails if
230 * there was a master already.
231 *
232 * @param client the JACK client structure.
233 * @param conditional non-zero for a conditional request.
234 * @param timebase_callback is a realtime function that returns
235 * position information.
236 * @param arg an argument for the @a timebase_callback function.
237 *
238 * @return
239 * - 0 on success;
240 * - EBUSY if a conditional request fails because there was already a
241 * timebase master;
242 * - other non-zero error code.
243 */
244 int jack_set_timebase_callback (jack_client_t *client,
245 int conditional,
246 JackTimebaseCallback timebase_callback,
247 void *arg);
248
249 /**
250 * Reposition the transport to a new frame number.
251 *
252 * May be called at any time by any client. The new position takes
253 * effect in two process cycles. If there are slow-sync clients and
254 * the transport is already rolling, it will enter the
255 * ::JackTransportStarting state and begin invoking their @a
256 * sync_callbacks until ready. This function is realtime-safe.
257 *
258 * @see jack_transport_reposition, jack_set_sync_callback
259 *
260 * @param client the JACK client structure.
261 * @param frame frame number of new transport position.
262 *
263 * @return 0 if valid request, non-zero otherwise.
264 */
265 int jack_transport_locate (jack_client_t *client,
266 jack_nframes_t frame);
267
268 /**
269 * Query the current transport state and position.
270 *
271 * This function is realtime-safe, and can be called from any thread.
272 * If called from the process thread, @a pos corresponds to the first
273 * frame of the current cycle and the state returned is valid for the
274 * entire cycle.
275 *
276 * @param client the JACK client structure.
277 * @param pos pointer to structure for returning current transport
278 * position; @a pos->valid will show which fields contain valid data.
279 * If @a pos is NULL, do not return position information.
280 *
281 * @return Current transport state.
282 */
283 jack_transport_state_t jack_transport_query (const jack_client_t *client,
284 jack_position_t *pos);
285
286 /**
287 * Return an estimate of the current transport frame,
288 * including any time elapsed since the last transport
289 * positional update.
290 *
291 * @param client the JACK client structure
292 */
293 jack_nframes_t jack_get_current_transport_frame (const jack_client_t *client);
294
295 /**
296 * Request a new transport position.
297 *
298 * May be called at any time by any client. The new position takes
299 * effect in two process cycles. If there are slow-sync clients and
300 * the transport is already rolling, it will enter the
301 * ::JackTransportStarting state and begin invoking their @a
302 * sync_callbacks until ready. This function is realtime-safe.
303 *
304 * @see jack_transport_locate, jack_set_sync_callback
305 *
306 * @param client the JACK client structure.
307 * @param pos requested new transport position.
308 *
309 * @return 0 if valid request, EINVAL if position structure rejected.
310 */
311 int jack_transport_reposition (jack_client_t *client,
312 jack_position_t *pos);
313
314 /**
315 * Start the JACK transport rolling.
316 *
317 * Any client can make this request at any time. It takes effect no
318 * sooner than the next process cycle, perhaps later if there are
319 * slow-sync clients. This function is realtime-safe.
320 *
321 * @see jack_set_sync_callback
322 *
323 * @param client the JACK client structure.
324 */
325 void jack_transport_start (jack_client_t *client);
326
327 /**
328 * Stop the JACK transport.
329 *
330 * Any client can make this request at any time. It takes effect on
331 * the next process cycle. This function is realtime-safe.
332 *
333 * @param client the JACK client structure.
334 */
335 void jack_transport_stop (jack_client_t *client);
336
337
338 /*********************************************************************
339 * The following interfaces are DEPRECATED. They are only provided
340 * for compatibility with the earlier JACK transport implementation.
341 *********************************************************************/
342
343 /**
344 * Optional struct jack_transport_info_t fields.
345 *
346 * @see jack_position_bits_t.
347 */
348 typedef enum {
349
350 JackTransportState = 0x1, /**< Transport state */
351 JackTransportPosition = 0x2, /**< Frame number */
352 JackTransportLoop = 0x4, /**< Loop boundaries (ignored) */
353 JackTransportSMPTE = 0x8, /**< SMPTE (ignored) */
354 JackTransportBBT = 0x10 /**< Bar, Beat, Tick */
355
356 } jack_transport_bits_t;
357
358 /**
359 * Deprecated struct for transport position information.
360 *
361 * @deprecated This is for compatibility with the earlier transport
362 * interface. Use the jack_position_t struct, instead.
363 */
364 typedef struct {
365
366 /* these two cannot be set from clients: the server sets them */
367
368 jack_nframes_t frame_rate; /**< current frame rate (per second) */
369 jack_time_t usecs; /**< monotonic, free-rolling */
370
371 jack_transport_bits_t valid; /**< which fields are legal to read */
372 jack_transport_state_t transport_state;
373 jack_nframes_t frame;
374 jack_nframes_t loop_start;
375 jack_nframes_t loop_end;
376
377 long smpte_offset; /**< SMPTE offset (from frame 0) */
378 float smpte_frame_rate; /**< 29.97, 30, 24 etc. */
379
380 int bar;
381 int beat;
382 int tick;
383 double bar_start_tick;
384
385 float beats_per_bar;
386 float beat_type;
387 double ticks_per_beat;
388 double beats_per_minute;
389
390 } jack_transport_info_t;
391
392 /**
393 * Gets the current transport info structure (deprecated).
394 *
395 * @param client the JACK client structure.
396 * @param tinfo current transport info structure. The "valid" field
397 * describes which fields contain valid data.
398 *
399 * @deprecated This is for compatibility with the earlier transport
400 * interface. Use jack_transport_query(), instead.
401 *
402 * @pre Must be called from the process thread.
403 */
404 void jack_get_transport_info (jack_client_t *client,
405 jack_transport_info_t *tinfo);
406
407 /**
408 * Set the transport info structure (deprecated).
409 *
410 * @deprecated This function still exists for compatibility with the
411 * earlier transport interface, but it does nothing. Instead, define
412 * a ::JackTimebaseCallback.
413 */
414 void jack_set_transport_info (jack_client_t *client,
415 jack_transport_info_t *tinfo);
416
417 #ifdef __cplusplus
418 }
419 #endif
420
421 #endif /* __jack_transport_h__ */
422
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.