libavutil/imgutils.h

   1 /*
   2  * This file is part of FFmpeg.
   3  *
   4  * FFmpeg is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2.1 of the License, or (at your option) any later version.
   8  *
   9  * FFmpeg is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with FFmpeg; if not, write to the Free Software
  16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  17  */
  18
  19 #ifndef AVUTIL_IMGUTILS_H
  20 #define AVUTIL_IMGUTILS_H
  21
  22 /**
  23  * @file
  24  * misc image utilities
  25  *
  26  * @addtogroup lavu_picture
  27  * @{
  28  */
  29
  30 #include <stddef.h>
  31 #include <stdint.h>
  32 #include "pixdesc.h"
  33 #include "pixfmt.h"
  34 #include "rational.h"
  35
  36 /**
  37  * Compute the max pixel step for each plane of an image with a
  38  * format described by pixdesc.
  39  *
  40  * The pixel step is the distance in bytes between the first byte of
  41  * the group of bytes which describe a pixel component and the first
  42  * byte of the successive group in the same plane for the same
  43  * component.
  44  *
  45  * @param max_pixsteps an array which is filled with the max pixel step
  46  * for each plane. Since a plane may contain different pixel
  47  * components, the computed max_pixsteps[plane] is relative to the
  48  * component in the plane with the max pixel step.
  49  * @param max_pixstep_comps an array which is filled with the component
  50  * for each plane which has the max pixel step. May be NULL.
  51  * @param pixdesc the AVPixFmtDescriptor for the image, describing its format
  52  */
  53 void av_image_fill_max_pixsteps(int max_pixsteps[4], int max_pixstep_comps[4],
  54                                 const AVPixFmtDescriptor *pixdesc);
  55
  56 /**
  57  * Compute the size of an image line with format pix_fmt and width
  58  * width for the plane plane.
  59  *
  60  * @return the computed size in bytes
  61  */
  62 int av_image_get_linesize(enum AVPixelFormat pix_fmt, int width, int plane);
  63
  64 /**
  65  * Fill plane linesizes for an image with pixel format pix_fmt and
  66  * width width.
  67  *
  68  * @param linesizes array to be filled with the linesize for each plane
  69  * @param pix_fmt the AVPixelFormat of the image
  70  * @param width width of the image in pixels
  71  * @return >= 0 in case of success, a negative error code otherwise
  72  */
  73 int av_image_fill_linesizes(int linesizes[4], enum AVPixelFormat pix_fmt, int width);
  74
  75 /**
  76  * Fill plane sizes for an image with pixel format pix_fmt and height height.
  77  *
  78  * @param size the array to be filled with the size of each image plane
  79  * @param pix_fmt the AVPixelFormat of the image
  80  * @param height height of the image in pixels
  81  * @param linesizes the array containing the linesize for each
  82  *        plane, should be filled by av_image_fill_linesizes()
  83  * @return >= 0 in case of success, a negative error code otherwise
  84  *
  85  * @note The linesize parameters have the type ptrdiff_t here, while they are
  86  *       int for av_image_fill_linesizes().
  87  */
  88 int av_image_fill_plane_sizes(size_t size[4], enum AVPixelFormat pix_fmt,
  89                               int height, const ptrdiff_t linesizes[4]);
  90
  91 /**
  92  * Fill plane data pointers for an image with pixel format pix_fmt and
  93  * height height.
  94  *
  95  * @param data pointers array to be filled with the pointer for each image plane
  96  * @param pix_fmt the AVPixelFormat of the image
  97  * @param height height of the image in pixels
  98  * @param ptr the pointer to a buffer which will contain the image
  99  * @param linesizes the array containing the linesize for each
 100  * plane, should be filled by av_image_fill_linesizes()
 101  * @return the size in bytes required for the image buffer, a negative
 102  * error code in case of failure
 103  */
 104 int av_image_fill_pointers(uint8_t *data[4], enum AVPixelFormat pix_fmt, int height,
 105                            uint8_t *ptr, const int linesizes[4]);
 106
 107 /**
 108  * Allocate an image with size w and h and pixel format pix_fmt, and
 109  * fill pointers and linesizes accordingly.
 110  * The allocated image buffer has to be freed by using
 111  * av_freep(&pointers[0]).
 112  *
 113  * @param pointers array to be filled with the pointer for each image plane
 114  * @param linesizes the array filled with the linesize for each plane
 115  * @param w width of the image in pixels
 116  * @param h height of the image in pixels
 117  * @param pix_fmt the AVPixelFormat of the image
 118  * @param align the value to use for buffer size alignment
 119  * @return the size in bytes required for the image buffer, a negative
 120  * error code in case of failure
 121  */
 122 int av_image_alloc(uint8_t *pointers[4], int linesizes[4],
 123                    int w, int h, enum AVPixelFormat pix_fmt, int align);
 124
 125 /**
 126  * Copy image plane from src to dst.
 127  * That is, copy "height" number of lines of "bytewidth" bytes each.
 128  * The first byte of each successive line is separated by *_linesize
 129  * bytes.
 130  *
 131  * bytewidth must be contained by both absolute values of dst_linesize
 132  * and src_linesize, otherwise the function behavior is undefined.
 133  *
 134  * @param dst          destination plane to copy to
 135  * @param dst_linesize linesize for the image plane in dst
 136  * @param src          source plane to copy from
 137  * @param src_linesize linesize for the image plane in src
 138  * @param height       height (number of lines) of the plane
 139  */
 140 void av_image_copy_plane(uint8_t       *dst, int dst_linesize,
 141                          const uint8_t *src, int src_linesize,
 142                          int bytewidth, int height);
 143
 144 /**
 145  * Copy image data located in uncacheable (e.g. GPU mapped) memory. Where
 146  * available, this function will use special functionality for reading from such
 147  * memory, which may result in greatly improved performance compared to plain
 148  * av_image_copy_plane().
 149  *
 150  * bytewidth must be contained by both absolute values of dst_linesize
 151  * and src_linesize, otherwise the function behavior is undefined.
 152  *
 153  * @note The linesize parameters have the type ptrdiff_t here, while they are
 154  *       int for av_image_copy_plane().
 155  * @note On x86, the linesizes currently need to be aligned to the cacheline
 156  *       size (i.e. 64) to get improved performance.
 157  */
 158 void av_image_copy_plane_uc_from(uint8_t       *dst, ptrdiff_t dst_linesize,
 159                                  const uint8_t *src, ptrdiff_t src_linesize,
 160                                  ptrdiff_t bytewidth, int height);
 161
 162 /**
 163  * Copy image in src_data to dst_data.
 164  *
 165  * @param dst_data      destination image data buffer to copy to
 166  * @param dst_linesizes linesizes for the image in dst_data
 167  * @param src_data      source image data buffer to copy from
 168  * @param src_linesizes linesizes for the image in src_data
 169  * @param pix_fmt       the AVPixelFormat of the image
 170  * @param width         width of the image in pixels
 171  * @param height        height of the image in pixels
 172  */
 173 void av_image_copy(uint8_t * const dst_data[4], const int dst_linesizes[4],
 174                    const uint8_t * const src_data[4], const int src_linesizes[4],
 175                    enum AVPixelFormat pix_fmt, int width, int height);
 176
 177 /**
 178  * Wrapper around av_image_copy() to workaround the limitation
 179  * that the conversion from uint8_t * const * to const uint8_t * const *
 180  * is not performed automatically in C.
 181  * @see av_image_copy()
 182  */
 183 static inline
 184 void av_image_copy2(uint8_t * const dst_data[4], const int dst_linesizes[4],
 185                     uint8_t * const src_data[4], const int src_linesizes[4],
 186                     enum AVPixelFormat pix_fmt, int width, int height)
 187 {
 188     av_image_copy(dst_data, dst_linesizes,
 189                   (const uint8_t * const *)src_data, src_linesizes,
 190                   pix_fmt, width, height);
 191 }
 192
 193 /**
 194  * Copy image data located in uncacheable (e.g. GPU mapped) memory. Where
 195  * available, this function will use special functionality for reading from such
 196  * memory, which may result in greatly improved performance compared to plain
 197  * av_image_copy().
 198  *
 199  * The data pointers and the linesizes must be aligned to the maximum required
 200  * by the CPU architecture.
 201  *
 202  * @note The linesize parameters have the type ptrdiff_t here, while they are
 203  *       int for av_image_copy().
 204  * @note On x86, the linesizes currently need to be aligned to the cacheline
 205  *       size (i.e. 64) to get improved performance.
 206  */
 207 void av_image_copy_uc_from(uint8_t * const dst_data[4],       const ptrdiff_t dst_linesizes[4],
 208                            const uint8_t * const src_data[4], const ptrdiff_t src_linesizes[4],
 209                            enum AVPixelFormat pix_fmt, int width, int height);
 210
 211 /**
 212  * Setup the data pointers and linesizes based on the specified image
 213  * parameters and the provided array.
 214  *
 215  * The fields of the given image are filled in by using the src
 216  * address which points to the image data buffer. Depending on the
 217  * specified pixel format, one or multiple image data pointers and
 218  * line sizes will be set.  If a planar format is specified, several
 219  * pointers will be set pointing to the different picture planes and
 220  * the line sizes of the different planes will be stored in the
 221  * lines_sizes array. Call with src == NULL to get the required
 222  * size for the src buffer.
 223  *
 224  * To allocate the buffer and fill in the dst_data and dst_linesize in
 225  * one call, use av_image_alloc().
 226  *
 227  * @param dst_data      data pointers to be filled in
 228  * @param dst_linesize  linesizes for the image in dst_data to be filled in
 229  * @param src           buffer which will contain or contains the actual image data, can be NULL
 230  * @param pix_fmt       the pixel format of the image
 231  * @param width         the width of the image in pixels
 232  * @param height        the height of the image in pixels
 233  * @param align         the value used in src for linesize alignment
 234  * @return the size in bytes required for src, a negative error code
 235  * in case of failure
 236  */
 237 int av_image_fill_arrays(uint8_t *dst_data[4], int dst_linesize[4],
 238                          const uint8_t *src,
 239                          enum AVPixelFormat pix_fmt, int width, int height, int align);
 240
 241 /**
 242  * Return the size in bytes of the amount of data required to store an
 243  * image with the given parameters.
 244  *
 245  * @param pix_fmt  the pixel format of the image
 246  * @param width    the width of the image in pixels
 247  * @param height   the height of the image in pixels
 248  * @param align    the assumed linesize alignment
 249  * @return the buffer size in bytes, a negative error code in case of failure
 250  */
 251 int av_image_get_buffer_size(enum AVPixelFormat pix_fmt, int width, int height, int align);
 252
 253 /**
 254  * Copy image data from an image into a buffer.
 255  *
 256  * av_image_get_buffer_size() can be used to compute the required size
 257  * for the buffer to fill.
 258  *
 259  * @param dst           a buffer into which picture data will be copied
 260  * @param dst_size      the size in bytes of dst
 261  * @param src_data      pointers containing the source image data
 262  * @param src_linesize  linesizes for the image in src_data
 263  * @param pix_fmt       the pixel format of the source image
 264  * @param width         the width of the source image in pixels
 265  * @param height        the height of the source image in pixels
 266  * @param align         the assumed linesize alignment for dst
 267  * @return the number of bytes written to dst, or a negative value
 268  * (error code) on error
 269  */
 270 int av_image_copy_to_buffer(uint8_t *dst, int dst_size,
 271                             const uint8_t * const src_data[4], const int src_linesize[4],
 272                             enum AVPixelFormat pix_fmt, int width, int height, int align);
 273
 274 /**
 275  * Check if the given dimension of an image is valid, meaning that all
 276  * bytes of the image can be addressed with a signed int.
 277  *
 278  * @param w the width of the picture
 279  * @param h the height of the picture
 280  * @param log_offset the offset to sum to the log level for logging with log_ctx
 281  * @param log_ctx the parent logging context, it may be NULL
 282  * @return >= 0 if valid, a negative error code otherwise
 283  */
 284 int av_image_check_size(unsigned int w, unsigned int h, int log_offset, void *log_ctx);
 285
 286 /**
 287  * Check if the given dimension of an image is valid, meaning that all
 288  * bytes of a plane of an image with the specified pix_fmt can be addressed
 289  * with a signed int.
 290  *
 291  * @param w the width of the picture
 292  * @param h the height of the picture
 293  * @param max_pixels the maximum number of pixels the user wants to accept
 294  * @param pix_fmt the pixel format, can be AV_PIX_FMT_NONE if unknown.
 295  * @param log_offset the offset to sum to the log level for logging with log_ctx
 296  * @param log_ctx the parent logging context, it may be NULL
 297  * @return >= 0 if valid, a negative error code otherwise
 298  */
 299 int av_image_check_size2(unsigned int w, unsigned int h, int64_t max_pixels, enum AVPixelFormat pix_fmt, int log_offset, void *log_ctx);
 300
 301 /**
 302  * Check if the given sample aspect ratio of an image is valid.
 303  *
 304  * It is considered invalid if the denominator is 0 or if applying the ratio
 305  * to the image size would make the smaller dimension less than 1. If the
 306  * sar numerator is 0, it is considered unknown and will return as valid.
 307  *
 308  * @param w width of the image
 309  * @param h height of the image
 310  * @param sar sample aspect ratio of the image
 311  * @return 0 if valid, a negative AVERROR code otherwise
 312  */
 313 int av_image_check_sar(unsigned int w, unsigned int h, AVRational sar);
 314
 315 /**
 316  * Overwrite the image data with black. This is suitable for filling a
 317  * sub-rectangle of an image, meaning the padding between the right most pixel
 318  * and the left most pixel on the next line will not be overwritten. For some
 319  * formats, the image size might be rounded up due to inherent alignment.
 320  *
 321  * If the pixel format has alpha, the alpha is cleared to opaque.
 322  *
 323  * This can return an error if the pixel format is not supported. Normally, all
 324  * non-hwaccel pixel formats should be supported.
 325  *
 326  * Passing NULL for dst_data is allowed. Then the function returns whether the
 327  * operation would have succeeded. (It can return an error if the pix_fmt is
 328  * not supported.)
 329  *
 330  * @param dst_data      data pointers to destination image
 331  * @param dst_linesize  linesizes for the destination image
 332  * @param pix_fmt       the pixel format of the image
 333  * @param range         the color range of the image (important for colorspaces such as YUV)
 334  * @param width         the width of the image in pixels
 335  * @param height        the height of the image in pixels
 336  * @return 0 if the image data was cleared, a negative AVERROR code otherwise
 337  */
 338 int av_image_fill_black(uint8_t * const dst_data[4], const ptrdiff_t dst_linesize[4],
 339                         enum AVPixelFormat pix_fmt, enum AVColorRange range,
 340                         int width, int height);
 341
 342 /**
 343  * Overwrite the image data with a color. This is suitable for filling a
 344  * sub-rectangle of an image, meaning the padding between the right most pixel
 345  * and the left most pixel on the next line will not be overwritten. For some
 346  * formats, the image size might be rounded up due to inherent alignment.
 347  *
 348  * If the pixel format has alpha, it is also replaced. Color component values
 349  * are interpreted as native integers (or intfloats) regardless of actual pixel
 350  * format endianness.
 351  *
 352  * This can return an error if the pixel format is not supported. Normally, all
 353  * non-hwaccel pixel formats should be supported.
 354  *
 355  * Passing NULL for dst_data is allowed. Then the function returns whether the
 356  * operation would have succeeded. (It can return an error if the pix_fmt is
 357  * not supported.)
 358  *
 359  * @param dst_data      data pointers to destination image
 360  * @param dst_linesize  linesizes for the destination image
 361  * @param pix_fmt       the pixel format of the image
 362  * @param color         the color components to be used for the fill
 363  * @param width         the width of the image in pixels
 364  * @param height        the height of the image in pixels
 365  * @param flags         currently unused
 366  * @return 0 if the image data was filled, a negative AVERROR code otherwise
 367  */
 368 int av_image_fill_color(uint8_t * const dst_data[4], const ptrdiff_t dst_linesize[4],
 369                         enum AVPixelFormat pix_fmt, const uint32_t color[4],
 370                         int width, int height, int flags);
 371
 372 /**
 373  * @}
 374  */
 375
 376
 377 #endif /* AVUTIL_IMGUTILS_H */