diff mbox series

[FFmpeg-devel,2/4] avcodec.h: split AVCodecParameters API into its own header

Message ID 20200410154201.22678-2-anton@khirnov.net
State Accepted
Headers show
Series [FFmpeg-devel,1/4] lavc: install codec_desc.h
Related show

Checks

Context Check Description
andriy/ffmpeg-patchwork pending
andriy/ffmpeg-patchwork success Applied patch
andriy/ffmpeg-patchwork success Configure finished
andriy/ffmpeg-patchwork success Make finished
andriy/ffmpeg-patchwork success Make fate finished

Commit Message

Anton Khirnov April 10, 2020, 3:41 p.m. UTC
---
Not sure what to do with AVFieldOrder. It gets moved to codec_par.h
since it is used in AVCodecParameters, but it isn't precisely the right
place for it, though it's not horribly wrong either.

Least bad solution I've come up with is making a separate header for
"misc small types used in lavc" and move there:
- AVFieldOrder
- AVAudioServiceType
- AVPanScan
- AVCPBProperties
- AVProducerReferenceTime
- AVProfile
- AVPictureStructure

but
- it's a "misc" header and misc headers are evil
- I can't come up with a good name for it

Suggestions?
---
 doc/APIchanges         |   3 +
 libavcodec/Makefile    |   1 +
 libavcodec/avcodec.h   | 189 +---------------------------------
 libavcodec/codec_par.h | 229 +++++++++++++++++++++++++++++++++++++++++
 libavcodec/version.h   |   2 +-
 5 files changed, 235 insertions(+), 189 deletions(-)
 create mode 100644 libavcodec/codec_par.h

Comments

James Almer April 11, 2020, 3:44 p.m. UTC | #1
On 4/10/2020 12:41 PM, Anton Khirnov wrote:
> ---
> Not sure what to do with AVFieldOrder. It gets moved to codec_par.h
> since it is used in AVCodecParameters, but it isn't precisely the right
> place for it, though it's not horribly wrong either.

How about moving it to lavu's pixfmt.h, alongside other format definitions?

> 
> Least bad solution I've come up with is making a separate header for
> "misc small types used in lavc" and move there:
> - AVFieldOrder
> - AVAudioServiceType
> - AVPanScan
> - AVCPBProperties
> - AVProducerReferenceTime
> - AVProfile
> - AVPictureStructure
> 
> but
> - it's a "misc" header and misc headers are evil
> - I can't come up with a good name for it
> 
> Suggestions?

AVCPBProperties and AVProducerReferenceTime are both packet or codec
coded side data, so maybe they could be moved to packet.h, or to codec_par.h
AVProfile is used by AVCodec only, AVAudioServiceType by AVCodecContext
only, and AVPictureStructure by AVCodecParserContext only, so IMO they
should be in the same header as their users.

But the above is not a priority. The blocker here is what to do with
AVFieldOrder.
Anton Khirnov May 18, 2020, 12:17 p.m. UTC | #2
Quoting James Almer (2020-04-11 17:44:51)
> On 4/10/2020 12:41 PM, Anton Khirnov wrote:
> > ---
> > Not sure what to do with AVFieldOrder. It gets moved to codec_par.h
> > since it is used in AVCodecParameters, but it isn't precisely the right
> > place for it, though it's not horribly wrong either.
> 
> How about moving it to lavu's pixfmt.h, alongside other format definitions?

It's a property of a coded bitstream, so pixfmt seems like the wrong
place for it.

> 
> > 
> > Least bad solution I've come up with is making a separate header for
> > "misc small types used in lavc" and move there:
> > - AVFieldOrder
> > - AVAudioServiceType
> > - AVPanScan
> > - AVCPBProperties
> > - AVProducerReferenceTime
> > - AVProfile
> > - AVPictureStructure
> > 
> > but
> > - it's a "misc" header and misc headers are evil
> > - I can't come up with a good name for it
> > 
> > Suggestions?
> 
> AVCPBProperties and AVProducerReferenceTime are both packet or codec
> coded side data, so maybe they could be moved to packet.h, or to codec_par.h
> AVProfile is used by AVCodec only, AVAudioServiceType by AVCodecContext
> only, and AVPictureStructure by AVCodecParserContext only, so IMO they
> should be in the same header as their users.

