deps/libretro-common/include/libretro_dspfilter.h

   1 /* Copyright (C) 2010-2020 The RetroArch team
   2  *
   3  * ---------------------------------------------------------------------------------------
   4  * The following license statement only applies to this libretro API header (libretro_dspfilter.h).
   5  * ---------------------------------------------------------------------------------------
   6  *
   7  * Permission is hereby granted, free of charge,
   8  * to any person obtaining a copy of this software and associated documentation files (the "Software"),
   9  * to deal in the Software without restriction, including without limitation the rights to
  10  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
  11  * and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
  16  * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  18  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  19  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  20  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  21  */
  22
  23 #ifndef LIBRETRO_DSPFILTER_API_H__
  24 #define LIBRETRO_DSPFILTER_API_H__
  25
  26 #include <retro_common_api.h>
  27
  28 RETRO_BEGIN_DECLS
  29
  30 #define DSPFILTER_SIMD_SSE      (1 << 0)
  31 #define DSPFILTER_SIMD_SSE2     (1 << 1)
  32 #define DSPFILTER_SIMD_VMX      (1 << 2)
  33 #define DSPFILTER_SIMD_VMX128   (1 << 3)
  34 #define DSPFILTER_SIMD_AVX      (1 << 4)
  35 #define DSPFILTER_SIMD_NEON     (1 << 5)
  36 #define DSPFILTER_SIMD_SSE3     (1 << 6)
  37 #define DSPFILTER_SIMD_SSSE3    (1 << 7)
  38 #define DSPFILTER_SIMD_MMX      (1 << 8)
  39 #define DSPFILTER_SIMD_MMXEXT   (1 << 9)
  40 #define DSPFILTER_SIMD_SSE4     (1 << 10)
  41 #define DSPFILTER_SIMD_SSE42    (1 << 11)
  42 #define DSPFILTER_SIMD_AVX2     (1 << 12)
  43 #define DSPFILTER_SIMD_VFPU     (1 << 13)
  44 #define DSPFILTER_SIMD_PS       (1 << 14)
  45
  46 /* A bit-mask of all supported SIMD instruction sets.
  47  * Allows an implementation to pick different
  48  * dspfilter_implementation structs.
  49  */
  50 typedef unsigned dspfilter_simd_mask_t;
  51
  52 /* Dynamic library endpoint. */
  53 typedef const struct dspfilter_implementation *(
  54       *dspfilter_get_implementation_t)(dspfilter_simd_mask_t mask);
  55
  56 /* The same SIMD mask argument is forwarded to create() callback
  57  * as well to avoid having to keep lots of state around. */
  58 const struct dspfilter_implementation *dspfilter_get_implementation(
  59       dspfilter_simd_mask_t mask);
  60
  61 #define DSPFILTER_API_VERSION 1
  62
  63 struct dspfilter_info
  64 {
  65    /* Input sample rate that the DSP plugin receives. */
  66    float input_rate;
  67 };
  68
  69 struct dspfilter_output
  70 {
  71    /* The DSP plugin has to provide the buffering for the
  72     * output samples or reuse the input buffer directly.
  73     *
  74     * The samples are laid out in interleaving order: LRLRLRLR
  75     * The range of the samples are [-1.0, 1.0].
  76     *
  77     * It is not necessary to manually clip values. */
  78    float *samples;
  79
  80    /* Frames which the DSP plugin outputted for the current process.
  81     *
  82     * One frame is here defined as a combined sample of
  83     * left and right channels.
  84     *
  85     * (I.e. 44.1kHz, 16bit stereo will have
  86     * 88.2k samples/sec and 44.1k frames/sec.)
  87     */
  88    unsigned frames;
  89 };
  90
  91 struct dspfilter_input
  92 {
  93    /* Input data for the DSP. The samples are interleaved in order: LRLRLRLR
  94     *
  95     * It is valid for a DSP plug to use this buffer for output as long as
  96     * the output size is less or equal to the input.
  97     *
  98     * This is useful for filters which can output one sample for each
  99     * input sample and do not need to maintain its own buffers.
 100     *
 101     * Block based filters must provide their own buffering scheme.
 102     *
 103     * The input size is not bound, but it can be safely assumed that it
 104     * will not exceed ~100ms worth of audio at a time. */
 105    float *samples;
 106
 107    /* Number of frames for input data.
 108     * One frame is here defined as a combined sample of
 109     * left and right channels.
 110     *
 111     * (I.e. 44.1kHz, 16bit stereo will have
 112     * 88.2k samples/sec and 44.1k frames/sec.)
 113     */
 114    unsigned frames;
 115 };
 116
 117 /* Returns true if config key was found. Otherwise,
 118  * returns false, and sets value to default value.
 119  */
 120 typedef int (*dspfilter_config_get_float_t)(void *userdata,
 121       const char *key, float *value, float default_value);
 122
 123 typedef int (*dspfilter_config_get_int_t)(void *userdata,
 124       const char *key, int *value, int default_value);
 125
 126 /* Allocates an array with values. free() with dspfilter_config_free_t. */
 127 typedef int (*dspfilter_config_get_float_array_t)(void *userdata,
 128       const char *key, float **values, unsigned *out_num_values,
 129       const float *default_values, unsigned num_default_values);
 130
 131 typedef int (*dspfilter_config_get_int_array_t)(void *userdata,
 132       const char *key, int **values, unsigned *out_num_values,
 133       const int *default_values, unsigned num_default_values);
 134
 135 typedef int (*dspfilter_config_get_string_t)(void *userdata,
 136       const char *key, char **output, const char *default_output);
 137
 138 /* Calls free() in host runtime. Sometimes needed on Windows.
 139  * free() on NULL is fine. */
 140 typedef void (*dspfilter_config_free_t)(void *ptr);
 141
 142 struct dspfilter_config
 143 {
 144    dspfilter_config_get_float_t get_float;
 145    dspfilter_config_get_int_t get_int;
 146
 147    dspfilter_config_get_float_array_t get_float_array;
 148    dspfilter_config_get_int_array_t get_int_array;
 149
 150    dspfilter_config_get_string_t get_string;
 151    /* Avoid problems where DSP plug and host are
 152     * linked against different C runtimes. */
 153    dspfilter_config_free_t free;
 154 };
 155
 156 /* Creates a handle of the plugin. Returns NULL if failed. */
 157 typedef void *(*dspfilter_init_t)(const struct dspfilter_info *info,
 158       const struct dspfilter_config *config, void *userdata);
 159
 160 /* Frees the handle. */
 161 typedef void (*dspfilter_free_t)(void *data);
 162
 163 /* Processes input data.
 164  * The plugin is allowed to return variable sizes for output data. */
 165 typedef void (*dspfilter_process_t)(void *data,
 166       struct dspfilter_output *output, const struct dspfilter_input *input);
 167
 168 struct dspfilter_implementation
 169 {
 170    dspfilter_init_t     init;
 171    dspfilter_process_t  process;
 172    dspfilter_free_t     free;
 173
 174    /* Must be DSPFILTER_API_VERSION */
 175    unsigned api_version;
 176
 177    /* Human readable identifier of implementation. */
 178    const char *ident;
 179
 180    /* Computer-friendly short version of ident.
 181     * Lower case, no spaces and special characters, etc. */
 182    const char *short_ident;
 183 };
 184
 185 RETRO_END_DECLS
 186
 187 #endif