* [FFmpeg-devel] [PATCH 1/2] doc: style changes for the AVCodecParameters
@ 2025-07-11 15:04 Marvin Scholz
2025-07-11 15:04 ` [FFmpeg-devel] [PATCH 2/2] doc: mark functions related to AVCodecParameters Marvin Scholz
0 siblings, 1 reply; 2+ messages in thread
From: Marvin Scholz @ 2025-07-11 15:04 UTC (permalink / raw)
To: ffmpeg-devel
Mostly adding references and making the video/audio only
annotations not be the brief description.
---
libavcodec/codec_par.h | 123 ++++++++++++++++++++++++++++-------------
1 file changed, 84 insertions(+), 39 deletions(-)
diff --git a/libavcodec/codec_par.h b/libavcodec/codec_par.h
index f4b9bb5c06..420884a1c8 100644
--- a/libavcodec/codec_par.h
+++ b/libavcodec/codec_par.h
@@ -33,16 +33,18 @@
#include "packet.h"
/**
- * @addtogroup lavc_core
+ * @defgroup lavc_codec_params Codec parameters
+ * @ingroup lavc_core
* @{
*/
/**
* 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().
+ * @note
+ * The `sizeof(AVCodecParameters)` is not a part of the public ABI,
+ * therefore this struct must be allocated with ::avcodec_parameters_alloc()
+ * and freed with ::avcodec_parameters_free().
*/
typedef struct AVCodecParameters {
/**
@@ -61,9 +63,9 @@ typedef struct AVCodecParameters {
/**
* 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
+ * 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;
@@ -75,19 +77,19 @@ typedef struct AVCodecParameters {
/**
* Additional data associated with the entire stream.
*
- * Should be allocated with av_packet_side_data_new() or
- * av_packet_side_data_add(), and will be freed by avcodec_parameters_free().
+ * Should be allocated with ::av_packet_side_data_new() or
+ * ::av_packet_side_data_add(), and will be freed by ::avcodec_parameters_free().
*/
AVPacketSideData *coded_side_data;
/**
- * Amount of entries in @ref coded_side_data.
+ * Amount of entries in ::coded_side_data.
*/
int nb_coded_side_data;
/**
- * - video: the pixel format, the value corresponds to enum AVPixelFormat.
- * - audio: the sample format, the value corresponds to enum AVSampleFormat.
+ * - Video: the pixel format, the value corresponds to enum ::AVPixelFormat.
+ * - Audio: the sample format, the value corresponds to enum ::AVSampleFormat.
*/
int format;
@@ -103,22 +105,27 @@ typedef struct AVCodecParameters {
* 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
+ * 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
+ * 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"."
+ * 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
+ *
+ * Can be 0.
*/
int bits_per_raw_sample;
@@ -129,9 +136,17 @@ typedef struct AVCodecParameters {
int level;
/**
- * Video only. The dimensions of the video frame in pixels.
+ * The width of the video frame in pixels
+ *
+ * Video only.
*/
int width;
+
+ /**
+ * The height of the video frame in pixels.
+ *
+ * Video only.
+ */
int height;
/**
@@ -145,7 +160,7 @@ typedef struct AVCodecParameters {
/**
* Video only. Number of frames per second, for streams with constant frame
- * durations. Should be set to { 0, 1 } when some frames have differing
+ * durations. Should be set to `{ 0, 1 }` when some frames have differing
* durations or if the value is not known.
*
* @note This field correponds to values that are stored in codec-level
@@ -156,12 +171,16 @@ typedef struct AVCodecParameters {
AVRational framerate;
/**
- * Video only. The order of the fields in interlaced video.
+ * The order of the fields in interlaced video.
+ *
+ * Video only.
*/
enum AVFieldOrder field_order;
/**
- * Video only. Additional colorspace characteristics.
+ * Additional colorspace characteristics.
+ *
+ * Video only.
*/
enum AVColorRange color_range;
enum AVColorPrimaries color_primaries;
@@ -170,65 +189,89 @@ typedef struct AVCodecParameters {
enum AVChromaLocation chroma_location;
/**
- * Video only. Number of delayed frames.
+ * Number of delayed frames.
+ *
+ * Video only.
*/
int video_delay;
/**
- * Audio only. The channel layout and number of channels.
+ * The channel layout and number of channels.
+ *
+ * Audio only.
*/
AVChannelLayout ch_layout;
/**
- * Audio only. The number of audio samples per second.
+ * The number of audio samples per second.
+ *
+ * Audio only.
*/
int sample_rate;
/**
- * Audio only. The number of bytes per coded audio frame, required by some
- * formats.
+ * The number of bytes per coded audio frame, required by some formats.
+ *
+ * Audio only.
*
* Corresponds to nBlockAlign in WAVEFORMATEX.
*/
int block_align;
/**
- * Audio only. Audio frame size, if known. Required by some formats to be static.
+ * Audio frame size, if known. Required by some formats to be static.
+ *
+ * Audio only.
*/
int frame_size;
/**
- * Audio only. The amount of padding (in samples) inserted by the encoder at
+ * Number of padding audio samples at the start.
+ *
+ * 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.
+ *
+ * Audio only.
*/
int initial_padding;
/**
- * Audio only. The amount of padding (in samples) appended by the encoder to
+ * Number of padding audio samples at the end.
+ *
+ * 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.
+ *
+ * Audio only.
*/
int trailing_padding;
/**
- * Audio only. Number of samples to skip after a discontinuity.
+ * Number of audio samples to skip after a discontinuity.
+ *
+ * Audio only.
*/
int seek_preroll;
} AVCodecParameters;
+/**
+ * @relates 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().
+ * ::avcodec_parameters_free().
*/
AVCodecParameters *avcodec_parameters_alloc(void);
/**
* Free an AVCodecParameters instance and everything associated with it and
- * write NULL to the supplied pointer.
+ * 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
+ * Copy the contents of \p src to \p 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.
@@ -236,11 +279,13 @@ void avcodec_parameters_free(AVCodecParameters **par);
int avcodec_parameters_copy(AVCodecParameters *dst, const AVCodecParameters *src);
/**
- * This function is the same as av_get_audio_frame_duration(), except it works
- * with AVCodecParameters instead of an AVCodecContext.
+ * This function is the same as ::av_get_audio_frame_duration(), except it works
+ * with ::AVCodecParameters instead of an ::AVCodecContext.
*/
int av_get_audio_frame_duration2(AVCodecParameters *par, int frame_bytes);
+/** @} */
+
/**
* @}
*/
--
2.39.5 (Apple Git-154)
_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".
^ permalink raw reply [flat|nested] 2+ messages in thread
* [FFmpeg-devel] [PATCH 2/2] doc: mark functions related to AVCodecParameters
2025-07-11 15:04 [FFmpeg-devel] [PATCH 1/2] doc: style changes for the AVCodecParameters Marvin Scholz
@ 2025-07-11 15:04 ` Marvin Scholz
0 siblings, 0 replies; 2+ messages in thread
From: Marvin Scholz @ 2025-07-11 15:04 UTC (permalink / raw)
To: ffmpeg-devel
This makes these functions appear in the AVCodecParameters
documentation page, so they are easier to find.
---
libavcodec/avcodec.h | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index a004cccd2d..a1d82cb9a9 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -2139,6 +2139,8 @@ const AVClass *avcodec_get_subtitle_rect_class(void);
* of the corresponding fields in codec.
*
* @return >= 0 on success, a negative AVERROR code on failure
+ *
+ * @relates AVCodecParameters
*/
int avcodec_parameters_from_context(struct AVCodecParameters *par,
const AVCodecContext *codec);
@@ -2150,6 +2152,8 @@ int avcodec_parameters_from_context(struct AVCodecParameters *par,
* Fields in codec that do not have a counterpart in par are not touched.
*
* @return >= 0 on success, a negative AVERROR code on failure.
+ *
+ * @relates AVCodecParameters
*/
int avcodec_parameters_to_context(AVCodecContext *codec,
const struct AVCodecParameters *par);
--
2.39.5 (Apple Git-154)
_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2025-07-11 15:04 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2025-07-11 15:04 [FFmpeg-devel] [PATCH 1/2] doc: style changes for the AVCodecParameters Marvin Scholz
2025-07-11 15:04 ` [FFmpeg-devel] [PATCH 2/2] doc: mark functions related to AVCodecParameters Marvin Scholz
Git Inbox Mirror of the ffmpeg-devel mailing list - see https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
This inbox may be cloned and mirrored by anyone:
git clone --mirror https://master.gitmailbox.com/ffmpegdev/0 ffmpegdev/git/0.git
# If you have public-inbox 1.1+ installed, you may
# initialize and index your mirror using the following commands:
public-inbox-init -V2 ffmpegdev ffmpegdev/ https://master.gitmailbox.com/ffmpegdev \
ffmpegdev@gitmailbox.com
public-inbox-index ffmpegdev
Example config snippet for mirrors.
AGPL code for this site: git clone https://public-inbox.org/public-inbox.git