XMMS2
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
src
include
xmms
xmms_outputplugin.h
Go to the documentation of this file.
1
/* XMMS2 - X Music Multiplexer System
2
* Copyright (C) 2003-2011 XMMS2 Team
3
*
4
* PLUGINS ARE NOT CONSIDERED TO BE DERIVED WORK !!!
5
*
6
* This library is free software; you can redistribute it and/or
7
* modify it under the terms of the GNU Lesser General Public
8
* License as published by the Free Software Foundation; either
9
* version 2.1 of the License, or (at your option) any later version.
10
*
11
* This library is distributed in the hope that it will be useful,
12
* but WITHOUT ANY WARRANTY; without even the implied warranty of
13
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14
* Lesser General Public License for more details.
15
*/
16
17
18
19
20
#ifndef _XMMS_OUTPUTPLUGIN_H_
21
#define _XMMS_OUTPUTPLUGIN_H_
22
23
#include <glib.h>
24
#include <string.h>
/* for memset() */
25
26
#include "
xmmsc/xmmsc_idnumbers.h
"
27
#include "
xmms/xmms_sample.h
"
28
#include "
xmms/xmms_plugin.h
"
29
#include "
xmms/xmms_error.h
"
30
#include "
xmms/xmms_config.h
"
31
#include "
xmms/xmms_streamtype.h
"
32
#include "
xmms/xmms_medialib.h
"
33
34
G_BEGIN_DECLS
35
36
/**
37
* @defgroup OutputPlugin OutputPlugin
38
* @ingroup XMMSPlugin
39
* @{
40
*/
41
42
43
typedef
struct
xmms_output_St
xmms_output_t
;
44
45
/**
46
* The current API version.
47
*/
48
#define XMMS_OUTPUT_API_VERSION 8
49
50
struct
xmms_output_plugin_St;
51
typedef
struct
xmms_output_plugin_St
xmms_output_plugin_t
;
52
53
/**
54
* Output functions that lets XMMS2 talk to the soundcard.
55
* An output plugin can behave in two diffrent ways. It can either use
56
* it's own event system, or it can depend on the one XMMS2 provides.
57
* If the architechture uses its own event mechanism the plugin should
58
* not implement open/close/write. Instead a status function is implemented
59
* which will be notified on playback status updates, and perform the
60
* proper actions based on this.
61
*/
62
typedef
struct
xmms_output_methods_St
{
63
/**
64
* Initiate the output plugin.
65
*
66
* This function should setup everything that is required to function
67
* once the output device is opened for playback. This may for example
68
* include probing for usable sound formats (#xmms_output_format_add)
69
* and setting up the mixer. Blocking calls in this function are to be
70
* avoided as far as possible as this would freeze the startup of xmms2d.
71
*
72
* @param output an output object
73
* @return TRUE on successful init, otherwise FALSE
74
*/
75
gboolean (*
new
)(
xmms_output_t
*output);
76
77
/**
78
* Destroy the output plugin.
79
*
80
* Tear down the data initialized in new.
81
*
82
* @param output an output object
83
*/
84
void (*
destroy
)(
xmms_output_t
*output);
85
86
/**
87
* Open the output device.
88
*
89
* Blocking calls in this function are to be avoided as far as
90
* possible as this would freeze xmms2d. This function cannot coexist
91
* with #status.
92
*
93
* @param output an output object
94
* @return TRUE on successful opening of the output device, otherwise FALSE
95
*/
96
gboolean (*
open
)(
xmms_output_t
*output);
97
98
/**
99
* Close the output device.
100
*
101
* This function cannot coexist with #status.
102
*
103
* @param output an output object
104
*/
105
void (*
close
)(
xmms_output_t
*output);
106
107
/**
108
* Flush the soundcard buffer.
109
*
110
* This should tell the soundcard to drop whatever it is doing and
111
* empty the buffer.
112
*
113
* @param output an output object
114
*/
115
void (*
flush
)(
xmms_output_t
*output);
116
117
/**
118
* Update the sample format.
119
*
120
* This should tell the soundcard what sample format that will be used
121
* for the next track. This is only called when there is an actual
122
* change in the sample format. This function cannot coexist with
123
* #format_set_always.
124
*
125
* @param output an output object
126
* @param type the stream type to use
127
* @return TRUE if the format was successfully set.
128
*/
129
gboolean (*
format_set
)(
xmms_output_t
*output,
130
const
xmms_stream_type_t
*type);
131
132
/**
133
* Update the sample format.
134
*
135
* This should tell the soundcard what sample format that will be used
136
* for the next track. This is called each time a track changes even
137
* if the sample format is identical to the previous one. This function
138
* cannot coexist with #format_set.
139
*
140
* @param output an output object
141
* @param type the stream type to use
142
* @return TRUE if the format was successfully set.
143
*/
144
gboolean (*
format_set_always
)(
xmms_output_t
*output,
145
const
xmms_stream_type_t
*type);
146
147
/**
148
* Update the output plugin with the current playback status.
149
*
150
* This function is used when the output architecture is driven by an
151
* external thread. When status is set to XMMS_PLAYBACK_STATUS_PLAY,
152
* the external thread should be activated, and will then get its data
153
* from #xmms_output_read, and render it to the soundcard buffer.
154
* This function cannot coexist with #open, #close or #write.
155
*
156
* @param output an output object
157
* @param status the new playback status
158
*/
159
gboolean (*
status
)(
xmms_output_t
*output,
xmms_playback_status_t
status
);
160
161
/**
162
* Set volume.
163
*
164
* @param output an output object
165
* @param chan the name of the channel to set volume on
166
* @param val the volume level to set
167
* @return TRUE if the update was successful, else FALSE
168
*/
169
gboolean (*
volume_set
)(
xmms_output_t
*output,
const
gchar *chan, guint val);
170
171
/**
172
* Get volume.
173
*
174
* This function is typically called twice. The first run NULL will be
175
* passed to parameters names and levels, and the output plugin will then
176
* set the number of available channels to nchans and return TRUE. When
177
* the channels are known memory will be allocated for the channel names
178
* and volume level lists and the function will be called again, and this
179
* time the volume levels are extracted for real.
180
*
181
* @param output an output object
182
* @param names a pointer to a list that is to be filled with channel names
183
* @param levels a pointer to a list that is to be filled with volume levels
184
* @param nchans a pointer to a list that is to be filled with the nbr of chns
185
* @return TRUE if the volume/chn count successfully retrieved, else FALSE
186
*/
187
gboolean (*
volume_get
)(
xmms_output_t
*output,
const
gchar **names,
188
guint *levels, guint *nchans);
189
190
/**
191
* Write audio data to the output device.
192
*
193
* This function is called from a separate thread and should block until
194
* the input buffer has been written to the soundcard. This function cannot
195
* coexist with #status.
196
*
197
* @param output an output object
198
* @param buffer a buffer with audio data to write to the soundcard
199
* @param size the number of bytes in the buffer
200
* @param err an error struct
201
*/
202
void (*
write
)(
xmms_output_t
*output, gpointer buffer,
203
gint size,
xmms_error_t
*err);
204
205
/**
206
* Get the number of bytes in the soundcard buffer.
207
*
208
* This is needed for the visualization to perform correct synchronization
209
* between audio and graphics for example.
210
*
211
* @param output an output object
212
* @return the number of bytes in the soundcard buffer or 0 on failure
213
*/
214
guint (*
latency_get
)(
xmms_output_t
*);
215
}
xmms_output_methods_t
;
216
217
/**
218
* Register the output plugin.
219
*
220
* @param shname short name of the plugin
221
* @param name long name of the plugin
222
* @param ver the version of the plugin, usually the XMMS_VERSION macro
223
* @param desc a description of the plugin
224
* @param setupfunc the function that sets up the plugin functions
225
*/
226
#define XMMS_OUTPUT_PLUGIN(shname, name, ver, desc, setupfunc) XMMS_PLUGIN(XMMS_PLUGIN_TYPE_OUTPUT, XMMS_OUTPUT_API_VERSION, shname, name, ver, desc, (gboolean (*)(gpointer))setupfunc)
227
228
/**
229
* Initialize the #xmms_output_methods_t struct.
230
*
231
* This should be run before any functions are associated.
232
*
233
* @param m the #xmms_output_methods_t struct to initialize
234
*/
235
#define XMMS_OUTPUT_METHODS_INIT(m) memset (&m, 0, sizeof (xmms_output_methods_t))
236
237
238
/**
239
* Register the output plugin functions.
240
*
241
* Performs basic validation, see #xmms_output_methods_St for more information.
242
*
243
* @param output an output plugin object
244
* @param methods a struct pointing to the plugin specific functions
245
*/
246
void
xmms_output_plugin_methods_set
(
xmms_output_plugin_t
*output,
xmms_output_methods_t
*methods);
247
248
249
/**
250
* Retrieve the private data for the plugin that was set with
251
* #xmms_output_private_data_set.
252
*
253
* @param output an output object
254
* @return the private data
255
*/
256
gpointer
xmms_output_private_data_get
(
xmms_output_t
*output);
257
258
/**
259
* Set the private data for the plugin that can be retrived
260
* with #xmms_output_private_data_get later.
261
*
262
* @param output an output object
263
* @param data the private data
264
*/
265
void
xmms_output_private_data_set
(
xmms_output_t
*output, gpointer data);
266
267
/**
268
* Add a format that the output plugin can feed the soundcard with.
269
*
270
* @param output an output object
271
* @param fmt a #xmms_sample_format_t
272
* @param ch the number of channels
273
* @param rate the sample rate
274
*/
275
#define xmms_output_format_add(output, fmt, ch, rate) \
276
xmms_output_stream_type_add (output, \
277
XMMS_STREAM_TYPE_MIMETYPE, \
278
"audio/pcm", \
279
XMMS_STREAM_TYPE_FMT_FORMAT, \
280
fmt, \
281
XMMS_STREAM_TYPE_FMT_CHANNELS, \
282
ch, \
283
XMMS_STREAM_TYPE_FMT_SAMPLERATE, \
284
rate, \
285
XMMS_STREAM_TYPE_END)
286
287
288
/**
289
* Add format to list of supported formats.
290
* Should be called from initialisation function for every supported
291
* format. Any call to the format_set function will be with one of these
292
* formats.
293
*
294
* @param output an output object
295
* @param ... pairs of #xmms_stream_type_key_t, value
296
*/
297
void
xmms_output_stream_type_add
(
xmms_output_t
*output, ...);
298
299
/**
300
* Read a number of bytes of data from the output buffer into a buffer.
301
*
302
* This is typically used when the output plugin is event driven, and is
303
* then used when the status is set to playing, and the output needs more
304
* data from xmms2 to write to the soundcard.
305
*
306
* @param output an output object
307
* @param buffer a buffer to store the read data in
308
* @param len the number of bytes to read
309
* @return the number of bytes read
310
*/
311
gint
xmms_output_read
(
xmms_output_t
*output,
char
*buffer, gint len);
312
313
/**
314
* Gets Number of available bytes in the output buffer
315
*
316
* This is typically used when the output plugin is event driven, and is
317
* then used when the status is set to playing, and the output needs more
318
* data from xmms2 to write to the soundcard.
319
*
320
* @param output an output object
321
* @param buffer a buffer to store the read data in
322
* @param len the number of bytes to read
323
* @return the number of bytes read
324
*/
325
gint
xmms_output_bytes_available
(
xmms_output_t
*output);
326
327
/**
328
* Set an error.
329
*
330
* When an error occurs in an asynchronous function, the error can be
331
* propagated using this function.
332
*
333
* @param output an output object
334
* @param error an error object
335
*/
336
void
xmms_output_set_error
(
xmms_output_t
*output,
xmms_error_t
*error);
337
338
/**
339
* Check if an output plugin needs format updates on each track change.
340
*
341
* @param plugin an output plugin object
342
* @return TRUE if the plugin should always be notified, otherwise FALSE
343
*/
344
gboolean
xmms_output_plugin_format_set_always
(
xmms_output_plugin_t
*plugin);
345
346
/**
347
* Register a configuration directive in the plugin setup function.
348
*
349
* As an optional, but recomended functionality the plugin can decide to
350
* subscribe on the configuration value and will thus be notified when it
351
* changes by passing a callback, and if needed, userdata.
352
*
353
* @param plugin an output plugin object
354
* @param name the name of the configuration directive
355
* @param default_value the default value of the configuration directive
356
* @param cb the function to call on configuration value changes
357
* @param userdata a user specified variable to be passed to the callback
358
* @return a #xmms_config_property_t based on the given input
359
*/
360
xmms_config_property_t
*
xmms_output_plugin_config_property_register
(
xmms_output_plugin_t
*plugin,
const
gchar *name,
const
gchar *default_value,
xmms_object_handler_t
cb, gpointer userdata);
361
362
/**
363
* Register a configuration directive.
364
*
365
* As an optional, but recomended functionality the plugin can decide to
366
* subscribe on the configuration value and will thus be notified when it
367
* changes by passing a callback, and if needed, userdata.
368
*
369
* @param output an output object
370
* @param name the name of the configuration directive
371
* @param default_value the default value of the configuration directive
372
* @param cb the function to call on configuration value changes
373
* @param userdata a user specified variable to be passed to the callback
374
* @return a #xmms_config_property_t based on the given input
375
*/
376
377
xmms_config_property_t
*
xmms_output_config_property_register
(
xmms_output_t
*output,
const
gchar *name,
const
gchar *default_value,
xmms_object_handler_t
cb, gpointer userdata);
378
379
/**
380
* Lookup a configuration directive for the output plugin.
381
*
382
* @param output an output object
383
* @param path the path to the configuration value
384
* @return a #xmms_config_property_t found at the given path
385
*/
386
xmms_config_property_t
*
xmms_output_config_lookup
(
xmms_output_t
*output,
const
gchar *path);
387
388
/**
389
* Get the currently medialib id of the currently played entry
390
*
391
* @param output an output object
392
* @return the current entry as #xmms_medialib_entry_t or 0 on error
393
*/
394
xmms_medialib_entry_t
xmms_output_current_id
(
xmms_output_t
*output);
395
396
/** @} */
397
398
G_END_DECLS
399
400
#endif
Generated by
1.8.1