XMMS2
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
27#include "xmms/xmms_sample.h"
28#include "xmms/xmms_plugin.h"
29#include "xmms/xmms_error.h"
30#include "xmms/xmms_config.h"
32#include "xmms/xmms_medialib.h"
33
34G_BEGIN_DECLS
35
36/**
37 * @defgroup OutputPlugin OutputPlugin
38 * @ingroup XMMSPlugin
39 * @{
40 */
41
42
43typedef struct xmms_output_St xmms_output_t;
44
45/**
46 * The current API version.
47 */
48#define XMMS_OUTPUT_API_VERSION 8
49
50struct xmms_output_plugin_St;
51typedef 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 */
62typedef 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 */
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 */
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 */
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 */
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 */
265void 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 */
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 */
311gint 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 */
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 */
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 */
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 */
360xmms_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
377xmms_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 */
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 */
395
396/** @} */
397
398G_END_DECLS
399
400#endif
void xmms_output_plugin_methods_set(xmms_output_plugin_t *output, xmms_output_methods_t *methods)
Register the output plugin functions.
Definition: outputplugin.c:87
gint xmms_output_bytes_available(xmms_output_t *output)
Gets Number of available bytes in the output buffer.
Definition: output.c:562
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)
Register a configuration directive in the plugin setup function.
Definition: outputplugin.c:146
xmms_medialib_entry_t xmms_output_current_id(xmms_output_t *output)
Get the currently medialib id of the currently played entry.
Definition: output.c:582
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)
Register a configuration directive.
Definition: output.c:568
xmms_config_property_t * xmms_output_config_lookup(xmms_output_t *output, const gchar *path)
Lookup a configuration directive for the output plugin.
Definition: output.c:575
void xmms_output_private_data_set(xmms_output_t *output, gpointer data)
Set the private data for the plugin that can be retrived with xmms_output_private_data_get later.
Definition: output.c:171
struct xmms_output_methods_St xmms_output_methods_t
Output functions that lets XMMS2 talk to the soundcard.
void xmms_output_stream_type_add(xmms_output_t *output,...)
Add format to list of supported formats.
Definition: output.c:180
void xmms_output_set_error(xmms_output_t *output, xmms_error_t *error)
Set an error.
Definition: output.c:255
gboolean xmms_output_plugin_format_set_always(xmms_output_plugin_t *plugin)
Check if an output plugin needs format updates on each track change.
Definition: outputplugin.c:226
gint xmms_output_read(xmms_output_t *output, char *buffer, gint len)
Read a number of bytes of data from the output buffer into a buffer.
Definition: output.c:522
struct xmms_output_St xmms_output_t
gpointer xmms_output_private_data_get(xmms_output_t *output)
Retrieve the private data for the plugin that was set with xmms_output_private_data_set.
Definition: output.c:162
struct xmms_output_plugin_St xmms_output_plugin_t
Output functions that lets XMMS2 talk to the soundcard.
void(* flush)(xmms_output_t *output)
Flush the soundcard buffer.
void(* write)(xmms_output_t *output, gpointer buffer, gint size, xmms_error_t *err)
Write audio data to the output device.
gboolean(* volume_get)(xmms_output_t *output, const gchar **names, guint *levels, guint *nchans)
Get volume.
void(* close)(xmms_output_t *output)
Close the output device.
gboolean(* volume_set)(xmms_output_t *output, const gchar *chan, guint val)
Set volume.
void(* destroy)(xmms_output_t *output)
Destroy the output plugin.
gboolean(* status)(xmms_output_t *output, xmms_playback_status_t status)
Update the output plugin with the current playback status.
gboolean(* format_set)(xmms_output_t *output, const xmms_stream_type_t *type)
Update the sample format.
guint(* latency_get)(xmms_output_t *)
Get the number of bytes in the soundcard buffer.
gboolean(* format_set_always)(xmms_output_t *output, const xmms_stream_type_t *type)
Update the sample format.
gboolean(* open)(xmms_output_t *output)
Open the output device.
struct xmms_config_property_St xmms_config_property_t
Definition: xmms_config.h:26
G_BEGIN_DECLS typedef gint32 xmms_medialib_entry_t
Definition: xmms_medialib.h:86
struct xmms_stream_type_St xmms_stream_type_t
G_BEGIN_DECLS struct xmms_error_St xmms_error_t
void(* xmms_object_handler_t)(xmms_object_t *object, xmmsv_t *data, gpointer userdata)
Definition: xmms_object.h:66
xmms_playback_status_t