They are used by those structs *now*. That can change in the future.
diff mbox series

Patch

diff --git a/doc/APIchanges b/doc/APIchanges
index 4cc2367e69..dbe7f5cd55 100644
--- a/doc/APIchanges
+++ b/doc/APIchanges
@@ -15,6 +15,9 @@  libavutil:     2017-10-21
 
 API changes, most recent first:
 
+2020-xx-xx - xxxxxxxxxx - lavc 58.79.100 - avcodec.h codec_par.h
+  Move AVCodecParameters-related public API to new header codec_par.h.
+
 2020-xx-xx - xxxxxxxxxx - lavc 58.78.100 - avcodec.h codec_desc.h codec_id.h packet.h
   Move AVCodecDesc-related public API to new header codec_desc.h.
   Move AVCodecID enum to new header codec_id.h.
diff --git a/libavcodec/Makefile b/libavcodec/Makefile
index 1970ff027f..7347f9c25b 100644
--- a/libavcodec/Makefile
+++ b/libavcodec/Makefile
@@ -8,6 +8,7 @@  HEADERS = ac3_parser.h                                                  \
           avfft.h                                                       \
           codec_desc.h                                                  \
           codec_id.h                                                    \
+          codec_par.h                                                   \
           d3d11va.h                                                     \
           dirac.h                                                       \
           dv_profile.h                                                  \
diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 55151a0b71..c91f0749ef 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -42,6 +42,7 @@ 
 #include "libavutil/rational.h"
 
 #include "codec_desc.h"
+#include "codec_par.h"
 #include "codec_id.h"
 #include "packet.h"
 #include "version.h"
