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 | /** |
20 | * @file |
21 | * @ingroup lavu_frame |
22 | * reference-counted frame API |
23 | */ |
24 | |
25 | #ifndef AVUTIL_FRAME_H |
26 | #define AVUTIL_FRAME_H |
27 | |
28 | #include <stddef.h> |
29 | #include <stdint.h> |
30 | |
31 | #include "avutil.h" |
32 | #include "buffer.h" |
33 | #include "channel_layout.h" |
34 | #include "dict.h" |
35 | #include "rational.h" |
36 | #include "samplefmt.h" |
37 | #include "pixfmt.h" |
38 | #include "version.h" |
39 | |
40 | |
41 | /** |
42 | * @defgroup lavu_frame AVFrame |
43 | * @ingroup lavu_data |
44 | * |
45 | * @{ |
46 | * AVFrame is an abstraction for reference-counted raw multimedia data. |
47 | */ |
48 | |
49 | enum AVFrameSideDataType { |
50 | /** |
51 | * The data is the AVPanScan struct defined in libavcodec. |
52 | */ |
53 | AV_FRAME_DATA_PANSCAN, |
54 | /** |
55 | * ATSC A53 Part 4 Closed Captions. |
56 | * A53 CC bitstream is stored as uint8_t in AVFrameSideData.data. |
57 | * The number of bytes of CC data is AVFrameSideData.size. |
58 | */ |
59 | AV_FRAME_DATA_A53_CC, |
60 | /** |
61 | * Stereoscopic 3d metadata. |
62 | * The data is the AVStereo3D struct defined in libavutil/stereo3d.h. |
63 | */ |
64 | AV_FRAME_DATA_STEREO3D, |
65 | /** |
66 | * The data is the AVMatrixEncoding enum defined in libavutil/channel_layout.h. |
67 | */ |
68 | AV_FRAME_DATA_MATRIXENCODING, |
69 | /** |
70 | * Metadata relevant to a downmix procedure. |
71 | * The data is the AVDownmixInfo struct defined in libavutil/downmix_info.h. |
72 | */ |
73 | AV_FRAME_DATA_DOWNMIX_INFO, |
74 | /** |
75 | * ReplayGain information in the form of the AVReplayGain struct. |
76 | */ |
77 | AV_FRAME_DATA_REPLAYGAIN, |
78 | /** |
79 | * This side data contains a 3x3 transformation matrix describing an affine |
80 | * transformation that needs to be applied to the frame for correct |
81 | * presentation. |
82 | * |
83 | * See libavutil/display.h for a detailed description of the data. |
84 | */ |
85 | AV_FRAME_DATA_DISPLAYMATRIX, |
86 | /** |
87 | * Active Format Description data consisting of a single byte as specified |
88 | * in ETSI TS 101 154 using AVActiveFormatDescription enum. |
89 | */ |
90 | AV_FRAME_DATA_AFD, |
91 | /** |
92 | * Motion vectors exported by some codecs (on demand through the export_mvs |
93 | * flag set in the libavcodec AVCodecContext flags2 option). |
94 | * The data is the AVMotionVector struct defined in |
95 | * libavutil/motion_vector.h. |
96 | */ |
97 | AV_FRAME_DATA_MOTION_VECTORS, |
98 | /** |
99 | * Recommmends skipping the specified number of samples. This is exported |
100 | * only if the "skip_manual" AVOption is set in libavcodec. |
101 | * This has the same format as AV_PKT_DATA_SKIP_SAMPLES. |
102 | * @code |
103 | * u32le number of samples to skip from start of this packet |
104 | * u32le number of samples to skip from end of this packet |
105 | * u8 reason for start skip |
106 | * u8 reason for end skip (0=padding silence, 1=convergence) |
107 | * @endcode |
108 | */ |
109 | AV_FRAME_DATA_SKIP_SAMPLES, |
110 | /** |
111 | * This side data must be associated with an audio frame and corresponds to |
112 | * enum AVAudioServiceType defined in avcodec.h. |
113 | */ |
114 | AV_FRAME_DATA_AUDIO_SERVICE_TYPE, |
115 | /** |
116 | * Mastering display metadata associated with a video frame. The payload is |
117 | * an AVMasteringDisplayMetadata type and contains information about the |
118 | * mastering display color volume. |
119 | */ |
120 | AV_FRAME_DATA_MASTERING_DISPLAY_METADATA, |
121 | /** |
122 | * The GOP timecode in 25 bit timecode format. Data format is 64-bit integer. |
123 | * This is set on the first frame of a GOP that has a temporal reference of 0. |
124 | */ |
125 | AV_FRAME_DATA_GOP_TIMECODE, |
126 | |
127 | /** |
128 | * The data represents the AVSphericalMapping structure defined in |
129 | * libavutil/spherical.h. |
130 | */ |
131 | AV_FRAME_DATA_SPHERICAL, |
132 | |
133 | /** |
134 | * Content light level (based on CTA-861.3). This payload contains data in |
135 | * the form of the AVContentLightMetadata struct. |
136 | */ |
137 | AV_FRAME_DATA_CONTENT_LIGHT_LEVEL, |
138 | |
139 | /** |
140 | * The data contains an ICC profile as an opaque octet buffer following the |
141 | * format described by ISO 15076-1 with an optional name defined in the |
142 | * metadata key entry "name". |
143 | */ |
144 | AV_FRAME_DATA_ICC_PROFILE, |
145 | |
146 | /** |
147 | * Timecode which conforms to SMPTE ST 12-1. The data is an array of 4 uint32_t |
148 | * where the first uint32_t describes how many (1-3) of the other timecodes are used. |
149 | * The timecode format is described in the documentation of av_timecode_get_smpte_from_framenum() |
150 | * function in libavutil/timecode.h. |
151 | */ |
152 | AV_FRAME_DATA_S12M_TIMECODE, |
153 | |
154 | /** |
155 | * HDR dynamic metadata associated with a video frame. The payload is |
156 | * an AVDynamicHDRPlus type and contains information for color |
157 | * volume transform - application 4 of SMPTE 2094-40:2016 standard. |
158 | */ |
159 | AV_FRAME_DATA_DYNAMIC_HDR_PLUS, |
160 | |
161 | /** |
162 | * Regions Of Interest, the data is an array of AVRegionOfInterest type, the number of |
163 | * array element is implied by AVFrameSideData.size / AVRegionOfInterest.self_size. |
164 | */ |
165 | AV_FRAME_DATA_REGIONS_OF_INTEREST, |
166 | |
167 | /** |
168 | * Encoding parameters for a video frame, as described by AVVideoEncParams. |
169 | */ |
170 | AV_FRAME_DATA_VIDEO_ENC_PARAMS, |
171 | |
172 | /** |
173 | * User data unregistered metadata associated with a video frame. |
174 | * This is the H.26[45] UDU SEI message, and shouldn't be used for any other purpose |
175 | * The data is stored as uint8_t in AVFrameSideData.data which is 16 bytes of |
176 | * uuid_iso_iec_11578 followed by AVFrameSideData.size - 16 bytes of user_data_payload_byte. |
177 | */ |
178 | AV_FRAME_DATA_SEI_UNREGISTERED, |
179 | |
180 | /** |
181 | * Film grain parameters for a frame, described by AVFilmGrainParams. |
182 | * Must be present for every frame which should have film grain applied. |
183 | */ |
184 | AV_FRAME_DATA_FILM_GRAIN_PARAMS, |
185 | |
186 | /** |
187 | * Bounding boxes for object detection and classification, |
188 | * as described by AVDetectionBBoxHeader. |
189 | */ |
190 | AV_FRAME_DATA_DETECTION_BBOXES, |
191 | |
192 | /** |
193 | * Dolby Vision RPU raw data, suitable for passing to x265 |
194 | * or other libraries. Array of uint8_t, with NAL emulation |
195 | * bytes intact. |
196 | */ |
197 | AV_FRAME_DATA_DOVI_RPU_BUFFER, |
198 | |
199 | /** |
200 | * Parsed Dolby Vision metadata, suitable for passing to a software |
201 | * implementation. The payload is the AVDOVIMetadata struct defined in |
202 | * libavutil/dovi_meta.h. |
203 | */ |
204 | AV_FRAME_DATA_DOVI_METADATA, |
205 | |
206 | /** |
207 | * HDR Vivid dynamic metadata associated with a video frame. The payload is |
208 | * an AVDynamicHDRVivid type and contains information for color |
209 | * volume transform - CUVA 005.1-2021. |
210 | */ |
211 | AV_FRAME_DATA_DYNAMIC_HDR_VIVID, |
212 | |
213 | /** |
214 | * Ambient viewing environment metadata, as defined by H.274. |
215 | */ |
216 | AV_FRAME_DATA_AMBIENT_VIEWING_ENVIRONMENT, |
217 | |
218 | /** |
219 | * Provide encoder-specific hinting information about changed/unchanged |
220 | * portions of a frame. It can be used to pass information about which |
221 | * macroblocks can be skipped because they didn't change from the |
222 | * corresponding ones in the previous frame. This could be useful for |
223 | * applications which know this information in advance to speed up |
224 | * encoding. |
225 | */ |
226 | AV_FRAME_DATA_VIDEO_HINT, |
227 | }; |
228 | |
229 | enum AVActiveFormatDescription { |
230 | AV_AFD_SAME = 8, |
231 | AV_AFD_4_3 = 9, |
232 | AV_AFD_16_9 = 10, |
233 | AV_AFD_14_9 = 11, |
234 | AV_AFD_4_3_SP_14_9 = 13, |
235 | AV_AFD_16_9_SP_14_9 = 14, |
236 | AV_AFD_SP_4_3 = 15, |
237 | }; |
238 | |
239 | |
240 | /** |
241 | * Structure to hold side data for an AVFrame. |
242 | * |
243 | * sizeof(AVFrameSideData) is not a part of the public ABI, so new fields may be added |
244 | * to the end with a minor bump. |
245 | */ |
246 | typedef struct AVFrameSideData { |
247 | enum AVFrameSideDataType type; |
248 | uint8_t *data; |
249 | size_t size; |
250 | AVDictionary *metadata; |
251 | AVBufferRef *buf; |
252 | } AVFrameSideData; |
253 | |
254 | /** |
255 | * Structure describing a single Region Of Interest. |
256 | * |
257 | * When multiple regions are defined in a single side-data block, they |
258 | * should be ordered from most to least important - some encoders are only |
259 | * capable of supporting a limited number of distinct regions, so will have |
260 | * to truncate the list. |
261 | * |
262 | * When overlapping regions are defined, the first region containing a given |
263 | * area of the frame applies. |
264 | */ |
265 | typedef struct AVRegionOfInterest { |
266 | /** |
267 | * Must be set to the size of this data structure (that is, |
268 | * sizeof(AVRegionOfInterest)). |
269 | */ |
270 | uint32_t self_size; |
271 | /** |
272 | * Distance in pixels from the top edge of the frame to the top and |
273 | * bottom edges and from the left edge of the frame to the left and |
274 | * right edges of the rectangle defining this region of interest. |
275 | * |
276 | * The constraints on a region are encoder dependent, so the region |
277 | * actually affected may be slightly larger for alignment or other |
278 | * reasons. |
279 | */ |
280 | int top; |
281 | int bottom; |
282 | int left; |
283 | int right; |
284 | /** |
285 | * Quantisation offset. |
286 | * |
287 | * Must be in the range -1 to +1. A value of zero indicates no quality |
288 | * change. A negative value asks for better quality (less quantisation), |
289 | * while a positive value asks for worse quality (greater quantisation). |
290 | * |
291 | * The range is calibrated so that the extreme values indicate the |
292 | * largest possible offset - if the rest of the frame is encoded with the |
293 | * worst possible quality, an offset of -1 indicates that this region |
294 | * should be encoded with the best possible quality anyway. Intermediate |
295 | * values are then interpolated in some codec-dependent way. |
296 | * |
297 | * For example, in 10-bit H.264 the quantisation parameter varies between |
298 | * -12 and 51. A typical qoffset value of -1/10 therefore indicates that |
299 | * this region should be encoded with a QP around one-tenth of the full |
300 | * range better than the rest of the frame. So, if most of the frame |
301 | * were to be encoded with a QP of around 30, this region would get a QP |
302 | * of around 24 (an offset of approximately -1/10 * (51 - -12) = -6.3). |
303 | * An extreme value of -1 would indicate that this region should be |
304 | * encoded with the best possible quality regardless of the treatment of |
305 | * the rest of the frame - that is, should be encoded at a QP of -12. |
306 | */ |
307 | AVRational qoffset; |
308 | } AVRegionOfInterest; |
309 | |
310 | /** |
311 | * This structure describes decoded (raw) audio or video data. |
312 | * |
313 | * AVFrame must be allocated using av_frame_alloc(). Note that this only |
314 | * allocates the AVFrame itself, the buffers for the data must be managed |
315 | * through other means (see below). |
316 | * AVFrame must be freed with av_frame_free(). |
317 | * |
318 | * AVFrame is typically allocated once and then reused multiple times to hold |
319 | * different data (e.g. a single AVFrame to hold frames received from a |
320 | * decoder). In such a case, av_frame_unref() will free any references held by |
321 | * the frame and reset it to its original clean state before it |
322 | * is reused again. |
323 | * |
324 | * The data described by an AVFrame is usually reference counted through the |
325 | * AVBuffer API. The underlying buffer references are stored in AVFrame.buf / |
326 | * AVFrame.extended_buf. An AVFrame is considered to be reference counted if at |
327 | * least one reference is set, i.e. if AVFrame.buf[0] != NULL. In such a case, |
328 | * every single data plane must be contained in one of the buffers in |
329 | * AVFrame.buf or AVFrame.extended_buf. |
330 | * There may be a single buffer for all the data, or one separate buffer for |
331 | * each plane, or anything in between. |
332 | * |
333 | * sizeof(AVFrame) is not a part of the public ABI, so new fields may be added |
334 | * to the end with a minor bump. |
335 | * |
336 | * Fields can be accessed through AVOptions, the name string used, matches the |
337 | * C structure field name for fields accessible through AVOptions. The AVClass |
338 | * for AVFrame can be obtained from avcodec_get_frame_class() |
339 | */ |
340 | typedef struct AVFrame { |
341 | #define AV_NUM_DATA_POINTERS 8 |
342 | /** |
343 | * pointer to the picture/channel planes. |
344 | * This might be different from the first allocated byte. For video, |
345 | * it could even point to the end of the image data. |
346 | * |
347 | * All pointers in data and extended_data must point into one of the |
348 | * AVBufferRef in buf or extended_buf. |
349 | * |
350 | * Some decoders access areas outside 0,0 - width,height, please |
351 | * see avcodec_align_dimensions2(). Some filters and swscale can read |
352 | * up to 16 bytes beyond the planes, if these filters are to be used, |
353 | * then 16 extra bytes must be allocated. |
354 | * |
355 | * NOTE: Pointers not needed by the format MUST be set to NULL. |
356 | * |
357 | * @attention In case of video, the data[] pointers can point to the |
358 | * end of image data in order to reverse line order, when used in |
359 | * combination with negative values in the linesize[] array. |
360 | */ |
361 | uint8_t *data[AV_NUM_DATA_POINTERS]; |
362 | |
363 | /** |
364 | * For video, a positive or negative value, which is typically indicating |
365 | * the size in bytes of each picture line, but it can also be: |
366 | * - the negative byte size of lines for vertical flipping |
367 | * (with data[n] pointing to the end of the data |
368 | * - a positive or negative multiple of the byte size as for accessing |
369 | * even and odd fields of a frame (possibly flipped) |
370 | * |
371 | * For audio, only linesize[0] may be set. For planar audio, each channel |
372 | * plane must be the same size. |
373 | * |
374 | * For video the linesizes should be multiples of the CPUs alignment |
375 | * preference, this is 16 or 32 for modern desktop CPUs. |
376 | * Some code requires such alignment other code can be slower without |
377 | * correct alignment, for yet other it makes no difference. |
378 | * |
379 | * @note The linesize may be larger than the size of usable data -- there |
380 | * may be extra padding present for performance reasons. |
381 | * |
382 | * @attention In case of video, line size values can be negative to achieve |
383 | * a vertically inverted iteration over image lines. |
384 | */ |
385 | int linesize[AV_NUM_DATA_POINTERS]; |
386 | |
387 | /** |
388 | * pointers to the data planes/channels. |
389 | * |
390 | * For video, this should simply point to data[]. |
391 | * |
392 | * For planar audio, each channel has a separate data pointer, and |
393 | * linesize[0] contains the size of each channel buffer. |
394 | * For packed audio, there is just one data pointer, and linesize[0] |
395 | * contains the total size of the buffer for all channels. |
396 | * |
397 | * Note: Both data and extended_data should always be set in a valid frame, |
398 | * but for planar audio with more channels that can fit in data, |
399 | * extended_data must be used in order to access all channels. |
400 | */ |
401 | uint8_t **extended_data; |
402 | |
403 | /** |
404 | * @name Video dimensions |
405 | * Video frames only. The coded dimensions (in pixels) of the video frame, |
406 | * i.e. the size of the rectangle that contains some well-defined values. |
407 | * |
408 | * @note The part of the frame intended for display/presentation is further |
409 | * restricted by the @ref cropping "Cropping rectangle". |
410 | * @{ |
411 | */ |
412 | int width, height; |
413 | /** |
414 | * @} |
415 | */ |
416 | |
417 | /** |
418 | * number of audio samples (per channel) described by this frame |
419 | */ |
420 | int nb_samples; |
421 | |
422 | /** |
423 | * format of the frame, -1 if unknown or unset |
424 | * Values correspond to enum AVPixelFormat for video frames, |
425 | * enum AVSampleFormat for audio) |
426 | */ |
427 | int format; |
428 | |
429 | #if FF_API_FRAME_KEY |
430 | /** |
431 | * 1 -> keyframe, 0-> not |
432 | * |
433 | * @deprecated Use AV_FRAME_FLAG_KEY instead |
434 | */ |
435 | attribute_deprecated |
436 | int key_frame; |
437 | #endif |
438 | |
439 | /** |
440 | * Picture type of the frame. |
441 | */ |
442 | enum AVPictureType pict_type; |
443 | |
444 | /** |
445 | * Sample aspect ratio for the video frame, 0/1 if unknown/unspecified. |
446 | */ |
447 | AVRational sample_aspect_ratio; |
448 | |
449 | /** |
450 | * Presentation timestamp in time_base units (time when frame should be shown to user). |
451 | */ |
452 | int64_t pts; |
453 | |
454 | /** |
455 | * DTS copied from the AVPacket that triggered returning this frame. (if frame threading isn't used) |
456 | * This is also the Presentation time of this AVFrame calculated from |
457 | * only AVPacket.dts values without pts values. |
458 | */ |
459 | int64_t pkt_dts; |
460 | |
461 | /** |
462 | * Time base for the timestamps in this frame. |
463 | * In the future, this field may be set on frames output by decoders or |
464 | * filters, but its value will be by default ignored on input to encoders |
465 | * or filters. |
466 | */ |
467 | AVRational time_base; |
468 | |
469 | #if FF_API_FRAME_PICTURE_NUMBER |
470 | /** |
471 | * picture number in bitstream order |
472 | */ |
473 | attribute_deprecated |
474 | int coded_picture_number; |
475 | /** |
476 | * picture number in display order |
477 | */ |
478 | attribute_deprecated |
479 | int display_picture_number; |
480 | #endif |
481 | |
482 | /** |
483 | * quality (between 1 (good) and FF_LAMBDA_MAX (bad)) |
484 | */ |
485 | int quality; |
486 | |
487 | /** |
488 | * Frame owner's private data. |
489 | * |
490 | * This field may be set by the code that allocates/owns the frame data. |
491 | * It is then not touched by any library functions, except: |
492 | * - it is copied to other references by av_frame_copy_props() (and hence by |
493 | * av_frame_ref()); |
494 | * - it is set to NULL when the frame is cleared by av_frame_unref() |
495 | * - on the caller's explicit request. E.g. libavcodec encoders/decoders |
496 | * will copy this field to/from @ref AVPacket "AVPackets" if the caller sets |
497 | * @ref AV_CODEC_FLAG_COPY_OPAQUE. |
498 | * |
499 | * @see opaque_ref the reference-counted analogue |
500 | */ |
501 | void *opaque; |
502 | |
503 | /** |
504 | * Number of fields in this frame which should be repeated, i.e. the total |
505 | * duration of this frame should be repeat_pict + 2 normal field durations. |
506 | * |
507 | * For interlaced frames this field may be set to 1, which signals that this |
508 | * frame should be presented as 3 fields: beginning with the first field (as |
509 | * determined by AV_FRAME_FLAG_TOP_FIELD_FIRST being set or not), followed |
510 | * by the second field, and then the first field again. |
511 | * |
512 | * For progressive frames this field may be set to a multiple of 2, which |
513 | * signals that this frame's duration should be (repeat_pict + 2) / 2 |
514 | * normal frame durations. |
515 | * |
516 | * @note This field is computed from MPEG2 repeat_first_field flag and its |
517 | * associated flags, H.264 pic_struct from picture timing SEI, and |
518 | * their analogues in other codecs. Typically it should only be used when |
519 | * higher-layer timing information is not available. |
520 | */ |
521 | int repeat_pict; |
522 | |
523 | #if FF_API_INTERLACED_FRAME |
524 | /** |
525 | * The content of the picture is interlaced. |
526 | * |
527 | * @deprecated Use AV_FRAME_FLAG_INTERLACED instead |
528 | */ |
529 | attribute_deprecated |
530 | int interlaced_frame; |
531 | |
532 | /** |
533 | * If the content is interlaced, is top field displayed first. |
534 | * |
535 | * @deprecated Use AV_FRAME_FLAG_TOP_FIELD_FIRST instead |
536 | */ |
537 | attribute_deprecated |
538 | int top_field_first; |
539 | #endif |
540 | |
541 | #if FF_API_PALETTE_HAS_CHANGED |
542 | /** |
543 | * Tell user application that palette has changed from previous frame. |
544 | */ |
545 | attribute_deprecated |
546 | int palette_has_changed; |
547 | #endif |
548 | |
549 | #if FF_API_REORDERED_OPAQUE |
550 | /** |
551 | * reordered opaque 64 bits (generally an integer or a double precision float |
552 | * PTS but can be anything). |
553 | * The user sets AVCodecContext.reordered_opaque to represent the input at |
554 | * that time, |
555 | * the decoder reorders values as needed and sets AVFrame.reordered_opaque |
556 | * to exactly one of the values provided by the user through AVCodecContext.reordered_opaque |
557 | * |
558 | * @deprecated Use AV_CODEC_FLAG_COPY_OPAQUE instead |
559 | */ |
560 | attribute_deprecated |
561 | int64_t reordered_opaque; |
562 | #endif |
563 | |
564 | /** |
565 | * Sample rate of the audio data. |
566 | */ |
567 | int sample_rate; |
568 | |
569 | #if FF_API_OLD_CHANNEL_LAYOUT |
570 | /** |
571 | * Channel layout of the audio data. |
572 | * @deprecated use ch_layout instead |
573 | */ |
574 | attribute_deprecated |
575 | uint64_t channel_layout; |
576 | #endif |
577 | |
578 | /** |
579 | * AVBuffer references backing the data for this frame. All the pointers in |
580 | * data and extended_data must point inside one of the buffers in buf or |
581 | * extended_buf. This array must be filled contiguously -- if buf[i] is |
582 | * non-NULL then buf[j] must also be non-NULL for all j < i. |
583 | * |
584 | * There may be at most one AVBuffer per data plane, so for video this array |
585 | * always contains all the references. For planar audio with more than |
586 | * AV_NUM_DATA_POINTERS channels, there may be more buffers than can fit in |
587 | * this array. Then the extra AVBufferRef pointers are stored in the |
588 | * extended_buf array. |
589 | */ |
590 | AVBufferRef *buf[AV_NUM_DATA_POINTERS]; |
591 | |
592 | /** |
593 | * For planar audio which requires more than AV_NUM_DATA_POINTERS |
594 | * AVBufferRef pointers, this array will hold all the references which |
595 | * cannot fit into AVFrame.buf. |
596 | * |
597 | * Note that this is different from AVFrame.extended_data, which always |
598 | * contains all the pointers. This array only contains the extra pointers, |
599 | * which cannot fit into AVFrame.buf. |
600 | * |
601 | * This array is always allocated using av_malloc() by whoever constructs |
602 | * the frame. It is freed in av_frame_unref(). |
603 | */ |
604 | AVBufferRef **extended_buf; |
605 | /** |
606 | * Number of elements in extended_buf. |
607 | */ |
608 | int nb_extended_buf; |
609 | |
610 | AVFrameSideData **side_data; |
611 | int nb_side_data; |
612 | |
613 | /** |
614 | * @defgroup lavu_frame_flags AV_FRAME_FLAGS |
615 | * @ingroup lavu_frame |
616 | * Flags describing additional frame properties. |
617 | * |
618 | * @{ |
619 | */ |
620 | |
621 | /** |
622 | * The frame data may be corrupted, e.g. due to decoding errors. |
623 | */ |
624 | #define AV_FRAME_FLAG_CORRUPT (1 << 0) |
625 | /** |
626 | * A flag to mark frames that are keyframes. |
627 | */ |
628 | #define AV_FRAME_FLAG_KEY (1 << 1) |
629 | /** |
630 | * A flag to mark the frames which need to be decoded, but shouldn't be output. |
631 | */ |
632 | #define AV_FRAME_FLAG_DISCARD (1 << 2) |
633 | /** |
634 | * A flag to mark frames whose content is interlaced. |
635 | */ |
636 | #define AV_FRAME_FLAG_INTERLACED (1 << 3) |
637 | /** |
638 | * A flag to mark frames where the top field is displayed first if the content |
639 | * is interlaced. |
640 | */ |
641 | #define AV_FRAME_FLAG_TOP_FIELD_FIRST (1 << 4) |
642 | /** |
643 | * @} |
644 | */ |
645 | |
646 | /** |
647 | * Frame flags, a combination of @ref lavu_frame_flags |
648 | */ |
649 | int flags; |
650 | |
651 | /** |
652 | * MPEG vs JPEG YUV range. |
653 | * - encoding: Set by user |
654 | * - decoding: Set by libavcodec |
655 | */ |
656 | enum AVColorRange color_range; |
657 | |
658 | enum AVColorPrimaries color_primaries; |
659 | |
660 | enum AVColorTransferCharacteristic color_trc; |
661 | |
662 | /** |
663 | * YUV colorspace type. |
664 | * - encoding: Set by user |
665 | * - decoding: Set by libavcodec |
666 | */ |
667 | enum AVColorSpace colorspace; |
668 | |
669 | enum AVChromaLocation chroma_location; |
670 | |
671 | /** |
672 | * frame timestamp estimated using various heuristics, in stream time base |
673 | * - encoding: unused |
674 | * - decoding: set by libavcodec, read by user. |
675 | */ |
676 | int64_t best_effort_timestamp; |
677 | |
678 | #if FF_API_FRAME_PKT |
679 | /** |
680 | * reordered pos from the last AVPacket that has been input into the decoder |
681 | * - encoding: unused |
682 | * - decoding: Read by user. |
683 | * @deprecated use AV_CODEC_FLAG_COPY_OPAQUE to pass through arbitrary user |
684 | * data from packets to frames |
685 | */ |
686 | attribute_deprecated |
687 | int64_t pkt_pos; |
688 | #endif |
689 | |
690 | #if FF_API_PKT_DURATION |
691 | /** |
692 | * duration of the corresponding packet, expressed in |
693 | * AVStream->time_base units, 0 if unknown. |
694 | * - encoding: unused |
695 | * - decoding: Read by user. |
696 | * |
697 | * @deprecated use duration instead |
698 | */ |
699 | attribute_deprecated |
700 | int64_t pkt_duration; |
701 | #endif |
702 | |
703 | /** |
704 | * metadata. |
705 | * - encoding: Set by user. |
706 | * - decoding: Set by libavcodec. |
707 | */ |
708 | AVDictionary *metadata; |
709 | |
710 | /** |
711 | * decode error flags of the frame, set to a combination of |
712 | * FF_DECODE_ERROR_xxx flags if the decoder produced a frame, but there |
713 | * were errors during the decoding. |
714 | * - encoding: unused |
715 | * - decoding: set by libavcodec, read by user. |
716 | */ |
717 | int decode_error_flags; |
718 | #define FF_DECODE_ERROR_INVALID_BITSTREAM 1 |
719 | #define FF_DECODE_ERROR_MISSING_REFERENCE 2 |
720 | #define FF_DECODE_ERROR_CONCEALMENT_ACTIVE 4 |
721 | #define FF_DECODE_ERROR_DECODE_SLICES 8 |
722 | |
723 | #if FF_API_OLD_CHANNEL_LAYOUT |
724 | /** |
725 | * number of audio channels, only used for audio. |
726 | * - encoding: unused |
727 | * - decoding: Read by user. |
728 | * @deprecated use ch_layout instead |
729 | */ |
730 | attribute_deprecated |
731 | int channels; |
732 | #endif |
733 | |
734 | #if FF_API_FRAME_PKT |
735 | /** |
736 | * size of the corresponding packet containing the compressed |
737 | * frame. |
738 | * It is set to a negative value if unknown. |
739 | * - encoding: unused |
740 | * - decoding: set by libavcodec, read by user. |
741 | * @deprecated use AV_CODEC_FLAG_COPY_OPAQUE to pass through arbitrary user |
742 | * data from packets to frames |
743 | */ |
744 | attribute_deprecated |
745 | int pkt_size; |
746 | #endif |
747 | |
748 | /** |
749 | * For hwaccel-format frames, this should be a reference to the |
750 | * AVHWFramesContext describing the frame. |
751 | */ |
752 | AVBufferRef *hw_frames_ctx; |
753 | |
754 | /** |
755 | * Frame owner's private data. |
756 | * |
757 | * This field may be set by the code that allocates/owns the frame data. |
758 | * It is then not touched by any library functions, except: |
759 | * - a new reference to the underlying buffer is propagated by |
760 | * av_frame_copy_props() (and hence by av_frame_ref()); |
761 | * - it is unreferenced in av_frame_unref(); |
762 | * - on the caller's explicit request. E.g. libavcodec encoders/decoders |
763 | * will propagate a new reference to/from @ref AVPacket "AVPackets" if the |
764 | * caller sets @ref AV_CODEC_FLAG_COPY_OPAQUE. |
765 | * |
766 | * @see opaque the plain pointer analogue |
767 | */ |
768 | AVBufferRef *opaque_ref; |
769 | |
770 | /** |
771 | * @anchor cropping |
772 | * @name Cropping |
773 | * Video frames only. The number of pixels to discard from the the |
774 | * top/bottom/left/right border of the frame to obtain the sub-rectangle of |
775 | * the frame intended for presentation. |
776 | * @{ |
777 | */ |
778 | size_t crop_top; |
779 | size_t crop_bottom; |
780 | size_t crop_left; |
781 | size_t crop_right; |
782 | /** |
783 | * @} |
784 | */ |
785 | |
786 | /** |
787 | * AVBufferRef for internal use by a single libav* library. |
788 | * Must not be used to transfer data between libraries. |
789 | * Has to be NULL when ownership of the frame leaves the respective library. |
790 | * |
791 | * Code outside the FFmpeg libs should never check or change the contents of the buffer ref. |
792 | * |
793 | * FFmpeg calls av_buffer_unref() on it when the frame is unreferenced. |
794 | * av_frame_copy_props() calls create a new reference with av_buffer_ref() |
795 | * for the target frame's private_ref field. |
796 | */ |
797 | AVBufferRef *private_ref; |
798 | |
799 | /** |
800 | * Channel layout of the audio data. |
801 | */ |
802 | AVChannelLayout ch_layout; |
803 | |
804 | /** |
805 | * Duration of the frame, in the same units as pts. 0 if unknown. |
806 | */ |
807 | int64_t duration; |
808 | } AVFrame; |
809 | |
810 | |
811 | /** |
812 | * Allocate an AVFrame and set its fields to default values. The resulting |
813 | * struct must be freed using av_frame_free(). |
814 | * |
815 | * @return An AVFrame filled with default values or NULL on failure. |
816 | * |
817 | * @note this only allocates the AVFrame itself, not the data buffers. Those |
818 | * must be allocated through other means, e.g. with av_frame_get_buffer() or |
819 | * manually. |
820 | */ |
821 | AVFrame *av_frame_alloc(void); |
822 | |
823 | /** |
824 | * Free the frame and any dynamically allocated objects in it, |
825 | * e.g. extended_data. If the frame is reference counted, it will be |
826 | * unreferenced first. |
827 | * |
828 | * @param frame frame to be freed. The pointer will be set to NULL. |
829 | */ |
830 | void av_frame_free(AVFrame **frame); |
831 | |
832 | /** |
833 | * Set up a new reference to the data described by the source frame. |
834 | * |
835 | * Copy frame properties from src to dst and create a new reference for each |
836 | * AVBufferRef from src. |
837 | * |
838 | * If src is not reference counted, new buffers are allocated and the data is |
839 | * copied. |
840 | * |
841 | * @warning: dst MUST have been either unreferenced with av_frame_unref(dst), |
842 | * or newly allocated with av_frame_alloc() before calling this |
843 | * function, or undefined behavior will occur. |
844 | * |
845 | * @return 0 on success, a negative AVERROR on error |
846 | */ |
847 | int av_frame_ref(AVFrame *dst, const AVFrame *src); |
848 | |
849 | /** |
850 | * Ensure the destination frame refers to the same data described by the source |
851 | * frame, either by creating a new reference for each AVBufferRef from src if |
852 | * they differ from those in dst, by allocating new buffers and copying data if |
853 | * src is not reference counted, or by unrefencing it if src is empty. |
854 | * |
855 | * Frame properties on dst will be replaced by those from src. |
856 | * |
857 | * @return 0 on success, a negative AVERROR on error. On error, dst is |
858 | * unreferenced. |
859 | */ |
860 | int av_frame_replace(AVFrame *dst, const AVFrame *src); |
861 | |
862 | /** |
863 | * Create a new frame that references the same data as src. |
864 | * |
865 | * This is a shortcut for av_frame_alloc()+av_frame_ref(). |
866 | * |
867 | * @return newly created AVFrame on success, NULL on error. |
868 | */ |
869 | AVFrame *av_frame_clone(const AVFrame *src); |
870 | |
871 | /** |
872 | * Unreference all the buffers referenced by frame and reset the frame fields. |
873 | */ |
874 | void av_frame_unref(AVFrame *frame); |
875 | |
876 | /** |
877 | * Move everything contained in src to dst and reset src. |
878 | * |
879 | * @warning: dst is not unreferenced, but directly overwritten without reading |
880 | * or deallocating its contents. Call av_frame_unref(dst) manually |
881 | * before calling this function to ensure that no memory is leaked. |
882 | */ |
883 | void av_frame_move_ref(AVFrame *dst, AVFrame *src); |
884 | |
885 | /** |
886 | * Allocate new buffer(s) for audio or video data. |
887 | * |
888 | * The following fields must be set on frame before calling this function: |
889 | * - format (pixel format for video, sample format for audio) |
890 | * - width and height for video |
891 | * - nb_samples and ch_layout for audio |
892 | * |
893 | * This function will fill AVFrame.data and AVFrame.buf arrays and, if |
894 | * necessary, allocate and fill AVFrame.extended_data and AVFrame.extended_buf. |
895 | * For planar formats, one buffer will be allocated for each plane. |
896 | * |
897 | * @warning: if frame already has been allocated, calling this function will |
898 | * leak memory. In addition, undefined behavior can occur in certain |
899 | * cases. |
900 | * |
901 | * @param frame frame in which to store the new buffers. |
902 | * @param align Required buffer size alignment. If equal to 0, alignment will be |
903 | * chosen automatically for the current CPU. It is highly |
904 | * recommended to pass 0 here unless you know what you are doing. |
905 | * |
906 | * @return 0 on success, a negative AVERROR on error. |
907 | */ |
908 | int av_frame_get_buffer(AVFrame *frame, int align); |
909 | |
910 | /** |
911 | * Check if the frame data is writable. |
912 | * |
913 | * @return A positive value if the frame data is writable (which is true if and |
914 | * only if each of the underlying buffers has only one reference, namely the one |
915 | * stored in this frame). Return 0 otherwise. |
916 | * |
917 | * If 1 is returned the answer is valid until av_buffer_ref() is called on any |
918 | * of the underlying AVBufferRefs (e.g. through av_frame_ref() or directly). |
919 | * |
920 | * @see av_frame_make_writable(), av_buffer_is_writable() |
921 | */ |
922 | int av_frame_is_writable(AVFrame *frame); |
923 | |
924 | /** |
925 | * Ensure that the frame data is writable, avoiding data copy if possible. |
926 | * |
927 | * Do nothing if the frame is writable, allocate new buffers and copy the data |
928 | * if it is not. Non-refcounted frames behave as non-writable, i.e. a copy |
929 | * is always made. |
930 | * |
931 | * @return 0 on success, a negative AVERROR on error. |
932 | * |
933 | * @see av_frame_is_writable(), av_buffer_is_writable(), |
934 | * av_buffer_make_writable() |
935 | */ |
936 | int av_frame_make_writable(AVFrame *frame); |
937 | |
938 | /** |
939 | * Copy the frame data from src to dst. |
940 | * |
941 | * This function does not allocate anything, dst must be already initialized and |
942 | * allocated with the same parameters as src. |
943 | * |
944 | * This function only copies the frame data (i.e. the contents of the data / |
945 | * extended data arrays), not any other properties. |
946 | * |
947 | * @return >= 0 on success, a negative AVERROR on error. |
948 | */ |
949 | int av_frame_copy(AVFrame *dst, const AVFrame *src); |
950 | |
951 | /** |
952 | * Copy only "metadata" fields from src to dst. |
953 | * |
954 | * Metadata for the purpose of this function are those fields that do not affect |
955 | * the data layout in the buffers. E.g. pts, sample rate (for audio) or sample |
956 | * aspect ratio (for video), but not width/height or channel layout. |
957 | * Side data is also copied. |
958 | */ |
959 | int av_frame_copy_props(AVFrame *dst, const AVFrame *src); |
960 | |
961 | /** |
962 | * Get the buffer reference a given data plane is stored in. |
963 | * |
964 | * @param frame the frame to get the plane's buffer from |
965 | * @param plane index of the data plane of interest in frame->extended_data. |
966 | * |
967 | * @return the buffer reference that contains the plane or NULL if the input |
968 | * frame is not valid. |
969 | */ |
970 | AVBufferRef *av_frame_get_plane_buffer(const AVFrame *frame, int plane); |
971 | |
972 | /** |
973 | * Add a new side data to a frame. |
974 | * |
975 | * @param frame a frame to which the side data should be added |
976 | * @param type type of the added side data |
977 | * @param size size of the side data |
978 | * |
979 | * @return newly added side data on success, NULL on error |
980 | */ |
981 | AVFrameSideData *av_frame_new_side_data(AVFrame *frame, |
982 | enum AVFrameSideDataType type, |
983 | size_t size); |
984 | |
985 | /** |
986 | * Add a new side data to a frame from an existing AVBufferRef |
987 | * |
988 | * @param frame a frame to which the side data should be added |
989 | * @param type the type of the added side data |
990 | * @param buf an AVBufferRef to add as side data. The ownership of |
991 | * the reference is transferred to the frame. |
992 | * |
993 | * @return newly added side data on success, NULL on error. On failure |
994 | * the frame is unchanged and the AVBufferRef remains owned by |
995 | * the caller. |
996 | */ |
997 | AVFrameSideData *av_frame_new_side_data_from_buf(AVFrame *frame, |
998 | enum AVFrameSideDataType type, |
999 | AVBufferRef *buf); |
1000 | |
1001 | /** |
1002 | * @return a pointer to the side data of a given type on success, NULL if there |
1003 | * is no side data with such type in this frame. |
1004 | */ |
1005 | AVFrameSideData *av_frame_get_side_data(const AVFrame *frame, |
1006 | enum AVFrameSideDataType type); |
1007 | |
1008 | /** |
1009 | * Remove and free all side data instances of the given type. |
1010 | */ |
1011 | void av_frame_remove_side_data(AVFrame *frame, enum AVFrameSideDataType type); |
1012 | |
1013 | |
1014 | /** |
1015 | * Flags for frame cropping. |
1016 | */ |
1017 | enum { |
1018 | /** |
1019 | * Apply the maximum possible cropping, even if it requires setting the |
1020 | * AVFrame.data[] entries to unaligned pointers. Passing unaligned data |
1021 | * to FFmpeg API is generally not allowed, and causes undefined behavior |
1022 | * (such as crashes). You can pass unaligned data only to FFmpeg APIs that |
1023 | * are explicitly documented to accept it. Use this flag only if you |
1024 | * absolutely know what you are doing. |
1025 | */ |
1026 | AV_FRAME_CROP_UNALIGNED = 1 << 0, |
1027 | }; |
1028 | |
1029 | /** |
1030 | * Crop the given video AVFrame according to its crop_left/crop_top/crop_right/ |
1031 | * crop_bottom fields. If cropping is successful, the function will adjust the |
1032 | * data pointers and the width/height fields, and set the crop fields to 0. |
1033 | * |
1034 | * In all cases, the cropping boundaries will be rounded to the inherent |
1035 | * alignment of the pixel format. In some cases, such as for opaque hwaccel |
1036 | * formats, the left/top cropping is ignored. The crop fields are set to 0 even |
1037 | * if the cropping was rounded or ignored. |
1038 | * |
1039 | * @param frame the frame which should be cropped |
1040 | * @param flags Some combination of AV_FRAME_CROP_* flags, or 0. |
1041 | * |
1042 | * @return >= 0 on success, a negative AVERROR on error. If the cropping fields |
1043 | * were invalid, AVERROR(ERANGE) is returned, and nothing is changed. |
1044 | */ |
1045 | int av_frame_apply_cropping(AVFrame *frame, int flags); |
1046 | |
1047 | /** |
1048 | * @return a string identifying the side data type |
1049 | */ |
1050 | const char *av_frame_side_data_name(enum AVFrameSideDataType type); |
1051 | |
1052 | /** |
1053 | * @} |
1054 | */ |
1055 | |
1056 | #endif /* AVUTIL_FRAME_H */ |
1057 | |