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 
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  */
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  */
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  */
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  */
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  */
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 
398 G_END_DECLS
399 
400 #endif
G_BEGIN_DECLS typedef gint32 xmms_medialib_entry_t
Definition: xmms_medialib.h:86
gboolean(* format_set)(xmms_output_t *output, const xmms_stream_type_t *type)
Update the sample format.
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
guint(* latency_get)(xmms_output_t *)
Get the number of bytes in the soundcard buffer.
struct xmms_stream_type_St xmms_stream_type_t
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_methods_St xmms_output_methods_t
Output functions that lets XMMS2 talk to the soundcard.
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
gboolean(* open)(xmms_output_t *output)
Open the output device.
void(* destroy)(xmms_output_t *output)
Destroy the output plugin.
Output functions that lets XMMS2 talk to the soundcard.
void(* close)(xmms_output_t *output)
Close the output device.
struct xmms_output_St xmms_output_t
struct xmms_output_plugin_St xmms_output_plugin_t
gboolean(* format_set_always)(xmms_output_t *output, const xmms_stream_type_t *type)
Update the sample format.
gboolean(* volume_get)(xmms_output_t *output, const gchar **names, guint *levels, guint *nchans)
Get volume.
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
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
gboolean(* volume_set)(xmms_output_t *output, const gchar *chan, guint val)
Set volume.
gint xmms_output_bytes_available(xmms_output_t *output)
Gets Number of available bytes in the output buffer.
Definition: output.c:562
void xmms_output_stream_type_add(xmms_output_t *output,...)
Add format to list of supported formats.
Definition: output.c:180
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
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
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_playback_status_t
G_BEGIN_DECLS struct xmms_error_St xmms_error_t
gboolean(* status)(xmms_output_t *output, xmms_playback_status_t status)
Update the output plugin with the current playback status.
struct xmms_config_property_St xmms_config_property_t
Definition: xmms_config.h:26
void(* write)(xmms_output_t *output, gpointer buffer, gint size, xmms_error_t *err)
Write audio data to the output device.
void(* flush)(xmms_output_t *output)
Flush the soundcard buffer.
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
void(* xmms_object_handler_t)(xmms_object_t *object, xmmsv_t *data, gpointer userdata)
Definition: xmms_object.h:66
void xmms_output_set_error(xmms_output_t *output, xmms_error_t *error)
Set an error.
Definition: output.c:255