tx.h (7140B)
1 /* 2 * This file is part of FFmpeg. 3 * 4 * FFmpeg is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation; either 7 * version 2.1 of the License, or (at your option) any later version. 8 * 9 * FFmpeg is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Lesser General Public License for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public 15 * License along with FFmpeg; if not, write to the Free Software 16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 17 */ 18 19 #ifndef AVUTIL_TX_H 20 #define AVUTIL_TX_H 21 22 #include <stdint.h> 23 #include <stddef.h> 24 25 typedef struct AVTXContext AVTXContext; 26 27 typedef struct AVComplexFloat { 28 float re, im; 29 } AVComplexFloat; 30 31 typedef struct AVComplexDouble { 32 double re, im; 33 } AVComplexDouble; 34 35 typedef struct AVComplexInt32 { 36 int32_t re, im; 37 } AVComplexInt32; 38 39 enum AVTXType { 40 /** 41 * Standard complex to complex FFT with sample data type of AVComplexFloat, 42 * AVComplexDouble or AVComplexInt32, for each respective variant. 43 * 44 * Output is not 1/len normalized. Scaling currently unsupported. 45 * The stride parameter must be set to the size of a single sample in bytes. 46 */ 47 AV_TX_FLOAT_FFT = 0, 48 AV_TX_DOUBLE_FFT = 2, 49 AV_TX_INT32_FFT = 4, 50 51 /** 52 * Standard MDCT with a sample data type of float, double or int32_t, 53 * respecively. For the float and int32 variants, the scale type is 54 * 'float', while for the double variant, it's 'double'. 55 * If scale is NULL, 1.0 will be used as a default. 56 * 57 * Length is the frame size, not the window size (which is 2x frame). 58 * For forward transforms, the stride specifies the spacing between each 59 * sample in the output array in bytes. The input must be a flat array. 60 * 61 * For inverse transforms, the stride specifies the spacing between each 62 * sample in the input array in bytes. The output must be a flat array. 63 * 64 * NOTE: the inverse transform is half-length, meaning the output will not 65 * contain redundant data. This is what most codecs work with. To do a full 66 * inverse transform, set the AV_TX_FULL_IMDCT flag on init. 67 */ 68 AV_TX_FLOAT_MDCT = 1, 69 AV_TX_DOUBLE_MDCT = 3, 70 AV_TX_INT32_MDCT = 5, 71 72 /** 73 * Real to complex and complex to real DFTs. 74 * For the float and int32 variants, the scale type is 'float', while for 75 * the double variant, it's a 'double'. If scale is NULL, 1.0 will be used 76 * as a default. 77 * 78 * For forward transforms (R2C), stride must be the spacing between two 79 * samples in bytes. For inverse transforms, the stride must be set 80 * to the spacing between two complex values in bytes. 81 * 82 * The forward transform performs a real-to-complex DFT of N samples to 83 * N/2+1 complex values. 84 * 85 * The inverse transform performs a complex-to-real DFT of N/2+1 complex 86 * values to N real samples. The output is not normalized, but can be 87 * made so by setting the scale value to 1.0/len. 88 * NOTE: the inverse transform always overwrites the input. 89 */ 90 AV_TX_FLOAT_RDFT = 6, 91 AV_TX_DOUBLE_RDFT = 7, 92 AV_TX_INT32_RDFT = 8, 93 94 /** 95 * Real to real (DCT) transforms. 96 * 97 * The forward transform is a DCT-II. 98 * The inverse transform is a DCT-III. 99 * 100 * The input array is always overwritten. DCT-III requires that the 101 * input be padded with 2 extra samples. Stride must be set to the 102 * spacing between two samples in bytes. 103 */ 104 AV_TX_FLOAT_DCT = 9, 105 AV_TX_DOUBLE_DCT = 10, 106 AV_TX_INT32_DCT = 11, 107 108 /** 109 * Discrete Cosine Transform I 110 * 111 * The forward transform is a DCT-I. 112 * The inverse transform is a DCT-I multiplied by 2/(N + 1). 113 * 114 * The input array is always overwritten. 115 */ 116 AV_TX_FLOAT_DCT_I = 12, 117 AV_TX_DOUBLE_DCT_I = 13, 118 AV_TX_INT32_DCT_I = 14, 119 120 /** 121 * Discrete Sine Transform I 122 * 123 * The forward transform is a DST-I. 124 * The inverse transform is a DST-I multiplied by 2/(N + 1). 125 * 126 * The input array is always overwritten. 127 */ 128 AV_TX_FLOAT_DST_I = 15, 129 AV_TX_DOUBLE_DST_I = 16, 130 AV_TX_INT32_DST_I = 17, 131 132 /* Not part of the API, do not use */ 133 AV_TX_NB, 134 }; 135 136 /** 137 * Function pointer to a function to perform the transform. 138 * 139 * @note Using a different context than the one allocated during av_tx_init() 140 * is not allowed. 141 * 142 * @param s the transform context 143 * @param out the output array 144 * @param in the input array 145 * @param stride the input or output stride in bytes 146 * 147 * The out and in arrays must be aligned to the maximum required by the CPU 148 * architecture unless the AV_TX_UNALIGNED flag was set in av_tx_init(). 149 * The stride must follow the constraints the transform type has specified. 150 */ 151 typedef void (*av_tx_fn)(AVTXContext *s, void *out, void *in, ptrdiff_t stride); 152 153 /** 154 * Flags for av_tx_init() 155 */ 156 enum AVTXFlags { 157 /** 158 * Allows for in-place transformations, where input == output. 159 * May be unsupported or slower for some transform types. 160 */ 161 AV_TX_INPLACE = 1ULL << 0, 162 163 /** 164 * Relaxes alignment requirement for the in and out arrays of av_tx_fn(). 165 * May be slower with certain transform types. 166 */ 167 AV_TX_UNALIGNED = 1ULL << 1, 168 169 /** 170 * Performs a full inverse MDCT rather than leaving out samples that can be 171 * derived through symmetry. Requires an output array of 'len' floats, 172 * rather than the usual 'len/2' floats. 173 * Ignored for all transforms but inverse MDCTs. 174 */ 175 AV_TX_FULL_IMDCT = 1ULL << 2, 176 177 /** 178 * Perform a real to half-complex RDFT. 179 * Only the real, or imaginary coefficients will 180 * be output, depending on the flag used. Only available for forward RDFTs. 181 * Output array must have enough space to hold N complex values 182 * (regular size for a real to complex transform). 183 */ 184 AV_TX_REAL_TO_REAL = 1ULL << 3, 185 AV_TX_REAL_TO_IMAGINARY = 1ULL << 4, 186 }; 187 188 /** 189 * Initialize a transform context with the given configuration 190 * (i)MDCTs with an odd length are currently not supported. 191 * 192 * @param ctx the context to allocate, will be NULL on error 193 * @param tx pointer to the transform function pointer to set 194 * @param type type the type of transform 195 * @param inv whether to do an inverse or a forward transform 196 * @param len the size of the transform in samples 197 * @param scale pointer to the value to scale the output if supported by type 198 * @param flags a bitmask of AVTXFlags or 0 199 * 200 * @return 0 on success, negative error code on failure 201 */ 202 int av_tx_init(AVTXContext **ctx, av_tx_fn *tx, enum AVTXType type, 203 int inv, int len, const void *scale, uint64_t flags); 204 205 /** 206 * Frees a context and sets *ctx to NULL, does nothing when *ctx == NULL. 207 */ 208 void av_tx_uninit(AVTXContext **ctx); 209 210 #endif /* AVUTIL_TX_H */