imgutils.h (16326B)
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 */