imdct.c: Add some more documentation.
[paraslash.git] / imdct.c
diff --git a/imdct.c b/imdct.c
index 89ee2dfb4ff8c48e78ad589d8bba0102d33bb153..6e0360b8b9018d951c7f1062b6411d4d48c80f76 100644 (file)
--- a/imdct.c
+++ b/imdct.c
 
 typedef float fftsample_t;
 
-#define DECLARE_ALIGNED(n,t,v)      t v __attribute__ ((aligned (n)))
-#define DECLARE_ALIGNED_16(t, v) DECLARE_ALIGNED(16, t, v)
-#define M_SQRT1_2      0.70710678118654752440  /* 1/sqrt(2) */
-
+/** Canonical representation of a complex number. */
 struct fft_complex {
-       fftsample_t re, im;
+       /** Real part. */
+       fftsample_t re;
+       /** Imaginary part. */
+       fftsample_t im;
 };
 
+/** FFT Lookup table. */
 struct fft_context {
+       /** Number of bits of this instance of the FFT. */
        int nbits;
-       int inverse;
+       /** The lookup table for cosine values. */
        uint16_t *revtab;
-       struct fft_complex *exptab;
-       struct fft_complex *exptab1;    /* only used by SSE code */
-       struct fft_complex *tmp_buf;
 };
 
 struct mdct_context {
-       /** Size of MDCT (i.e. number of input data * 2). */
+       /** Size of MDCT (number of input data * 2). */
        int n;
        /** n = 2^n bits. */
        int nbits;
-       /** pre/post rotation tables */
+       /** Cosine table for pre/post rotation. */
        fftsample_t *tcos;
+       /** Sine table for pre/post rotation. */
        fftsample_t *tsin;
+       /** The context for the underlying fast Fourier transform. */
        struct fft_context fft;
 };
 
