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 }