lavc: deprecate AV_CODEC_FLAG_DROPCHANGED

This decoding flag makes decoders drop all frames after a parameter
change, but what exactly constitutes a parameter change is not well
defined and will typically depend on the exact use case.
This functionality then does not belong in libavcodec, but rather in
user code

doc/APIchanges

@@ -2,6 +2,9 @@ The last version increases of all libraries were on 2023-02-09
 
 API changes, most recent first:
 
+2023-07-xx - xxxxxxxxxx - lavc 60 - avcodec.h
+  Deprecate AV_CODEC_FLAG_DROPCHANGED without replacement.
+
 2023-07-05 - xxxxxxxxxx - lavu 58.14.100 - random_seed.h
   Add av_random_bytes()
 

libavcodec/avcodec.c

@@ -456,7 +456,9 @@ av_cold int avcodec_close(AVCodecContext *avctx)
 
         av_bsf_free(&avci->bsf);
 
+#if FF_API_DROPCHANGED
         av_channel_layout_uninit(&avci->initial_ch_layout);
+#endif
 
 #if CONFIG_LCMS2
         ff_icc_context_uninit(&avci->icc);

libavcodec/avcodec.h

@@ -226,11 +226,15 @@ typedef struct RcOverride{
  * Use qpel MC.
  */
 #define AV_CODEC_FLAG_QPEL            (1 <<  4)
+#if FF_API_DROPCHANGED
 /**
  * Don't output frames whose parameters differ from first
  * decoded frame in stream.
+ *
+ * @deprecated callers should implement this functionality in their own code
  */
 #define AV_CODEC_FLAG_DROPCHANGED     (1 <<  5)
+#endif
 /**
  * Request the encoder to output reconstructed frames, i.e.\ frames that would
  * be produced by decoding the encoded bistream. These frames may be retrieved
@@ -2713,9 +2717,6 @@ int avcodec_send_packet(AVCodecContext *avctx, const AVPacket *avpkt);
  *                          no more output frames
  * @retval AVERROR(EINVAL)  codec not opened, or it is an encoder without the
  *                          @ref AV_CODEC_FLAG_RECON_FRAME flag enabled
- * @retval AVERROR_INPUT_CHANGED current decoded frame has changed parameters with
- *                          respect to first decoded frame. Applicable when flag
- *                          AV_CODEC_FLAG_DROPCHANGED is set.
  * @retval "other negative error code" legitimate decoding errors
  */
 int avcodec_receive_frame(AVCodecContext *avctx, AVFrame *frame);

libavcodec/decode.c

@@ -773,7 +773,7 @@ fail:
 int ff_decode_receive_frame(AVCodecContext *avctx, AVFrame *frame)
 {
     AVCodecInternal *avci = avctx->internal;
-    int ret, changed;
+    int ret;
 
     if (!avcodec_is_open(avctx) || !av_codec_is_decoder(avctx->codec))
         return AVERROR(EINVAL);
@@ -803,6 +803,7 @@ FF_DISABLE_DEPRECATION_WARNINGS
 FF_ENABLE_DEPRECATION_WARNINGS
 #endif
 
+#if FF_API_DROPCHANGED
     if (avctx->flags & AV_CODEC_FLAG_DROPCHANGED) {
 
         if (avctx->frame_num == 1) {
@@ -823,7 +824,7 @@ FF_ENABLE_DEPRECATION_WARNINGS
         }
 
         if (avctx->frame_num > 1) {
-            changed = avci->initial_format != frame->format;
+            int changed = avci->initial_format != frame->format;
 
             switch(avctx->codec_type) {
             case AVMEDIA_TYPE_VIDEO:
@@ -848,6 +849,7 @@ FF_ENABLE_DEPRECATION_WARNINGS
             }
         }
     }
+#endif
     return 0;
 fail:
     av_frame_unref(frame);
@@ -1773,6 +1775,11 @@ int ff_decode_preinit(AVCodecContext *avctx)
     if (ret < 0)
         return ret;
 
+#if FF_API_DROPCHANGED
+    if (avctx->flags & AV_CODEC_FLAG_DROPCHANGED)
+        av_log(avctx, AV_LOG_WARNING, "The dropchanged flag is deprecated.\n");
+#endif
+
     return 0;
 }
 

libavcodec/internal.h

@@ -135,12 +135,14 @@ typedef struct AVCodecInternal {
     AVFrame *buffer_frame;
     int draining_done;
 
+#if FF_API_DROPCHANGED
     /* used when avctx flag AV_CODEC_FLAG_DROPCHANGED is set */
     int changed_frames_dropped;
     int initial_format;
     int initial_width, initial_height;
     int initial_sample_rate;
     AVChannelLayout initial_ch_layout;
+#endif
 
 #if CONFIG_LCMS2
     FFIccContext icc; /* used to read and write embedded ICC profiles */

libavcodec/options_table.h

@@ -72,7 +72,9 @@ static const AVOption avcodec_options[] = {
 {"ilme", "interlaced motion estimation", 0, AV_OPT_TYPE_CONST, {.i64 = AV_CODEC_FLAG_INTERLACED_ME }, INT_MIN, INT_MAX, V|E, "flags"},
 {"cgop", "closed GOP", 0, AV_OPT_TYPE_CONST, {.i64 = AV_CODEC_FLAG_CLOSED_GOP }, INT_MIN, INT_MAX, V|E, "flags"},
 {"output_corrupt", "Output even potentially corrupted frames", 0, AV_OPT_TYPE_CONST, {.i64 = AV_CODEC_FLAG_OUTPUT_CORRUPT }, INT_MIN, INT_MAX, V|D, "flags"},
-{"drop_changed", "Drop frames whose parameters differ from first decoded frame", 0, AV_OPT_TYPE_CONST, {.i64 = AV_CODEC_FLAG_DROPCHANGED }, INT_MIN, INT_MAX, A|V|D, "flags"},
+#if FF_API_DROPCHANGED
+{"drop_changed", "Drop frames whose parameters differ from first decoded frame", 0, AV_OPT_TYPE_CONST, {.i64 = AV_CODEC_FLAG_DROPCHANGED }, INT_MIN, INT_MAX, A|V|D | AV_OPT_FLAG_DEPRECATED, "flags"},
+#endif
 {"flags2", NULL, OFFSET(flags2), AV_OPT_TYPE_FLAGS, {.i64 = DEFAULT}, 0, UINT_MAX, V|A|E|D|S, "flags2"},
 {"fast", "allow non-spec-compliant speedup tricks", 0, AV_OPT_TYPE_CONST, {.i64 = AV_CODEC_FLAG2_FAST }, INT_MIN, INT_MAX, V|E, "flags2"},
 {"noout", "skip bitstream encoding", 0, AV_OPT_TYPE_CONST, {.i64 = AV_CODEC_FLAG2_NO_OUTPUT }, INT_MIN, INT_MAX, V|E, "flags2"},

libavcodec/version_major.h

@@ -48,6 +48,7 @@
 #define FF_API_SLICE_OFFSET        (LIBAVCODEC_VERSION_MAJOR < 61)
 #define FF_API_SUBFRAMES           (LIBAVCODEC_VERSION_MAJOR < 61)
 #define FF_API_TICKS_PER_FRAME     (LIBAVCODEC_VERSION_MAJOR < 61)
+#define FF_API_DROPCHANGED         (LIBAVCODEC_VERSION_MAJOR < 61)
 
 // reminder to remove CrystalHD decoders on next major bump
 #define FF_CODEC_CRYSTAL_HD        (LIBAVCODEC_VERSION_MAJOR < 61)