-/* cos(2*pi*x/n) for 0<=x<=n/4, followed by its reverse */
-DECLARE_ALIGNED_16(fftsample_t, ff_cos_16[8]);
-DECLARE_ALIGNED_16(fftsample_t, ff_cos_32[16]);
-DECLARE_ALIGNED_16(fftsample_t, ff_cos_64[32]);
-DECLARE_ALIGNED_16(fftsample_t, ff_cos_128[64]);
-DECLARE_ALIGNED_16(fftsample_t, ff_cos_256[128]);
-DECLARE_ALIGNED_16(fftsample_t, ff_cos_512[256]);
-DECLARE_ALIGNED_16(fftsample_t, ff_cos_1024[512]);
-DECLARE_ALIGNED_16(fftsample_t, ff_cos_2048[1024]);
-DECLARE_ALIGNED_16(fftsample_t, ff_cos_4096[2048]);
-DECLARE_ALIGNED_16(fftsample_t, ff_cos_8192[4096]);
-DECLARE_ALIGNED_16(fftsample_t, ff_cos_16384[8192]);
-DECLARE_ALIGNED_16(fftsample_t, ff_cos_32768[16384]);
-DECLARE_ALIGNED_16(fftsample_t, ff_cos_65536[32768]);
-
-static fftsample_t *ff_cos_tabs[] = {
-       ff_cos_16, ff_cos_32, ff_cos_64, ff_cos_128, ff_cos_256,
-       ff_cos_512, ff_cos_1024, ff_cos_2048, ff_cos_4096, ff_cos_8192,
-       ff_cos_16384, ff_cos_32768, ff_cos_65536,
+/** cos(2 * pi * x / n) for 0 <= x <= n / 4, followed by its reverse */
+#define COSINE_TAB(n) fftsample_t cos_ ## n[n / 2] __aligned(16)
+
+COSINE_TAB(16);
+COSINE_TAB(32);
+COSINE_TAB(64);
+COSINE_TAB(128);
+COSINE_TAB(256);
+COSINE_TAB(512);
+COSINE_TAB(1024);
+COSINE_TAB(2048);
+COSINE_TAB(4096);
+COSINE_TAB(8192);
+COSINE_TAB(16384);
+COSINE_TAB(32768);
+COSINE_TAB(65536);
+
+static fftsample_t *cos_tabs[] = {
+       cos_16, cos_32, cos_64, cos_128, cos_256, cos_512, cos_1024, cos_2048,
+       cos_4096, cos_8192, cos_16384, cos_32768, cos_65536,
 };
 
-static int split_radix_permutation(int i, int n, int inverse)
+static int split_radix_permutation(int i, int n)
 {
        int m;
        if (n <= 2)
                return i & 1;
        m = n >> 1;
-       if (!(i & m))
-               return split_radix_permutation(i, m, inverse) * 2;
+       if ((i & m) == 0)
+               return split_radix_permutation(i, m) * 2;
        m >>= 1;
-       if (inverse == !(i & m))
-               return split_radix_permutation(i, m, inverse) * 4 + 1;
+       if ((i & m) == 0)
+               return split_radix_permutation(i, m) * 4 + 1;
        else
-               return split_radix_permutation(i, m, inverse) * 4 - 1;
+               return split_radix_permutation(i, m) * 4 - 1;
 }
 
-#define sqrthalf (float)M_SQRT1_2
+/** 1 / sqrt(2). */
+#define SQRTHALF (float)0.70710678118654752440
 
 #define BF(x,y,a,b) {\
     x = a - b;\
@@ -170,7 +173,7 @@ static void fft##n(struct fft_complex *z)\
     fft##n2(z);\
     fft##n4(z+n4*2);\
     fft##n4(z+n4*3);\
-    pass(z,ff_cos_##n,n4/2);\
+    pass(z,cos_##n,n4/2);\
 }
 static void fft4(struct fft_complex *z)
 {
@@ -203,7 +206,7 @@ static void fft8(struct fft_complex *z)
        BF(z[6].re, z[2].re, z[2].re, t7);
        BF(z[6].im, z[2].im, z[2].im, t8);
 
-       TRANSFORM(z[1], z[3], z[5], z[7], sqrthalf, sqrthalf);
+       TRANSFORM(z[1], z[3], z[5], z[7], SQRTHALF, SQRTHALF);
 }
 
 static void fft16(struct fft_complex *z)
@@ -215,9 +218,9 @@ static void fft16(struct fft_complex *z)
        fft4(z + 12);
 
        TRANSFORM_ZERO(z[0], z[4], z[8], z[12]);
-       TRANSFORM(z[2], z[6], z[10], z[14], sqrthalf, sqrthalf);
-       TRANSFORM(z[1], z[5], z[9], z[13], ff_cos_16[1], ff_cos_16[3]);
-       TRANSFORM(z[3], z[7], z[11], z[15], ff_cos_16[3], ff_cos_16[1]);
+       TRANSFORM(z[2], z[6], z[10], z[14], SQRTHALF, SQRTHALF);
+       TRANSFORM(z[1], z[5], z[9], z[13], cos_16[1], cos_16[3]);
+       TRANSFORM(z[3], z[7], z[11], z[15], cos_16[3], cos_16[1]);
 }
 
 DECL_FFT(32, 16, 8)
@@ -305,19 +308,22 @@ static void imdct_half(struct mdct_context *s, fftsample_t *output,
 }
 
 /**
- * Compute the inverse MDCT of size N = 2^nbits.
+ * Compute the inverse MDCT.
  *
+ * \param ctx The initialized context structure.
  * \param output N samples.
  * \param input N/2 samples.
+ *
+ * \sa \ref imdct_init().
  */
-void imdct(struct mdct_context *s, float *output, const float *input)
+void imdct(struct mdct_context *ctx, float *output, const float *input)
 {
        int k;
-       int n = 1 << s->nbits;
+       int n = 1 << ctx->nbits;
        int n2 = n >> 1;
        int n4 = n >> 2;
 
-       imdct_half(s, output + n4, input);
+       imdct_half(ctx, output + n4, input);
 
        for (k = 0; k < n4; k++) {
                output[k] = -output[n2 - k - 1];
@@ -325,7 +331,7 @@ void imdct(struct mdct_context *s, float *output, const float *input)
        }
 }
 
-static int fft_init(struct fft_context *s, int nbits, int inverse)
+static int fft_init(struct fft_context *s, int nbits)
 {
        int i, j, n;
 
@@ -334,62 +340,31 @@ static int fft_init(struct fft_context *s, int nbits, int inverse)
        s->nbits = nbits;
        n = 1 << nbits;
 
-       s->tmp_buf = NULL;
-       s->exptab = para_malloc((n / 2) * sizeof(struct fft_complex));
        s->revtab = para_malloc(n * sizeof(uint16_t));
-       s->inverse = inverse;
-
-       s->exptab1 = NULL;
-
        for (j = 4; j <= nbits; j++) {
                int k = 1 << j;
                double freq = 2 * M_PI / k;
-               fftsample_t *tab = ff_cos_tabs[j - 4];
+               fftsample_t *tab = cos_tabs[j - 4];
                for (i = 0; i <= k / 4; i++)
                        tab[i] = cos(i * freq);
                for (i = 1; i < k / 4; i++)
                        tab[k / 2 - i] = tab[i];
        }
        for (i = 0; i < n; i++)
-               s->revtab[-split_radix_permutation(
-                       i, n, s->inverse) & (n - 1)] = i;
-       s->tmp_buf = para_malloc(n * sizeof(struct fft_complex));
+               s->revtab[-split_radix_permutation(i, n) & (n - 1)] = i;
        return 0;
 }
 
-static void fft_end(struct fft_context *ctx)
-{
-       freep(&ctx->revtab);
-       freep(&ctx->exptab);
-       freep(&ctx->exptab1);
-       freep(&ctx->tmp_buf);
-}
-
-DECLARE_ALIGNED(16, float, ff_sine_128[128]);
-DECLARE_ALIGNED(16, float, ff_sine_256[256]);
-DECLARE_ALIGNED(16, float, ff_sine_512[512]);
-DECLARE_ALIGNED(16, float, ff_sine_1024[1024]);
-DECLARE_ALIGNED(16, float, ff_sine_2048[2048]);
-DECLARE_ALIGNED(16, float, ff_sine_4096[4096]);
-
-float *ff_sine_windows[6] = {
-       ff_sine_128, ff_sine_256, ff_sine_512, ff_sine_1024,
-       ff_sine_2048, ff_sine_4096
-};
-
-// Generate a sine window.
-void sine_window_init(float *window, int n)
-{
-       int i;
-
-       for (i = 0; i < n; i++)
-               window[i] = sinf((i + 0.5) * (M_PI / (2.0 * n)));
-}
-
 /**
- * Init MDCT or IMDCT computation.
+ * Initialize the inverse modified cosine transform.
+ *
+ * \param nbits The number of bits to use (4 <= \a nbits <= 18).
+ *
+ * \param result Opaque structure that must be passed to \ref imdct().
+ *
+ * \return Standard.
  */
-int imdct_init(int nbits, int inverse, struct mdct_context **result)
+int imdct_init(int nbits, struct mdct_context **result)
 {
        int ret, n, n4, i;
        double alpha;
@@ -408,7 +383,7 @@ int imdct_init(int nbits, int inverse, struct mdct_context **result)
                s->tcos[i] = -cos(alpha);
                s->tsin[i] = -sin(alpha);
        }
-       ret = fft_init(&s->fft, s->nbits - 2, inverse);
+       ret = fft_init(&s->fft, s->nbits - 2);
        if (ret < 0)
                goto fail;
        *result = s;
@@ -420,10 +395,15 @@ fail:
        return ret;
 }
 
+/**
+ * Deallocate imdct resources.
+ *
+ * \param ctx The pointer obtained by imdct_init().
+ */
 void imdct_end(struct mdct_context *ctx)
 {
-       freep(&ctx->tcos);
-       freep(&ctx->tsin);
-       fft_end(&ctx->fft);
+       free(ctx->tcos);
+       free(ctx->tsin);
+       free(ctx->fft.revtab);
        free(ctx);
 }