[FFmpeg-devel] [PATCH 1/1] avutil/frame: Document the possibility of negative line sizes

[Soft Works]

> -----Original Message-----
> From: ffmpeg-devel <ffmpeg-devel-bounces at ffmpeg.org> On Behalf Of
> Soft Works
> Sent: Thursday, September 30, 2021 5:31 AM
> To: ffmpeg-devel at ffmpeg.org
> Subject: [FFmpeg-devel] [PATCH 1/1] avutil/frame: Document the
> possibility of negative line sizes
> 
> Signed-off-by: softworkz <softworkz at hotmail.com>
> ---
>  libavutil/frame.h | 13 +++++++++++--
>  1 file changed, 11 insertions(+), 2 deletions(-)
> 
> diff --git a/libavutil/frame.h b/libavutil/frame.h
> index ff2540a20f..f07e690410 100644
> --- a/libavutil/frame.h
> +++ b/libavutil/frame.h
> @@ -304,7 +304,8 @@ typedef struct AVFrame {
>  #define AV_NUM_DATA_POINTERS 8
>      /**
>       * pointer to the picture/channel planes.
> -     * This might be different from the first allocated byte
> +     * This might be different from the first allocated byte. For
> video,
> +     * it could even point to the end of the image data.
>       *
>       * Some decoders access areas outside 0,0 - width,height, please
>       * see avcodec_align_dimensions2(). Some filters and swscale can
> read
> @@ -313,11 +314,16 @@ typedef struct AVFrame {
>       *
>       * NOTE: Except for hwaccel formats, pointers not needed by the
> format
>       * MUST be set to NULL.
> +     *
> +     * @attention In case of video, the data[] pointers can point to
> the
> +     * end of image data in order to reverse line order, when used
> in
> +     * combination with negative values in the linesize[] array.
>       */
>      uint8_t *data[AV_NUM_DATA_POINTERS];
> 
>      /**
> -     * For video, size in bytes of each picture line.
> +     * For video, a positive or negative value, the ABS() value of
> which is indicating
> +     * the size in bytes of each picture line.
>       * For audio, size in bytes of each plane.
>       *
>       * For audio, only linesize[0] may be set. For planar audio,
> each channel
> @@ -330,6 +336,9 @@ typedef struct AVFrame {
>       *
>       * @note The linesize may be larger than the size of usable data
> -- there
>       * may be extra padding present for performance reasons.
> +     *
> +     * @attention In case of video, line size values can be negative
> to achieve
> +     * a vertically inverted iteration over image lines.
>       */
>      int linesize[AV_NUM_DATA_POINTERS];
> 
> --

Any objections regarding this?

Thanks,
sw