Commit | Line | Data |
---|---|---|
2ba45a60 DM |
1 | /* |
2 | * | |
3 | * This file is part of FFmpeg. | |
4 | * | |
5 | * FFmpeg is free software; you can redistribute it and/or | |
6 | * modify it under the terms of the GNU Lesser General Public | |
7 | * License as published by the Free Software Foundation; either | |
8 | * version 2.1 of the License, or (at your option) any later version. | |
9 | * | |
10 | * FFmpeg is distributed in the hope that it will be useful, | |
11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
13 | * Lesser General Public License for more details. | |
14 | * | |
15 | * You should have received a copy of the GNU Lesser General Public | |
16 | * License along with FFmpeg; if not, write to the Free Software | |
17 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | |
18 | */ | |
19 | ||
20 | /** | |
21 | * @file | |
22 | * @ingroup lavu_frame | |
23 | * reference-counted frame API | |
24 | */ | |
25 | ||
26 | #ifndef AVUTIL_FRAME_H | |
27 | #define AVUTIL_FRAME_H | |
28 | ||
29 | #include <stdint.h> | |
30 | ||
31 | #include "avutil.h" | |
32 | #include "buffer.h" | |
33 | #include "dict.h" | |
34 | #include "rational.h" | |
35 | #include "samplefmt.h" | |
36 | #include "pixfmt.h" | |
37 | #include "version.h" | |
38 | ||
39 | ||
40 | /** | |
41 | * @defgroup lavu_frame AVFrame | |
42 | * @ingroup lavu_data | |
43 | * | |
44 | * @{ | |
45 | * AVFrame is an abstraction for reference-counted raw multimedia data. | |
46 | */ | |
47 | ||
48 | enum AVFrameSideDataType { | |
49 | /** | |
50 | * The data is the AVPanScan struct defined in libavcodec. | |
51 | */ | |
52 | AV_FRAME_DATA_PANSCAN, | |
53 | /** | |
54 | * ATSC A53 Part 4 Closed Captions. | |
55 | * A53 CC bitstream is stored as uint8_t in AVFrameSideData.data. | |
56 | * The number of bytes of CC data is AVFrameSideData.size. | |
57 | */ | |
58 | AV_FRAME_DATA_A53_CC, | |
59 | /** | |
60 | * Stereoscopic 3d metadata. | |
61 | * The data is the AVStereo3D struct defined in libavutil/stereo3d.h. | |
62 | */ | |
63 | AV_FRAME_DATA_STEREO3D, | |
64 | /** | |
65 | * The data is the AVMatrixEncoding enum defined in libavutil/channel_layout.h. | |
66 | */ | |
67 | AV_FRAME_DATA_MATRIXENCODING, | |
68 | /** | |
69 | * Metadata relevant to a downmix procedure. | |
70 | * The data is the AVDownmixInfo struct defined in libavutil/downmix_info.h. | |
71 | */ | |
72 | AV_FRAME_DATA_DOWNMIX_INFO, | |
73 | /** | |
74 | * ReplayGain information in the form of the AVReplayGain struct. | |
75 | */ | |
76 | AV_FRAME_DATA_REPLAYGAIN, | |
77 | /** | |
78 | * This side data contains a 3x3 transformation matrix describing an affine | |
79 | * transformation that needs to be applied to the frame for correct | |
80 | * presentation. | |
81 | * | |
82 | * See libavutil/display.h for a detailed description of the data. | |
83 | */ | |
84 | AV_FRAME_DATA_DISPLAYMATRIX, | |
85 | /** | |
86 | * Active Format Description data consisting of a single byte as specified | |
87 | * in ETSI TS 101 154 using AVActiveFormatDescription enum. | |
88 | */ | |
89 | AV_FRAME_DATA_AFD, | |
90 | /** | |
91 | * Motion vectors exported by some codecs (on demand through the export_mvs | |
92 | * flag set in the libavcodec AVCodecContext flags2 option). | |
93 | * The data is the AVMotionVector struct defined in | |
94 | * libavutil/motion_vector.h. | |
95 | */ | |
96 | AV_FRAME_DATA_MOTION_VECTORS, | |
97 | }; | |
98 | ||
99 | enum AVActiveFormatDescription { | |
100 | AV_AFD_SAME = 8, | |
101 | AV_AFD_4_3 = 9, | |
102 | AV_AFD_16_9 = 10, | |
103 | AV_AFD_14_9 = 11, | |
104 | AV_AFD_4_3_SP_14_9 = 13, | |
105 | AV_AFD_16_9_SP_14_9 = 14, | |
106 | AV_AFD_SP_4_3 = 15, | |
107 | }; | |
108 | ||
109 | typedef struct AVFrameSideData { | |
110 | enum AVFrameSideDataType type; | |
111 | uint8_t *data; | |
112 | int size; | |
113 | AVDictionary *metadata; | |
114 | } AVFrameSideData; | |
115 | ||
116 | /** | |
117 | * This structure describes decoded (raw) audio or video data. | |
118 | * | |
119 | * AVFrame must be allocated using av_frame_alloc(). Note that this only | |
120 | * allocates the AVFrame itself, the buffers for the data must be managed | |
121 | * through other means (see below). | |
122 | * AVFrame must be freed with av_frame_free(). | |
123 | * | |
124 | * AVFrame is typically allocated once and then reused multiple times to hold | |
125 | * different data (e.g. a single AVFrame to hold frames received from a | |
126 | * decoder). In such a case, av_frame_unref() will free any references held by | |
127 | * the frame and reset it to its original clean state before it | |
128 | * is reused again. | |
129 | * | |
130 | * The data described by an AVFrame is usually reference counted through the | |
131 | * AVBuffer API. The underlying buffer references are stored in AVFrame.buf / | |
132 | * AVFrame.extended_buf. An AVFrame is considered to be reference counted if at | |
133 | * least one reference is set, i.e. if AVFrame.buf[0] != NULL. In such a case, | |
134 | * every single data plane must be contained in one of the buffers in | |
135 | * AVFrame.buf or AVFrame.extended_buf. | |
136 | * There may be a single buffer for all the data, or one separate buffer for | |
137 | * each plane, or anything in between. | |
138 | * | |
139 | * sizeof(AVFrame) is not a part of the public ABI, so new fields may be added | |
140 | * to the end with a minor bump. | |
141 | * Similarly fields that are marked as to be only accessed by | |
142 | * av_opt_ptr() can be reordered. This allows 2 forks to add fields | |
143 | * without breaking compatibility with each other. | |
144 | */ | |
145 | typedef struct AVFrame { | |
146 | #define AV_NUM_DATA_POINTERS 8 | |
147 | /** | |
148 | * pointer to the picture/channel planes. | |
149 | * This might be different from the first allocated byte | |
150 | * | |
151 | * Some decoders access areas outside 0,0 - width,height, please | |
152 | * see avcodec_align_dimensions2(). Some filters and swscale can read | |
153 | * up to 16 bytes beyond the planes, if these filters are to be used, | |
154 | * then 16 extra bytes must be allocated. | |
155 | */ | |
156 | uint8_t *data[AV_NUM_DATA_POINTERS]; | |
157 | ||
158 | /** | |
159 | * For video, size in bytes of each picture line. | |
160 | * For audio, size in bytes of each plane. | |
161 | * | |
162 | * For audio, only linesize[0] may be set. For planar audio, each channel | |
163 | * plane must be the same size. | |
164 | * | |
165 | * For video the linesizes should be multiples of the CPUs alignment | |
166 | * preference, this is 16 or 32 for modern desktop CPUs. | |
167 | * Some code requires such alignment other code can be slower without | |
168 | * correct alignment, for yet other it makes no difference. | |
169 | * | |
170 | * @note The linesize may be larger than the size of usable data -- there | |
171 | * may be extra padding present for performance reasons. | |
172 | */ | |
173 | int linesize[AV_NUM_DATA_POINTERS]; | |
174 | ||
175 | /** | |
176 | * pointers to the data planes/channels. | |
177 | * | |
178 | * For video, this should simply point to data[]. | |
179 | * | |
180 | * For planar audio, each channel has a separate data pointer, and | |
181 | * linesize[0] contains the size of each channel buffer. | |
182 | * For packed audio, there is just one data pointer, and linesize[0] | |
183 | * contains the total size of the buffer for all channels. | |
184 | * | |
185 | * Note: Both data and extended_data should always be set in a valid frame, | |
186 | * but for planar audio with more channels that can fit in data, | |
187 | * extended_data must be used in order to access all channels. | |
188 | */ | |
189 | uint8_t **extended_data; | |
190 | ||
191 | /** | |
192 | * width and height of the video frame | |
193 | */ | |
194 | int width, height; | |
195 | ||
196 | /** | |
197 | * number of audio samples (per channel) described by this frame | |
198 | */ | |
199 | int nb_samples; | |
200 | ||
201 | /** | |
202 | * format of the frame, -1 if unknown or unset | |
203 | * Values correspond to enum AVPixelFormat for video frames, | |
204 | * enum AVSampleFormat for audio) | |
205 | */ | |
206 | int format; | |
207 | ||
208 | /** | |
209 | * 1 -> keyframe, 0-> not | |
210 | */ | |
211 | int key_frame; | |
212 | ||
213 | /** | |
214 | * Picture type of the frame. | |
215 | */ | |
216 | enum AVPictureType pict_type; | |
217 | ||
218 | #if FF_API_AVFRAME_LAVC | |
219 | attribute_deprecated | |
220 | uint8_t *base[AV_NUM_DATA_POINTERS]; | |
221 | #endif | |
222 | ||
223 | /** | |
224 | * Sample aspect ratio for the video frame, 0/1 if unknown/unspecified. | |
225 | */ | |
226 | AVRational sample_aspect_ratio; | |
227 | ||
228 | /** | |
229 | * Presentation timestamp in time_base units (time when frame should be shown to user). | |
230 | */ | |
231 | int64_t pts; | |
232 | ||
233 | /** | |
234 | * PTS copied from the AVPacket that was decoded to produce this frame. | |
235 | */ | |
236 | int64_t pkt_pts; | |
237 | ||
238 | /** | |
239 | * DTS copied from the AVPacket that triggered returning this frame. (if frame threading isn't used) | |
240 | * This is also the Presentation time of this AVFrame calculated from | |
241 | * only AVPacket.dts values without pts values. | |
242 | */ | |
243 | int64_t pkt_dts; | |
244 | ||
245 | /** | |
246 | * picture number in bitstream order | |
247 | */ | |
248 | int coded_picture_number; | |
249 | /** | |
250 | * picture number in display order | |
251 | */ | |
252 | int display_picture_number; | |
253 | ||
254 | /** | |
255 | * quality (between 1 (good) and FF_LAMBDA_MAX (bad)) | |
256 | */ | |
257 | int quality; | |
258 | ||
259 | #if FF_API_AVFRAME_LAVC | |
260 | attribute_deprecated | |
261 | int reference; | |
262 | ||
263 | /** | |
264 | * QP table | |
265 | */ | |
266 | attribute_deprecated | |
267 | int8_t *qscale_table; | |
268 | /** | |
269 | * QP store stride | |
270 | */ | |
271 | attribute_deprecated | |
272 | int qstride; | |
273 | ||
274 | attribute_deprecated | |
275 | int qscale_type; | |
276 | ||
277 | /** | |
278 | * mbskip_table[mb]>=1 if MB didn't change | |
279 | * stride= mb_width = (width+15)>>4 | |
280 | */ | |
281 | attribute_deprecated | |
282 | uint8_t *mbskip_table; | |
283 | ||
284 | /** | |
285 | * motion vector table | |
286 | * @code | |
287 | * example: | |
288 | * int mv_sample_log2= 4 - motion_subsample_log2; | |
289 | * int mb_width= (width+15)>>4; | |
290 | * int mv_stride= (mb_width << mv_sample_log2) + 1; | |
291 | * motion_val[direction][x + y*mv_stride][0->mv_x, 1->mv_y]; | |
292 | * @endcode | |
293 | */ | |
294 | int16_t (*motion_val[2])[2]; | |
295 | ||
296 | /** | |
297 | * macroblock type table | |
298 | * mb_type_base + mb_width + 2 | |
299 | */ | |
300 | attribute_deprecated | |
301 | uint32_t *mb_type; | |
302 | ||
303 | /** | |
304 | * DCT coefficients | |
305 | */ | |
306 | attribute_deprecated | |
307 | short *dct_coeff; | |
308 | ||
309 | /** | |
310 | * motion reference frame index | |
311 | * the order in which these are stored can depend on the codec. | |
312 | */ | |
313 | attribute_deprecated | |
314 | int8_t *ref_index[2]; | |
315 | #endif | |
316 | ||
317 | /** | |
318 | * for some private data of the user | |
319 | */ | |
320 | void *opaque; | |
321 | ||
322 | /** | |
323 | * error | |
324 | */ | |
325 | uint64_t error[AV_NUM_DATA_POINTERS]; | |
326 | ||
327 | #if FF_API_AVFRAME_LAVC | |
328 | attribute_deprecated | |
329 | int type; | |
330 | #endif | |
331 | ||
332 | /** | |
333 | * When decoding, this signals how much the picture must be delayed. | |
334 | * extra_delay = repeat_pict / (2*fps) | |
335 | */ | |
336 | int repeat_pict; | |
337 | ||
338 | /** | |
339 | * The content of the picture is interlaced. | |
340 | */ | |
341 | int interlaced_frame; | |
342 | ||
343 | /** | |
344 | * If the content is interlaced, is top field displayed first. | |
345 | */ | |
346 | int top_field_first; | |
347 | ||
348 | /** | |
349 | * Tell user application that palette has changed from previous frame. | |
350 | */ | |
351 | int palette_has_changed; | |
352 | ||
353 | #if FF_API_AVFRAME_LAVC | |
354 | attribute_deprecated | |
355 | int buffer_hints; | |
356 | ||
357 | /** | |
358 | * Pan scan. | |
359 | */ | |
360 | attribute_deprecated | |
361 | struct AVPanScan *pan_scan; | |
362 | #endif | |
363 | ||
364 | /** | |
365 | * reordered opaque 64bit (generally an integer or a double precision float | |
366 | * PTS but can be anything). | |
367 | * The user sets AVCodecContext.reordered_opaque to represent the input at | |
368 | * that time, | |
369 | * the decoder reorders values as needed and sets AVFrame.reordered_opaque | |
370 | * to exactly one of the values provided by the user through AVCodecContext.reordered_opaque | |
371 | * @deprecated in favor of pkt_pts | |
372 | */ | |
373 | int64_t reordered_opaque; | |
374 | ||
375 | #if FF_API_AVFRAME_LAVC | |
376 | /** | |
377 | * @deprecated this field is unused | |
378 | */ | |
379 | attribute_deprecated void *hwaccel_picture_private; | |
380 | ||
381 | attribute_deprecated | |
382 | struct AVCodecContext *owner; | |
383 | attribute_deprecated | |
384 | void *thread_opaque; | |
385 | ||
386 | /** | |
387 | * log2 of the size of the block which a single vector in motion_val represents: | |
388 | * (4->16x16, 3->8x8, 2-> 4x4, 1-> 2x2) | |
389 | */ | |
390 | uint8_t motion_subsample_log2; | |
391 | #endif | |
392 | ||
393 | /** | |
394 | * Sample rate of the audio data. | |
395 | */ | |
396 | int sample_rate; | |
397 | ||
398 | /** | |
399 | * Channel layout of the audio data. | |
400 | */ | |
401 | uint64_t channel_layout; | |
402 | ||
403 | /** | |
404 | * AVBuffer references backing the data for this frame. If all elements of | |
405 | * this array are NULL, then this frame is not reference counted. | |
406 | * | |
407 | * There may be at most one AVBuffer per data plane, so for video this array | |
408 | * always contains all the references. For planar audio with more than | |
409 | * AV_NUM_DATA_POINTERS channels, there may be more buffers than can fit in | |
410 | * this array. Then the extra AVBufferRef pointers are stored in the | |
411 | * extended_buf array. | |
412 | */ | |
413 | AVBufferRef *buf[AV_NUM_DATA_POINTERS]; | |
414 | ||
415 | /** | |
416 | * For planar audio which requires more than AV_NUM_DATA_POINTERS | |
417 | * AVBufferRef pointers, this array will hold all the references which | |
418 | * cannot fit into AVFrame.buf. | |
419 | * | |
420 | * Note that this is different from AVFrame.extended_data, which always | |
421 | * contains all the pointers. This array only contains the extra pointers, | |
422 | * which cannot fit into AVFrame.buf. | |
423 | * | |
424 | * This array is always allocated using av_malloc() by whoever constructs | |
425 | * the frame. It is freed in av_frame_unref(). | |
426 | */ | |
427 | AVBufferRef **extended_buf; | |
428 | /** | |
429 | * Number of elements in extended_buf. | |
430 | */ | |
431 | int nb_extended_buf; | |
432 | ||
433 | AVFrameSideData **side_data; | |
434 | int nb_side_data; | |
435 | ||
436 | /** | |
437 | * @defgroup lavu_frame_flags AV_FRAME_FLAGS | |
438 | * Flags describing additional frame properties. | |
439 | * | |
440 | * @{ | |
441 | */ | |
442 | ||
443 | /** | |
444 | * The frame data may be corrupted, e.g. due to decoding errors. | |
445 | */ | |
446 | #define AV_FRAME_FLAG_CORRUPT (1 << 0) | |
447 | /** | |
448 | * @} | |
449 | */ | |
450 | ||
451 | /** | |
452 | * Frame flags, a combination of @ref lavu_frame_flags | |
453 | */ | |
454 | int flags; | |
455 | ||
456 | /** | |
457 | * MPEG vs JPEG YUV range. | |
458 | * It must be accessed using av_frame_get_color_range() and | |
459 | * av_frame_set_color_range(). | |
460 | * - encoding: Set by user | |
461 | * - decoding: Set by libavcodec | |
462 | */ | |
463 | enum AVColorRange color_range; | |
464 | ||
465 | enum AVColorPrimaries color_primaries; | |
466 | ||
467 | enum AVColorTransferCharacteristic color_trc; | |
468 | ||
469 | /** | |
470 | * YUV colorspace type. | |
471 | * It must be accessed using av_frame_get_colorspace() and | |
472 | * av_frame_set_colorspace(). | |
473 | * - encoding: Set by user | |
474 | * - decoding: Set by libavcodec | |
475 | */ | |
476 | enum AVColorSpace colorspace; | |
477 | ||
478 | enum AVChromaLocation chroma_location; | |
479 | ||
480 | /** | |
481 | * frame timestamp estimated using various heuristics, in stream time base | |
482 | * Code outside libavcodec should access this field using: | |
483 | * av_frame_get_best_effort_timestamp(frame) | |
484 | * - encoding: unused | |
485 | * - decoding: set by libavcodec, read by user. | |
486 | */ | |
487 | int64_t best_effort_timestamp; | |
488 | ||
489 | /** | |
490 | * reordered pos from the last AVPacket that has been input into the decoder | |
491 | * Code outside libavcodec should access this field using: | |
492 | * av_frame_get_pkt_pos(frame) | |
493 | * - encoding: unused | |
494 | * - decoding: Read by user. | |
495 | */ | |
496 | int64_t pkt_pos; | |
497 | ||
498 | /** | |
499 | * duration of the corresponding packet, expressed in | |
500 | * AVStream->time_base units, 0 if unknown. | |
501 | * Code outside libavcodec should access this field using: | |
502 | * av_frame_get_pkt_duration(frame) | |
503 | * - encoding: unused | |
504 | * - decoding: Read by user. | |
505 | */ | |
506 | int64_t pkt_duration; | |
507 | ||
508 | /** | |
509 | * metadata. | |
510 | * Code outside libavcodec should access this field using: | |
511 | * av_frame_get_metadata(frame) | |
512 | * - encoding: Set by user. | |
513 | * - decoding: Set by libavcodec. | |
514 | */ | |
515 | AVDictionary *metadata; | |
516 | ||
517 | /** | |
518 | * decode error flags of the frame, set to a combination of | |
519 | * FF_DECODE_ERROR_xxx flags if the decoder produced a frame, but there | |
520 | * were errors during the decoding. | |
521 | * Code outside libavcodec should access this field using: | |
522 | * av_frame_get_decode_error_flags(frame) | |
523 | * - encoding: unused | |
524 | * - decoding: set by libavcodec, read by user. | |
525 | */ | |
526 | int decode_error_flags; | |
527 | #define FF_DECODE_ERROR_INVALID_BITSTREAM 1 | |
528 | #define FF_DECODE_ERROR_MISSING_REFERENCE 2 | |
529 | ||
530 | /** | |
531 | * number of audio channels, only used for audio. | |
532 | * Code outside libavcodec should access this field using: | |
533 | * av_frame_get_channels(frame) | |
534 | * - encoding: unused | |
535 | * - decoding: Read by user. | |
536 | */ | |
537 | int channels; | |
538 | ||
539 | /** | |
540 | * size of the corresponding packet containing the compressed | |
541 | * frame. It must be accessed using av_frame_get_pkt_size() and | |
542 | * av_frame_set_pkt_size(). | |
543 | * It is set to a negative value if unknown. | |
544 | * - encoding: unused | |
545 | * - decoding: set by libavcodec, read by user. | |
546 | */ | |
547 | int pkt_size; | |
548 | ||
549 | /** | |
550 | * Not to be accessed directly from outside libavutil | |
551 | */ | |
552 | AVBufferRef *qp_table_buf; | |
553 | } AVFrame; | |
554 | ||
555 | /** | |
556 | * Accessors for some AVFrame fields. | |
557 | * The position of these field in the structure is not part of the ABI, | |
558 | * they should not be accessed directly outside libavcodec. | |
559 | */ | |
560 | int64_t av_frame_get_best_effort_timestamp(const AVFrame *frame); | |
561 | void av_frame_set_best_effort_timestamp(AVFrame *frame, int64_t val); | |
562 | int64_t av_frame_get_pkt_duration (const AVFrame *frame); | |
563 | void av_frame_set_pkt_duration (AVFrame *frame, int64_t val); | |
564 | int64_t av_frame_get_pkt_pos (const AVFrame *frame); | |
565 | void av_frame_set_pkt_pos (AVFrame *frame, int64_t val); | |
566 | int64_t av_frame_get_channel_layout (const AVFrame *frame); | |
567 | void av_frame_set_channel_layout (AVFrame *frame, int64_t val); | |
568 | int av_frame_get_channels (const AVFrame *frame); | |
569 | void av_frame_set_channels (AVFrame *frame, int val); | |
570 | int av_frame_get_sample_rate (const AVFrame *frame); | |
571 | void av_frame_set_sample_rate (AVFrame *frame, int val); | |
572 | AVDictionary *av_frame_get_metadata (const AVFrame *frame); | |
573 | void av_frame_set_metadata (AVFrame *frame, AVDictionary *val); | |
574 | int av_frame_get_decode_error_flags (const AVFrame *frame); | |
575 | void av_frame_set_decode_error_flags (AVFrame *frame, int val); | |
576 | int av_frame_get_pkt_size(const AVFrame *frame); | |
577 | void av_frame_set_pkt_size(AVFrame *frame, int val); | |
578 | AVDictionary **avpriv_frame_get_metadatap(AVFrame *frame); | |
579 | int8_t *av_frame_get_qp_table(AVFrame *f, int *stride, int *type); | |
580 | int av_frame_set_qp_table(AVFrame *f, AVBufferRef *buf, int stride, int type); | |
581 | enum AVColorSpace av_frame_get_colorspace(const AVFrame *frame); | |
582 | void av_frame_set_colorspace(AVFrame *frame, enum AVColorSpace val); | |
583 | enum AVColorRange av_frame_get_color_range(const AVFrame *frame); | |
584 | void av_frame_set_color_range(AVFrame *frame, enum AVColorRange val); | |
585 | ||
586 | /** | |
587 | * Get the name of a colorspace. | |
588 | * @return a static string identifying the colorspace; can be NULL. | |
589 | */ | |
590 | const char *av_get_colorspace_name(enum AVColorSpace val); | |
591 | ||
592 | /** | |
593 | * Allocate an AVFrame and set its fields to default values. The resulting | |
594 | * struct must be freed using av_frame_free(). | |
595 | * | |
596 | * @return An AVFrame filled with default values or NULL on failure. | |
597 | * | |
598 | * @note this only allocates the AVFrame itself, not the data buffers. Those | |
599 | * must be allocated through other means, e.g. with av_frame_get_buffer() or | |
600 | * manually. | |
601 | */ | |
602 | AVFrame *av_frame_alloc(void); | |
603 | ||
604 | /** | |
605 | * Free the frame and any dynamically allocated objects in it, | |
606 | * e.g. extended_data. If the frame is reference counted, it will be | |
607 | * unreferenced first. | |
608 | * | |
609 | * @param frame frame to be freed. The pointer will be set to NULL. | |
610 | */ | |
611 | void av_frame_free(AVFrame **frame); | |
612 | ||
613 | /** | |
614 | * Set up a new reference to the data described by the source frame. | |
615 | * | |
616 | * Copy frame properties from src to dst and create a new reference for each | |
617 | * AVBufferRef from src. | |
618 | * | |
619 | * If src is not reference counted, new buffers are allocated and the data is | |
620 | * copied. | |
621 | * | |
622 | * @return 0 on success, a negative AVERROR on error | |
623 | */ | |
624 | int av_frame_ref(AVFrame *dst, const AVFrame *src); | |
625 | ||
626 | /** | |
627 | * Create a new frame that references the same data as src. | |
628 | * | |
629 | * This is a shortcut for av_frame_alloc()+av_frame_ref(). | |
630 | * | |
631 | * @return newly created AVFrame on success, NULL on error. | |
632 | */ | |
633 | AVFrame *av_frame_clone(const AVFrame *src); | |
634 | ||
635 | /** | |
636 | * Unreference all the buffers referenced by frame and reset the frame fields. | |
637 | */ | |
638 | void av_frame_unref(AVFrame *frame); | |
639 | ||
640 | /** | |
641 | * Move everythnig contained in src to dst and reset src. | |
642 | */ | |
643 | void av_frame_move_ref(AVFrame *dst, AVFrame *src); | |
644 | ||
645 | /** | |
646 | * Allocate new buffer(s) for audio or video data. | |
647 | * | |
648 | * The following fields must be set on frame before calling this function: | |
649 | * - format (pixel format for video, sample format for audio) | |
650 | * - width and height for video | |
651 | * - nb_samples and channel_layout for audio | |
652 | * | |
653 | * This function will fill AVFrame.data and AVFrame.buf arrays and, if | |
654 | * necessary, allocate and fill AVFrame.extended_data and AVFrame.extended_buf. | |
655 | * For planar formats, one buffer will be allocated for each plane. | |
656 | * | |
657 | * @param frame frame in which to store the new buffers. | |
658 | * @param align required buffer size alignment | |
659 | * | |
660 | * @return 0 on success, a negative AVERROR on error. | |
661 | */ | |
662 | int av_frame_get_buffer(AVFrame *frame, int align); | |
663 | ||
664 | /** | |
665 | * Check if the frame data is writable. | |
666 | * | |
667 | * @return A positive value if the frame data is writable (which is true if and | |
668 | * only if each of the underlying buffers has only one reference, namely the one | |
669 | * stored in this frame). Return 0 otherwise. | |
670 | * | |
671 | * If 1 is returned the answer is valid until av_buffer_ref() is called on any | |
672 | * of the underlying AVBufferRefs (e.g. through av_frame_ref() or directly). | |
673 | * | |
674 | * @see av_frame_make_writable(), av_buffer_is_writable() | |
675 | */ | |
676 | int av_frame_is_writable(AVFrame *frame); | |
677 | ||
678 | /** | |
679 | * Ensure that the frame data is writable, avoiding data copy if possible. | |
680 | * | |
681 | * Do nothing if the frame is writable, allocate new buffers and copy the data | |
682 | * if it is not. | |
683 | * | |
684 | * @return 0 on success, a negative AVERROR on error. | |
685 | * | |
686 | * @see av_frame_is_writable(), av_buffer_is_writable(), | |
687 | * av_buffer_make_writable() | |
688 | */ | |
689 | int av_frame_make_writable(AVFrame *frame); | |
690 | ||
691 | /** | |
692 | * Copy the frame data from src to dst. | |
693 | * | |
694 | * This function does not allocate anything, dst must be already initialized and | |
695 | * allocated with the same parameters as src. | |
696 | * | |
697 | * This function only copies the frame data (i.e. the contents of the data / | |
698 | * extended data arrays), not any other properties. | |
699 | * | |
700 | * @return >= 0 on success, a negative AVERROR on error. | |
701 | */ | |
702 | int av_frame_copy(AVFrame *dst, const AVFrame *src); | |
703 | ||
704 | /** | |
705 | * Copy only "metadata" fields from src to dst. | |
706 | * | |
707 | * Metadata for the purpose of this function are those fields that do not affect | |
708 | * the data layout in the buffers. E.g. pts, sample rate (for audio) or sample | |
709 | * aspect ratio (for video), but not width/height or channel layout. | |
710 | * Side data is also copied. | |
711 | */ | |
712 | int av_frame_copy_props(AVFrame *dst, const AVFrame *src); | |
713 | ||
714 | /** | |
715 | * Get the buffer reference a given data plane is stored in. | |
716 | * | |
717 | * @param plane index of the data plane of interest in frame->extended_data. | |
718 | * | |
719 | * @return the buffer reference that contains the plane or NULL if the input | |
720 | * frame is not valid. | |
721 | */ | |
722 | AVBufferRef *av_frame_get_plane_buffer(AVFrame *frame, int plane); | |
723 | ||
724 | /** | |
725 | * Add a new side data to a frame. | |
726 | * | |
727 | * @param frame a frame to which the side data should be added | |
728 | * @param type type of the added side data | |
729 | * @param size size of the side data | |
730 | * | |
731 | * @return newly added side data on success, NULL on error | |
732 | */ | |
733 | AVFrameSideData *av_frame_new_side_data(AVFrame *frame, | |
734 | enum AVFrameSideDataType type, | |
735 | int size); | |
736 | ||
737 | /** | |
738 | * @return a pointer to the side data of a given type on success, NULL if there | |
739 | * is no side data with such type in this frame. | |
740 | */ | |
741 | AVFrameSideData *av_frame_get_side_data(const AVFrame *frame, | |
742 | enum AVFrameSideDataType type); | |
743 | ||
744 | /** | |
745 | * If side data of the supplied type exists in the frame, free it and remove it | |
746 | * from the frame. | |
747 | */ | |
748 | void av_frame_remove_side_data(AVFrame *frame, enum AVFrameSideDataType type); | |
749 | ||
750 | /** | |
751 | * @return a string identifying the side data type | |
752 | */ | |
753 | const char *av_frame_side_data_name(enum AVFrameSideDataType type); | |
754 | ||
755 | /** | |
756 | * @} | |
757 | */ | |
758 | ||
759 | #endif /* AVUTIL_FRAME_H */ |