source: roaraudio/include/libroar/vs.h @ 5823:f9f70dbaa376

Last change on this file since 5823:f9f70dbaa376 was 5823:f9f70dbaa376, checked in by phi, 11 years ago

updated copyright

File size: 14.3 KB
Line 
1//vs.h:
2
3/*
4 *      Copyright (C) Philipp 'ph3-der-loewe' Schafft - 2010-2013
5 *
6 *  This file is part of libroar a part of RoarAudio,
7 *  a cross-platform sound system for both, home and professional use.
8 *  See README for details.
9 *
10 *  This file is free software; you can redistribute it and/or modify
11 *  it under the terms of the GNU General Public License version 3
12 *  as published by the Free Software Foundation.
13 *
14 *  libroar is distributed in the hope that it will be useful,
15 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
16 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17 *  GNU General Public License for more details.
18 *
19 *  You should have received a copy of the GNU General Public License
20 *  along with this software; see the file COPYING.  If not, write to
21 *  the Free Software Foundation, 51 Franklin Street, Fifth Floor,
22 *  Boston, MA 02110-1301, USA.
23 *
24 *  NOTE for everyone want's to change something and send patches:
25 *  read README and HACKING! There a addition information on
26 *  the license of this document you need to read before you send
27 *  any patches.
28 *
29 *  NOTE for uses of non-GPL (LGPL,...) software using libesd, libartsc
30 *  or libpulse*:
31 *  The libs libroaresd, libroararts and libroarpulse link this lib
32 *  and are therefore GPL. Because of this it may be illegal to use
33 *  them with any software that uses libesd, libartsc or libpulse*.
34 */
35
36#ifndef _LIBROARVS_H_
37#define _LIBROARVS_H_
38
39#include "libroar.h"
40
41#define _LIBROAR_VS_STDATTRS _LIBROAR_ATTR_USE_RESULT _LIBROAR_ATTR_NONNULL(1)
42
43struct roar_vs;
44
45typedef struct roar_vs roar_vs_t;
46typedef signed long int roar_mus_t;
47
48/* return readable string describing the problem */
49const char * roar_vs_strerr(int error) _LIBROAR_ATTR_PURE _LIBROAR_ATTR_USE_RESULT;
50
51/* create a new VS object from normal RoarAudio connection object
52 * The connection must not be closed caller before roar_vs_close() is called.
53 * The connection is not closed by roar_vs_close().
54 */
55roar_vs_t * roar_vs_new_from_con(struct roar_connection * con, int * error) _LIBROAR_VS_STDATTRS;
56
57/* create a new VS object with a new connection */
58roar_vs_t * roar_vs_new(const char * server, const char * name, int * error) _LIBROAR_ATTR_USE_RESULT;
59
60/* start a the stream in the VS object */
61int roar_vs_stream(roar_vs_t * vss, const struct roar_audio_info * info, int dir, int * error) _LIBROAR_ATTR_USE_RESULT _LIBROAR_ATTR_NONNULL(1, 2);
62
63/* connect to server and start stream in once
64 * this is basically roar_vs_new() and roar_vs_stream() in one function.
65 */
66roar_vs_t * roar_vs_new_simple(const char * server, const char * name, int rate, int channels, int codec, int bits, int dir, int * error) _LIBROAR_ATTR_USE_RESULT;
67
68/* create a VS object for playback.
69 * This is roar_vs_new_simple() with direction set to 'playback' (wave form data)
70 */
71#define roar_vs_new_playback(s,n,r,c,e,b,error) roar_vs_new_simple((s), (n), (r), (c), (e), (b), ROAR_DIR_PLAY, (error))
72
73
74/* Attach a open file.
75 */
76
77int roar_vs_file(roar_vs_t * vss, struct roar_vio_calls * vio, int closefile, int * error) _LIBROAR_ATTR_USE_RESULT _LIBROAR_ATTR_NONNULL(1, 2);
78
79/* Open a file and attach it.
80 */
81int roar_vs_file_simple(roar_vs_t * vss, const char * filename, int * error) _LIBROAR_ATTR_USE_RESULT _LIBROAR_ATTR_NONNULL(1, 2);
82
83/* Connects to a server to just play a file.
84 */
85roar_vs_t * roar_vs_new_from_file(const char * server, const char * name, const char * filename, int * error) _LIBROAR_ATTR_USE_RESULT _LIBROAR_ATTR_NONNULL(3);
86
87/* Switch to buffered mode.
88 * After swiching to buffered mode you can use the buffered
89 * mode functions. You must use roar_vs_iterate() to send data
90 * from local buffer to server.
91 * This is currently not thread safe but you may implement it in
92 * diffrent thread if you do the locking yourself.
93 * Takes the size for the used buffers as argument.
94 * Buffer size should be a value of 2^n. Typical values are 2048 and 4096.
95 */
96int roar_vs_buffer(roar_vs_t * vss, size_t buffer, int * error) _LIBROAR_VS_STDATTRS;
97
98
99/* Boolean TRUE for VS functions */
100#define ROAR_VS_TRUE     1
101/* Boolean FALSE for VS functions */
102#define ROAR_VS_FALSE    0
103/* Boolean TOGGLE for VS functions */
104#define ROAR_VS_TOGGLE  -1
105/* Boolean value used to ask for a value, do not change the value only ask for current value */
106#define ROAR_VS_ASK     -2
107
108/* close and free the VS object
109 * This does all needed cleanup.
110 * If server connection was made by VS it is closed, too.
111 * If server connection was provided by caller it is untouched.
112 */
113int roar_vs_close(roar_vs_t * vss, int killit, int * error) _LIBROAR_ATTR_NONNULL(1);
114
115/* write data to a stream
116 * This function writes some data to the stream.
117 * return is number of bytes written or -1 on error.
118 * return value can be zero to indicate no data can be written but no error.
119 * this may be the case with non-blocking streams.
120 * returned value can be less then requested value. indicates a short write.
121 * you should wait some (short!) time (for example one main loop iteration) and try again.
122 */
123ssize_t roar_vs_write(roar_vs_t * vss, const void * buf, size_t len, int * error) _LIBROAR_ATTR_USE_RESULT _LIBROAR_ATTR_NONNULL(1, 2);
124
125/* read data from a stream
126 * This function reads some data from the stream.
127 * return is number of bytes read or -1 on error.
128 * return value can be zero to indicate no data can be read but no error.
129 * this may be the case with non-blocking streams.
130 * returned value can be less then requested value. indicates a short read.
131 * you should wait some (short!) time (for example one main loop iteration) and try again.
132 */
133ssize_t roar_vs_read (roar_vs_t * vss,       void * buf, size_t len, int * error) _LIBROAR_ATTR_USE_RESULT _LIBROAR_ATTR_NONNULL(1, 2);
134
135/* wait value for waiting */
136#define ROAR_VS_WAIT    1
137/* wait value for no waiting */
138#define ROAR_VS_NOWAIT  0
139/* Trigger action but do not wait for it to complet */
140#define ROAR_VS_ASYNC  -1
141
142/* sync a stream with the server (flush buffers)
143 * Returns 0 on no error and -1 on error.
144 */
145int     roar_vs_sync (roar_vs_t * vss, int wait, int * error) _LIBROAR_ATTR_NONNULL(1);
146
147/* set blocking mode of stream
148 * returns old blocking state
149 */
150int     roar_vs_blocking (roar_vs_t * vss, int val, int * error) _LIBROAR_VS_STDATTRS;
151
152/* do not supply backend offset */
153#define ROAR_VS_BACKEND_NONE    -1
154/* use first found primary stream of same mixer as offset source */
155#define ROAR_VS_BACKEND_FIRST   -2
156/* use mean of primary streams of same mixer as offset source */
157#define ROAR_VS_BACKEND_MEAN    -3
158/* default backend, now handled at runtime, old value was hard coded to _FIRST */
159#define ROAR_VS_BACKEND_DEFAULT -4
160
161/* get server's position of stream
162 * returns server's position of the stream or -1 on error.
163 * The returned server position is the position in samples
164 * plus a offset provided by the selected backend
165 */
166ssize_t roar_vs_position(roar_vs_t * vss, int backend, int * error) _LIBROAR_VS_STDATTRS;
167
168/* get latency between playback and local write counter
169 * This function may fail because the used codec uses
170 * non-fixed bitrate.
171 * if this function fails it returns zero and sets error or
172 * clear error to ROAR_ERROR_NONE.
173 * If non-zero is returned error is untouched.
174 * return value is in mu-sec (units of 10^-6s).
175 * Note that the returned value may be negative (the server being
176 * ahead of us). This is normal in case we read a stream.
177 */
178roar_mus_t roar_vs_latency(roar_vs_t * vss, int backend, int wait, int * error) _LIBROAR_VS_STDATTRS;
179
180/* set pause flag
181 * The pause flag should be set whenever the user presses the pause button or similar.
182 * The stream may be come blocking after the pause flag has been set.
183 * returns old pause setting (useful with ROAR_VS_TOGGLE)
184 */
185int     roar_vs_pause(roar_vs_t * vss, int val, int * error) _LIBROAR_ATTR_NONNULL(1);
186
187/* set the mute flag of the stream
188 * The pause flag should be set whenever the user mutes the stream in some way.
189 * This flag is used so the volume is not changed and can be restored by the server
190 * while unmuting.
191 * It is very recommended to use this flag and not just set the volume to zero
192 * returns old mute setting (useful with ROAR_VS_TOGGLE)
193 */
194int     roar_vs_mute (roar_vs_t * vss, int val, int * error) _LIBROAR_ATTR_NONNULL(1);
195
196/* set volume of stream (all channels to the same value)
197 * volume c is float from 0 ('muted', see above) to 1 (full volume).
198 * Returns 0 on no error and -1 on error.
199 */
200int     roar_vs_volume_mono   (roar_vs_t * vss, float c, int * error) _LIBROAR_ATTR_NONNULL(1);
201/* set volume of stream (like volume + balance, stereo mode)
202 * volume l and r are floats from 0 ('muted', see above) to 1 (full volume).
203 * Returns 0 on no error and -1 on error.
204 */
205int     roar_vs_volume_stereo (roar_vs_t * vss, float l, float r, int * error) _LIBROAR_ATTR_NONNULL(1);
206
207/* get volume from stream (like volume + balance, stereo mode)
208 * volume pointers l and r are floats from 0 ('muted', see above) to 1 (full volume).
209 * Returns 0 on no error and -1 on error.
210 * NOTE: if you want a 'mono' volume (like roar_vs_volume_mono() takes)
211 * you can just use: c = (*l + *r)/2
212 */
213int     roar_vs_volume_get    (roar_vs_t * vss, float * l, float * r, int * error) _LIBROAR_ATTR_USE_RESULT _LIBROAR_ATTR_NONNULL(1, 2, 3);
214
215/* set an array of meta data for the stream
216 * This sets an array of meta data stored in kv of length len for
217 * the stream.
218 * This should be called before streaming is started using read or write functions
219 * but may be called at any time (for example to updata meta data).
220 * Returns 0 on no error and -1 on error.
221 * Example:
222 * struct roar_keyval kv = {.key = "TITLE", .value = "Some title"};
223 * ret = roar_vs_meta(vss, &kv, 1, &err);
224 */
225int     roar_vs_meta          (roar_vs_t * vss, struct roar_keyval * kv, size_t len, int * error) _LIBROAR_ATTR_NONNULL(1, 2);
226
227/* sets the stream role
228 * see ../roaraudio/stream.h for possible roles
229 * Returns 0 on no error and -1 on error.
230 */
231int     roar_vs_role          (roar_vs_t * vss, int role, int * error) _LIBROAR_ATTR_NONNULL(1);
232
233/* Run a single iteration.
234 * This will try to read data from source, write it to the stream
235 * and flush the buffer in buffered mode.
236 * Returns -1 on error, 0 on EOF and positive true value on no error.
237 */
238int     roar_vs_iterate       (roar_vs_t * vss, int wait, int * error) _LIBROAR_ATTR_NONNULL(1);
239
240/* Iterate until EOF or error.
241 * Very simple main loop.
242 * Returns 0 on no error and -1 on error.
243 */
244int     roar_vs_run           (roar_vs_t * vss, int * error) _LIBROAR_ATTR_NONNULL(1);
245
246ssize_t roar_vs_get_avail_read(roar_vs_t * vss, int * error) _LIBROAR_VS_STDATTRS;
247ssize_t roar_vs_get_avail_write(roar_vs_t * vss, int * error) _LIBROAR_VS_STDATTRS;
248
249/* If in buffered mode drop all data from internal buffer.
250 * This drops all data in current ringbuffers. You can
251 * select if data is only droped in write or read buffer.
252 * This may be usefull in case of seeking and such
253 * but should be avoided as it may break the bitstream.
254 */
255int     roar_vs_reset_buffer(roar_vs_t * vss, int writering, int readring, int * error) _LIBROAR_VS_STDATTRS _LIBROAR_ATTR_DEPRECATED;
256
257/* Misc controls.
258 * Use of this should be avoided by application.
259 */
260
261enum roar_vs_ctlcmd {
262 ROAR_VS_CMD_NOOP      = 0,
263#define ROAR_VS_CMD_NOOP ROAR_VS_CMD_NOOP
264 ROAR_VS_CMD_SET_MIXER,
265#define ROAR_VS_CMD_SET_MIXER ROAR_VS_CMD_SET_MIXER
266 ROAR_VS_CMD_GET_MIXER,
267#define ROAR_VS_CMD_GET_MIXER ROAR_VS_CMD_GET_MIXER
268 ROAR_VS_CMD_SET_FIRST_PRIM,
269#define ROAR_VS_CMD_SET_FIRST_PRIM ROAR_VS_CMD_SET_FIRST_PRIM
270 ROAR_VS_CMD_GET_FIRST_PRIM,
271#define ROAR_VS_CMD_GET_FIRST_PRIM ROAR_VS_CMD_GET_FIRST_PRIM
272
273 // Latency control:
274 ROAR_VS_CMD_SET_LATC_P,
275#define ROAR_VS_CMD_SET_LATC_P ROAR_VS_CMD_SET_LATC_P
276 ROAR_VS_CMD_GET_LATC_P,
277#define ROAR_VS_CMD_GET_LATC_P ROAR_VS_CMD_GET_LATC_P
278 ROAR_VS_CMD_SET_LATC_TARGET,
279#define ROAR_VS_CMD_SET_LATC_TARGET ROAR_VS_CMD_SET_LATC_TARGET
280 ROAR_VS_CMD_GET_LATC_TARGET,
281#define ROAR_VS_CMD_GET_LATC_TARGET ROAR_VS_CMD_GET_LATC_TARGET
282 ROAR_VS_CMD_SET_LATC_WINDOW,
283#define ROAR_VS_CMD_SET_LATC_WINDOW ROAR_VS_CMD_SET_LATC_WINDOW
284 ROAR_VS_CMD_GET_LATC_WINDOW,
285#define ROAR_VS_CMD_GET_LATC_WINDOW ROAR_VS_CMD_GET_LATC_WINDOW
286 ROAR_VS_CMD_SET_LATC_MINLAG,
287#define ROAR_VS_CMD_SET_LATC_MINLAG ROAR_VS_CMD_SET_LATC_MINLAG
288 ROAR_VS_CMD_GET_LATC_MINLAG,
289#define ROAR_VS_CMD_GET_LATC_MINLAG ROAR_VS_CMD_GET_LATC_MINLAG
290
291 // Volume:
292 ROAR_VS_CMD_SET_FREE_VOLUME,
293#define ROAR_VS_CMD_SET_FREE_VOLUME ROAR_VS_CMD_SET_FREE_VOLUME
294 ROAR_VS_CMD_GET_FREE_VOLUME,
295#define ROAR_VS_CMD_GET_FREE_VOLUME ROAR_VS_CMD_GET_FREE_VOLUME
296
297 // auto pause flag, needed for sync streams:
298 ROAR_VS_CMD_SET_DEFAULT_PAUSED,
299#define ROAR_VS_CMD_SET_DEFAULT_PAUSED ROAR_VS_CMD_SET_DEFAULT_PAUSED
300 ROAR_VS_CMD_GET_DEFAULT_PAUSED,
301#define ROAR_VS_CMD_GET_DEFAULT_PAUSED ROAR_VS_CMD_GET_DEFAULT_PAUSED
302
303 // Async operation:
304 ROAR_VS_CMD_SET_ASYNC,
305#define ROAR_VS_CMD_SET_ASYNC ROAR_VS_CMD_SET_ASYNC
306 ROAR_VS_CMD_GET_ASYNC,
307#define ROAR_VS_CMD_GET_ASYNC ROAR_VS_CMD_GET_ASYNC
308 ROAR_VS_CMD_LOCK_ASYNC,
309#define ROAR_VS_CMD_LOCK_ASYNC ROAR_VS_CMD_LOCK_ASYNC
310 ROAR_VS_CMD_UNLOCK_ASYNC,
311#define ROAR_VS_CMD_UNLOCK_ASYNC ROAR_VS_CMD_UNLOCK_ASYNC
312};
313
314typedef enum roar_vs_ctlcmd roar_vs_ctlcmd;
315
316#define ROAR_VS_ASYNCLEVEL_NONE   0
317#define ROAR_VS_ASYNCLEVEL_ENABLE 1
318#define ROAR_VS_ASYNCLEVEL_AUTO   2
319
320int     roar_vs_ctl           (roar_vs_t * vss, roar_vs_ctlcmd cmd, void * argp, int * error) _LIBROAR_VS_STDATTRS;
321
322
323/* Get used connection object
324 * This may be useful if you want to use functions from the main API.
325 * Returns used connection object or NULL on error.
326 */
327struct roar_connection * roar_vs_connection_obj(roar_vs_t * vss, int * error) _LIBROAR_VS_STDATTRS;
328
329/* Get used stream object
330 * This may be useful if you want to use functions from the main API.
331 * Returns used stream object or NULL on error.
332 */
333struct roar_stream     * roar_vs_stream_obj    (roar_vs_t * vss, int * error) _LIBROAR_VS_STDATTRS;
334
335/* Get used VIO object
336 * This may be useful if you want to use functions from the main API.
337 * For example this can be used in non-blocking mode
338 * to test if we can read or write. To test that use roar_vio_select().
339 * Returns used VIO object or NULL on error.
340 */
341struct roar_vio_calls  * roar_vs_vio_obj       (roar_vs_t * vss, int * error) _LIBROAR_VS_STDATTRS;
342
343/* send NOOP command to server
344 * This can be used to ping the server.
345 * This is of no use normally.
346 * Returns 0 on no error and -1 on error.
347 */
348#define roar_vs_noop(v, error) roar_noop(roar_vs_connection_obj((v), (error)))
349
350#endif
351
352//ll
Note: See TracBrowser for help on using the repository browser.