FFmpeg
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
frame.h
Go to the documentation of this file.
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 #ifndef AVUTIL_FRAME_H
21 #define AVUTIL_FRAME_H
22 
23 #include <stdint.h>
24 
25 #include "libavcodec/version.h"
26 
27 #include "avutil.h"
28 #include "buffer.h"
29 #include "dict.h"
30 #include "rational.h"
31 #include "samplefmt.h"
32 
34  /**
35  * The data is the AVPanScan struct defined in libavcodec.
36  */
38 };
39 
40 typedef struct AVFrameSideData {
43  int size;
46 
47 /**
48  * This structure describes decoded (raw) audio or video data.
49  *
50  * AVFrame must be allocated using av_frame_alloc(). Note that this only
51  * allocates the AVFrame itself, the buffers for the data must be managed
52  * through other means (see below).
53  * AVFrame must be freed with av_frame_free().
54  *
55  * AVFrame is typically allocated once and then reused multiple times to hold
56  * different data (e.g. a single AVFrame to hold frames received from a
57  * decoder). In such a case, av_frame_unref() will free any references held by
58  * the frame and reset it to its original clean state before it
59  * is reused again.
60  *
61  * The data described by an AVFrame is usually reference counted through the
62  * AVBuffer API. The underlying buffer references are stored in AVFrame.buf /
63  * AVFrame.extended_buf. An AVFrame is considered to be reference counted if at
64  * least one reference is set, i.e. if AVFrame.buf[0] != NULL. In such a case,
65  * every single data plane must be contained in one of the buffers in
66  * AVFrame.buf or AVFrame.extended_buf.
67  * There may be a single buffer for all the data, or one separate buffer for
68  * each plane, or anything in between.
69  *
70  * sizeof(AVFrame) is not a part of the public ABI, so new fields may be added
71  * to the end with a minor bump.
72  * Similarly fields that are marked as to be only accessed by
73  * av_opt_ptr() can be reordered. This allows 2 forks to add fields
74  * without breaking compatibility with each other.
75  */
76 typedef struct AVFrame {
77 #define AV_NUM_DATA_POINTERS 8
78  /**
79  * pointer to the picture/channel planes.
80  * This might be different from the first allocated byte
81  *
82  * Some decoders access areas outside 0,0 - width,height, please
83  * see avcodec_align_dimensions2(). Some filters and swscale can read
84  * up to 16 bytes beyond the planes, if these filters are to be used,
85  * then 16 extra bytes must be allocated.
86  */
88 
89  /**
90  * For video, size in bytes of each picture line.
91  * For audio, size in bytes of each plane.
92  *
93  * For audio, only linesize[0] may be set. For planar audio, each channel
94  * plane must be the same size.
95  *
96  * For video the linesizes should be multiplies of the CPUs alignment
97  * preference, this is 16 or 32 for modern desktop CPUs.
98  * Some code requires such alignment other code can be slower without
99  * correct alignment, for yet other it makes no difference.
100  */
102 
103  /**
104  * pointers to the data planes/channels.
105  *
106  * For video, this should simply point to data[].
107  *
108  * For planar audio, each channel has a separate data pointer, and
109  * linesize[0] contains the size of each channel buffer.
110  * For packed audio, there is just one data pointer, and linesize[0]
111  * contains the total size of the buffer for all channels.
112  *
113  * Note: Both data and extended_data should always be set in a valid frame,
114  * but for planar audio with more channels that can fit in data,
115  * extended_data must be used in order to access all channels.
116  */
118 
119  /**
120  * width and height of the video frame
121  */
122  int width, height;
123 
124  /**
125  * number of audio samples (per channel) described by this frame
126  */
128 
129  /**
130  * format of the frame, -1 if unknown or unset
131  * Values correspond to enum AVPixelFormat for video frames,
132  * enum AVSampleFormat for audio)
133  */
134  int format;
135 
136  /**
137  * 1 -> keyframe, 0-> not
138  */
140 
141  /**
142  * Picture type of the frame.
143  */
145 
146 #if FF_API_AVFRAME_LAVC
149 #endif
150 
151  /**
152  * Sample aspect ratio for the video frame, 0/1 if unknown/unspecified.
153  */
155 
156  /**
157  * Presentation timestamp in time_base units (time when frame should be shown to user).
158  */
159  int64_t pts;
160 
161  /**
162  * PTS copied from the AVPacket that was decoded to produce this frame.
163  */
164  int64_t pkt_pts;
165 
166  /**
167  * DTS copied from the AVPacket that triggered returning this frame. (if frame threading isnt used)
168  * This is also the Presentation time of this AVFrame calculated from
169  * only AVPacket.dts values without pts values.
170  */
171  int64_t pkt_dts;
172 
173  /**
174  * picture number in bitstream order
175  */
177  /**
178  * picture number in display order
179  */
181 
182  /**
183  * quality (between 1 (good) and FF_LAMBDA_MAX (bad))
184  */
185  int quality;
186 
187 #if FF_API_AVFRAME_LAVC
190 
191  /**
192  * QP table
193  */
195  int8_t *qscale_table;
196  /**
197  * QP store stride
198  */
200  int qstride;
201 
204 
205  /**
206  * mbskip_table[mb]>=1 if MB didn't change
207  * stride= mb_width = (width+15)>>4
208  */
211 
212  /**
213  * motion vector table
214  * @code
215  * example:
216  * int mv_sample_log2= 4 - motion_subsample_log2;
217  * int mb_width= (width+15)>>4;
218  * int mv_stride= (mb_width << mv_sample_log2) + 1;
219  * motion_val[direction][x + y*mv_stride][0->mv_x, 1->mv_y];
220  * @endcode
221  */
223  int16_t (*motion_val[2])[2];
224 
225  /**
226  * macroblock type table
227  * mb_type_base + mb_width + 2
228  */
230  uint32_t *mb_type;
231 
232  /**
233  * DCT coefficients
234  */
236  short *dct_coeff;
237 
238  /**
239  * motion reference frame index
240  * the order in which these are stored can depend on the codec.
241  */
243  int8_t *ref_index[2];
244 #endif
245 
246  /**
247  * for some private data of the user
248  */
249  void *opaque;
250 
251  /**
252  * error
253  */
255 
256 #if FF_API_AVFRAME_LAVC
258  int type;
259 #endif
260 
261  /**
262  * When decoding, this signals how much the picture must be delayed.
263  * extra_delay = repeat_pict / (2*fps)
264  */
266 
267  /**
268  * The content of the picture is interlaced.
269  */
271 
272  /**
273  * If the content is interlaced, is top field displayed first.
274  */
276 
277  /**
278  * Tell user application that palette has changed from previous frame.
279  */
281 
282 #if FF_API_AVFRAME_LAVC
285 
286  /**
287  * Pan scan.
288  */
291 #endif
292 
293  /**
294  * reordered opaque 64bit (generally an integer or a double precision float
295  * PTS but can be anything).
296  * The user sets AVCodecContext.reordered_opaque to represent the input at
297  * that time,
298  * the decoder reorders values as needed and sets AVFrame.reordered_opaque
299  * to exactly one of the values provided by the user through AVCodecContext.reordered_opaque
300  * @deprecated in favor of pkt_pts
301  */
303 
304 #if FF_API_AVFRAME_LAVC
305  /**
306  * @deprecated this field is unused
307  */
309 
314 
315  /**
316  * log2 of the size of the block which a single vector in motion_val represents:
317  * (4->16x16, 3->8x8, 2-> 4x4, 1-> 2x2)
318  */
321 #endif
322 
323  /**
324  * Sample rate of the audio data.
325  */
327 
328  /**
329  * Channel layout of the audio data.
330  */
331  uint64_t channel_layout;
332 
333  /**
334  * AVBuffer references backing the data for this frame. If all elements of
335  * this array are NULL, then this frame is not reference counted.
336  *
337  * There may be at most one AVBuffer per data plane, so for video this array
338  * always contains all the references. For planar audio with more than
339  * AV_NUM_DATA_POINTERS channels, there may be more buffers than can fit in
340  * this array. Then the extra AVBufferRef pointers are stored in the
341  * extended_buf array.
342  */
344 
345  /**
346  * For planar audio which requires more than AV_NUM_DATA_POINTERS
347  * AVBufferRef pointers, this array will hold all the references which
348  * cannot fit into AVFrame.buf.
349  *
350  * Note that this is different from AVFrame.extended_data, which always
351  * contains all the pointers. This array only contains the extra pointers,
352  * which cannot fit into AVFrame.buf.
353  *
354  * This array is always allocated using av_malloc() by whoever constructs
355  * the frame. It is freed in av_frame_unref().
356  */
358  /**
359  * Number of elements in extended_buf.
360  */
362 
365 
366  /**
367  * frame timestamp estimated using various heuristics, in stream time base
368  * Code outside libavcodec should access this field using:
369  * av_frame_get_best_effort_timestamp(frame)
370  * - encoding: unused
371  * - decoding: set by libavcodec, read by user.
372  */
374 
375  /**
376  * reordered pos from the last AVPacket that has been input into the decoder
377  * Code outside libavcodec should access this field using:
378  * av_frame_get_pkt_pos(frame)
379  * - encoding: unused
380  * - decoding: Read by user.
381  */
382  int64_t pkt_pos;
383 
384  /**
385  * duration of the corresponding packet, expressed in
386  * AVStream->time_base units, 0 if unknown.
387  * Code outside libavcodec should access this field using:
388  * av_frame_get_pkt_duration(frame)
389  * - encoding: unused
390  * - decoding: Read by user.
391  */
392  int64_t pkt_duration;
393 
394  /**
395  * metadata.
396  * Code outside libavcodec should access this field using:
397  * av_frame_get_metadata(frame)
398  * - encoding: Set by user.
399  * - decoding: Set by libavcodec.
400  */
402 
403  /**
404  * decode error flags of the frame, set to a combination of
405  * FF_DECODE_ERROR_xxx flags if the decoder produced a frame, but there
406  * were errors during the decoding.
407  * Code outside libavcodec should access this field using:
408  * av_frame_get_decode_error_flags(frame)
409  * - encoding: unused
410  * - decoding: set by libavcodec, read by user.
411  */
413 #define FF_DECODE_ERROR_INVALID_BITSTREAM 1
414 #define FF_DECODE_ERROR_MISSING_REFERENCE 2
415 
416  /**
417  * number of audio channels, only used for audio.
418  * Code outside libavcodec should access this field using:
419  * av_frame_get_channels(frame)
420  * - encoding: unused
421  * - decoding: Read by user.
422  */
423  int channels;
424 
425  /**
426  * size of the corresponding packet containing the compressed
427  * frame. It must be accessed using av_frame_get_pkt_size() and
428  * av_frame_set_pkt_size().
429  * It is set to a negative value if unknown.
430  * - encoding: unused
431  * - decoding: set by libavcodec, read by user.
432  */
433  int pkt_size;
434 
435  /**
436  * Not to be accessed directly from outside libavutil
437  */
439 } AVFrame;
440 
441 /**
442  * Accessors for some AVFrame fields.
443  * The position of these field in the structure is not part of the ABI,
444  * they should not be accessed directly outside libavcodec.
445  */
448 int64_t av_frame_get_pkt_duration (const AVFrame *frame);
449 void av_frame_set_pkt_duration (AVFrame *frame, int64_t val);
450 int64_t av_frame_get_pkt_pos (const AVFrame *frame);
451 void av_frame_set_pkt_pos (AVFrame *frame, int64_t val);
452 int64_t av_frame_get_channel_layout (const AVFrame *frame);
454 int av_frame_get_channels (const AVFrame *frame);
465 int8_t *av_frame_get_qp_table(AVFrame *f, int *stride, int *type);
466 int av_frame_set_qp_table(AVFrame *f, AVBufferRef *buf, int stride, int type);
467 
468 /**
469  * Allocate an AVFrame and set its fields to default values. The resulting
470  * struct must be freed using av_frame_free().
471  *
472  * @return An AVFrame filled with default values or NULL on failure.
473  *
474  * @note this only allocates the AVFrame itself, not the data buffers. Those
475  * must be allocated through other means, e.g. with av_frame_get_buffer() or
476  * manually.
477  */
478 AVFrame *av_frame_alloc(void);
479 
480 /**
481  * Free the frame and any dynamically allocated objects in it,
482  * e.g. extended_data. If the frame is reference counted, it will be
483  * unreferenced first.
484  *
485  * @param frame frame to be freed. The pointer will be set to NULL.
486  */
487 void av_frame_free(AVFrame **frame);
488 
489 /**
490  * Setup a new reference to the data described by an given frame.
491  *
492  * Copy frame properties from src to dst and create a new reference for each
493  * AVBufferRef from src.
494  *
495  * If src is not reference counted, new buffers are allocated and the data is
496  * copied.
497  *
498  * @return 0 on success, a negative AVERROR on error
499  */
500 int av_frame_ref(AVFrame *dst, AVFrame *src);
501 
502 /**
503  * Create a new frame that references the same data as src.
504  *
505  * This is a shortcut for av_frame_alloc()+av_frame_ref().
506  *
507  * @return newly created AVFrame on success, NULL on error.
508  */
510 
511 /**
512  * Unreference all the buffers referenced by frame and reset the frame fields.
513  */
515 
516 /**
517  * Move everythnig contained in src to dst and reset src.
518  */
519 void av_frame_move_ref(AVFrame *dst, AVFrame *src);
520 
521 /**
522  * Allocate new buffer(s) for audio or video data.
523  *
524  * The following fields must be set on frame before calling this function:
525  * - format (pixel format for video, sample format for audio)
526  * - width and height for video
527  * - nb_samples and channel_layout for audio
528  *
529  * This function will fill AVFrame.data and AVFrame.buf arrays and, if
530  * necessary, allocate and fill AVFrame.extended_data and AVFrame.extended_buf.
531  * For planar formats, one buffer will be allocated for each plane.
532  *
533  * @param frame frame in which to store the new buffers.
534  * @param align required buffer size alignment
535  *
536  * @return 0 on success, a negative AVERROR on error.
537  */
539 
540 /**
541  * Check if the frame data is writable.
542  *
543  * @return A positive value if the frame data is writable (which is true if and
544  * only if each of the underlying buffers has only one reference, namely the one
545  * stored in this frame). Return 0 otherwise.
546  *
547  * If 1 is returned the answer is valid until av_buffer_ref() is called on any
548  * of the underlying AVBufferRefs (e.g. through av_frame_ref() or directly).
549  *
550  * @see av_frame_make_writable(), av_buffer_is_writable()
551  */
553 
554 /**
555  * Ensure that the frame data is writable, avoiding data copy if possible.
556  *
557  * Do nothing if the frame is writable, allocate new buffers and copy the data
558  * if it is not.
559  *
560  * @return 0 on success, a negative AVERROR on error.
561  *
562  * @see av_frame_is_writable(), av_buffer_is_writable(),
563  * av_buffer_make_writable()
564  */
566 
567 /**
568  * Copy only "metadata" fields from src to dst.
569  *
570  * Metadata for the purpose of this function are those fields that do not affect
571  * the data layout in the buffers. E.g. pts, sample rate (for audio) or sample
572  * aspect ratio (for video), but not width/height or channel layout.
573  * Side data is also copied.
574  */
575 int av_frame_copy_props(AVFrame *dst, const AVFrame *src);
576 
577 /**
578  * Get the buffer reference a given data plane is stored in.
579  *
580  * @param plane index of the data plane of interest in frame->extended_data.
581  *
582  * @return the buffer reference that contains the plane or NULL if the input
583  * frame is not valid.
584  */
586 
587 /**
588  * Add a new side data to a frame.
589  *
590  * @param frame a frame to which the side data should be added
591  * @param type type of the added side data
592  * @param size size of the side data
593  *
594  * @return newly added side data on success, NULL on error
595  */
597  enum AVFrameSideDataType type,
598  int size);
599 
600 /**
601  * @return a pointer to the side data of a given type on success, NULL if there
602  * is no side data with such type in this frame.
603  */
605  enum AVFrameSideDataType type);
606 
607 #endif /* AVUTIL_FRAME_H */