00001 /* XMMS2 - X Music Multiplexer System 00002 * Copyright (C) 2003-2008 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 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 6 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 * Get the current medialib id. 00326 * 00327 * @param output an output object 00328 * @param error an error object 00329 * @return the current medialib id 00330 */ 00331 guint xmms_output_current_id (xmms_output_t *output, xmms_error_t *error); 00332 00333 /** 00334 * Check if an output plugin needs format updates on each track change. 00335 * 00336 * @param plugin an output plugin object 00337 * @return TRUE if the plugin should always be notified, otherwise FALSE 00338 */ 00339 gboolean xmms_output_plugin_format_set_always (xmms_output_plugin_t *plugin); 00340 00341 /** 00342 * Register a configuration directive in the plugin setup function. 00343 * 00344 * As an optional, but recomended functionality the plugin can decide to 00345 * subscribe on the configuration value and will thus be notified when it 00346 * changes by passing a callback, and if needed, userdata. 00347 * 00348 * @param plugin an output plugin object 00349 * @param name the name of the configuration directive 00350 * @param default_value the default value of the configuration directive 00351 * @param cb the function to call on configuration value changes 00352 * @param userdata a user specified variable to be passed to the callback 00353 * @return a #xmms_config_property_t based on the given input 00354 */ 00355 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); 00356 00357 /** 00358 * Register a configuration directive. 00359 * 00360 * As an optional, but recomended functionality the plugin can decide to 00361 * subscribe on the configuration value and will thus be notified when it 00362 * changes by passing a callback, and if needed, userdata. 00363 * 00364 * @param output an output object 00365 * @param name the name of the configuration directive 00366 * @param default_value the default value of the configuration directive 00367 * @param cb the function to call on configuration value changes 00368 * @param userdata a user specified variable to be passed to the callback 00369 * @return a #xmms_config_property_t based on the given input 00370 */ 00371 00372 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); 00373 00374 /** 00375 * Lookup a configuration directive for the output plugin. 00376 * 00377 * @param output an output object 00378 * @param path the path to the configuration value 00379 * @return a #xmms_config_property_t found at the given path 00380 */ 00381 xmms_config_property_t *xmms_output_config_lookup (xmms_output_t *output, const gchar *path); 00382 00383 /** @} */ 00384 00385 G_END_DECLS 00386 00387 #endif