include/pcm_extplug.h

   1 /**
   2  * \file include/pcm_extplug.h
   3  * \brief External Filter-Plugin SDK
   4  * \author Takashi Iwai <tiwai@suse.de>
   5  * \date 2005
   6  *
   7  * External Filter-Plugin SDK
   8  */
   9
  10 /*
  11  * ALSA external PCM plugin SDK (draft version)
  12  *
  13  * Copyright (c) 2005 Takashi Iwai <tiwai@suse.de>
  14  *
  15  *   This library is free software; you can redistribute it and/or modify
  16  *   it under the terms of the GNU Lesser General Public License as
  17  *   published by the Free Software Foundation; either version 2.1 of
  18  *   the License, or (at your option) any later version.
  19  *
  20  *   This program is distributed in the hope that it will be useful,
  21  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
  22  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  23  *   GNU Lesser General Public License for more details.
  24  *
  25  *   You should have received a copy of the GNU Lesser General Public
  26  *   License along with this library; if not, write to the Free Software
  27  *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  28  *
  29  */
  30
  31 #ifndef __ALSA_PCM_EXTPLUG_H
  32 #define __ALSA_PCM_EXTPLUG_H
  33
  34 /**
  35  * \defgroup PCM_ExtPlug External Filter plugin SDK
  36  * \ingroup Plugin_SDK
  37  * See the \ref pcm page for more details.
  38  * \{
  39  */
  40
  41 /** hw constraints for extplug */
  42 enum {
  43         SND_PCM_EXTPLUG_HW_FORMAT,      /**< format */
  44         SND_PCM_EXTPLUG_HW_CHANNELS,    /**< channels */
  45         SND_PCM_EXTPLUG_HW_PARAMS       /**< max number of hw constraints */
  46 };
  47
  48 /** Handle of external filter plugin */
  49 typedef struct snd_pcm_extplug snd_pcm_extplug_t;
  50 /** Callback table of extplug */
  51 typedef struct snd_pcm_extplug_callback snd_pcm_extplug_callback_t;
  52
  53 /*
  54  * Protocol version
  55  */
  56 #define SND_PCM_EXTPLUG_VERSION_MAJOR   1       /**< Protocol major version */
  57 #define SND_PCM_EXTPLUG_VERSION_MINOR   0       /**< Protocol minor version */
  58 #define SND_PCM_EXTPLUG_VERSION_TINY    1       /**< Protocol tiny version */
  59 /**
  60  * Filter-plugin protocol version
  61  */
  62 #define SND_PCM_EXTPLUG_VERSION         ((SND_PCM_EXTPLUG_VERSION_MAJOR<<16) |\
  63                                          (SND_PCM_EXTPLUG_VERSION_MINOR<<8) |\
  64                                          (SND_PCM_EXTPLUG_VERSION_TINY))
  65
  66 /** Handle of extplug */
  67 struct snd_pcm_extplug {
  68         /**
  69          * protocol version; #SND_PCM_EXTPLUG_VERSION must be filled here
  70          * before calling #snd_pcm_extplug_create()
  71          */
  72         unsigned int version;
  73         /**
  74          * name of this plugin; must be filled before calling #snd_pcm_extplug_create()
  75          */
  76         const char *name;
  77         /**
  78          * callbacks of this plugin; must be filled before calling #snd_pcm_extplug_create()
  79          */
  80         const snd_pcm_extplug_callback_t *callback;
  81         /**
  82          * private data, which can be used freely in the driver callbacks
  83          */
  84         void *private_data;
  85         /**
  86          * PCM handle filled by #snd_pcm_extplug_create()
  87          */
  88         snd_pcm_t *pcm;
  89         /**
  90          * stream direction; read-only status
  91          */
  92         snd_pcm_stream_t stream;
  93         /**
  94          * format hw parameter; filled after hw_params is caled
  95          */
  96         snd_pcm_format_t format;
  97         /**
  98          * subformat hw parameter; filled after hw_params is caled
  99          */
 100         snd_pcm_subformat_t subformat;
 101         /**
 102          * channels hw parameter; filled after hw_params is caled
 103          */
 104         unsigned int channels;
 105         /**
 106          * rate hw parameter; filled after hw_params is caled
 107          */
 108         unsigned int rate;
 109         /**
 110          * slave_format hw parameter; filled after hw_params is caled
 111          */
 112         snd_pcm_format_t slave_format;
 113         /**
 114          * slave_subformat hw parameter; filled after hw_params is caled
 115          */
 116         snd_pcm_subformat_t slave_subformat;
 117         /**
 118          * slave_channels hw parameter; filled after hw_params is caled
 119          */
 120         unsigned int slave_channels;
 121 };
 122
 123 /** Callback table of extplug */
 124 struct snd_pcm_extplug_callback {
 125         /**
 126          * transfer between source and destination; this is a required callback
 127          */
 128         snd_pcm_sframes_t (*transfer)(snd_pcm_extplug_t *ext,
 129                                       const snd_pcm_channel_area_t *dst_areas,
 130                                       snd_pcm_uframes_t dst_offset,
 131                                       const snd_pcm_channel_area_t *src_areas,
 132                                       snd_pcm_uframes_t src_offset,
 133                                       snd_pcm_uframes_t size);
 134         /**
 135          * close the PCM; optional
 136          */
 137         int (*close)(snd_pcm_extplug_t *ext);
 138         /**
 139          * hw_params; optional
 140          */
 141         int (*hw_params)(snd_pcm_extplug_t *ext, snd_pcm_hw_params_t *params);
 142         /**
 143          * hw_free; optional
 144          */
 145         int (*hw_free)(snd_pcm_extplug_t *ext);
 146         /**
 147          * dump; optional
 148          */
 149         void (*dump)(snd_pcm_extplug_t *ext, snd_output_t *out);
 150         /**
 151          * init; optional initialization called at prepare or reset
 152          */
 153         int (*init)(snd_pcm_extplug_t *ext);
 154 };
 155
 156
 157 int snd_pcm_extplug_create(snd_pcm_extplug_t *ext, const char *name,
 158                            snd_config_t *root, snd_config_t *slave_conf,
 159                            snd_pcm_stream_t stream, int mode);
 160 int snd_pcm_extplug_delete(snd_pcm_extplug_t *ext);
 161
 162 /* clear hw_parameter setting */
 163 void snd_pcm_extplug_params_reset(snd_pcm_extplug_t *ext);
 164
 165 /* hw_parameter setting */
 166 int snd_pcm_extplug_set_param_list(snd_pcm_extplug_t *extplug, int type, unsigned int num_list, const unsigned int *list);
 167 int snd_pcm_extplug_set_param_minmax(snd_pcm_extplug_t *extplug, int type, unsigned int min, unsigned int max);
 168 int snd_pcm_extplug_set_slave_param_list(snd_pcm_extplug_t *extplug, int type, unsigned int num_list, const unsigned int *list);
 169 int snd_pcm_extplug_set_slave_param_minmax(snd_pcm_extplug_t *extplug, int type, unsigned int min, unsigned int max);
 170
 171 /**
 172  * set the parameter constraint with a single value
 173  */
 174 static inline int snd_pcm_extplug_set_param(snd_pcm_extplug_t *extplug, int type, unsigned int val)
 175 {
 176         return snd_pcm_extplug_set_param_list(extplug, type, 1, &val);
 177 }
 178
 179 /**
 180  * set the parameter constraint for slave PCM with a single value
 181  */
 182 static inline int snd_pcm_extplug_set_slave_param(snd_pcm_extplug_t *extplug, int type, unsigned int val)
 183 {
 184         return snd_pcm_extplug_set_slave_param_list(extplug, type, 1, &val);
 185 }
 186
 187 /** \} */
 188
 189 #endif /* __ALSA_PCM_EXTPLUG_H */