src/filter_plugin.h

   1 /*
   2  * Copyright (C) 2003-2010 The Music Player Daemon Project
   3  * http://www.musicpd.org
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18  */
  19
  20 /** \file
  21  *
  22  * This header declares the filter_plugin class.  It describes a
  23  * plugin API for objects which filter raw PCM data.
  24  */
  25
  26 #ifndef MPD_FILTER_PLUGIN_H
  27 #define MPD_FILTER_PLUGIN_H
  28
  29 #include <glib.h>
  30
  31 #include <stdbool.h>
  32 #include <stddef.h>
  33
  34 struct config_param;
  35 struct filter;
  36
  37 struct filter_plugin {
  38         const char *name;
  39
  40         /**
  41          * Allocates and configures a filter.
  42          */
  43         struct filter *(*init)(const struct config_param *param,
  44                                GError **error_r);
  45
  46         /**
  47          * Free instance data.
  48          */
  49         void (*finish)(struct filter *filter);
  50
  51         /**
  52          * Opens a filter.
  53          *
  54          * @param audio_format the audio format of incoming data; the
  55          * plugin may modify the object to enforce another input
  56          * format
  57          */
  58         const struct audio_format *
  59         (*open)(struct filter *filter,
  60                 struct audio_format *audio_format,
  61                 GError **error_r);
  62
  63         /**
  64          * Closes a filter.
  65          */
  66         void (*close)(struct filter *filter);
  67
  68         /**
  69          * Filters a block of PCM data.
  70          */
  71         const void *(*filter)(struct filter *filter,
  72                               const void *src, size_t src_size,
  73                               size_t *dest_buffer_r,
  74                               GError **error_r);
  75 };
  76
  77 /**
  78  * Creates a new instance of the specified filter plugin.
  79  *
  80  * @param plugin the filter plugin
  81  * @param param optional configuration section
  82  * @param error location to store the error occuring, or NULL to
  83  * ignore errors.
  84  * @return a new filter object, or NULL on error
  85  */
  86 struct filter *
  87 filter_new(const struct filter_plugin *plugin,
  88            const struct config_param *param, GError **error_r);
  89
  90 /**
  91  * Creates a new filter, loads configuration and the plugin name from
  92  * the specified configuration section.
  93  *
  94  * @param param the configuration section
  95  * @param error location to store the error occuring, or NULL to
  96  * ignore errors.
  97  * @return a new filter object, or NULL on error
  98  */
  99 struct filter *
 100 filter_configured_new(const struct config_param *param, GError **error_r);
 101
 102 /**
 103  * Deletes a filter.  It must be closed prior to calling this
 104  * function, see filter_close().
 105  *
 106  * @param filter the filter object
 107  */
 108 void
 109 filter_free(struct filter *filter);
 110
 111 /**
 112  * Opens the filter, preparing it for filter_filter().
 113  *
 114  * @param filter the filter object
 115  * @param audio_format the audio format of incoming data; the plugin
 116  * may modify the object to enforce another input format
 117  * @param error location to store the error occuring, or NULL to
 118  * ignore errors.
 119  * @return the format of outgoing data
 120  */
 121 const struct audio_format *
 122 filter_open(struct filter *filter, struct audio_format *audio_format,
 123             GError **error_r);
 124
 125 /**
 126  * Closes the filter.  After that, you may call filter_open() again.
 127  *
 128  * @param filter the filter object
 129  */
 130 void
 131 filter_close(struct filter *filter);
 132
 133 /**
 134  * Filters a block of PCM data.
 135  *
 136  * @param filter the filter object
 137  * @param src the input buffer
 138  * @param src_size the size of #src_buffer in bytes
 139  * @param dest_size_r the size of the returned buffer
 140  * @param error location to store the error occuring, or NULL to
 141  * ignore errors.
 142  * @return the destination buffer on success (will be invalidated by
 143  * filter_close() or filter_filter()), NULL on error
 144  */
 145 const void *
 146 filter_filter(struct filter *filter, const void *src, size_t src_size,
 147               size_t *dest_size_r,
 148               GError **error_r);
 149
 150 #endif