Commit | Line | Data |
---|---|---|
2ba45a60 DM |
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 | #endif /* AVUTIL_PIXDESC_H */ |