| 1 | /* |
| 2 | * pixel format descriptor |
| 3 | * Copyright (c) 2009 Michael Niedermayer <michaelni@gmx.at> |
| 4 | * |
| 5 | * This file is part of FFmpeg. |
| 6 | * |
| 7 | * FFmpeg is free software; you can redistribute it and/or |
| 8 | * modify it under the terms of the GNU Lesser General Public |
| 9 | * License as published by the Free Software Foundation; either |
| 10 | * version 2.1 of the License, or (at your option) any later version. |
| 11 | * |
| 12 | * FFmpeg is distributed in the hope that it will be useful, |
| 13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 15 | * Lesser General Public License for more details. |
| 16 | * |
| 17 | * You should have received a copy of the GNU Lesser General Public |
| 18 | * License along with FFmpeg; if not, write to the Free Software |
| 19 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
| 20 | */ |
| 21 | |
| 22 | #ifndef AVUTIL_PIXDESC_H |
| 23 | #define AVUTIL_PIXDESC_H |
| 24 | |
| 25 | #include <inttypes.h> |
| 26 | |
| 27 | #include "attributes.h" |
| 28 | #include "pixfmt.h" |
| 29 | |
| 30 | typedef struct AVComponentDescriptor { |
| 31 | /** |
| 32 | * Which of the 4 planes contains the component. |
| 33 | */ |
| 34 | uint16_t plane : 2; |
| 35 | |
| 36 | /** |
| 37 | * Number of elements between 2 horizontally consecutive pixels minus 1. |
| 38 | * Elements are bits for bitstream formats, bytes otherwise. |
| 39 | */ |
| 40 | uint16_t step_minus1 : 3; |
| 41 | |
| 42 | /** |
| 43 | * Number of elements before the component of the first pixel plus 1. |
| 44 | * Elements are bits for bitstream formats, bytes otherwise. |
| 45 | */ |
| 46 | uint16_t offset_plus1 : 3; |
| 47 | |
| 48 | /** |
| 49 | * Number of least significant bits that must be shifted away |
| 50 | * to get the value. |
| 51 | */ |
| 52 | uint16_t shift : 3; |
| 53 | |
| 54 | /** |
| 55 | * Number of bits in the component minus 1. |
| 56 | */ |
| 57 | uint16_t depth_minus1 : 4; |
| 58 | } AVComponentDescriptor; |
| 59 | |
| 60 | /** |
| 61 | * Descriptor that unambiguously describes how the bits of a pixel are |
| 62 | * stored in the up to 4 data planes of an image. It also stores the |
| 63 | * subsampling factors and number of components. |
| 64 | * |
| 65 | * @note This is separate of the colorspace (RGB, YCbCr, YPbPr, JPEG-style YUV |
| 66 | * and all the YUV variants) AVPixFmtDescriptor just stores how values |
| 67 | * are stored not what these values represent. |
| 68 | */ |
| 69 | typedef struct AVPixFmtDescriptor { |
| 70 | const char *name; |
| 71 | uint8_t nb_components; ///< The number of components each pixel has, (1-4) |
| 72 | |
| 73 | /** |
| 74 | * Amount to shift the luma width right to find the chroma width. |
| 75 | * For YV12 this is 1 for example. |
| 76 | * chroma_width = -((-luma_width) >> log2_chroma_w) |
| 77 | * The note above is needed to ensure rounding up. |
| 78 | * This value only refers to the chroma components. |
| 79 | */ |
| 80 | uint8_t log2_chroma_w; ///< chroma_width = -((-luma_width )>>log2_chroma_w) |
| 81 | |
| 82 | /** |
| 83 | * Amount to shift the luma height right to find the chroma height. |
| 84 | * For YV12 this is 1 for example. |
| 85 | * chroma_height= -((-luma_height) >> log2_chroma_h) |
| 86 | * The note above is needed to ensure rounding up. |
| 87 | * This value only refers to the chroma components. |
| 88 | */ |
| 89 | uint8_t log2_chroma_h; |
| 90 | uint8_t flags; |
| 91 | |
| 92 | /** |
| 93 | * Parameters that describe how pixels are packed. |
| 94 | * If the format has 2 or 4 components, then alpha is last. |
| 95 | * If the format has 1 or 2 components, then luma is 0. |
| 96 | * If the format has 3 or 4 components, |
| 97 | * if the RGB flag is set then 0 is red, 1 is green and 2 is blue; |
| 98 | * otherwise 0 is luma, 1 is chroma-U and 2 is chroma-V. |
| 99 | */ |
| 100 | AVComponentDescriptor comp[4]; |
| 101 | |
| 102 | /** |
| 103 | * Alternative comma-separated names. |
| 104 | */ |
| 105 | const char *alias; |
| 106 | } AVPixFmtDescriptor; |
| 107 | |
| 108 | /** |
| 109 | * Pixel format is big-endian. |
| 110 | */ |
| 111 | #define AV_PIX_FMT_FLAG_BE (1 << 0) |
| 112 | /** |
| 113 | * Pixel format has a palette in data[1], values are indexes in this palette. |
| 114 | */ |
| 115 | #define AV_PIX_FMT_FLAG_PAL (1 << 1) |
| 116 | /** |
| 117 | * All values of a component are bit-wise packed end to end. |
| 118 | */ |
| 119 | #define AV_PIX_FMT_FLAG_BITSTREAM (1 << 2) |
| 120 | /** |
| 121 | * Pixel format is an HW accelerated format. |
| 122 | */ |
| 123 | #define AV_PIX_FMT_FLAG_HWACCEL (1 << 3) |
| 124 | /** |
| 125 | * At least one pixel component is not in the first data plane. |
| 126 | */ |
| 127 | #define AV_PIX_FMT_FLAG_PLANAR (1 << 4) |
| 128 | /** |
| 129 | * The pixel format contains RGB-like data (as opposed to YUV/grayscale). |
| 130 | */ |
| 131 | #define AV_PIX_FMT_FLAG_RGB (1 << 5) |
| 132 | /** |
| 133 | * The pixel format is "pseudo-paletted". This means that FFmpeg treats it as |
| 134 | * paletted internally, but the palette is generated by the decoder and is not |
| 135 | * stored in the file. |
| 136 | */ |
| 137 | #define AV_PIX_FMT_FLAG_PSEUDOPAL (1 << 6) |
| 138 | /** |
| 139 | * The pixel format has an alpha channel. |
| 140 | */ |
| 141 | #define AV_PIX_FMT_FLAG_ALPHA (1 << 7) |
| 142 | |
| 143 | #if FF_API_PIX_FMT |
| 144 | /** |
| 145 | * @deprecated use the AV_PIX_FMT_FLAG_* flags |
| 146 | */ |
| 147 | #define PIX_FMT_BE AV_PIX_FMT_FLAG_BE |
| 148 | #define PIX_FMT_PAL AV_PIX_FMT_FLAG_PAL |
| 149 | #define PIX_FMT_BITSTREAM AV_PIX_FMT_FLAG_BITSTREAM |
| 150 | #define PIX_FMT_HWACCEL AV_PIX_FMT_FLAG_HWACCEL |
| 151 | #define PIX_FMT_PLANAR AV_PIX_FMT_FLAG_PLANAR |
| 152 | #define PIX_FMT_RGB AV_PIX_FMT_FLAG_RGB |
| 153 | #define PIX_FMT_PSEUDOPAL AV_PIX_FMT_FLAG_PSEUDOPAL |
| 154 | #define PIX_FMT_ALPHA AV_PIX_FMT_FLAG_ALPHA |
| 155 | #endif |
| 156 | |
| 157 | #if FF_API_PIX_FMT_DESC |
| 158 | /** |
| 159 | * The array of all the pixel format descriptors. |
| 160 | */ |
| 161 | extern attribute_deprecated const AVPixFmtDescriptor av_pix_fmt_descriptors[]; |
| 162 | #endif |
| 163 | |
| 164 | /** |
| 165 | * Read a line from an image, and write the values of the |
| 166 | * pixel format component c to dst. |
| 167 | * |
| 168 | * @param data the array containing the pointers to the planes of the image |
| 169 | * @param linesize the array containing the linesizes of the image |
| 170 | * @param desc the pixel format descriptor for the image |
| 171 | * @param x the horizontal coordinate of the first pixel to read |
| 172 | * @param y the vertical coordinate of the first pixel to read |
| 173 | * @param w the width of the line to read, that is the number of |
| 174 | * values to write to dst |
| 175 | * @param read_pal_component if not zero and the format is a paletted |
| 176 | * format writes the values corresponding to the palette |
| 177 | * component c in data[1] to dst, rather than the palette indexes in |
| 178 | * data[0]. The behavior is undefined if the format is not paletted. |
| 179 | */ |
| 180 | void av_read_image_line(uint16_t *dst, const uint8_t *data[4], |
| 181 | const int linesize[4], const AVPixFmtDescriptor *desc, |
| 182 | int x, int y, int c, int w, int read_pal_component); |
| 183 | |
| 184 | /** |
| 185 | * Write the values from src to the pixel format component c of an |
| 186 | * image line. |
| 187 | * |
| 188 | * @param src array containing the values to write |
| 189 | * @param data the array containing the pointers to the planes of the |
| 190 | * image to write into. It is supposed to be zeroed. |
| 191 | * @param linesize the array containing the linesizes of the image |
| 192 | * @param desc the pixel format descriptor for the image |
| 193 | * @param x the horizontal coordinate of the first pixel to write |
| 194 | * @param y the vertical coordinate of the first pixel to write |
| 195 | * @param w the width of the line to write, that is the number of |
| 196 | * values to write to the image line |
| 197 | */ |
| 198 | void av_write_image_line(const uint16_t *src, uint8_t *data[4], |
| 199 | const int linesize[4], const AVPixFmtDescriptor *desc, |
| 200 | int x, int y, int c, int w); |
| 201 | |
| 202 | /** |
| 203 | * Return the pixel format corresponding to name. |
| 204 | * |
| 205 | * If there is no pixel format with name name, then looks for a |
| 206 | * pixel format with the name corresponding to the native endian |
| 207 | * format of name. |
| 208 | * For example in a little-endian system, first looks for "gray16", |
| 209 | * then for "gray16le". |
| 210 | * |
| 211 | * Finally if no pixel format has been found, returns AV_PIX_FMT_NONE. |
| 212 | */ |
| 213 | enum AVPixelFormat av_get_pix_fmt(const char *name); |
| 214 | |
| 215 | /** |
| 216 | * Return the short name for a pixel format, NULL in case pix_fmt is |
| 217 | * unknown. |
| 218 | * |
| 219 | * @see av_get_pix_fmt(), av_get_pix_fmt_string() |
| 220 | */ |
| 221 | const char *av_get_pix_fmt_name(enum AVPixelFormat pix_fmt); |
| 222 | |
| 223 | /** |
| 224 | * Print in buf the string corresponding to the pixel format with |
| 225 | * number pix_fmt, or a header if pix_fmt is negative. |
| 226 | * |
| 227 | * @param buf the buffer where to write the string |
| 228 | * @param buf_size the size of buf |
| 229 | * @param pix_fmt the number of the pixel format to print the |
| 230 | * corresponding info string, or a negative value to print the |
| 231 | * corresponding header. |
| 232 | */ |
| 233 | char *av_get_pix_fmt_string(char *buf, int buf_size, |
| 234 | enum AVPixelFormat pix_fmt); |
| 235 | |
| 236 | /** |
| 237 | * Return the number of bits per pixel used by the pixel format |
| 238 | * described by pixdesc. Note that this is not the same as the number |
| 239 | * of bits per sample. |
| 240 | * |
| 241 | * The returned number of bits refers to the number of bits actually |
| 242 | * used for storing the pixel information, that is padding bits are |
| 243 | * not counted. |
| 244 | */ |
| 245 | int av_get_bits_per_pixel(const AVPixFmtDescriptor *pixdesc); |
| 246 | |
| 247 | /** |
| 248 | * Return the number of bits per pixel for the pixel format |
| 249 | * described by pixdesc, including any padding or unused bits. |
| 250 | */ |
| 251 | int av_get_padded_bits_per_pixel(const AVPixFmtDescriptor *pixdesc); |
| 252 | |
| 253 | /** |
| 254 | * @return a pixel format descriptor for provided pixel format or NULL if |
| 255 | * this pixel format is unknown. |
| 256 | */ |
| 257 | const AVPixFmtDescriptor *av_pix_fmt_desc_get(enum AVPixelFormat pix_fmt); |
| 258 | |
| 259 | /** |
| 260 | * Iterate over all pixel format descriptors known to libavutil. |
| 261 | * |
| 262 | * @param prev previous descriptor. NULL to get the first descriptor. |
| 263 | * |
| 264 | * @return next descriptor or NULL after the last descriptor |
| 265 | */ |
| 266 | const AVPixFmtDescriptor *av_pix_fmt_desc_next(const AVPixFmtDescriptor *prev); |
| 267 | |
| 268 | /** |
| 269 | * @return an AVPixelFormat id described by desc, or AV_PIX_FMT_NONE if desc |
| 270 | * is not a valid pointer to a pixel format descriptor. |
| 271 | */ |
| 272 | enum AVPixelFormat av_pix_fmt_desc_get_id(const AVPixFmtDescriptor *desc); |
| 273 | |
| 274 | /** |
| 275 | * Utility function to access log2_chroma_w log2_chroma_h from |
| 276 | * the pixel format AVPixFmtDescriptor. |
| 277 | * |
| 278 | * See av_get_chroma_sub_sample() for a function that asserts a |
| 279 | * valid pixel format instead of returning an error code. |
| 280 | * Its recommended that you use avcodec_get_chroma_sub_sample unless |
| 281 | * you do check the return code! |
| 282 | * |
| 283 | * @param[in] pix_fmt the pixel format |
| 284 | * @param[out] h_shift store log2_chroma_w |
| 285 | * @param[out] v_shift store log2_chroma_h |
| 286 | * |
| 287 | * @return 0 on success, AVERROR(ENOSYS) on invalid or unknown pixel format |
| 288 | */ |
| 289 | int av_pix_fmt_get_chroma_sub_sample(enum AVPixelFormat pix_fmt, |
| 290 | int *h_shift, int *v_shift); |
| 291 | |
| 292 | /** |
| 293 | * @return number of planes in pix_fmt, a negative AVERROR if pix_fmt is not a |
| 294 | * valid pixel format. |
| 295 | */ |
| 296 | int av_pix_fmt_count_planes(enum AVPixelFormat pix_fmt); |
| 297 | |
| 298 | void ff_check_pixfmt_descriptors(void); |
| 299 | |
| 300 | /** |
| 301 | * Utility function to swap the endianness of a pixel format. |
| 302 | * |
| 303 | * @param[in] pix_fmt the pixel format |
| 304 | * |
| 305 | * @return pixel format with swapped endianness if it exists, |
| 306 | * otherwise AV_PIX_FMT_NONE |
| 307 | */ |
| 308 | enum AVPixelFormat av_pix_fmt_swap_endianness(enum AVPixelFormat pix_fmt); |
| 309 | |
| 310 | #define FF_LOSS_RESOLUTION 0x0001 /**< loss due to resolution change */ |
| 311 | #define FF_LOSS_DEPTH 0x0002 /**< loss due to color depth change */ |
| 312 | #define FF_LOSS_COLORSPACE 0x0004 /**< loss due to color space conversion */ |
| 313 | #define FF_LOSS_ALPHA 0x0008 /**< loss of alpha bits */ |
| 314 | #define FF_LOSS_COLORQUANT 0x0010 /**< loss due to color quantization */ |
| 315 | #define FF_LOSS_CHROMA 0x0020 /**< loss of chroma (e.g. RGB to gray conversion) */ |
| 316 | |
| 317 | /** |
| 318 | * Compute what kind of losses will occur when converting from one specific |
| 319 | * pixel format to another. |
| 320 | * When converting from one pixel format to another, information loss may occur. |
| 321 | * For example, when converting from RGB24 to GRAY, the color information will |
| 322 | * be lost. Similarly, other losses occur when converting from some formats to |
| 323 | * other formats. These losses can involve loss of chroma, but also loss of |
| 324 | * resolution, loss of color depth, loss due to the color space conversion, loss |
| 325 | * of the alpha bits or loss due to color quantization. |
| 326 | * av_get_fix_fmt_loss() informs you about the various types of losses |
| 327 | * which will occur when converting from one pixel format to another. |
| 328 | * |
| 329 | * @param[in] dst_pix_fmt destination pixel format |
| 330 | * @param[in] src_pix_fmt source pixel format |
| 331 | * @param[in] has_alpha Whether the source pixel format alpha channel is used. |
| 332 | * @return Combination of flags informing you what kind of losses will occur |
| 333 | * (maximum loss for an invalid dst_pix_fmt). |
| 334 | */ |
| 335 | int av_get_pix_fmt_loss(enum AVPixelFormat dst_pix_fmt, |
| 336 | enum AVPixelFormat src_pix_fmt, |
| 337 | int has_alpha); |
| 338 | |
| 339 | /** |
| 340 | * Compute what kind of losses will occur when converting from one specific |
| 341 | * pixel format to another. |
| 342 | * When converting from one pixel format to another, information loss may occur. |
| 343 | * For example, when converting from RGB24 to GRAY, the color information will |
| 344 | * be lost. Similarly, other losses occur when converting from some formats to |
| 345 | * other formats. These losses can involve loss of chroma, but also loss of |
| 346 | * resolution, loss of color depth, loss due to the color space conversion, loss |
| 347 | * of the alpha bits or loss due to color quantization. |
| 348 | * av_get_fix_fmt_loss() informs you about the various types of losses |
| 349 | * which will occur when converting from one pixel format to another. |
| 350 | * |
| 351 | * @param[in] dst_pix_fmt destination pixel format |
| 352 | * @param[in] src_pix_fmt source pixel format |
| 353 | * @param[in] has_alpha Whether the source pixel format alpha channel is used. |
| 354 | * @return Combination of flags informing you what kind of losses will occur |
| 355 | * (maximum loss for an invalid dst_pix_fmt). |
| 356 | */ |
| 357 | enum AVPixelFormat av_find_best_pix_fmt_of_2(enum AVPixelFormat dst_pix_fmt1, enum AVPixelFormat dst_pix_fmt2, |
| 358 | enum AVPixelFormat src_pix_fmt, int has_alpha, int *loss_ptr); |
| 359 | |
| 360 | /** |
| 361 | * @return the name for provided color range or NULL if unknown. |
| 362 | */ |
| 363 | const char *av_color_range_name(enum AVColorRange range); |
| 364 | |
| 365 | /** |
| 366 | * @return the name for provided color primaries or NULL if unknown. |
| 367 | */ |
| 368 | const char *av_color_primaries_name(enum AVColorPrimaries primaries); |
| 369 | |
| 370 | /** |
| 371 | * @return the name for provided color transfer or NULL if unknown. |
| 372 | */ |
| 373 | const char *av_color_transfer_name(enum AVColorTransferCharacteristic transfer); |
| 374 | |
| 375 | /** |
| 376 | * @return the name for provided color space or NULL if unknown. |
| 377 | */ |
| 378 | const char *av_color_space_name(enum AVColorSpace space); |
| 379 | |
| 380 | /** |
| 381 | * @return the name for provided chroma location or NULL if unknown. |
| 382 | */ |
| 383 | const char *av_chroma_location_name(enum AVChromaLocation location); |
| 384 | |
| 385 | #endif /* AVUTIL_PIXDESC_H */ |