• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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      * The stride parameter must be set to the size of a single sample in bytes.
79      *
80      * The forward transform performs a real-to-complex DFT of N samples to
81      * N/2+1 complex values.
82      *
83      * The inverse transform performs a complex-to-real DFT of N/2+1 complex
84      * values to N real samples. The output is not normalized, but can be
85      * made so by setting the scale value to 1.0/len.
86      * NOTE: the inverse transform always overwrites the input.
87      */
88     AV_TX_FLOAT_RDFT  = 6,
89     AV_TX_DOUBLE_RDFT = 7,
90     AV_TX_INT32_RDFT  = 8,
91 
92     /* Not part of the API, do not use */
93     AV_TX_NB,
94 };
95 
96 /**
97  * Function pointer to a function to perform the transform.
98  *
99  * @note Using a different context than the one allocated during av_tx_init()
100  * is not allowed.
101  *
102  * @param s the transform context
103  * @param out the output array
104  * @param in the input array
105  * @param stride the input or output stride in bytes
106  *
107  * The out and in arrays must be aligned to the maximum required by the CPU
108  * architecture unless the AV_TX_UNALIGNED flag was set in av_tx_init().
109  * The stride must follow the constraints the transform type has specified.
110  */
111 typedef void (*av_tx_fn)(AVTXContext *s, void *out, void *in, ptrdiff_t stride);
112 
113 /**
114  * Flags for av_tx_init()
115  */
116 enum AVTXFlags {
117     /**
118      * Performs an in-place transformation on the input. The output argument
119      * of av_tn_fn() MUST match the input. May be unsupported or slower for some
120      * transform types.
121      */
122     AV_TX_INPLACE = 1ULL << 0,
123 
124     /**
125      * Relaxes alignment requirement for the in and out arrays of av_tx_fn().
126      * May be slower with certain transform types.
127      */
128     AV_TX_UNALIGNED = 1ULL << 1,
129 
130     /**
131      * Performs a full inverse MDCT rather than leaving out samples that can be
132      * derived through symmetry. Requires an output array of 'len' floats,
133      * rather than the usual 'len/2' floats.
134      * Ignored for all transforms but inverse MDCTs.
135      */
136     AV_TX_FULL_IMDCT = 1ULL << 2,
137 };
138 
139 /**
140  * Initialize a transform context with the given configuration
141  * (i)MDCTs with an odd length are currently not supported.
142  *
143  * @param ctx the context to allocate, will be NULL on error
144  * @param tx pointer to the transform function pointer to set
145  * @param type type the type of transform
146  * @param inv whether to do an inverse or a forward transform
147  * @param len the size of the transform in samples
148  * @param scale pointer to the value to scale the output if supported by type
149  * @param flags a bitmask of AVTXFlags or 0
150  *
151  * @return 0 on success, negative error code on failure
152  */
153 int av_tx_init(AVTXContext **ctx, av_tx_fn *tx, enum AVTXType type,
154                int inv, int len, const void *scale, uint64_t flags);
155 
156 /**
157  * Frees a context and sets *ctx to NULL, does nothing when *ctx == NULL.
158  */
159 void av_tx_uninit(AVTXContext **ctx);
160 
161 #endif /* AVUTIL_TX_H */
162