doxy: Document better the available AVFrame flags
[ffmpeg.git] / libavutil / frame.h
1 /*
2  *
3  * This file is part of Libav.
4  *
5  * Libav 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  * Libav 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 Libav; 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 "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
69 typedef struct AVFrameSideData {
70     enum AVFrameSideDataType type;
71     uint8_t *data;
72     int      size;
73     AVDictionary *metadata;
74 } AVFrameSideData;
75
76 /**
77  * This structure describes decoded (raw) audio or video data.
78  *
79  * AVFrame must be allocated using av_frame_alloc(). Note that this only
80  * allocates the AVFrame itself, the buffers for the data must be managed
81  * through other means (see below).
82  * AVFrame must be freed with av_frame_free().
83  *
84  * AVFrame is typically allocated once and then reused multiple times to hold
85  * different data (e.g. a single AVFrame to hold frames received from a
86  * decoder). In such a case, av_frame_unref() will free any references held by
87  * the frame and reset it to its original clean state before it
88  * is reused again.
89  *
90  * The data described by an AVFrame is usually reference counted through the
91  * AVBuffer API. The underlying buffer references are stored in AVFrame.buf /
92  * AVFrame.extended_buf. An AVFrame is considered to be reference counted if at
93  * least one reference is set, i.e. if AVFrame.buf[0] != NULL. In such a case,
94  * every single data plane must be contained in one of the buffers in
95  * AVFrame.buf or AVFrame.extended_buf.
96  * There may be a single buffer for all the data, or one separate buffer for
97  * each plane, or anything in between.
98  *
99  * sizeof(AVFrame) is not a part of the public ABI, so new fields may be added
100  * to the end with a minor bump.
101  */
102 typedef struct AVFrame {
103 #define AV_NUM_DATA_POINTERS 8
104     /**
105      * pointer to the picture/channel planes.
106      * This might be different from the first allocated byte
107      */
108     uint8_t *data[AV_NUM_DATA_POINTERS];
109
110     /**
111      * For video, size in bytes of each picture line.
112      * For audio, size in bytes of each plane.
113      *
114      * For audio, only linesize[0] may be set. For planar audio, each channel
115      * plane must be the same size.
116      *
117      * @note The linesize may be larger than the size of usable data -- there
118      * may be extra padding present for performance reasons.
119      */
120     int linesize[AV_NUM_DATA_POINTERS];
121
122     /**
123      * pointers to the data planes/channels.
124      *
125      * For video, this should simply point to data[].
126      *
127      * For planar audio, each channel has a separate data pointer, and
128      * linesize[0] contains the size of each channel buffer.
129      * For packed audio, there is just one data pointer, and linesize[0]
130      * contains the total size of the buffer for all channels.
131      *
132      * Note: Both data and extended_data should always be set in a valid frame,
133      * but for planar audio with more channels that can fit in data,
134      * extended_data must be used in order to access all channels.
135      */
136     uint8_t **extended_data;
137
138     /**
139      * width and height of the video frame
140      */
141     int width, height;
142
143     /**
144      * number of audio samples (per channel) described by this frame
145      */
146     int nb_samples;
147
148     /**
149      * format of the frame, -1 if unknown or unset
150      * Values correspond to enum AVPixelFormat for video frames,
151      * enum AVSampleFormat for audio)
152      */
153     int format;
154
155     /**
156      * 1 -> keyframe, 0-> not
157      */
158     int key_frame;
159
160     /**
161      * Picture type of the frame.
162      */
163     enum AVPictureType pict_type;
164
165 #if FF_API_AVFRAME_LAVC
166     attribute_deprecated
167     uint8_t *base[AV_NUM_DATA_POINTERS];
168 #endif
169
170     /**
171      * Sample aspect ratio for the video frame, 0/1 if unknown/unspecified.
172      */
173     AVRational sample_aspect_ratio;
174
175     /**
176      * Presentation timestamp in time_base units (time when frame should be shown to user).
177      */
178     int64_t pts;
179
180     /**
181      * PTS copied from the AVPacket that was decoded to produce this frame.
182      */
183     int64_t pkt_pts;
184
185     /**
186      * DTS copied from the AVPacket that triggered returning this frame.
187      */
188     int64_t pkt_dts;
189
190     /**
191      * picture number in bitstream order
192      */
193     int coded_picture_number;
194     /**
195      * picture number in display order
196      */
197     int display_picture_number;
198
199     /**
200      * quality (between 1 (good) and FF_LAMBDA_MAX (bad))
201      */
202     int quality;
203
204 #if FF_API_AVFRAME_LAVC
205     attribute_deprecated
206     int reference;
207
208     /**
209      * QP table
210      */
211     attribute_deprecated
212     int8_t *qscale_table;
213     /**
214      * QP store stride
215      */
216     attribute_deprecated
217     int qstride;
218
219     attribute_deprecated
220     int qscale_type;
221
222     /**
223      * mbskip_table[mb]>=1 if MB didn't change
224      * stride= mb_width = (width+15)>>4
225      */
226     attribute_deprecated
227     uint8_t *mbskip_table;
228
229     /**
230      * motion vector table
231      * @code
232      * example:
233      * int mv_sample_log2= 4 - motion_subsample_log2;
234      * int mb_width= (width+15)>>4;
235      * int mv_stride= (mb_width << mv_sample_log2) + 1;
236      * motion_val[direction][x + y*mv_stride][0->mv_x, 1->mv_y];
237      * @endcode
238      */
239     attribute_deprecated
240     int16_t (*motion_val[2])[2];
241
242     /**
243      * macroblock type table
244      * mb_type_base + mb_width + 2
245      */
246     attribute_deprecated
247     uint32_t *mb_type;
248
249     /**
250      * DCT coefficients
251      */
252     attribute_deprecated
253     short *dct_coeff;
254
255     /**
256      * motion reference frame index
257      * the order in which these are stored can depend on the codec.
258      */
259     attribute_deprecated
260     int8_t *ref_index[2];
261 #endif
262
263     /**
264      * for some private data of the user
265      */
266     void *opaque;
267
268     /**
269      * error
270      */
271     uint64_t error[AV_NUM_DATA_POINTERS];
272
273 #if FF_API_AVFRAME_LAVC
274     attribute_deprecated
275     int type;
276 #endif
277
278     /**
279      * When decoding, this signals how much the picture must be delayed.
280      * extra_delay = repeat_pict / (2*fps)
281      */
282     int repeat_pict;
283
284     /**
285      * The content of the picture is interlaced.
286      */
287     int interlaced_frame;
288
289     /**
290      * If the content is interlaced, is top field displayed first.
291      */
292     int top_field_first;
293
294     /**
295      * Tell user application that palette has changed from previous frame.
296      */
297     int palette_has_changed;
298
299 #if FF_API_AVFRAME_LAVC
300     attribute_deprecated
301     int buffer_hints;
302
303     /**
304      * Pan scan.
305      */
306     attribute_deprecated
307     struct AVPanScan *pan_scan;
308 #endif
309
310     /**
311      * reordered opaque 64bit (generally an integer or a double precision float
312      * PTS but can be anything).
313      * The user sets AVCodecContext.reordered_opaque to represent the input at
314      * that time,
315      * the decoder reorders values as needed and sets AVFrame.reordered_opaque
316      * to exactly one of the values provided by the user through AVCodecContext.reordered_opaque
317      * @deprecated in favor of pkt_pts
318      */
319     int64_t reordered_opaque;
320
321 #if FF_API_AVFRAME_LAVC
322     /**
323      * @deprecated this field is unused
324      */
325     attribute_deprecated void *hwaccel_picture_private;
326
327     attribute_deprecated
328     struct AVCodecContext *owner;
329     attribute_deprecated
330     void *thread_opaque;
331
332     /**
333      * log2 of the size of the block which a single vector in motion_val represents:
334      * (4->16x16, 3->8x8, 2-> 4x4, 1-> 2x2)
335      */
336     attribute_deprecated
337     uint8_t motion_subsample_log2;
338 #endif
339
340     /**
341      * Sample rate of the audio data.
342      */
343     int sample_rate;
344
345     /**
346      * Channel layout of the audio data.
347      */
348     uint64_t channel_layout;
349
350     /**
351      * AVBuffer references backing the data for this frame. If all elements of
352      * this array are NULL, then this frame is not reference counted.
353      *
354      * There may be at most one AVBuffer per data plane, so for video this array
355      * always contains all the references. For planar audio with more than
356      * AV_NUM_DATA_POINTERS channels, there may be more buffers than can fit in
357      * this array. Then the extra AVBufferRef pointers are stored in the
358      * extended_buf array.
359      */
360     AVBufferRef *buf[AV_NUM_DATA_POINTERS];
361
362     /**
363      * For planar audio which requires more than AV_NUM_DATA_POINTERS
364      * AVBufferRef pointers, this array will hold all the references which
365      * cannot fit into AVFrame.buf.
366      *
367      * Note that this is different from AVFrame.extended_data, which always
368      * contains all the pointers. This array only contains the extra pointers,
369      * which cannot fit into AVFrame.buf.
370      *
371      * This array is always allocated using av_malloc() by whoever constructs
372      * the frame. It is freed in av_frame_unref().
373      */
374     AVBufferRef **extended_buf;
375     /**
376      * Number of elements in extended_buf.
377      */
378     int        nb_extended_buf;
379
380     AVFrameSideData **side_data;
381     int            nb_side_data;
382
383 /**
384  * @defgroup lavu_frame_flags AV_FRAME_FLAGS
385  * Flags describing additional frame properties.
386  *
387  * @{
388  */
389
390 /**
391  * The frame data may be corrupted, e.g. due to decoding errors.
392  */
393 #define AV_FRAME_FLAG_CORRUPT       (1 << 0)
394 /**
395  * @}
396  */
397
398     /**
399      * Frame flags, a combination of @ref lavu_frame_flags
400      */
401     int flags;
402 } AVFrame;
403
404 /**
405  * Allocate an AVFrame and set its fields to default values.  The resulting
406  * struct must be freed using av_frame_free().
407  *
408  * @return An AVFrame filled with default values or NULL on failure.
409  *
410  * @note this only allocates the AVFrame itself, not the data buffers. Those
411  * must be allocated through other means, e.g. with av_frame_get_buffer() or
412  * manually.
413  */
414 AVFrame *av_frame_alloc(void);
415
416 /**
417  * Free the frame and any dynamically allocated objects in it,
418  * e.g. extended_data. If the frame is reference counted, it will be
419  * unreferenced first.
420  *
421  * @param frame frame to be freed. The pointer will be set to NULL.
422  */
423 void av_frame_free(AVFrame **frame);
424
425 /**
426  * Setup a new reference to the data described by an given frame.
427  *
428  * Copy frame properties from src to dst and create a new reference for each
429  * AVBufferRef from src.
430  *
431  * If src is not reference counted, new buffers are allocated and the data is
432  * copied.
433  *
434  * @return 0 on success, a negative AVERROR on error
435  */
436 int av_frame_ref(AVFrame *dst, const AVFrame *src);
437
438 /**
439  * Create a new frame that references the same data as src.
440  *
441  * This is a shortcut for av_frame_alloc()+av_frame_ref().
442  *
443  * @return newly created AVFrame on success, NULL on error.
444  */
445 AVFrame *av_frame_clone(const AVFrame *src);
446
447 /**
448  * Unreference all the buffers referenced by frame and reset the frame fields.
449  */
450 void av_frame_unref(AVFrame *frame);
451
452 /**
453  * Move everythnig contained in src to dst and reset src.
454  */
455 void av_frame_move_ref(AVFrame *dst, AVFrame *src);
456
457 /**
458  * Allocate new buffer(s) for audio or video data.
459  *
460  * The following fields must be set on frame before calling this function:
461  * - format (pixel format for video, sample format for audio)
462  * - width and height for video
463  * - nb_samples and channel_layout for audio
464  *
465  * This function will fill AVFrame.data and AVFrame.buf arrays and, if
466  * necessary, allocate and fill AVFrame.extended_data and AVFrame.extended_buf.
467  * For planar formats, one buffer will be allocated for each plane.
468  *
469  * @param frame frame in which to store the new buffers.
470  * @param align required buffer size alignment
471  *
472  * @return 0 on success, a negative AVERROR on error.
473  */
474 int av_frame_get_buffer(AVFrame *frame, int align);
475
476 /**
477  * Check if the frame data is writable.
478  *
479  * @return A positive value if the frame data is writable (which is true if and
480  * only if each of the underlying buffers has only one reference, namely the one
481  * stored in this frame). Return 0 otherwise.
482  *
483  * If 1 is returned the answer is valid until av_buffer_ref() is called on any
484  * of the underlying AVBufferRefs (e.g. through av_frame_ref() or directly).
485  *
486  * @see av_frame_make_writable(), av_buffer_is_writable()
487  */
488 int av_frame_is_writable(AVFrame *frame);
489
490 /**
491  * Ensure that the frame data is writable, avoiding data copy if possible.
492  *
493  * Do nothing if the frame is writable, allocate new buffers and copy the data
494  * if it is not.
495  *
496  * @return 0 on success, a negative AVERROR on error.
497  *
498  * @see av_frame_is_writable(), av_buffer_is_writable(),
499  * av_buffer_make_writable()
500  */
501 int av_frame_make_writable(AVFrame *frame);
502
503 /**
504  * Copy only "metadata" fields from src to dst.
505  *
506  * Metadata for the purpose of this function are those fields that do not affect
507  * the data layout in the buffers.  E.g. pts, sample rate (for audio) or sample
508  * aspect ratio (for video), but not width/height or channel layout.
509  * Side data is also copied.
510  */
511 int av_frame_copy_props(AVFrame *dst, const AVFrame *src);
512
513 /**
514  * Get the buffer reference a given data plane is stored in.
515  *
516  * @param plane index of the data plane of interest in frame->extended_data.
517  *
518  * @return the buffer reference that contains the plane or NULL if the input
519  * frame is not valid.
520  */
521 AVBufferRef *av_frame_get_plane_buffer(AVFrame *frame, int plane);
522
523 /**
524  * Add a new side data to a frame.
525  *
526  * @param frame a frame to which the side data should be added
527  * @param type type of the added side data
528  * @param size size of the side data
529  *
530  * @return newly added side data on success, NULL on error
531  */
532 AVFrameSideData *av_frame_new_side_data(AVFrame *frame,
533                                         enum AVFrameSideDataType type,
534                                         int size);
535
536 /**
537  * @return a pointer to the side data of a given type on success, NULL if there
538  * is no side data with such type in this frame.
539  */
540 AVFrameSideData *av_frame_get_side_data(const AVFrame *frame,
541                                         enum AVFrameSideDataType type);
542
543 /**
544  * @}
545  */
546
547 #endif /* AVUTIL_FRAME_H */