From patchwork Sat Jan 28 13:45:51 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anton Khirnov X-Patchwork-Id: 40155 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:3ca3:b0:b9:1511:ac2c with SMTP id b35csp2125920pzj; Sat, 28 Jan 2023 05:46:17 -0800 (PST) X-Google-Smtp-Source: AK7set8QpV0F1m9T3X1aDGtsX2oS8qs3f1sNNqKCac7nK36VJW15A8xkBSbKlD1dPV4+1XMOFfUv X-Received: by 2002:a17:906:81c3:b0:878:7819:b8c3 with SMTP id e3-20020a17090681c300b008787819b8c3mr9186892ejx.46.1674913576892; Sat, 28 Jan 2023 05:46:16 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1674913576; cv=none; d=google.com; s=arc-20160816; b=ydDorxc6p86t5+wHq2UID4kzRI22nN4NfiKwJ8Bwjyycc2eaL7tlKzcmAP1bPOf3F3 Qq6cC61sH7+ICzosBHyH3v/pR7LPDeZ3F2SiuAsYgfl+JoCMiarjeR796PfFEMqfxPF0 eIs5dp0HxeS9+ObsoiEyb4ZxQpm37TR9oRPnNC0ncILSs+cmv3q+Tp/nGcQ/OyTycRwq VWlOJnDUZ+XkzKv8YtgVnc769BDx32KTmzhC4Xdk43fup/5c1KPcj4YX/fMHRfWejC2t cTGgjPNTk3AVKWJN6sXRP/s1shRJAjTLVTu1gNBVdH1M/aQ54PYqYRKIkjbgDZDzV8uC S6fQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding: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:delivered-to; bh=fH/TNwKdzJIojUtsdnB1l0ZXpHYnjQNuCHvUpNnzeiM=; b=ywvZBrdaV1gQzU1KbOJmgBtN7Zva2isJGJ3VNpA/IkUA8K2/JrSDnM8RfIX1e9SGql ySpVICkXQtZszVtTioUJTQU5d1rjoeMqLG3dnFmBfOekZcevC5QtSiyUY4ZMa6mf4ZrB P7FLMpTsLWa7pE43URy0Z7xHPVI9fEDY5w0v0iVIDYjpulJ1MmbRJcp1IH7FMrpV30mw 6gmuCP19yKRQRNfhAnCllYr9QOyX251T4JTflORjgWeAJMWa2P7PW99boMVGaHrOZY9W 8RoUcgCN4+HSy1xcLbL9CE7zbl2SyAxIuHkjLnEIkqK3qWAXaoGh2U2kkSC2lWhSDGDl 9IWw== ARC-Authentication-Results: i=1; mx.google.com; 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 Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id fh7-20020a1709073a8700b008817e670a18si2304207ejc.900.2023.01.28.05.46.12; Sat, 28 Jan 2023 05:46:16 -0800 (PST) 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; 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 Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 24D9268BE2F; Sat, 28 Jan 2023 15:46:09 +0200 (EET) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail0.khirnov.net (red.khirnov.net [176.97.15.12]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id C154868BDFF for ; Sat, 28 Jan 2023 15:46:02 +0200 (EET) Received: from localhost (localhost [IPv6:::1]) by mail0.khirnov.net (Postfix) with ESMTP id 31C7D2404EC for ; Sat, 28 Jan 2023 14:46:02 +0100 (CET) Received: from mail0.khirnov.net ([IPv6:::1]) by localhost (mail0.khirnov.net [IPv6:::1]) (amavisd-new, port 10024) with ESMTP id Gl91oVs7NXSE for ; Sat, 28 Jan 2023 14:46:01 +0100 (CET) Received: from libav.khirnov.net (libav.khirnov.net [IPv6:2a00:c500:561:201::7]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "libav.khirnov.net", Issuer "smtp.khirnov.net SMTP CA" (verified OK)) by mail0.khirnov.net (Postfix) with ESMTPS id 504EA240178 for ; Sat, 28 Jan 2023 14:46:01 +0100 (CET) Received: from libav.khirnov.net (libav.khirnov.net [IPv6:::1]) by libav.khirnov.net (Postfix) with ESMTP id 711C03A0101 for ; Sat, 28 Jan 2023 14:45:53 +0100 (CET) From: Anton Khirnov To: ffmpeg-devel@ffmpeg.org Date: Sat, 28 Jan 2023 14:45:51 +0100 Message-Id: <20230128134551.11892-1-anton@khirnov.net> X-Mailer: git-send-email 2.35.1 In-Reply-To: References: MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH] lavc/avcodec: improve enc/dec API doxy 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 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: 56+C76YPZTdz Change return value descriptions into proper lists. --- libavcodec/avcodec.h | 79 ++++++++++++++++++++++---------------------- 1 file changed, 39 insertions(+), 40 deletions(-) diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h index 0ac581d660..ad6377e8d8 100644 --- a/libavcodec/avcodec.h +++ b/libavcodec/avcodec.h @@ -2605,17 +2605,17 @@ int avcodec_decode_subtitle2(AVCodecContext *avctx, AVSubtitle *sub, * still has frames buffered, it will return them after sending * a flush packet. * - * @return 0 on success, otherwise negative error code: - * AVERROR(EAGAIN): input is not accepted in the current state - user - * must read output with avcodec_receive_frame() (once - * all output is read, the packet should be resent, and - * the call will not fail with EAGAIN). - * AVERROR_EOF: the decoder has been flushed, and no new packets can - * be sent to it (also returned if more than 1 flush - * packet is sent) - * AVERROR(EINVAL): codec not opened, it is an encoder, or requires flush - * AVERROR(ENOMEM): failed to add packet to internal queue, or similar - * other errors: legitimate decoding errors + * @retval 0 success + * @retval AVERROR(EAGAIN) input is not accepted in the current state - user + * must read output with avcodec_receive_frame() (once + * all output is read, the packet should be resent, + * and the call will not fail with EAGAIN). + * @retval AVERROR_EOF the decoder has been flushed, and no new packets can be + * sent to it (also returned if more than 1 flush + * packet is sent) + * @retval AVERROR(EINVAL) codec not opened, it is an encoder, or requires flush + * @retval AVERROR(ENOMEM) failed to add packet to internal queue, or similar + * @retval "another negative error code" legitimate decoding errors */ int avcodec_send_packet(AVCodecContext *avctx, const AVPacket *avpkt); @@ -2629,18 +2629,17 @@ int avcodec_send_packet(AVCodecContext *avctx, const AVPacket *avpkt); * codec. Note that the function will always call * av_frame_unref(frame) before doing anything else. * - * @return - * 0: success, a frame was returned - * AVERROR(EAGAIN): output is not available in this state - user must try - * to send new input - * AVERROR_EOF: the codec has been fully flushed, and there will be - * no more output frames - * AVERROR(EINVAL): codec not opened, or it is an encoder without - * the AV_CODEC_FLAG_RECON_FRAME flag enabled - * AVERROR_INPUT_CHANGED: current decoded frame has changed parameters - * with respect to first decoded frame. Applicable - * when flag AV_CODEC_FLAG_DROPCHANGED is set. - * other negative values: legitimate decoding errors + * @retval 0 success, a frame was returned + * @retval AVERROR(EAGAIN) output is not available in this state - user must + * try to send new input + * @retval AVERROR_EOF the codec has been fully flushed, and there will be + * no more output frames + * @retval AVERROR(EINVAL) codec not opened, or it is an encoder without the + * 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); @@ -2667,16 +2666,16 @@ int avcodec_receive_frame(AVCodecContext *avctx, AVFrame *frame); * If it is not set, frame->nb_samples must be equal to * avctx->frame_size for all frames except the last. * The final frame may be smaller than avctx->frame_size. - * @return 0 on success, otherwise negative error code: - * AVERROR(EAGAIN): input is not accepted in the current state - user - * must read output with avcodec_receive_packet() (once - * all output is read, the packet should be resent, and - * the call will not fail with EAGAIN). - * AVERROR_EOF: the encoder has been flushed, and no new frames can - * be sent to it - * AVERROR(EINVAL): codec not opened, it is a decoder, or requires flush - * AVERROR(ENOMEM): failed to add packet to internal queue, or similar - * other errors: legitimate encoding errors + * @retval 0 success + * @retval AVERROR(EAGAIN) input is not accepted in the current state - user must + * read output with avcodec_receive_packet() (once all + * output is read, the packet should be resent, and the + * call will not fail with EAGAIN). + * @retval AVERROR_EOF the encoder has been flushed, and no new frames can + * be sent to it + * @retval AVERROR(EINVAL) codec not opened, it is a decoder, or requires flush + * @retval AVERROR(ENOMEM) failed to add packet to internal queue, or similar + * @retval "another negative error code" legitimate encoding errors */ int avcodec_send_frame(AVCodecContext *avctx, const AVFrame *frame); @@ -2687,13 +2686,13 @@ int avcodec_send_frame(AVCodecContext *avctx, const AVFrame *frame); * @param avpkt This will be set to a reference-counted packet allocated by the * encoder. Note that the function will always call * av_packet_unref(avpkt) before doing anything else. - * @return 0 on success, otherwise negative error code: - * AVERROR(EAGAIN): output is not available in the current state - user - * must try to send input - * AVERROR_EOF: the encoder has been fully flushed, and there will be - * no more output packets - * AVERROR(EINVAL): codec not opened, or it is a decoder - * other errors: legitimate encoding errors + * @retval 0 success + * @retval AVERROR(EAGAIN) output is not available in the current state - user must + * try to send input + * @retval AVERROR_EOF the encoder has been fully flushed, and there will be no + * more output packets + * @retval AVERROR(EINVAL) codec not opened, or it is a decoder + * @retval "another negative error code" legitimate encoding errors */ int avcodec_receive_packet(AVCodecContext *avctx, AVPacket *avpkt);