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