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