From patchwork Sun Sep 25 00:10:33 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Marvin Scholz X-Patchwork-Id: 38224 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:3b1c:b0:96:9ee8:5cfd with SMTP id c28csp1390118pzh; Sat, 24 Sep 2022 17:12:51 -0700 (PDT) X-Google-Smtp-Source: AMsMyM7p7dObX3iBQAd6ReM3Ctb8qQEbso2VFV3i7vu3fQZna8aG2djKtJzf7chvOomHJBHuHnO5 X-Received: by 2002:a17:907:70c:b0:740:33f3:cbab with SMTP id xb12-20020a170907070c00b0074033f3cbabmr12620804ejb.600.1664064770759; Sat, 24 Sep 2022 17:12:50 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1664064770; cv=none; d=google.com; s=arc-20160816; b=mo8al7p4nbXHZ32tUMUw/Pczx+n3zu64N0aNGuUgxuxTFlDdRZ6PGaVp3JXLrU1SpL FDunlW/IGfTLf/rhgEVe/+d3WUxo1gKlPu4r9GRpepYTRhgfUChhKtEGUXT6iItC+8nX +lITY+gw2+vbP7HileraGsmHfmAczgf7qemk5xLOKARbt/eSBtnevXyPymNbWVm6SRqL 1BJRln+pr7Tmk0C2jXq/EKlT4oxcJYZF/P5bfw7UmK9u90l0i1dkAiKgQziXf6AxK3nZ k3f2OUDuP4fmKEzONhZ0W2kLqF2pRz+U82Gc0MUvAbkYkw2KzeZMztP9Gz/1SH7WohQA 40xQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:cc:reply-to :list-subscribe:list-help:list-post:list-archive:list-unsubscribe :list-id:precedence:subject:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature:delivered-to; bh=zL4sWPEaj0B3K4EhUdeISEm/5+PpAfw9gHsO+d5hPDQ=; b=Re4Zly2JWX8Klxw40vjpjdM+0PXY5fNcr2n19KoRJx1QilCybo1TzkBhDMbZZAuzOa PDXLcWC7mXDw8nRNg0uP0sD69xzGdnRD/O3oS6WHuko30RPFs7Z6/ydOz4e1+37LxkDZ nCQB/GRGsyU3pCiqcIBC8wgAl1c8lMXzkAMsm9rLRCAu1NaHn540kxFVU/tB4tqKuQBY SQmgTkDxEmrcRHzNws4CekvHl8Jusuz5/3Qub055QphxQVH5LjlCSLZa/2b2GXKx29ZD jMl38LVo1q6SX9+fAJlhy9wi7IOgLdFXXFXO0QlRBS4mSussbI5m2fHbmzZ0Y0t8QdBD wymg== ARC-Authentication-Results: i=1; mx.google.com; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20210112 header.b=StzJyWEe; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org; dmarc=fail (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id js16-20020a17090797d000b007808427b24dsi12850754ejc.370.2022.09.24.17.12.50; Sat, 24 Sep 2022 17:12:50 -0700 (PDT) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20210112 header.b=StzJyWEe; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org; dmarc=fail (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id D2D7B68BB10; Sun, 25 Sep 2022 03:11:52 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail-ej1-f50.google.com (mail-ej1-f50.google.com [209.85.218.50]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 58E8468BB14 for ; Sun, 25 Sep 2022 03:11:44 +0300 (EEST) Received: by mail-ej1-f50.google.com with SMTP id l14so7433563eja.7 for ; Sat, 24 Sep 2022 17:11:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date; bh=wLYnHglkepTFDqeEdl4n8vXjnkT5gb6SWHBZfelC0DE=; b=StzJyWEe68VgUdRJFwB8gvxFAAZBxd033j7PtqBH67Nc3tB9/q4QHu/zxCr2/uBQaq ruqyj8y6mxCfZnvsljrZKwG+M5FtaAV3Qu3nBTtWZu6ItiqinAe9OapF8tT05I94aG+A oLfQwAUYprN7TO0gZka25pxsQLfI02bankEvjKq6Ghnpj317tSo+uOBMnSA/+d2i1Bks 9cQTrNMvOvd/gfwYTgvD3VVDd7jVEMKl+HtK3QKLssn7AGRHA3aA4ZwRRh/2MU+9ECTC tGgwDWKv+Uq6wa3l99viiIuHVKA9Npa0SvthsrHcj2XHW7DrpHybyrMNl4k0RtTW3LW9 GqWg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date; bh=wLYnHglkepTFDqeEdl4n8vXjnkT5gb6SWHBZfelC0DE=; b=UFK7H+6vQL9D7jnrD6K6ev1oxbXHitaPfRZsWBeMENyIQMBP0I08hqDoX3YyA7JLBd neA7PSleqEos1IohP6ypEkN5OVs7S+AgLFF/L3WD8bAz5F0S1Ou8DtO2uhSs/XjIrNPp OCO4Rmrtg5e3IbRuZqH6VJBGfPL/oFdCaUs3UgVK/+etkI1wQZhJMv8NI9WI8TSe6L2c jL0V/VUgmSySY/A4mbFjc5SWe/eQsTgeYGHbBI+hNkcuvS3+GbzB1bER6heoDFxseBHp ayYQQE2JSotyLpQmJZ7T32NUezmupRTRGcbJCdZUlXGb+bNfcF38rJdsxqBuEnAcYYaY 6oGg== X-Gm-Message-State: ACrzQf3v1N6lT1jlyPALE1W0iEhJPghX4juKo6c1kJhckVf+Hl6R2kwY 9VJJ4zEyfvVNUOLFdRiOCp+q13aKplM= X-Received: by 2002:a17:907:60d1:b0:780:6a13:43 with SMTP id hv17-20020a17090760d100b007806a130043mr12714539ejc.559.1664064703562; Sat, 24 Sep 2022 17:11:43 -0700 (PDT) Received: from MBP-von-Marvin.citadel.scalie.me (84-112-104-25.cable.dynamic.surfer.at. [84.112.104.25]) by smtp.gmail.com with ESMTPSA id kz3-20020a17090777c300b007812ba2a360sm6208042ejc.149.2022.09.24.17.11.42 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 24 Sep 2022 17:11:43 -0700 (PDT) From: Marvin Scholz To: ffmpeg-devel@ffmpeg.org Date: Sun, 25 Sep 2022 02:10:33 +0200 Message-Id: <20220925001121.37721-7-epirat07@gmail.com> X-Mailer: git-send-email 2.37.0 (Apple Git-136) In-Reply-To: <20220925001121.37721-1-epirat07@gmail.com> References: <20220922020400.46715-1-epirat07@gmail.com> <20220925001121.37721-1-epirat07@gmail.com> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v3 06/54] avformat/avformat: Improve doxy style 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 Cc: Marvin Scholz Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: sU9zqUcSCWNA Mostly re-indenting and adding some missing references. --- libavformat/avformat.h | 180 +++++++++++++++++++++++------------------ 1 file changed, 103 insertions(+), 77 deletions(-) diff --git a/libavformat/avformat.h b/libavformat/avformat.h index c695cfc6de..1d97d56ac5 100644 --- a/libavformat/avformat.h +++ b/libavformat/avformat.h @@ -1898,8 +1898,8 @@ const AVOutputFormat *av_muxer_iterate(void **opaque); /** * Iterate over all registered demuxers. * - * @param opaque a pointer where libavformat will store the iteration state. Must - * point to NULL to start the iteration. + * @param opaque a pointer where libavformat will store the iteration state. + * Must point to NULL to start the iteration. * * @return the next registered demuxer or NULL when the iteration is * finished @@ -1957,12 +1957,13 @@ AVStream *avformat_new_stream(AVFormatContext *s, const AVCodec *c); /** * Wrap an existing array as stream side data. * - * @param st stream + * @param st stream * @param type side information type * @param data the side data array. It must be allocated with the av_malloc() * family of functions. The ownership of the data is transferred to * st. * @param size side information size + * * @return zero on success, a negative AVERROR code on failure. On failure, * the stream is unchanged and the data remains owned by the caller. */ @@ -1973,8 +1974,9 @@ int av_stream_add_side_data(AVStream *st, enum AVPacketSideDataType type, * Allocate new information from stream. * * @param stream stream - * @param type desired side information type - * @param size side information size + * @param type desired side information type + * @param size side information size + * * @return pointer to fresh allocated data or NULL otherwise */ uint8_t *av_stream_new_side_data(AVStream *stream, @@ -1983,9 +1985,10 @@ uint8_t *av_stream_new_side_data(AVStream *stream, * Get side information from stream. * * @param stream stream - * @param type desired side information type - * @param size If supplied, *size will be set to the size of the side data - * or to zero if the desired side data is not present. + * @param type desired side information type + * @param size If supplied, *size will be set to the size of the side data + * or to zero if the desired side data is not present. + * * @return pointer to data if present or NULL otherwise */ uint8_t *av_stream_get_side_data(const AVStream *stream, @@ -2003,16 +2006,17 @@ AVProgram *av_new_program(AVFormatContext *s, int id); * avformat_free_context() can be used to free the context and * everything allocated by the framework within it. * - * @param ctx pointee is set to the created format context, or to NULL in - * case of failure - * @param oformat format to use for allocating the context, if NULL - * format_name and filename are used instead - * @param format_name the name of output format to use for allocating the - * context, if NULL filename is used instead - * @param filename the name of the filename to use for allocating the - * context, may be NULL - * @return >= 0 in case of success, a negative AVERROR code in case of - * failure + * @param ctx pointee is set to the created format context, + * or to NULL in case of failure + * @param oformat format to use for allocating the context, if NULL + * format_name and filename are used instead + * @param format_name the name of output format to use for allocating the + * context, if NULL filename is used instead + * @param filename the name of the filename to use for allocating the + * context, may be NULL + * + * @return >= 0 in case of success, a negative AVERROR code in case of + * failure */ int avformat_alloc_output_context2(AVFormatContext **ctx, const AVOutputFormat *oformat, const char *format_name, const char *filename); @@ -2067,15 +2071,16 @@ const AVInputFormat *av_probe_input_format3(const AVProbeData *pd, * attempt is made. When the maximum probe size is reached, the input format * with the highest score is returned. * - * @param pb the bytestream to probe - * @param fmt the input format is put here - * @param url the url of the stream - * @param logctx the log context - * @param offset the offset within the bytestream to probe from + * @param pb the bytestream to probe + * @param fmt the input format is put here + * @param url the url of the stream + * @param logctx the log context + * @param offset the offset within the bytestream to probe from * @param max_probe_size the maximum probe buffer size (zero for default) + * * @return the score in case of success, a negative value corresponding to an * the maximal score is AVPROBE_SCORE_MAX - * AVERROR code otherwise + * AVERROR code otherwise */ int av_probe_input_buffer2(AVIOContext *pb, const AVInputFormat **fmt, const char *url, void *logctx, @@ -2092,16 +2097,19 @@ int av_probe_input_buffer(AVIOContext *pb, const AVInputFormat **fmt, * Open an input stream and read the header. The codecs are not opened. * The stream must be closed with avformat_close_input(). * - * @param ps Pointer to user-supplied AVFormatContext (allocated by avformat_alloc_context). - * May be a pointer to NULL, in which case an AVFormatContext is allocated by this - * function and written into ps. - * Note that a user-supplied AVFormatContext will be freed on failure. - * @param url URL of the stream to open. - * @param fmt If non-NULL, this parameter forces a specific input format. - * Otherwise the format is autodetected. - * @param options A dictionary filled with AVFormatContext and demuxer-private options. - * On return this parameter will be destroyed and replaced with a dict containing - * options that were not found. May be NULL. + * @param ps Pointer to user-supplied AVFormatContext (allocated by + * avformat_alloc_context). May be a pointer to NULL, in + * which case an AVFormatContext is allocated by this + * function and written into ps. + * Note that a user-supplied AVFormatContext will be freed + * on failure. + * @param url URL of the stream to open. + * @param fmt If non-NULL, this parameter forces a specific input format. + * Otherwise the format is autodetected. + * @param options A dictionary filled with AVFormatContext and demuxer-private + * options. + * On return this parameter will be destroyed and replaced with + * a dict containing options that were not found. May be NULL. * * @return 0 on success, a negative AVERROR on failure. * @@ -2140,6 +2148,7 @@ int avformat_find_stream_info(AVFormatContext *ic, AVDictionary **options); * @param last the last found program, the search will start after this * program, or from the beginning if it is NULL * @param s stream index + * * @return the next program which belongs to s, NULL if no program is found or * the last program is not among the programs of ic. */ @@ -2164,10 +2173,12 @@ void av_program_add_stream_index(AVFormatContext *ac, int progid, unsigned int i * @param decoder_ret if non-NULL, returns the decoder for the * selected stream * @param flags flags; none are currently defined + * * @return the non-negative stream number in case of success, * AVERROR_STREAM_NOT_FOUND if no stream with the requested type * could be found, * AVERROR_DECODER_NOT_FOUND if streams were found but no decoder + * * @note If av_find_best_stream returns successfully and decoder_ret is not * NULL, then *decoder_ret is guaranteed to be set to a valid AVCodec. */ @@ -2211,13 +2222,14 @@ int av_read_frame(AVFormatContext *s, AVPacket *pkt); * Seek to the keyframe at timestamp. * 'timestamp' in 'stream_index'. * - * @param s media file handle - * @param stream_index If stream_index is (-1), a default - * stream is selected, and timestamp is automatically converted - * from AV_TIME_BASE units to the stream specific time_base. - * @param timestamp Timestamp in AVStream.time_base units - * or, if no stream is specified, in AV_TIME_BASE units. - * @param flags flags which select direction and seeking mode + * @param s media file handle + * @param stream_index If stream_index is (-1), a default stream is selected, + * and timestamp is automatically converted from + * AV_TIME_BASE units to the stream specific time_base. + * @param timestamp Timestamp in AVStream.time_base units or, if no stream + * is specified, in AV_TIME_BASE units. + * @param flags flags which select direction and seeking mode + * * @return >= 0 on success */ int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp, @@ -2239,12 +2251,12 @@ int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp, * keyframes (this may not be supported by all demuxers). * If flags contain AVSEEK_FLAG_BACKWARD, it is ignored. * - * @param s media file handle + * @param s media file handle * @param stream_index index of the stream which is used as time base reference - * @param min_ts smallest acceptable timestamp - * @param ts target timestamp - * @param max_ts largest acceptable timestamp - * @param flags flags + * @param min_ts smallest acceptable timestamp + * @param ts target timestamp + * @param max_ts largest acceptable timestamp + * @param flags flags * @return >=0 on success, error code otherwise * * @note This is part of the new seek API which is still under construction. @@ -2308,16 +2320,22 @@ void avformat_close_input(AVFormatContext **s); * Allocate the stream private data and write the stream header to * an output media file. * - * @param s Media file handle, must be allocated with avformat_alloc_context(). - * Its oformat field must be set to the desired output format; - * Its pb field must be set to an already opened AVIOContext. - * @param options An AVDictionary filled with AVFormatContext and muxer-private options. - * On return this parameter will be destroyed and replaced with a dict containing - * options that were not found. May be NULL. - * - * @return AVSTREAM_INIT_IN_WRITE_HEADER on success if the codec had not already been fully initialized in avformat_init, - * AVSTREAM_INIT_IN_INIT_OUTPUT on success if the codec had already been fully initialized in avformat_init, - * negative AVERROR on failure. + * @param s Media file handle, must be allocated with + * avformat_alloc_context(). + * Its \ref AVFormatContext.oformat "oformat" field must be set + * to the desired output format; + * Its \ref AVFormatContext.pb "pb" field must be set to an + * already opened ::AVIOContext. + * @param options An ::AVDictionary filled with AVFormatContext and + * muxer-private options. + * On return this parameter will be destroyed and replaced with + * a dict containing options that were not found. May be NULL. + * + * @retval AVSTREAM_INIT_IN_WRITE_HEADER On success, if the codec had not already been + * fully initialized in avformat_init_output(). + * @retval AVSTREAM_INIT_IN_INIT_OUTPUT On success, if the codec had already been fully + * initialized in avformat_init_output(). + * @retval AVERROR A negative AVERROR on failure. * * @see av_opt_find, av_dict_set, avio_open, av_oformat_next, avformat_init_output. */ @@ -2326,20 +2344,26 @@ int avformat_write_header(AVFormatContext *s, AVDictionary **options); /** * Allocate the stream private data and initialize the codec, but do not write the header. - * May optionally be used before avformat_write_header to initialize stream parameters + * May optionally be used before avformat_write_header() to initialize stream parameters * before actually writing the header. - * If using this function, do not pass the same options to avformat_write_header. - * - * @param s Media file handle, must be allocated with avformat_alloc_context(). - * Its oformat field must be set to the desired output format; - * Its pb field must be set to an already opened AVIOContext. - * @param options An AVDictionary filled with AVFormatContext and muxer-private options. - * On return this parameter will be destroyed and replaced with a dict containing - * options that were not found. May be NULL. - * - * @return AVSTREAM_INIT_IN_WRITE_HEADER on success if the codec requires avformat_write_header to fully initialize, - * AVSTREAM_INIT_IN_INIT_OUTPUT on success if the codec has been fully initialized, - * negative AVERROR on failure. + * If using this function, do not pass the same options to avformat_write_header(). + * + * @param s Media file handle, must be allocated with + * avformat_alloc_context(). + * Its \ref AVFormatContext.oformat "oformat" field must be set + * to the desired output format; + * Its \ref AVFormatContext.pb "pb" field must be set to an + * already opened ::AVIOContext. + * @param options An ::AVDictionary filled with AVFormatContext and + * muxer-private options. + * On return this parameter will be destroyed and replaced with + * a dict containing options that were not found. May be NULL. + * + * @retval AVSTREAM_INIT_IN_WRITE_HEADER On success, if the codec requires + * avformat_write_header to fully initialize. + * @retval AVSTREAM_INIT_IN_INIT_OUTPUT On success, if the codec has been fully + * initialized. + * @retval AVERROR Anegative AVERROR on failure. * * @see av_opt_find, av_dict_set, avio_open, av_oformat_next, avformat_write_header. */ @@ -2484,11 +2508,11 @@ int av_write_trailer(AVFormatContext *s); * there is no match. * * @param short_name if non-NULL checks if short_name matches with the - * names of the registered formats - * @param filename if non-NULL checks if filename terminates with the - * extensions of the registered formats - * @param mime_type if non-NULL checks if mime_type matches with the - * MIME type of the registered formats + * names of the registered formats + * @param filename if non-NULL checks if filename terminates with the + * extensions of the registered formats + * @param mime_type if non-NULL checks if mime_type matches with the + * MIME type of the registered formats */ const AVOutputFormat *av_guess_format(const char *short_name, const char *filename, @@ -2512,9 +2536,11 @@ enum AVCodecID av_guess_codec(const AVOutputFormat *fmt, const char *short_name, * time_base units * @param[out] wall absolute time when that packet whas output, * in microsecond - * @return 0 if OK, AVERROR(ENOSYS) if the format does not support it - * Note: some formats or devices may not allow to measure dts and wall - * atomically. + * @retval 0 Success + * @retval AVERROR(ENOSYS) The format does not support it + * + * @note Some formats or devices may not allow to measure dts and wall + * atomically. */ int av_get_output_timestamp(struct AVFormatContext *s, int stream, int64_t *dts, int64_t *wall);