@@ -624,15 +625,6 @@  typedef struct AVProducerReferenceTime {
 
 struct AVCodecInternal;
 
-enum AVFieldOrder {
-    AV_FIELD_UNKNOWN,
-    AV_FIELD_PROGRESSIVE,
-    AV_FIELD_TT,          //< Top coded_first, top displayed first
-    AV_FIELD_BB,          //< Bottom coded first, bottom displayed first
-    AV_FIELD_TB,          //< Top coded first, bottom displayed first
-    AV_FIELD_BT,          //< Bottom coded first, top displayed first
-};
-
 /**
  * main external API structure.
  * New fields can be added to the end with minor version bumps.
@@ -3040,164 +3032,6 @@  typedef struct AVSubtitle {
     int64_t pts;    ///< Same as packet pts, in AV_TIME_BASE
 } AVSubtitle;
 
-/**
- * This struct describes the properties of an encoded stream.
- *
- * sizeof(AVCodecParameters) is not a part of the public ABI, this struct must
- * be allocated with avcodec_parameters_alloc() and freed with
- * avcodec_parameters_free().
- */
-typedef struct AVCodecParameters {
-    /**
-     * General type of the encoded data.
-     */
-    enum AVMediaType codec_type;
-    /**
-     * Specific type of the encoded data (the codec used).
-     */
-    enum AVCodecID   codec_id;
-    /**
-     * Additional information about the codec (corresponds to the AVI FOURCC).
-     */
-    uint32_t         codec_tag;
-
-    /**
-     * Extra binary data needed for initializing the decoder, codec-dependent.
-     *
-     * Must be allocated with av_malloc() and will be freed by
-     * avcodec_parameters_free(). The allocated size of extradata must be at
-     * least extradata_size + AV_INPUT_BUFFER_PADDING_SIZE, with the padding
-     * bytes zeroed.
-     */
-    uint8_t *extradata;
-    /**
-     * Size of the extradata content in bytes.
-     */
-    int      extradata_size;
-
-    /**
-     * - video: the pixel format, the value corresponds to enum AVPixelFormat.
-     * - audio: the sample format, the value corresponds to enum AVSampleFormat.
-     */
-    int format;
-
-    /**
-     * The average bitrate of the encoded data (in bits per second).
-     */
-    int64_t bit_rate;
-
-    /**
-     * The number of bits per sample in the codedwords.
-     *
-     * This is basically the bitrate per sample. It is mandatory for a bunch of
-     * formats to actually decode them. It's the number of bits for one sample in
-     * the actual coded bitstream.
-     *
-     * This could be for example 4 for ADPCM
-     * For PCM formats this matches bits_per_raw_sample
-     * Can be 0
-     */
-    int bits_per_coded_sample;
-
-    /**
-     * This is the number of valid bits in each output sample. If the
-     * sample format has more bits, the least significant bits are additional
-     * padding bits, which are always 0. Use right shifts to reduce the sample
-     * to its actual size. For example, audio formats with 24 bit samples will
-     * have bits_per_raw_sample set to 24, and format set to AV_SAMPLE_FMT_S32.
-     * To get the original sample use "(int32_t)sample >> 8"."
-     *
-     * For ADPCM this might be 12 or 16 or similar
-     * Can be 0
-     */
-    int bits_per_raw_sample;
-
-    /**
-     * Codec-specific bitstream restrictions that the stream conforms to.
-     */
-    int profile;
-    int level;
-
-    /**
-     * Video only. The dimensions of the video frame in pixels.
-     */
-    int width;
-    int height;
-
-    /**
-     * Video only. The aspect ratio (width / height) which a single pixel
-     * should have when displayed.
-     *
-     * When the aspect ratio is unknown / undefined, the numerator should be
-     * set to 0 (the denominator may have any value).
-     */
-    AVRational sample_aspect_ratio;
-
-    /**
-     * Video only. The order of the fields in interlaced video.
-     */
-    enum AVFieldOrder                  field_order;
-
-    /**
-     * Video only. Additional colorspace characteristics.
-     */
-    enum AVColorRange                  color_range;
-    enum AVColorPrimaries              color_primaries;
-    enum AVColorTransferCharacteristic color_trc;
-    enum AVColorSpace                  color_space;
-    enum AVChromaLocation              chroma_location;
-
-    /**
-     * Video only. Number of delayed frames.
-     */
-    int video_delay;
-
-    /**
-     * Audio only. The channel layout bitmask. May be 0 if the channel layout is
-     * unknown or unspecified, otherwise the number of bits set must be equal to
-     * the channels field.
-     */
-    uint64_t channel_layout;
-    /**
-     * Audio only. The number of audio channels.
-     */
-    int      channels;
-    /**
-     * Audio only. The number of audio samples per second.
-     */
-    int      sample_rate;
-    /**
-     * Audio only. The number of bytes per coded audio frame, required by some
-     * formats.
-     *
-     * Corresponds to nBlockAlign in WAVEFORMATEX.
-     */
-    int      block_align;
-    /**
-     * Audio only. Audio frame size, if known. Required by some formats to be static.
-     */
-    int      frame_size;
-
-    /**
-     * Audio only. The amount of padding (in samples) inserted by the encoder at
-     * the beginning of the audio. I.e. this number of leading decoded samples
-     * must be discarded by the caller to get the original audio without leading
-     * padding.
-     */
-    int initial_padding;
-    /**
-     * Audio only. The amount of padding (in samples) appended by the encoder to
-     * the end of the audio. I.e. this number of decoded samples must be
-     * discarded by the caller from the end of the stream to get the original
-     * audio without any trailing padding.
-     */
-    int trailing_padding;
-    /**
-     * Audio only. Number of samples to skip after a discontinuity.
-     */
-    int seek_preroll;
-} AVCodecParameters;
-
 /**
  * Iterate over all registered codecs.
  *
@@ -3336,27 +3170,6 @@  attribute_deprecated
 int avcodec_copy_context(AVCodecContext *dest, const AVCodecContext *src);
 #endif
 
-/**
- * Allocate a new AVCodecParameters and set its fields to default values
- * (unknown/invalid/0). The returned struct must be freed with
- * avcodec_parameters_free().
- */
-AVCodecParameters *avcodec_parameters_alloc(void);
-
-/**
- * Free an AVCodecParameters instance and everything associated with it and
- * write NULL to the supplied pointer.
- */
-void avcodec_parameters_free(AVCodecParameters **par);
-
-/**
- * Copy the contents of src to dst. Any allocated fields in dst are freed and
- * replaced with newly allocated duplicates of the corresponding fields in src.
- *
- * @return >= 0 on success, a negative AVERROR code on failure.
- */
-int avcodec_parameters_copy(AVCodecParameters *dst, const AVCodecParameters *src);
-
 /**
  * Fill the parameters struct based on the values from the supplied codec
  * context. Any allocated fields in par are freed and replaced with duplicates
diff --git a/libavcodec/codec_par.h b/libavcodec/codec_par.h
new file mode 100644
index 0000000000..948758e237
--- /dev/null
+++ b/libavcodec/codec_par.h
@@ -0,0 +1,229 @@ 
+/*
+ * Codec parameters public API
+ *
+ * This file is part of FFmpeg.
+ *
+ * FFmpeg is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * FFmpeg is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with FFmpeg; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ */
+
+#ifndef AVCODEC_CODEC_PAR_H
+#define AVCODEC_CODEC_PAR_H
+
+#include <stdint.h>
+
+#include "libavutil/avutil.h"
+#include "libavutil/rational.h"
+#include "libavutil/pixfmt.h"
+
+#include "codec_id.h"
+
+/**
+ * @addtogroup lavc_core
+ */
+
+enum AVFieldOrder {
+    AV_FIELD_UNKNOWN,
+    AV_FIELD_PROGRESSIVE,
+    AV_FIELD_TT,          //< Top coded_first, top displayed first
+    AV_FIELD_BB,          //< Bottom coded first, bottom displayed first
+    AV_FIELD_TB,          //< Top coded first, bottom displayed first
+    AV_FIELD_BT,          //< Bottom coded first, top displayed first
+};
+
+/**
+ * This struct describes the properties of an encoded stream.
+ *
+ * sizeof(AVCodecParameters) is not a part of the public ABI, this struct must
+ * be allocated with avcodec_parameters_alloc() and freed with
+ * avcodec_parameters_free().
+ */
+typedef struct AVCodecParameters {
+    /**
+     * General type of the encoded data.
+     */
+    enum AVMediaType codec_type;
+    /**
+     * Specific type of the encoded data (the codec used).
+     */
+    enum AVCodecID   codec_id;
+    /**
+     * Additional information about the codec (corresponds to the AVI FOURCC).
+     */
+    uint32_t         codec_tag;
+
+    /**
+     * Extra binary data needed for initializing the decoder, codec-dependent.
+     *
+     * Must be allocated with av_malloc() and will be freed by
+     * avcodec_parameters_free(). The allocated size of extradata must be at
+     * least extradata_size + AV_INPUT_BUFFER_PADDING_SIZE, with the padding
+     * bytes zeroed.
+     */
+    uint8_t *extradata;
+    /**
+     * Size of the extradata content in bytes.
+     */
+    int      extradata_size;
+
+    /**
+     * - video: the pixel format, the value corresponds to enum AVPixelFormat.
+     * - audio: the sample format, the value corresponds to enum AVSampleFormat.
+     */
+    int format;
+
+    /**
+     * The average bitrate of the encoded data (in bits per second).
+     */
+    int64_t bit_rate;
+
+    /**
+     * The number of bits per sample in the codedwords.
+     *
+     * This is basically the bitrate per sample. It is mandatory for a bunch of
+     * formats to actually decode them. It's the number of bits for one sample in
+     * the actual coded bitstream.
+     *
+     * This could be for example 4 for ADPCM
+     * For PCM formats this matches bits_per_raw_sample
+     * Can be 0
+     */
+    int bits_per_coded_sample;
+
+    /**
+     * This is the number of valid bits in each output sample. If the
+     * sample format has more bits, the least significant bits are additional
+     * padding bits, which are always 0. Use right shifts to reduce the sample
+     * to its actual size. For example, audio formats with 24 bit samples will
+     * have bits_per_raw_sample set to 24, and format set to AV_SAMPLE_FMT_S32.
+     * To get the original sample use "(int32_t)sample >> 8"."
+     *
+     * For ADPCM this might be 12 or 16 or similar
+     * Can be 0
+     */
+    int bits_per_raw_sample;
+
+    /**
+     * Codec-specific bitstream restrictions that the stream conforms to.
+     */
+    int profile;
+    int level;
+
+    /**
+     * Video only. The dimensions of the video frame in pixels.
+     */
+    int width;
+    int height;
+
+    /**
+     * Video only. The aspect ratio (width / height) which a single pixel
+     * should have when displayed.
+     *
+     * When the aspect ratio is unknown / undefined, the numerator should be
+     * set to 0 (the denominator may have any value).
+     */
+    AVRational sample_aspect_ratio;
+
+    /**
+     * Video only. The order of the fields in interlaced video.
+     */
+    enum AVFieldOrder                  field_order;
+
+    /**
+     * Video only. Additional colorspace characteristics.
+     */
+    enum AVColorRange                  color_range;
+    enum AVColorPrimaries              color_primaries;
+    enum AVColorTransferCharacteristic color_trc;
+    enum AVColorSpace                  color_space;
+    enum AVChromaLocation              chroma_location;
+
+    /**
+     * Video only. Number of delayed frames.
+     */
+    int video_delay;
+
+    /**
+     * Audio only. The channel layout bitmask. May be 0 if the channel layout is
+     * unknown or unspecified, otherwise the number of bits set must be equal to
+     * the channels field.
+     */
+    uint64_t channel_layout;
+    /**
+     * Audio only. The number of audio channels.
+     */
+    int      channels;
+    /**
+     * Audio only. The number of audio samples per second.
+     */
+    int      sample_rate;
+    /**
+     * Audio only. The number of bytes per coded audio frame, required by some
+     * formats.
+     *
+     * Corresponds to nBlockAlign in WAVEFORMATEX.
+     */
+    int      block_align;
+    /**
+     * Audio only. Audio frame size, if known. Required by some formats to be static.
+     */
+    int      frame_size;
+
+    /**
+     * Audio only. The amount of padding (in samples) inserted by the encoder at
+     * the beginning of the audio. I.e. this number of leading decoded samples
+     * must be discarded by the caller to get the original audio without leading
+     * padding.
+     */
+    int initial_padding;
+    /**
+     * Audio only. The amount of padding (in samples) appended by the encoder to
+     * the end of the audio. I.e. this number of decoded samples must be
+     * discarded by the caller from the end of the stream to get the original
+     * audio without any trailing padding.
+     */
+    int trailing_padding;
+    /**
+     * Audio only. Number of samples to skip after a discontinuity.
+     */
+    int seek_preroll;
+} AVCodecParameters;
+
+/**
+ * Allocate a new AVCodecParameters and set its fields to default values
+ * (unknown/invalid/0). The returned struct must be freed with
+ * avcodec_parameters_free().
+ */
+AVCodecParameters *avcodec_parameters_alloc(void);
+
+/**
+ * Free an AVCodecParameters instance and everything associated with it and
+ * write NULL to the supplied pointer.
+ */
+void avcodec_parameters_free(AVCodecParameters **par);
+
+/**
+ * Copy the contents of src to dst. Any allocated fields in dst are freed and
+ * replaced with newly allocated duplicates of the corresponding fields in src.
+ *
+ * @return >= 0 on success, a negative AVERROR code on failure.
+ */
+int avcodec_parameters_copy(AVCodecParameters *dst, const AVCodecParameters *src);
+
+
+/**
+ * @}
+ */
+
+#endif // AVCODEC_CODEC_PAR_H
diff --git a/libavcodec/version.h b/libavcodec/version.h
index e62d1a7925..a4eb83124c 100644
--- a/libavcodec/version.h
+++ b/libavcodec/version.h
@@ -28,7 +28,7 @@ 
 #include "libavutil/version.h"
 
 #define LIBAVCODEC_VERSION_MAJOR  58
-#define LIBAVCODEC_VERSION_MINOR  78
+#define LIBAVCODEC_VERSION_MINOR  79
 #define LIBAVCODEC_VERSION_MICRO 100
 
 #define LIBAVCODEC_VERSION_INT  AV_VERSION_INT(LIBAVCODEC_VERSION_MAJOR, \