XMMS2

src/include/xmms/xmms_outputplugin.h

Go to the documentation of this file.
00001 /*  XMMS2 - X Music Multiplexer System
00002  *  Copyright (C) 2003-2009 XMMS2 Team
00003  *
00004  *  PLUGINS ARE NOT CONSIDERED TO BE DERIVED WORK !!!
00005  *
00006  *  This library is free software; you can redistribute it and/or
00007  *  modify it under the terms of the GNU Lesser General Public
00008  *  License as published by the Free Software Foundation; either
00009  *  version 2.1 of the License, or (at your option) any later version.
00010  *
00011  *  This library is distributed in the hope that it will be useful,
00012  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00013  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00014  *  Lesser General Public License for more details.
00015  */
00016 
00017 
00018 
00019 
00020 #ifndef _XMMS_OUTPUTPLUGIN_H_
00021 #define _XMMS_OUTPUTPLUGIN_H_
00022 
00023 #include <glib.h>
00024 #include <string.h> /* for memset() */
00025 
00026 #include "xmmsc/xmmsc_idnumbers.h"
00027 #include "xmms/xmms_sample.h"
00028 #include "xmms/xmms_plugin.h"
00029 #include "xmms/xmms_error.h"
00030 #include "xmms/xmms_config.h"
00031 #include "xmms/xmms_streamtype.h"
00032 #include "xmms/xmms_medialib.h"
00033 
00034 G_BEGIN_DECLS
00035 
00036 /**
00037  * @defgroup OutputPlugin OutputPlugin
00038  * @ingroup XMMSPlugin
00039  * @{
00040  */
00041 
00042 
00043 typedef struct xmms_output_St xmms_output_t;
00044 
00045 /**
00046  * The current API version.
00047  */
00048 #define XMMS_OUTPUT_API_VERSION 8
00049 
00050 struct xmms_output_plugin_St;
00051 typedef struct xmms_output_plugin_St xmms_output_plugin_t;
00052 
00053 /**
00054  * Output functions that lets XMMS2 talk to the soundcard.
00055  * An output plugin can behave in two diffrent ways. It can either use
00056  * it's own event system, or it can depend on the one XMMS2 provides.
00057  * If the architechture uses its own event mechanism the plugin should
00058  * not implement open/close/write. Instead a status function is implemented
00059  * which will be notified on playback status updates, and perform the
00060  * proper actions based on this.
00061  */
00062 typedef struct xmms_output_methods_St {
00063     /**
00064      * Initiate the output plugin.
00065      *
00066      * This function should setup everything that is required to function
00067      * once the output device is opened for playback. This may for example
00068      * include probing for usable sound formats (#xmms_output_format_add)
00069      * and setting up the mixer. Blocking calls in this function are to be
00070      * avoided as far as possible as this would freeze the startup of xmms2d.
00071      *
00072      * @param output an output object
00073      * @return TRUE on successful init, otherwise FALSE
00074      */
00075     gboolean (*new)(xmms_output_t *output);
00076 
00077     /**
00078      * Destroy the output plugin.
00079      *
00080      * Tear down the data initialized in new.
00081      *
00082      * @param output an output object
00083      */
00084     void (*destroy)(xmms_output_t *output);
00085 
00086     /**
00087      * Open the output device.
00088      *
00089      * Blocking calls in this function are to be avoided as far as
00090      * possible as this would freeze xmms2d. This function cannot coexist
00091      * with #status.
00092      *
00093      * @param output an output object
00094      * @return TRUE on successful opening of the output device, otherwise FALSE
00095      */
00096     gboolean (*open)(xmms_output_t *output);
00097 
00098     /**
00099      * Close the output device.
00100      *
00101      * This function cannot coexist with #status.
00102      *
00103      * @param output an output object
00104      */
00105     void (*close)(xmms_output_t *output);
00106 
00107     /**
00108      * Flush the soundcard buffer.
00109      *
00110      * This should tell the soundcard to drop whatever it is doing and
00111      * empty the buffer.
00112      *
00113      * @param output an output object
00114      */
00115     void (*flush)(xmms_output_t *output);
00116 
00117     /**
00118      * Update the sample format.
00119      *
00120      * This should tell the soundcard what sample format that will be used
00121      * for the next track. This is only called when there is an actual
00122      * change in the sample format. This function cannot coexist with
00123      * #format_set_always.
00124      *
00125      * @param output an output object
00126      * @param type the stream type to use
00127      * @return TRUE if the format was successfully set.
00128      */
00129     gboolean (*format_set)(xmms_output_t *output,
00130                            const xmms_stream_type_t *type);
00131 
00132     /**
00133      * Update the sample format.
00134      *
00135      * This should tell the soundcard what sample format that will be used
00136      * for the next track. This is called each time a track changes even
00137      * if the sample format is identical to the previous one. This function
00138      * cannot coexist with #format_set.
00139      *
00140      * @param output an output object
00141      * @param type the stream type to use
00142      * @return TRUE if the format was successfully set.
00143      */
00144     gboolean (*format_set_always)(xmms_output_t *output,
00145                                   const xmms_stream_type_t *type);
00146 
00147     /**
00148      * Update the output plugin with the current playback status.
00149      *
00150      * This function is used when the output architecture is driven by an
00151      * external thread. When status is set to XMMS_PLAYBACK_STATUS_PLAY,
00152      * the external thread should be activated, and will then get its data
00153      * from #xmms_output_read, and render it to the soundcard buffer.
00154      * This function cannot coexist with #open, #close or #write.
00155      *
00156      * @param output an output object
00157      * @param status the new playback status
00158      */
00159     gboolean (*status)(xmms_output_t *output, xmms_playback_status_t status);
00160 
00161     /**
00162      * Set volume.
00163      *
00164      * @param output an output object
00165      * @param chan the name of the channel to set volume on
00166      * @param val the volume level to set
00167      * @return TRUE if the update was successful, else FALSE
00168      */
00169     gboolean (*volume_set)(xmms_output_t *output, const gchar *chan, guint val);
00170 
00171     /**
00172      * Get volume.
00173      *
00174      * This function is typically called twice. The first run NULL will be
00175      * passed to parameters names and levels, and the output plugin will then
00176      * set the number of available channels to nchans and return TRUE. When
00177      * the channels are known memory will be allocated for the channel names
00178      * and volume level lists and the function will be called again, and this
00179      * time the volume levels are extracted for real.
00180      *
00181      * @param output an output object
00182      * @param names a pointer to a list that is to be filled with channel names
00183      * @param levels a pointer to a list that is to be filled with volume levels
00184      * @param nchans a pointer to a list that is to be filled with the nbr of chns
00185      * @return TRUE if the volume/chn count successfully retrieved, else FALSE
00186      */
00187     gboolean (*volume_get)(xmms_output_t *output, const gchar **names,
00188                            guint *levels, guint *nchans);
00189 
00190     /**
00191      * Write audio data to the output device.
00192      *
00193      * This function is called from a separate thread and should block until
00194      * the input buffer has been written to the soundcard. This function cannot
00195      * coexist with #status.
00196      *
00197      * @param output an output object
00198      * @param buffer a buffer with audio data to write to the soundcard
00199      * @param size the number of bytes in the buffer
00200      * @param err an error struct
00201      */
00202     void (*write)(xmms_output_t *output, gpointer buffer,
00203                   gint size, xmms_error_t *err);
00204 
00205     /**
00206      * Get the number of bytes in the soundcard buffer.
00207      *
00208      * This is needed for the visualization to perform correct synchronization
00209      * between audio and graphics for example.
00210      *
00211      * @param output an output object
00212      * @return the number of bytes in the soundcard buffer or 0 on failure
00213      */
00214     guint (*latency_get)(xmms_output_t *);
00215 } xmms_output_methods_t;
00216 
00217 /**
00218  * Register the output plugin.
00219  *
00220  * @param shname short name of the plugin
00221  * @param name long name of the plugin
00222  * @param ver the version of the plugin, usually the XMMS_VERSION macro
00223  * @param desc a description of the plugin
00224  * @param setupfunc the function that sets up the plugin functions
00225  */
00226 #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)
00227 
00228 /**
00229  * Initialize the #xmms_output_methods_t struct.
00230  *
00231  * This should be run before any functions are associated.
00232  *
00233  * @param m the #xmms_output_methods_t struct to initialize
00234  */
00235 #define XMMS_OUTPUT_METHODS_INIT(m) memset (&m, 0, sizeof (xmms_output_methods_t))
00236 
00237 
00238 /**
00239  * Register the output plugin functions.
00240  *
00241  * Performs basic validation, see #xmms_output_methods_St for more information.
00242  *
00243  * @param output an output plugin object
00244  * @param methods a struct pointing to the plugin specific functions
00245  */
00246 void xmms_output_plugin_methods_set (xmms_output_plugin_t *output, xmms_output_methods_t *methods);
00247 
00248 
00249 /**
00250  * Retrieve the private data for the plugin that was set with
00251  * #xmms_output_private_data_set.
00252  *
00253  * @param output an output object
00254  * @return the private data
00255  */
00256 gpointer xmms_output_private_data_get (xmms_output_t *output);
00257 
00258 /**
00259  * Set the private data for the plugin that can be retrived
00260  * with #xmms_output_private_data_get later.
00261  *
00262  * @param output an output object
00263  * @param data the private data
00264  */
00265 void xmms_output_private_data_set (xmms_output_t *output, gpointer data);
00266 
00267 /**
00268  * Add a format that the output plugin can feed the soundcard with.
00269  *
00270  * @param output an output object
00271  * @param fmt a #xmms_sample_format_t
00272  * @param ch the number of channels
00273  * @param rate the sample rate
00274  */
00275 #define xmms_output_format_add(output, fmt, ch, rate)           \
00276         xmms_output_stream_type_add (output,                            \
00277                                      XMMS_STREAM_TYPE_MIMETYPE,         \
00278                                      "audio/pcm",                       \
00279                                      XMMS_STREAM_TYPE_FMT_FORMAT,       \
00280                                      fmt,                               \
00281                                      XMMS_STREAM_TYPE_FMT_CHANNELS,     \
00282                                      ch,                                \
00283                                      XMMS_STREAM_TYPE_FMT_SAMPLERATE,   \
00284                                      rate,                              \
00285                                      XMMS_STREAM_TYPE_END)
00286 
00287 
00288 /**
00289  * Add format to list of supported formats.
00290  * Should be called from initialisation function for every supported
00291  * format. Any call to the format_set function will be with one of these
00292  * formats.
00293  *
00294  * @param output an output object
00295  * @param ... pairs of #xmms_stream_type_key_t, value
00296  */
00297 void xmms_output_stream_type_add (xmms_output_t *output, ...);
00298 
00299 /**
00300  * Read a number of bytes of data from the output buffer into a buffer.
00301  *
00302  * This is typically used when the output plugin is event driven, and is
00303  * then used when the status is set to playing, and the output needs more
00304  * data from xmms2 to write to the soundcard.
00305  *
00306  * @param output an output object
00307  * @param buffer a buffer to store the read data in
00308  * @param len the number of bytes to read
00309  * @return the number of bytes read
00310  */
00311 gint xmms_output_read (xmms_output_t *output, char *buffer, gint len);
00312 
00313 /**
00314  * Set an error.
00315  *
00316  * When an error occurs in an asynchronous function, the error can be
00317  * propagated using this function.
00318  *
00319  * @param output an output object
00320  * @param error an error object
00321  */
00322 void xmms_output_set_error (xmms_output_t *output, xmms_error_t *error);
00323 
00324 /**
00325  * Check if an output plugin needs format updates on each track change.
00326  *
00327  * @param plugin an output plugin object
00328  * @return TRUE if the plugin should always be notified, otherwise FALSE
00329  */
00330 gboolean xmms_output_plugin_format_set_always (xmms_output_plugin_t *plugin);
00331 
00332 /**
00333  * Register a configuration directive in the plugin setup function.
00334  *
00335  * As an optional, but recomended functionality the plugin can decide to
00336  * subscribe on the configuration value and will thus be notified when it
00337  * changes by passing a callback, and if needed, userdata.
00338  *
00339  * @param plugin an output plugin object
00340  * @param name the name of the configuration directive
00341  * @param default_value the default value of the configuration directive
00342  * @param cb the function to call on configuration value changes
00343  * @param userdata a user specified variable to be passed to the callback
00344  * @return a #xmms_config_property_t based on the given input
00345  */
00346 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);
00347 
00348 /**
00349  * Register a configuration directive.
00350  *
00351  * As an optional, but recomended functionality the plugin can decide to
00352  * subscribe on the configuration value and will thus be notified when it
00353  * changes by passing a callback, and if needed, userdata.
00354  *
00355  * @param output an output object
00356  * @param name the name of the configuration directive
00357  * @param default_value the default value of the configuration directive
00358  * @param cb the function to call on configuration value changes
00359  * @param userdata a user specified variable to be passed to the callback
00360  * @return a #xmms_config_property_t based on the given input
00361  */
00362 
00363 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);
00364 
00365 /**
00366  * Lookup a configuration directive for the output plugin.
00367  *
00368  * @param output an output object
00369  * @param path the path to the configuration value
00370  * @return a #xmms_config_property_t found at the given path
00371  */
00372 xmms_config_property_t *xmms_output_config_lookup (xmms_output_t *output, const gchar *path);
00373 
00374 /**
00375  * Get the currently medialib id of the currently played entry
00376  *
00377  * @param output an output object
00378  * @return the current entry as #xmms_medialib_entry_t or 0 on error
00379  */
00380 xmms_medialib_entry_t xmms_output_current_id (xmms_output_t *output);
00381 
00382 /** @} */
00383 
00384 G_END_DECLS
00385 
00386 #endif