From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from ffbox0-bg.ffmpeg.org (ffbox0-bg.ffmpeg.org [79.124.17.100]) by master.gitmailbox.com (Postfix) with ESMTPS id 2AF364E652 for ; Fri, 11 Jul 2025 15:04:28 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.ffmpeg.org (Postfix) with ESMTP id 2817368CA13; Fri, 11 Jul 2025 18:04:22 +0300 (EEST) Received: from mail-ed1-f50.google.com (mail-ed1-f50.google.com [209.85.208.50]) by ffbox0-bg.ffmpeg.org (Postfix) with ESMTPS id EDB1D68EFC7 for ; Fri, 11 Jul 2025 18:04:15 +0300 (EEST) Received: by mail-ed1-f50.google.com with SMTP id 4fb4d7f45d1cf-6070293103cso3347269a12.0 for ; Fri, 11 Jul 2025 08:04:15 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1752246255; x=1752851055; darn=ffmpeg.org; h=content-transfer-encoding:mime-version:message-id:date:subject:to :from:from:to:cc:subject:date:message-id:reply-to; bh=zmT/hrz514w7N+sMIjvFngVufGddMsUHBqMjsKFqt4Q=; b=efgZZ8eOl15IA1WfoFRSLnU+2ZJN8QXsQYYEkQm10ebHOFXoaLWdctjMhKlkgCAIfu owUnUsDLut5p1l8m4Dj9n2CoUfmJ7+qN62gz7jSPeYEXQPaR93deG1Be4wdtMf7D3Rzd Gj4aXRr4dWQtAqzacqeX0CuNZLm3uvtoA52hbX+EiVLNMHYiHzmu7/pFdEeZQo22Wnlj zwS/ADryesJo3mk1aIxB1cXE4XpKjPFqEthehgO+FL8vb4z7G2q6larcP8PE0RUsIITJ ONlBhyMj8UN0pTMtN4W6sZB0E0FqBIE3Q1Cduz9Ty1gpUsIUePPIToqi3ofFdPzoVl0s BvNw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1752246255; x=1752851055; h=content-transfer-encoding:mime-version:message-id:date:subject:to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=zmT/hrz514w7N+sMIjvFngVufGddMsUHBqMjsKFqt4Q=; b=kxANBaD0cRxi0LDX/BZJXv1h2PQXUTWmrzUfI6C03PF8SW1ZvgilKPjcE9URbP77p0 WLJbrirjLPwogk2393Zdm6D0Z8buWoji4cT6oN1ryDq5LAd7efd8rqTgO3LW7fjOV29S dCur10MUBhRa7oq+k0xo2/C8fIz3rSxvORql8N7l+/876PXVO6tgzJsQ3oCNoyxrfSiL qM2tODfJrTcdeG8r2JWc0wjPjzyJN+t4SceY0N6Ye7X5ulQN0hQqOHKpEEWgpgSxeo87 NDyQnhTZutWo3XWhmdqdyRoM/FLmDx2v4mL9/0IoiBMicFrj6OKmECnBTXj+4Rg14xMZ fc7g== X-Gm-Message-State: AOJu0YyecrUAoajJomI8indaHf3FSvXvX7R6PNvJLV/C1RQzL2+6d4BS /Tp/PWKdQm8WEw2futhUON0gTtbfdBteUb4z3B8fE6w1uAkCx/KVtl6lvT4Hxw== X-Gm-Gg: ASbGncuSEIzZXPFk01LeUinn/5NAcO9L4I/g+vBawXuZ3GxsCXbU3JQDPP32DG7h5gt YK1ZXWA57clOLAdMunoFg4SZwjyzp8STEvAE8SAVihfw6/2VkZBH6LCeaARH6SdLfzCGSX7iD8q yMQGLaeQI/dYNT18LSwHQxx8QTvMXPy+Fdx9r3NMuz3TyBScX80kSpdtR0hk6bHYwXUUjVmLfPk IaSzrmUjsXC4PWtqw/3HEGh9O9FUsYBKaPfg3Hg8GJXav6mRoLgfu62G4J1Q/Ykjlrlu3K8mJBd 9DGX4t5QJBY+pDFDuIVqRZlkQ98obWHGfbd2/6/W1nwkbMHpFh078BtlYh6eNLN4nZXgcjvOiT8 cSlbTJYiNsBUPQuMBAr/c2rSzBp36v40UAeeIoesWc9hme0I7HxiUkiJjSF/uXbGV18tCSyaLuS 34MFrNwsqa3SuaXd+QvP1qaBwGYxX123+whs+Iix9+SQ== X-Google-Smtp-Source: AGHT+IHHHRuoAqYQDMpBiUo2X7DstsZITUJQ4PY0+DO9k9uD761hg7FPGKwsce5DcRP5n9+6XAHHsw== X-Received: by 2002:a05:6402:44db:b0:608:b3c3:3aea with SMTP id 4fb4d7f45d1cf-611e84a465amr2686316a12.16.1752246254656; Fri, 11 Jul 2025 08:04:14 -0700 (PDT) Received: from localhost.localdomain (p200301023701fa0039c61cc86b66e99e.dip0.t-ipconnect.de. [2003:102:3701:fa00:39c6:1cc8:6b66:e99e]) by smtp.gmail.com with ESMTPSA id 4fb4d7f45d1cf-611c9528b05sm2306345a12.30.2025.07.11.08.04.13 for (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Fri, 11 Jul 2025 08:04:13 -0700 (PDT) From: Marvin Scholz To: ffmpeg-devel@ffmpeg.org Date: Fri, 11 Jul 2025 17:04:08 +0200 Message-Id: <20250711150409.33466-1-epirat07@gmail.com> X-Mailer: git-send-email 2.39.5 (Apple Git-154) MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH 1/2] doc: style changes for the AVCodecParameters X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Archived-At: List-Archive: List-Post: 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".