FFmpeg
frame.h
Go to the documentation of this file.
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 <stddef.h>
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 
49  /**
50  * The data is the AVPanScan struct defined in libavcodec.
51  */
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  */
59  /**
60  * Stereoscopic 3d metadata.
61  * The data is the AVStereo3D struct defined in libavutil/stereo3d.h.
62  */
64  /**
65  * The data is the AVMatrixEncoding enum defined in libavutil/channel_layout.h.
66  */
68  /**
69  * Metadata relevant to a downmix procedure.
70  * The data is the AVDownmixInfo struct defined in libavutil/downmix_info.h.
71  */
73  /**
74  * ReplayGain information in the form of the AVReplayGain struct.
75  */
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  */
85  /**
86  * Active Format Description data consisting of a single byte as specified
87  * in ETSI TS 101 154 using AVActiveFormatDescription enum.
88  */
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  */
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  */
109  /**
110  * This side data must be associated with an audio frame and corresponds to
111  * enum AVAudioServiceType defined in avcodec.h.
112  */
114  /**
115  * Mastering display metadata associated with a video frame. The payload is
116  * an AVMasteringDisplayMetadata type and contains information about the
117  * mastering display color volume.
118  */
120  /**
121  * The GOP timecode in 25 bit timecode format. Data format is 64-bit integer.
122  * This is set on the first frame of a GOP that has a temporal reference of 0.
123  */
125 
126  /**
127  * The data represents the AVSphericalMapping structure defined in
128  * libavutil/spherical.h.
129  */
131 
132  /**
133  * Content light level (based on CTA-861.3). This payload contains data in
134  * the form of the AVContentLightMetadata struct.
135  */
137 
138  /**
139  * The data contains an ICC profile as an opaque octet buffer following the
140  * format described by ISO 15076-1 with an optional name defined in the
141  * metadata key entry "name".
142  */
144 
145 #if FF_API_FRAME_QP
146  /**
147  * Implementation-specific description of the format of AV_FRAME_QP_TABLE_DATA.
148  * The contents of this side data are undocumented and internal; use
149  * av_frame_set_qp_table() and av_frame_get_qp_table() to access this in a
150  * meaningful way instead.
151  */
153 
154  /**
155  * Raw QP table data. Its format is described by
156  * AV_FRAME_DATA_QP_TABLE_PROPERTIES. Use av_frame_set_qp_table() and
157  * av_frame_get_qp_table() to access this instead.
158  */
160 #endif
161 
162  /**
163  * Timecode which conforms to SMPTE ST 12-1. The data is an array of 4 uint32_t
164  * where the first uint32_t describes how many (1-3) of the other timecodes are used.
165  * The timecode format is described in the av_timecode_get_smpte_from_framenum()
166  * function in libavutil/timecode.c.
167  */
169 
170  /**
171  * HDR dynamic metadata associated with a video frame. The payload is
172  * an AVDynamicHDRPlus type and contains information for color
173  * volume transform - application 4 of SMPTE 2094-40:2016 standard.
174  */
176 
177  /**
178  * Regions Of Interest, the data is an array of AVRegionOfInterest type, the number of
179  * array element is implied by AVFrameSideData.size / AVRegionOfInterest.self_size.
180  */
182 };
183 
192 };
193 
194 
195 /**
196  * Structure to hold side data for an AVFrame.
197  *
198  * sizeof(AVFrameSideData) is not a part of the public ABI, so new fields may be added
199  * to the end with a minor bump.
200  */
201 typedef struct AVFrameSideData {
204  int size;
208 
209 /**
210  * Structure to hold Region Of Interest.
211  *
212  * self_size specifies the size of this data structure. This value
213  * should be set to sizeof(AVRegionOfInterest). EINVAL is returned if self_size is zero.
214  *
215  * Number of pixels to discard from the top/bottom/left/right border of
216  * the frame to obtain the region of interest of the frame.
217  * They are encoder dependent and will be extended internally
218  * if the codec requires an alignment.
219  * If the regions overlap, the last value in the list will be used.
220  *
221  * qoffset is quant offset, and base rule here:
222  * returns EINVAL if AVRational.den is zero.
223  * the value (num/den) range is [-1.0, 1.0], clamp to +-1.0 if out of range.
224  * 0 means no picture quality change,
225  * negative offset asks for better quality (and the best with value -1.0),
226  * positive offset asks for worse quality (and the worst with value 1.0).
227  * How to explain/implement the different quilaity requirement is encoder dependent.
228  */
229 typedef struct AVRegionOfInterest {
230  uint32_t self_size;
231  int top;
232  int bottom;
233  int left;
234  int right;
237 
238 /**
239  * This structure describes decoded (raw) audio or video data.
240  *
241  * AVFrame must be allocated using av_frame_alloc(). Note that this only
242  * allocates the AVFrame itself, the buffers for the data must be managed
243  * through other means (see below).
244  * AVFrame must be freed with av_frame_free().
245  *
246  * AVFrame is typically allocated once and then reused multiple times to hold
247  * different data (e.g. a single AVFrame to hold frames received from a
248  * decoder). In such a case, av_frame_unref() will free any references held by
249  * the frame and reset it to its original clean state before it
250  * is reused again.
251  *
252  * The data described by an AVFrame is usually reference counted through the
253  * AVBuffer API. The underlying buffer references are stored in AVFrame.buf /
254  * AVFrame.extended_buf. An AVFrame is considered to be reference counted if at
255  * least one reference is set, i.e. if AVFrame.buf[0] != NULL. In such a case,
256  * every single data plane must be contained in one of the buffers in
257  * AVFrame.buf or AVFrame.extended_buf.
258  * There may be a single buffer for all the data, or one separate buffer for
259  * each plane, or anything in between.
260  *
261  * sizeof(AVFrame) is not a part of the public ABI, so new fields may be added
262  * to the end with a minor bump.
263  *
264  * Fields can be accessed through AVOptions, the name string used, matches the
265  * C structure field name for fields accessible through AVOptions. The AVClass
266  * for AVFrame can be obtained from avcodec_get_frame_class()
267  */
268 typedef struct AVFrame {
269 #define AV_NUM_DATA_POINTERS 8
270  /**
271  * pointer to the picture/channel planes.
272  * This might be different from the first allocated byte
273  *
274  * Some decoders access areas outside 0,0 - width,height, please
275  * see avcodec_align_dimensions2(). Some filters and swscale can read
276  * up to 16 bytes beyond the planes, if these filters are to be used,
277  * then 16 extra bytes must be allocated.
278  *
279  * NOTE: Except for hwaccel formats, pointers not needed by the format
280  * MUST be set to NULL.
281  */
283 
284  /**
285  * For video, size in bytes of each picture line.
286  * For audio, size in bytes of each plane.
287  *
288  * For audio, only linesize[0] may be set. For planar audio, each channel
289  * plane must be the same size.
290  *
291  * For video the linesizes should be multiples of the CPUs alignment
292  * preference, this is 16 or 32 for modern desktop CPUs.
293  * Some code requires such alignment other code can be slower without
294  * correct alignment, for yet other it makes no difference.
295  *
296  * @note The linesize may be larger than the size of usable data -- there
297  * may be extra padding present for performance reasons.
298  */
299  int linesize[AV_NUM_DATA_POINTERS];
300 
301  /**
302  * pointers to the data planes/channels.
303  *
304  * For video, this should simply point to data[].
305  *
306  * For planar audio, each channel has a separate data pointer, and
307  * linesize[0] contains the size of each channel buffer.
308  * For packed audio, there is just one data pointer, and linesize[0]
309  * contains the total size of the buffer for all channels.
310  *
311  * Note: Both data and extended_data should always be set in a valid frame,
312  * but for planar audio with more channels that can fit in data,
313  * extended_data must be used in order to access all channels.
314  */
316 
317  /**
318  * @name Video dimensions
319  * Video frames only. The coded dimensions (in pixels) of the video frame,
320  * i.e. the size of the rectangle that contains some well-defined values.
321  *
322  * @note The part of the frame intended for display/presentation is further
323  * restricted by the @ref cropping "Cropping rectangle".
324  * @{
325  */
326  int width, height;
327  /**
328  * @}
329  */
330 
331  /**
332  * number of audio samples (per channel) described by this frame
333  */
335 
336  /**
337  * format of the frame, -1 if unknown or unset
338  * Values correspond to enum AVPixelFormat for video frames,
339  * enum AVSampleFormat for audio)
340  */
341  int format;
342 
343  /**
344  * 1 -> keyframe, 0-> not
345  */
347 
348  /**
349  * Picture type of the frame.
350  */
351  enum AVPictureType pict_type;
352 
353  /**
354  * Sample aspect ratio for the video frame, 0/1 if unknown/unspecified.
355  */
357 
358  /**
359  * Presentation timestamp in time_base units (time when frame should be shown to user).
360  */
361  int64_t pts;
362 
363 #if FF_API_PKT_PTS
364  /**
365  * PTS copied from the AVPacket that was decoded to produce this frame.
366  * @deprecated use the pts field instead
367  */
369  int64_t pkt_pts;
370 #endif
371 
372  /**
373  * DTS copied from the AVPacket that triggered returning this frame. (if frame threading isn't used)
374  * This is also the Presentation time of this AVFrame calculated from
375  * only AVPacket.dts values without pts values.
376  */
377  int64_t pkt_dts;
378 
379  /**
380  * picture number in bitstream order
381  */
383  /**
384  * picture number in display order
385  */
387 
388  /**
389  * quality (between 1 (good) and FF_LAMBDA_MAX (bad))
390  */
391  int quality;
392 
393  /**
394  * for some private data of the user
395  */
396  void *opaque;
397 
398 #if FF_API_ERROR_FRAME
399  /**
400  * @deprecated unused
401  */
404 #endif
405 
406  /**
407  * When decoding, this signals how much the picture must be delayed.
408  * extra_delay = repeat_pict / (2*fps)
409  */
411 
412  /**
413  * The content of the picture is interlaced.
414  */
416 
417  /**
418  * If the content is interlaced, is top field displayed first.
419  */
421 
422  /**
423  * Tell user application that palette has changed from previous frame.
424  */
426 
427  /**
428  * reordered opaque 64 bits (generally an integer or a double precision float
429  * PTS but can be anything).
430  * The user sets AVCodecContext.reordered_opaque to represent the input at
431  * that time,
432  * the decoder reorders values as needed and sets AVFrame.reordered_opaque
433  * to exactly one of the values provided by the user through AVCodecContext.reordered_opaque
434  */
436 
437  /**
438  * Sample rate of the audio data.
439  */
441 
442  /**
443  * Channel layout of the audio data.
444  */
445  uint64_t channel_layout;
446 
447  /**
448  * AVBuffer references backing the data for this frame. If all elements of
449  * this array are NULL, then this frame is not reference counted. This array
450  * must be filled contiguously -- if buf[i] is non-NULL then buf[j] must
451  * also be non-NULL for all j < i.
452  *
453  * There may be at most one AVBuffer per data plane, so for video this array
454  * always contains all the references. For planar audio with more than
455  * AV_NUM_DATA_POINTERS channels, there may be more buffers than can fit in
456  * this array. Then the extra AVBufferRef pointers are stored in the
457  * extended_buf array.
458  */
460 
461  /**
462  * For planar audio which requires more than AV_NUM_DATA_POINTERS
463  * AVBufferRef pointers, this array will hold all the references which
464  * cannot fit into AVFrame.buf.
465  *
466  * Note that this is different from AVFrame.extended_data, which always
467  * contains all the pointers. This array only contains the extra pointers,
468  * which cannot fit into AVFrame.buf.
469  *
470  * This array is always allocated using av_malloc() by whoever constructs
471  * the frame. It is freed in av_frame_unref().
472  */
474  /**
475  * Number of elements in extended_buf.
476  */
478 
481 
482 /**
483  * @defgroup lavu_frame_flags AV_FRAME_FLAGS
484  * @ingroup lavu_frame
485  * Flags describing additional frame properties.
486  *
487  * @{
488  */
489 
490 /**
491  * The frame data may be corrupted, e.g. due to decoding errors.
492  */
493 #define AV_FRAME_FLAG_CORRUPT (1 << 0)
494 /**
495  * A flag to mark the frames which need to be decoded, but shouldn't be output.
496  */
497 #define AV_FRAME_FLAG_DISCARD (1 << 2)
498 /**
499  * @}
500  */
501 
502  /**
503  * Frame flags, a combination of @ref lavu_frame_flags
504  */
505  int flags;
506 
507  /**
508  * MPEG vs JPEG YUV range.
509  * - encoding: Set by user
510  * - decoding: Set by libavcodec
511  */
513 
515 
517 
518  /**
519  * YUV colorspace type.
520  * - encoding: Set by user
521  * - decoding: Set by libavcodec
522  */
523  enum AVColorSpace colorspace;
524 
525  enum AVChromaLocation chroma_location;
526 
527  /**
528  * frame timestamp estimated using various heuristics, in stream time base
529  * - encoding: unused
530  * - decoding: set by libavcodec, read by user.
531  */
533 
534  /**
535  * reordered pos from the last AVPacket that has been input into the decoder
536  * - encoding: unused
537  * - decoding: Read by user.
538  */
539  int64_t pkt_pos;
540 
541  /**
542  * duration of the corresponding packet, expressed in
543  * AVStream->time_base units, 0 if unknown.
544  * - encoding: unused
545  * - decoding: Read by user.
546  */
547  int64_t pkt_duration;
548 
549  /**
550  * metadata.
551  * - encoding: Set by user.
552  * - decoding: Set by libavcodec.
553  */
555 
556  /**
557  * decode error flags of the frame, set to a combination of
558  * FF_DECODE_ERROR_xxx flags if the decoder produced a frame, but there
559  * were errors during the decoding.
560  * - encoding: unused
561  * - decoding: set by libavcodec, read by user.
562  */
564 #define FF_DECODE_ERROR_INVALID_BITSTREAM 1
565 #define FF_DECODE_ERROR_MISSING_REFERENCE 2
566 #define FF_DECODE_ERROR_CONCEALMENT_ACTIVE 4
567 
568  /**
569  * number of audio channels, only used for audio.
570  * - encoding: unused
571  * - decoding: Read by user.
572  */
573  int channels;
574 
575  /**
576  * size of the corresponding packet containing the compressed
577  * frame.
578  * It is set to a negative value if unknown.
579  * - encoding: unused
580  * - decoding: set by libavcodec, read by user.
581  */
582  int pkt_size;
583 
584 #if FF_API_FRAME_QP
585  /**
586  * QP table
587  */
589  int8_t *qscale_table;
590  /**
591  * QP store stride
592  */
594  int qstride;
595 
598 
601 #endif
602  /**
603  * For hwaccel-format frames, this should be a reference to the
604  * AVHWFramesContext describing the frame.
605  */
607 
608  /**
609  * AVBufferRef for free use by the API user. FFmpeg will never check the
610  * contents of the buffer ref. FFmpeg calls av_buffer_unref() on it when
611  * the frame is unreferenced. av_frame_copy_props() calls create a new
612  * reference with av_buffer_ref() for the target frame's opaque_ref field.
613  *
614  * This is unrelated to the opaque field, although it serves a similar
615  * purpose.
616  */
618 
619  /**
620  * @anchor cropping
621  * @name Cropping
622  * Video frames only. The number of pixels to discard from the the
623  * top/bottom/left/right border of the frame to obtain the sub-rectangle of
624  * the frame intended for presentation.
625  * @{
626  */
627  size_t crop_top;
628  size_t crop_bottom;
629  size_t crop_left;
630  size_t crop_right;
631  /**
632  * @}
633  */
634 
635  /**
636  * AVBufferRef for internal use by a single libav* library.
637  * Must not be used to transfer data between libraries.
638  * Has to be NULL when ownership of the frame leaves the respective library.
639  *
640  * Code outside the FFmpeg libs should never check or change the contents of the buffer ref.
641  *
642  * FFmpeg calls av_buffer_unref() on it when the frame is unreferenced.
643  * av_frame_copy_props() calls create a new reference with av_buffer_ref()
644  * for the target frame's private_ref field.
645  */
647 } AVFrame;
648 
649 #if FF_API_FRAME_GET_SET
650 /**
651  * Accessors for some AVFrame fields. These used to be provided for ABI
652  * compatibility, and do not need to be used anymore.
653  */
659 int64_t av_frame_get_pkt_duration (const AVFrame *frame);
661 void av_frame_set_pkt_duration (AVFrame *frame, int64_t val);
663 int64_t av_frame_get_pkt_pos (const AVFrame *frame);
665 void av_frame_set_pkt_pos (AVFrame *frame, int64_t val);
667 int64_t av_frame_get_channel_layout (const AVFrame *frame);
671 int av_frame_get_channels (const AVFrame *frame);
690 #if FF_API_FRAME_QP
692 int8_t *av_frame_get_qp_table(AVFrame *f, int *stride, int *type);
695 #endif
704 #endif
705 
706 /**
707  * Get the name of a colorspace.
708  * @return a static string identifying the colorspace; can be NULL.
709  */
710 const char *av_get_colorspace_name(enum AVColorSpace val);
711 
712 /**
713  * Allocate an AVFrame and set its fields to default values. The resulting
714  * struct must be freed using av_frame_free().
715  *
716  * @return An AVFrame filled with default values or NULL on failure.
717  *
718  * @note this only allocates the AVFrame itself, not the data buffers. Those
719  * must be allocated through other means, e.g. with av_frame_get_buffer() or
720  * manually.
721  */
722 AVFrame *av_frame_alloc(void);
723 
724 /**
725  * Free the frame and any dynamically allocated objects in it,
726  * e.g. extended_data. If the frame is reference counted, it will be
727  * unreferenced first.
728  *
729  * @param frame frame to be freed. The pointer will be set to NULL.
730  */
731 void av_frame_free(AVFrame **frame);
732 
733 /**
734  * Set up a new reference to the data described by the source frame.
735  *
736  * Copy frame properties from src to dst and create a new reference for each
737  * AVBufferRef from src.
738  *
739  * If src is not reference counted, new buffers are allocated and the data is
740  * copied.
741  *
742  * @warning: dst MUST have been either unreferenced with av_frame_unref(dst),
743  * or newly allocated with av_frame_alloc() before calling this
744  * function, or undefined behavior will occur.
745  *
746  * @return 0 on success, a negative AVERROR on error
747  */
748 int av_frame_ref(AVFrame *dst, const AVFrame *src);
749 
750 /**
751  * Create a new frame that references the same data as src.
752  *
753  * This is a shortcut for av_frame_alloc()+av_frame_ref().
754  *
755  * @return newly created AVFrame on success, NULL on error.
756  */
758 
759 /**
760  * Unreference all the buffers referenced by frame and reset the frame fields.
761  */
763 
764 /**
765  * Move everything contained in src to dst and reset src.
766  *
767  * @warning: dst is not unreferenced, but directly overwritten without reading
768  * or deallocating its contents. Call av_frame_unref(dst) manually
769  * before calling this function to ensure that no memory is leaked.
770  */
771 void av_frame_move_ref(AVFrame *dst, AVFrame *src);
772 
773 /**
774  * Allocate new buffer(s) for audio or video data.
775  *
776  * The following fields must be set on frame before calling this function:
777  * - format (pixel format for video, sample format for audio)
778  * - width and height for video
779  * - nb_samples and channel_layout for audio
780  *
781  * This function will fill AVFrame.data and AVFrame.buf arrays and, if
782  * necessary, allocate and fill AVFrame.extended_data and AVFrame.extended_buf.
783  * For planar formats, one buffer will be allocated for each plane.
784  *
785  * @warning: if frame already has been allocated, calling this function will
786  * leak memory. In addition, undefined behavior can occur in certain
787  * cases.
788  *
789  * @param frame frame in which to store the new buffers.
790  * @param align Required buffer size alignment. If equal to 0, alignment will be
791  * chosen automatically for the current CPU. It is highly
792  * recommended to pass 0 here unless you know what you are doing.
793  *
794  * @return 0 on success, a negative AVERROR on error.
795  */
797 
798 /**
799  * Check if the frame data is writable.
800  *
801  * @return A positive value if the frame data is writable (which is true if and
802  * only if each of the underlying buffers has only one reference, namely the one
803  * stored in this frame). Return 0 otherwise.
804  *
805  * If 1 is returned the answer is valid until av_buffer_ref() is called on any
806  * of the underlying AVBufferRefs (e.g. through av_frame_ref() or directly).
807  *
808  * @see av_frame_make_writable(), av_buffer_is_writable()
809  */
811 
812 /**
813  * Ensure that the frame data is writable, avoiding data copy if possible.
814  *
815  * Do nothing if the frame is writable, allocate new buffers and copy the data
816  * if it is not.
817  *
818  * @return 0 on success, a negative AVERROR on error.
819  *
820  * @see av_frame_is_writable(), av_buffer_is_writable(),
821  * av_buffer_make_writable()
822  */
824 
825 /**
826  * Copy the frame data from src to dst.
827  *
828  * This function does not allocate anything, dst must be already initialized and
829  * allocated with the same parameters as src.
830  *
831  * This function only copies the frame data (i.e. the contents of the data /
832  * extended data arrays), not any other properties.
833  *
834  * @return >= 0 on success, a negative AVERROR on error.
835  */
836 int av_frame_copy(AVFrame *dst, const AVFrame *src);
837 
838 /**
839  * Copy only "metadata" fields from src to dst.
840  *
841  * Metadata for the purpose of this function are those fields that do not affect
842  * the data layout in the buffers. E.g. pts, sample rate (for audio) or sample
843  * aspect ratio (for video), but not width/height or channel layout.
844  * Side data is also copied.
845  */
846 int av_frame_copy_props(AVFrame *dst, const AVFrame *src);
847 
848 /**
849  * Get the buffer reference a given data plane is stored in.
850  *
851  * @param plane index of the data plane of interest in frame->extended_data.
852  *
853  * @return the buffer reference that contains the plane or NULL if the input
854  * frame is not valid.
855  */
857 
858 /**
859  * Add a new side data to a frame.
860  *
861  * @param frame a frame to which the side data should be added
862  * @param type type of the added side data
863  * @param size size of the side data
864  *
865  * @return newly added side data on success, NULL on error
866  */
869  int size);
870 
871 /**
872  * Add a new side data to a frame from an existing AVBufferRef
873  *
874  * @param frame a frame to which the side data should be added
875  * @param type the type of the added side data
876  * @param buf an AVBufferRef to add as side data. The ownership of
877  * the reference is transferred to the frame.
878  *
879  * @return newly added side data on success, NULL on error. On failure
880  * the frame is unchanged and the AVBufferRef remains owned by
881  * the caller.
882  */
885  AVBufferRef *buf);
886 
887 /**
888  * @return a pointer to the side data of a given type on success, NULL if there
889  * is no side data with such type in this frame.
890  */
893 
894 /**
895  * If side data of the supplied type exists in the frame, free it and remove it
896  * from the frame.
897  */
899 
900 
901 /**
902  * Flags for frame cropping.
903  */
904 enum {
905  /**
906  * Apply the maximum possible cropping, even if it requires setting the
907  * AVFrame.data[] entries to unaligned pointers. Passing unaligned data
908  * to FFmpeg API is generally not allowed, and causes undefined behavior
909  * (such as crashes). You can pass unaligned data only to FFmpeg APIs that
910  * are explicitly documented to accept it. Use this flag only if you
911  * absolutely know what you are doing.
912  */
914 };
915 
916 /**
917  * Crop the given video AVFrame according to its crop_left/crop_top/crop_right/
918  * crop_bottom fields. If cropping is successful, the function will adjust the
919  * data pointers and the width/height fields, and set the crop fields to 0.
920  *
921  * In all cases, the cropping boundaries will be rounded to the inherent
922  * alignment of the pixel format. In some cases, such as for opaque hwaccel
923  * formats, the left/top cropping is ignored. The crop fields are set to 0 even
924  * if the cropping was rounded or ignored.
925  *
926  * @param frame the frame which should be cropped
927  * @param flags Some combination of AV_FRAME_CROP_* flags, or 0.
928  *
929  * @return >= 0 on success, a negative AVERROR on error. If the cropping fields
930  * were invalid, AVERROR(ERANGE) is returned, and nothing is changed.
931  */
933 
934 /**
935  * @return a string identifying the side data type
936  */
938 
939 /**
940  * @}
941  */
942 
943 #endif /* AVUTIL_FRAME_H */
int plane
Definition: avisynth_c.h:384
attribute_deprecated int av_frame_set_qp_table(AVFrame *f, AVBufferRef *buf, int stride, int type)
Definition: frame.c:54
const char const char void * val
Definition: avisynth_c.h:863
#define AV_NUM_DATA_POINTERS
Definition: frame.h:269
This structure describes decoded (raw) audio or video data.
Definition: frame.h:268
ptrdiff_t const GLvoid * data
Definition: opengl_enc.c:100
This side data must be associated with an audio frame and corresponds to enum AVAudioServiceType defi...
Definition: frame.h:113
attribute_deprecated int qscale_type
Definition: frame.h:597
int64_t pkt_pos
reordered pos from the last AVPacket that has been input into the decoder
Definition: frame.h:539
attribute_deprecated void av_frame_set_pkt_pos(AVFrame *frame, int64_t val)
AVDictionary * metadata
Definition: frame.h:205
void * opaque
for some private data of the user
Definition: frame.h:396
int nb_extended_buf
Number of elements in extended_buf.
Definition: frame.h:477
Content light level (based on CTA-861.3).
Definition: frame.h:136
Timecode which conforms to SMPTE ST 12-1.
Definition: frame.h:168
int repeat_pict
When decoding, this signals how much the picture must be delayed.
Definition: frame.h:410
Convenience header that includes libavutil&#39;s core.
GLint GLenum type
Definition: opengl_enc.c:104
Mastering display metadata associated with a video frame.
Definition: frame.h:119
attribute_deprecated AVBufferRef * qp_table_buf
Definition: frame.h:600
color_range
void av_frame_move_ref(AVFrame *dst, AVFrame *src)
Move everything contained in src to dst and reset src.
Definition: frame.c:582
size_t crop_bottom
Definition: frame.h:628
attribute_deprecated enum AVColorRange av_frame_get_color_range(const AVFrame *frame)
#define src
Definition: vp8dsp.c:254
attribute_deprecated int8_t * qscale_table
QP table.
Definition: frame.h:589
AVColorTransferCharacteristic
Color Transfer Characteristic.
Definition: pixfmt.h:467
AVRational qoffset
Definition: frame.h:235
AVFrameSideData * av_frame_get_side_data(const AVFrame *frame, enum AVFrameSideDataType type)
Definition: frame.c:734
AVBufferRef * hw_frames_ctx
For hwaccel-format frames, this should be a reference to the AVHWFramesContext describing the frame...
Definition: frame.h:606
Public dictionary API.
uint8_t
attribute_deprecated void av_frame_set_best_effort_timestamp(AVFrame *frame, int64_t val)
AVFrame * av_frame_alloc(void)
Allocate an AVFrame and set its fields to default values.
Definition: frame.c:189
AVColorSpace
YUV colorspace type.
Definition: pixfmt.h:496
size_t crop_left
Definition: frame.h:629
#define f(width, name)
Definition: cbs_vp9.c:255
attribute_deprecated int qstride
QP store stride.
Definition: frame.h:594
attribute_deprecated void av_frame_set_pkt_size(AVFrame *frame, int val)
AVBufferRef * private_ref
AVBufferRef for internal use by a single libav* library.
Definition: frame.h:646
int av_frame_ref(AVFrame *dst, const AVFrame *src)
Set up a new reference to the data described by the source frame.
Definition: frame.c:443
int64_t pts
Presentation timestamp in time_base units (time when frame should be shown to user).
Definition: frame.h:361
AVBufferRef * buf
Definition: frame.h:206
The data is the AVPanScan struct defined in libavcodec.
Definition: frame.h:52
HDR dynamic metadata associated with a video frame.
Definition: frame.h:175
attribute_deprecated void av_frame_set_pkt_duration(AVFrame *frame, int64_t val)
Structure to hold side data for an AVFrame.
Definition: frame.h:201
#define height
AVDictionary * metadata
metadata.
Definition: frame.h:554
int interlaced_frame
The content of the picture is interlaced.
Definition: frame.h:415
AVColorRange
MPEG vs JPEG YUV range.
Definition: pixfmt.h:519
ptrdiff_t size
Definition: opengl_enc.c:100
attribute_deprecated int64_t av_frame_get_channel_layout(const AVFrame *frame)
uint32_t self_size
Definition: frame.h:230
attribute_deprecated int av_frame_get_sample_rate(const AVFrame *frame)
The data represents the AVSphericalMapping structure defined in libavutil/spherical.h.
Definition: frame.h:130
AVColorPrimaries
Chromaticity coordinates of the source primaries.
Definition: pixfmt.h:443
Active Format Description data consisting of a single byte as specified in ETSI TS 101 154 using AVAc...
Definition: frame.h:89
Metadata relevant to a downmix procedure.
Definition: frame.h:72
int nb_side_data
Definition: frame.h:480
AVFrameSideData ** side_data
Definition: frame.h:479
attribute_deprecated int av_frame_get_pkt_size(const AVFrame *frame)
Implementation-specific description of the format of AV_FRAME_QP_TABLE_DATA.
Definition: frame.h:152
int width
Definition: frame.h:326
attribute_deprecated void av_frame_set_decode_error_flags(AVFrame *frame, int val)
attribute_deprecated int64_t av_frame_get_best_effort_timestamp(const AVFrame *frame)
Accessors for some AVFrame fields.
int av_frame_apply_cropping(AVFrame *frame, int flags)
Crop the given video AVFrame according to its crop_left/crop_top/crop_right/ crop_bottom fields...
Definition: frame.c:881
void av_frame_free(AVFrame **frame)
Free the frame and any dynamically allocated objects in it, e.g.
Definition: frame.c:202
attribute_deprecated void av_frame_set_color_range(AVFrame *frame, enum AVColorRange val)
ATSC A53 Part 4 Closed Captions.
Definition: frame.h:58
Libavutil version macros.
The GOP timecode in 25 bit timecode format.
Definition: frame.h:124
attribute_deprecated void av_frame_set_channels(AVFrame *frame, int val)
int av_frame_copy(AVFrame *dst, const AVFrame *src)
Copy the frame data from src to dst.
Definition: frame.c:792
attribute_deprecated AVDictionary * av_frame_get_metadata(const AVFrame *frame)
uint64_t channel_layout
Channel layout of the audio data.
Definition: frame.h:445
size_t crop_top
Definition: frame.h:627
int channels
number of audio channels, only used for audio.
Definition: frame.h:573
int flags
Frame flags, a combination of AV_FRAME_FLAGS.
Definition: frame.h:505
int display_picture_number
picture number in display order
Definition: frame.h:386
AVBufferRef ** extended_buf
For planar audio which requires more than AV_NUM_DATA_POINTERS AVBufferRef pointers, this array will hold all the references which cannot fit into AVFrame.buf.
Definition: frame.h:473
AVFrameSideData * av_frame_new_side_data_from_buf(AVFrame *frame, enum AVFrameSideDataType type, AVBufferRef *buf)
Add a new side data to a frame from an existing AVBufferRef.
Definition: frame.c:690
static const struct ColorPrimaries color_primaries[AVCOL_PRI_NB]
Motion vectors exported by some codecs (on demand through the export_mvs flag set in the libavcodec A...
Definition: frame.h:96
AVBufferRef * av_frame_get_plane_buffer(AVFrame *frame, int plane)
Get the buffer reference a given data plane is stored in.
Definition: frame.c:659
AVFrameSideDataType
Definition: frame.h:48
these buffered frames must be flushed immediately if a new input produces new the filter must not call request_frame to get more It must just process the frame or queue it The task of requesting more frames is left to the filter s request_frame method or the application If a filter has several the filter must be ready for frames arriving randomly on any input any filter with several inputs will most likely require some kind of queuing mechanism It is perfectly acceptable to have a limited queue and to drop frames when the inputs are too unbalanced request_frame For filters that do not use the this method is called when a frame is wanted on an output For a it should directly call filter_frame on the corresponding output For a if there are queued frames already one of these frames should be pushed If the filter should request a frame on one of its repeatedly until at least one frame has been pushed Return or at least make progress towards producing a frame
int quality
quality (between 1 (good) and FF_LAMBDA_MAX (bad))
Definition: frame.h:391
The data contains an ICC profile as an opaque octet buffer following the format described by ISO 1507...
Definition: frame.h:143
Structure to hold Region Of Interest.
Definition: frame.h:229
const char * av_get_colorspace_name(enum AVColorSpace val)
Get the name of a colorspace.
Definition: frame.c:122
static void error(const char *err)
AVFrame * av_frame_clone(const AVFrame *src)
Create a new frame that references the same data as src.
Definition: frame.c:540
attribute_deprecated int64_t av_frame_get_pkt_pos(const AVFrame *frame)
const AVS_VideoInfo int align
Definition: avisynth_c.h:887
int format
format of the frame, -1 if unknown or unset Values correspond to enum AVPixelFormat for video frames...
Definition: frame.h:341
int coded_picture_number
picture number in bitstream order
Definition: frame.h:382
int64_t pkt_duration
duration of the corresponding packet, expressed in AVStream->time_base units, 0 if unknown...
Definition: frame.h:547
Apply the maximum possible cropping, even if it requires setting the AVFrame.data[] entries to unalig...
Definition: frame.h:913
This side data contains a 3x3 transformation matrix describing an affine transformation that needs to...
Definition: frame.h:84
int av_frame_is_writable(AVFrame *frame)
Check if the frame data is writable.
Definition: frame.c:594
attribute_deprecated int64_t av_frame_get_pkt_duration(const AVFrame *frame)
AVRational sample_aspect_ratio
Sample aspect ratio for the video frame, 0/1 if unknown/unspecified.
Definition: frame.h:356
uint8_t * data
Definition: frame.h:203
void av_frame_remove_side_data(AVFrame *frame, enum AVFrameSideDataType type)
If side data of the supplied type exists in the frame, free it and remove it from the frame...
Definition: frame.c:805
size_t crop_right
Definition: frame.h:630
attribute_deprecated void av_frame_set_channel_layout(AVFrame *frame, int64_t val)
int64_t reordered_opaque
reordered opaque 64 bits (generally an integer or a double precision float PTS but can be anything)...
Definition: frame.h:435
attribute_deprecated enum AVColorSpace av_frame_get_colorspace(const AVFrame *frame)
int sample_rate
Sample rate of the audio data.
Definition: frame.h:440
AVFrameSideData * av_frame_new_side_data(AVFrame *frame, enum AVFrameSideDataType type, int size)
Add a new side data to a frame.
Definition: frame.c:722
Rational number (pair of numerator and denominator).
Definition: rational.h:58
Regions Of Interest, the data is an array of AVRegionOfInterest type, the number of array element is ...
Definition: frame.h:181
int palette_has_changed
Tell user application that palette has changed from previous frame.
Definition: frame.h:425
attribute_deprecated void av_frame_set_metadata(AVFrame *frame, AVDictionary *val)
refcounted data buffer API
AVPictureType
Definition: avutil.h:272
int64_t best_effort_timestamp
frame timestamp estimated using various heuristics, in stream time base
Definition: frame.h:532
AVActiveFormatDescription
Definition: frame.h:184
int decode_error_flags
decode error flags of the frame, set to a combination of FF_DECODE_ERROR_xxx flags if the decoder pro...
Definition: frame.h:563
const char * av_frame_side_data_name(enum AVFrameSideDataType type)
Definition: frame.c:819
int av_frame_get_buffer(AVFrame *frame, int align)
Allocate new buffer(s) for audio or video data.
Definition: frame.c:324
void av_frame_unref(AVFrame *frame)
Unreference all the buffers referenced by frame and reset the frame fields.
Definition: frame.c:553
enum AVFrameSideDataType type
Definition: frame.h:202
int av_frame_make_writable(AVFrame *frame)
Ensure that the frame data is writable, avoiding data copy if possible.
Definition: frame.c:611
#define flags(name, subs,...)
Definition: cbs_av1.c:561
#define attribute_deprecated
Definition: attributes.h:94
attribute_deprecated int64_t pkt_pts
PTS copied from the AVPacket that was decoded to produce this frame.
Definition: frame.h:369
int64_t pkt_dts
DTS copied from the AVPacket that triggered returning this frame.
Definition: frame.h:377
A reference to a data buffer.
Definition: buffer.h:81
attribute_deprecated int av_frame_get_channels(const AVFrame *frame)
GLint GLenum GLboolean GLsizei stride
Definition: opengl_enc.c:104
Utilties for rational number calculation.
pixel format definitions
attribute_deprecated void av_frame_set_colorspace(AVFrame *frame, enum AVColorSpace val)
int top_field_first
If the content is interlaced, is top field displayed first.
Definition: frame.h:420
AVBufferRef * opaque_ref
AVBufferRef for free use by the API user.
Definition: frame.h:617
int key_frame
1 -> keyframe, 0-> not
Definition: frame.h:346
attribute_deprecated void av_frame_set_sample_rate(AVFrame *frame, int val)
AVChromaLocation
Location of chroma samples.
Definition: pixfmt.h:541
Recommmends skipping the specified number of samples.
Definition: frame.h:108
ReplayGain information in the form of the AVReplayGain struct.
Definition: frame.h:76
uint8_t ** extended_data
pointers to the data planes/channels.
Definition: frame.h:315
attribute_deprecated int8_t * av_frame_get_qp_table(AVFrame *f, int *stride, int *type)
Definition: frame.c:90
int pkt_size
size of the corresponding packet containing the compressed frame.
Definition: frame.h:582
attribute_deprecated int av_frame_get_decode_error_flags(const AVFrame *frame)
Stereoscopic 3d metadata.
Definition: frame.h:63
int nb_samples
number of audio samples (per channel) described by this frame
Definition: frame.h:334
The data is the AVMatrixEncoding enum defined in libavutil/channel_layout.h.
Definition: frame.h:67
int av_frame_copy_props(AVFrame *dst, const AVFrame *src)
Copy only "metadata" fields from src to dst.
Definition: frame.c:654
Raw QP table data.
Definition: frame.h:159