[FFmpeg-devel] [PATCH 2/2] lavc/avfft: deprecate the API

[Andreas Rheinhardt]

Lynne:
> Subject: [PATCH 2/2] lavc/avfft: deprecate the API
> 
> This deprecates the currently unused API.
                      ^
                     superseded

> ---
>  doc/APIchanges             |  4 ++++
>  libavcodec/avfft.h         | 25 +++++++++++++++++++++++++
>  libavcodec/tests/fft.c     |  4 ++++
>  libavcodec/version.h       |  2 +-
>  libavcodec/version_major.h |  2 ++
>  5 files changed, 36 insertions(+), 1 deletion(-)
> 
> diff --git a/doc/APIchanges b/doc/APIchanges
> index 5afe8bcb75..38fc0b1459 100644
> --- a/doc/APIchanges
> +++ b/doc/APIchanges
> @@ -2,6 +2,10 @@ The last version increases of all libraries were on 2023-02-09
>  
>  API changes, most recent first:
>  
> +2023-07-xx - xxxxxxxxxx - lavc 60.23.100 - avfft.h
> +  Deprecate av_dct, av_rdft, av_fft and av_mdct.

This should mention that the whole header is deprecated and will be removed.

> +  Replaced by libavutil/tx.h
> +
>  2023-07-xx - xxxxxxxxxx - lavc 60 - avcodec.h
>    Deprecate AV_CODEC_FLAG_DROPCHANGED without replacement.
>  
> diff --git a/libavcodec/avfft.h b/libavcodec/avfft.h
> index 0c0f9b8d8d..6401833089 100644
> --- a/libavcodec/avfft.h
> +++ b/libavcodec/avfft.h
> @@ -19,6 +19,10 @@
>  #ifndef AVCODEC_AVFFT_H
>  #define AVCODEC_AVFFT_H
>  
> +#include "libavutil/attributes.h"
> +#include "version_major.h"
> +#if FF_API_AVFFT
> +
>  /**
>   * @file
>   * @ingroup lavc_fft
> @@ -44,26 +48,38 @@ typedef struct FFTContext FFTContext;
>   * Set up a complex FFT.
>   * @param nbits           log2 of the length of the input array
>   * @param inverse         if 0 perform the forward transform, if 1 perform the inverse
> + * @deprecated use AVTXContext from libavutil/tx.h
>   */
> +attribute_deprecated
>  FFTContext *av_fft_init(int nbits, int inverse);
>  
>  /**
>   * Do the permutation needed BEFORE calling ff_fft_calc().
> + * @deprecated use AVTXContext from libavutil/tx.h
>   */
> +attribute_deprecated
>  void av_fft_permute(FFTContext *s, FFTComplex *z);
>  
>  /**
>   * Do a complex FFT with the parameters defined in av_fft_init(). The
>   * input data must be permuted before. No 1.0/sqrt(n) normalization is done.
> + * @deprecated use AVTXContext from libavutil/tx.h

This deprecation warning is supposed to apply to av_fft_calc() and
apparently AVTXContext is not a replacement for av_fft_calc(). Probably
better to write something like: "Use the AVTX API from libavutil/tx.h."

>   */
> +attribute_deprecated
>  void av_fft_calc(FFTContext *s, FFTComplex *z);
>  
> +attribute_deprecated
>  void av_fft_end(FFTContext *s);
>  
> +attribute_deprecated
>  FFTContext *av_mdct_init(int nbits, int inverse, double scale);
> +attribute_deprecated
>  void av_imdct_calc(FFTContext *s, FFTSample *output, const FFTSample *input);
> +attribute_deprecated
>  void av_imdct_half(FFTContext *s, FFTSample *output, const FFTSample *input);
> +attribute_deprecated
>  void av_mdct_calc(FFTContext *s, FFTSample *output, const FFTSample *input);
> +attribute_deprecated
>  void av_mdct_end(FFTContext *s);
>  
>  /* Real Discrete Fourier Transform */
> @@ -81,9 +97,13 @@ typedef struct RDFTContext RDFTContext;
>   * Set up a real FFT.
>   * @param nbits           log2 of the length of the input array
>   * @param trans           the type of transform
> + * @deprecated use AVTXContext from libavutil/tx.h
>   */
> +attribute_deprecated
>  RDFTContext *av_rdft_init(int nbits, enum RDFTransformType trans);
> +attribute_deprecated
>  void av_rdft_calc(RDFTContext *s, FFTSample *data);
> +attribute_deprecated
>  void av_rdft_end(RDFTContext *s);
>  
>  /* Discrete Cosine Transform */
> @@ -106,13 +126,18 @@ enum DCTTransformType {
>   * @param type            the type of transform
>   *
>   * @note the first element of the input of DST-I is ignored
> + * @deprecated use AVTXContext from libavutil/tx.h
>   */
> +attribute_deprecated
>  DCTContext *av_dct_init(int nbits, enum DCTTransformType type);
> +attribute_deprecated
>  void av_dct_calc(DCTContext *s, FFTSample *data);
> +attribute_deprecated
>  void av_dct_end (DCTContext *s);
>  
>  /**
>   * @}
>   */
>  
> +#endif /* FF_API_AVFFT */
>  #endif /* AVCODEC_AVFFT_H */
> diff --git a/libavcodec/tests/fft.c b/libavcodec/tests/fft.c
> index 163f3e89c4..a9ea457bc9 100644
> --- a/libavcodec/tests/fft.c
> +++ b/libavcodec/tests/fft.c
> @@ -18,6 +18,8 @@
>   * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
>   */
>  
> +FF_DISABLE_DEPRECATION_WARNINGS
> +
>  /**
>   * @file
>   * FFT and MDCT tests.
> @@ -675,3 +677,5 @@ cleanup:
>  
>      return !!err;
>  }
> +
> +FF_ENABLE_DEPRECATION_WARNINGS
> diff --git a/libavcodec/version.h b/libavcodec/version.h
> index 9411511e04..728ab8839d 100644
> --- a/libavcodec/version.h
> +++ b/libavcodec/version.h
> @@ -29,7 +29,7 @@
>  
>  #include "version_major.h"
>  
> -#define LIBAVCODEC_VERSION_MINOR  22
> +#define LIBAVCODEC_VERSION_MINOR  23
>  #define LIBAVCODEC_VERSION_MICRO 100
>  
>  #define LIBAVCODEC_VERSION_INT  AV_VERSION_INT(LIBAVCODEC_VERSION_MAJOR, \
> diff --git a/libavcodec/version_major.h b/libavcodec/version_major.h
> index 95c5aec0c5..cfd0b5023e 100644
> --- a/libavcodec/version_major.h
> +++ b/libavcodec/version_major.h
> @@ -50,6 +50,8 @@
>  #define FF_API_TICKS_PER_FRAME     (LIBAVCODEC_VERSION_MAJOR < 61)
>  #define FF_API_DROPCHANGED         (LIBAVCODEC_VERSION_MAJOR < 61)
>  
> +#define FF_API_AVFFT               (LIBAVCODEC_VERSION_MAJOR < 62)
> +
>  // reminder to remove CrystalHD decoders on next major bump
>  #define FF_CODEC_CRYSTAL_HD        (LIBAVCODEC_VERSION_MAJOR < 61)
>  

This patch is very much orthogonal to my patch (as expected).

- Andreas