1 /* Copyright (C) 2010-2020 The RetroArch team
3 * ---------------------------------------------------------------------------------------
4 * The following license statement only applies to this libretro API header (libretro_dspfilter.h).
5 * ---------------------------------------------------------------------------------------
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:
13 * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
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.
23 #ifndef LIBRETRO_DSPFILTER_API_H__
24 #define LIBRETRO_DSPFILTER_API_H__
26 #include <retro_common_api.h>
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)
46 /* A bit-mask of all supported SIMD instruction sets.
47 * Allows an implementation to pick different
48 * dspfilter_implementation structs.
50 typedef unsigned dspfilter_simd_mask_t;
52 /* Dynamic library endpoint. */
53 typedef const struct dspfilter_implementation *(
54 *dspfilter_get_implementation_t)(dspfilter_simd_mask_t mask);
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);
61 #define DSPFILTER_API_VERSION 1
65 /* Input sample rate that the DSP plugin receives. */
69 struct dspfilter_output
71 /* The DSP plugin has to provide the buffering for the
72 * output samples or reuse the input buffer directly.
74 * The samples are laid out in interleaving order: LRLRLRLR
75 * The range of the samples are [-1.0, 1.0].
77 * It is not necessary to manually clip values. */
80 /* Frames which the DSP plugin outputted for the current process.
82 * One frame is here defined as a combined sample of
83 * left and right channels.
85 * (I.e. 44.1kHz, 16bit stereo will have
86 * 88.2k samples/sec and 44.1k frames/sec.)
91 struct dspfilter_input
93 /* Input data for the DSP. The samples are interleaved in order: LRLRLRLR
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.
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.
101 * Block based filters must provide their own buffering scheme.
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. */
107 /* Number of frames for input data.
108 * One frame is here defined as a combined sample of
109 * left and right channels.
111 * (I.e. 44.1kHz, 16bit stereo will have
112 * 88.2k samples/sec and 44.1k frames/sec.)
117 /* Returns true if config key was found. Otherwise,
118 * returns false, and sets value to default value.
120 typedef int (*dspfilter_config_get_float_t)(void *userdata,
121 const char *key, float *value, float default_value);
123 typedef int (*dspfilter_config_get_int_t)(void *userdata,
124 const char *key, int *value, int default_value);
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);
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);
135 typedef int (*dspfilter_config_get_string_t)(void *userdata,
136 const char *key, char **output, const char *default_output);
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);
142 struct dspfilter_config
144 dspfilter_config_get_float_t get_float;
145 dspfilter_config_get_int_t get_int;
147 dspfilter_config_get_float_array_t get_float_array;
148 dspfilter_config_get_int_array_t get_int_array;
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;
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);
160 /* Frees the handle. */
161 typedef void (*dspfilter_free_t)(void *data);
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);
168 struct dspfilter_implementation
170 dspfilter_init_t init;
171 dspfilter_process_t process;
172 dspfilter_free_t free;
174 /* Must be DSPFILTER_API_VERSION */
175 unsigned api_version;
177 /* Human readable identifier of implementation. */
180 /* Computer-friendly short version of ident.
181 * Lower case, no spaces and special characters, etc. */
182 const char *short_ident;