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  /**
146  * Timecode which conforms to SMPTE ST 12-1. The data is an array of 4 uint32_t
147  * where the first uint32_t describes how many (1-3) of the other timecodes are used.
148  * The timecode format is described in the documentation of av_timecode_get_smpte_from_framenum()
149  * function in libavutil/timecode.h.
150  */
152 
153  /**
154  * HDR dynamic metadata associated with a video frame. The payload is
155  * an AVDynamicHDRPlus type and contains information for color
156  * volume transform - application 4 of SMPTE 2094-40:2016 standard.
157  */
159 
160  /**
161  * Regions Of Interest, the data is an array of AVRegionOfInterest type, the number of
162  * array element is implied by AVFrameSideData.size / AVRegionOfInterest.self_size.
163  */
165 
166  /**
167  * Encoding parameters for a video frame, as described by AVVideoEncParams.
168  */
170 
171  /**
172  * User data unregistered metadata associated with a video frame.
173  * This is the H.26[45] UDU SEI message, and shouldn't be used for any other purpose
174  * The data is stored as uint8_t in AVFrameSideData.data which is 16 bytes of
175  * uuid_iso_iec_11578 followed by AVFrameSideData.size - 16 bytes of user_data_payload_byte.
176  */
178 
179  /**
180  * Film grain parameters for a frame, described by AVFilmGrainParams.
181  * Must be present for every frame which should have film grain applied.
182  */
184 
185  /**
186  * Bounding boxes for object detection and classification,
187  * as described by AVDetectionBBoxHeader.
188  */
190 
191  /**
192  * Dolby Vision RPU data, suitable for passing to x265
193  * or other libraries. Array of uint8_t, with NAL emulation
194  * bytes intact.
195  */
197 };
198 
207 };
208 
209 
210 /**
211  * Structure to hold side data for an AVFrame.
212  *
213  * sizeof(AVFrameSideData) is not a part of the public ABI, so new fields may be added
214  * to the end with a minor bump.
215  */
216 typedef struct AVFrameSideData {
218  uint8_t *data;
219  size_t size;
223 
224 /**
225  * Structure describing a single Region Of Interest.
226  *
227  * When multiple regions are defined in a single side-data block, they
228  * should be ordered from most to least important - some encoders are only
229  * capable of supporting a limited number of distinct regions, so will have
230  * to truncate the list.
231  *
232  * When overlapping regions are defined, the first region containing a given
233  * area of the frame applies.
234  */
235 typedef struct AVRegionOfInterest {
236  /**
237  * Must be set to the size of this data structure (that is,
238  * sizeof(AVRegionOfInterest)).
239  */
240  uint32_t self_size;
241  /**
242  * Distance in pixels from the top edge of the frame to the top and
243  * bottom edges and from the left edge of the frame to the left and
244  * right edges of the rectangle defining this region of interest.
245  *
246  * The constraints on a region are encoder dependent, so the region
247  * actually affected may be slightly larger for alignment or other
248  * reasons.
249  */
250  int top;
251  int bottom;
252  int left;
253  int right;
254  /**
255  * Quantisation offset.
256  *
257  * Must be in the range -1 to +1. A value of zero indicates no quality
258  * change. A negative value asks for better quality (less quantisation),
259  * while a positive value asks for worse quality (greater quantisation).
260  *
261  * The range is calibrated so that the extreme values indicate the
262  * largest possible offset - if the rest of the frame is encoded with the
263  * worst possible quality, an offset of -1 indicates that this region
264  * should be encoded with the best possible quality anyway. Intermediate
265  * values are then interpolated in some codec-dependent way.
266  *
267  * For example, in 10-bit H.264 the quantisation parameter varies between
268  * -12 and 51. A typical qoffset value of -1/10 therefore indicates that
269  * this region should be encoded with a QP around one-tenth of the full
270  * range better than the rest of the frame. So, if most of the frame
271  * were to be encoded with a QP of around 30, this region would get a QP
272  * of around 24 (an offset of approximately -1/10 * (51 - -12) = -6.3).
273  * An extreme value of -1 would indicate that this region should be
274  * encoded with the best possible quality regardless of the treatment of
275  * the rest of the frame - that is, should be encoded at a QP of -12.
276  */
279 
280 /**
281  * This structure describes decoded (raw) audio or video data.
282  *
283  * AVFrame must be allocated using av_frame_alloc(). Note that this only
284  * allocates the AVFrame itself, the buffers for the data must be managed
285  * through other means (see below).
286  * AVFrame must be freed with av_frame_free().
287  *
288  * AVFrame is typically allocated once and then reused multiple times to hold
289  * different data (e.g. a single AVFrame to hold frames received from a
290  * decoder). In such a case, av_frame_unref() will free any references held by
291  * the frame and reset it to its original clean state before it
292  * is reused again.
293  *
294  * The data described by an AVFrame is usually reference counted through the
295  * AVBuffer API. The underlying buffer references are stored in AVFrame.buf /
296  * AVFrame.extended_buf. An AVFrame is considered to be reference counted if at
297  * least one reference is set, i.e. if AVFrame.buf[0] != NULL. In such a case,
298  * every single data plane must be contained in one of the buffers in
299  * AVFrame.buf or AVFrame.extended_buf.
300  * There may be a single buffer for all the data, or one separate buffer for
301  * each plane, or anything in between.
302  *
303  * sizeof(AVFrame) is not a part of the public ABI, so new fields may be added
304  * to the end with a minor bump.
305  *
306  * Fields can be accessed through AVOptions, the name string used, matches the
307  * C structure field name for fields accessible through AVOptions. The AVClass
308  * for AVFrame can be obtained from avcodec_get_frame_class()
309  */
310 typedef struct AVFrame {
311 #define AV_NUM_DATA_POINTERS 8
312  /**
313  * pointer to the picture/channel planes.
314  * This might be different from the first allocated byte. For video,
315  * it could even point to the end of the image data.
316  *
317  * Some decoders access areas outside 0,0 - width,height, please
318  * see avcodec_align_dimensions2(). Some filters and swscale can read
319  * up to 16 bytes beyond the planes, if these filters are to be used,
320  * then 16 extra bytes must be allocated.
321  *
322  * NOTE: Except for hwaccel formats, pointers not needed by the format
323  * MUST be set to NULL.
324  *
325  * @attention In case of video, the data[] pointers can point to the
326  * end of image data in order to reverse line order, when used in
327  * combination with negative values in the linesize[] array.
328  */
330 
331  /**
332  * For video, a positive or negative value, which is typically indicating
333  * the size in bytes of each picture line, but it can also be:
334  * - the negative byte size of lines for vertical flipping
335  * (with data[n] pointing to the end of the data
336  * - a positive or negative multiple of the byte size as for accessing
337  * even and odd fields of a frame (possibly flipped)
338  *
339  * For audio, only linesize[0] may be set. For planar audio, each channel
340  * plane must be the same size.
341  *
342  * For video the linesizes should be multiples of the CPUs alignment
343  * preference, this is 16 or 32 for modern desktop CPUs.
344  * Some code requires such alignment other code can be slower without
345  * correct alignment, for yet other it makes no difference.
346  *
347  * @note The linesize may be larger than the size of usable data -- there
348  * may be extra padding present for performance reasons.
349  *
350  * @attention In case of video, line size values can be negative to achieve
351  * a vertically inverted iteration over image lines.
352  */
354 
355  /**
356  * pointers to the data planes/channels.
357  *
358  * For video, this should simply point to data[].
359  *
360  * For planar audio, each channel has a separate data pointer, and
361  * linesize[0] contains the size of each channel buffer.
362  * For packed audio, there is just one data pointer, and linesize[0]
363  * contains the total size of the buffer for all channels.
364  *
365  * Note: Both data and extended_data should always be set in a valid frame,
366  * but for planar audio with more channels that can fit in data,
367  * extended_data must be used in order to access all channels.
368  */
369  uint8_t **extended_data;
370 
371  /**
372  * @name Video dimensions
373  * Video frames only. The coded dimensions (in pixels) of the video frame,
374  * i.e. the size of the rectangle that contains some well-defined values.
375  *
376  * @note The part of the frame intended for display/presentation is further
377  * restricted by the @ref cropping "Cropping rectangle".
378  * @{
379  */
380  int width, height;
381  /**
382  * @}
383  */
384 
385  /**
386  * number of audio samples (per channel) described by this frame
387  */
389 
390  /**
391  * format of the frame, -1 if unknown or unset
392  * Values correspond to enum AVPixelFormat for video frames,
393  * enum AVSampleFormat for audio)
394  */
395  int format;
396 
397  /**
398  * 1 -> keyframe, 0-> not
399  */
401 
402  /**
403  * Picture type of the frame.
404  */
406 
407  /**
408  * Sample aspect ratio for the video frame, 0/1 if unknown/unspecified.
409  */
411 
412  /**
413  * Presentation timestamp in time_base units (time when frame should be shown to user).
414  */
415  int64_t pts;
416 
417  /**
418  * DTS copied from the AVPacket that triggered returning this frame. (if frame threading isn't used)
419  * This is also the Presentation time of this AVFrame calculated from
420  * only AVPacket.dts values without pts values.
421  */
422  int64_t pkt_dts;
423 
424  /**
425  * picture number in bitstream order
426  */
428  /**
429  * picture number in display order
430  */
432 
433  /**
434  * quality (between 1 (good) and FF_LAMBDA_MAX (bad))
435  */
436  int quality;
437 
438  /**
439  * for some private data of the user
440  */
441  void *opaque;
442 
443  /**
444  * When decoding, this signals how much the picture must be delayed.
445  * extra_delay = repeat_pict / (2*fps)
446  */
448 
449  /**
450  * The content of the picture is interlaced.
451  */
453 
454  /**
455  * If the content is interlaced, is top field displayed first.
456  */
458 
459  /**
460  * Tell user application that palette has changed from previous frame.
461  */
463 
464  /**
465  * reordered opaque 64 bits (generally an integer or a double precision float
466  * PTS but can be anything).
467  * The user sets AVCodecContext.reordered_opaque to represent the input at
468  * that time,
469  * the decoder reorders values as needed and sets AVFrame.reordered_opaque
470  * to exactly one of the values provided by the user through AVCodecContext.reordered_opaque
471  */
473 
474  /**
475  * Sample rate of the audio data.
476  */
478 
479  /**
480  * Channel layout of the audio data.
481  */
482  uint64_t channel_layout;
483 
484  /**
485  * AVBuffer references backing the data for this frame. If all elements of
486  * this array are NULL, then this frame is not reference counted. This array
487  * must be filled contiguously -- if buf[i] is non-NULL then buf[j] must
488  * also be non-NULL for all j < i.
489  *
490  * There may be at most one AVBuffer per data plane, so for video this array
491  * always contains all the references. For planar audio with more than
492  * AV_NUM_DATA_POINTERS channels, there may be more buffers than can fit in
493  * this array. Then the extra AVBufferRef pointers are stored in the
494  * extended_buf array.
495  */
497 
498  /**
499  * For planar audio which requires more than AV_NUM_DATA_POINTERS
500  * AVBufferRef pointers, this array will hold all the references which
501  * cannot fit into AVFrame.buf.
502  *
503  * Note that this is different from AVFrame.extended_data, which always
504  * contains all the pointers. This array only contains the extra pointers,
505  * which cannot fit into AVFrame.buf.
506  *
507  * This array is always allocated using av_malloc() by whoever constructs
508  * the frame. It is freed in av_frame_unref().
509  */
511  /**
512  * Number of elements in extended_buf.
513  */
515 
518 
519 /**
520  * @defgroup lavu_frame_flags AV_FRAME_FLAGS
521  * @ingroup lavu_frame
522  * Flags describing additional frame properties.
523  *
524  * @{
525  */
526 
527 /**
528  * The frame data may be corrupted, e.g. due to decoding errors.
529  */
530 #define AV_FRAME_FLAG_CORRUPT (1 << 0)
531 /**
532  * A flag to mark the frames which need to be decoded, but shouldn't be output.
533  */
534 #define AV_FRAME_FLAG_DISCARD (1 << 2)
535 /**
536  * @}
537  */
538 
539  /**
540  * Frame flags, a combination of @ref lavu_frame_flags
541  */
542  int flags;
543 
544  /**
545  * MPEG vs JPEG YUV range.
546  * - encoding: Set by user
547  * - decoding: Set by libavcodec
548  */
550 
552 
554 
555  /**
556  * YUV colorspace type.
557  * - encoding: Set by user
558  * - decoding: Set by libavcodec
559  */
561 
563 
564  /**
565  * frame timestamp estimated using various heuristics, in stream time base
566  * - encoding: unused
567  * - decoding: set by libavcodec, read by user.
568  */
570 
571  /**
572  * reordered pos from the last AVPacket that has been input into the decoder
573  * - encoding: unused
574  * - decoding: Read by user.
575  */
576  int64_t pkt_pos;
577 
578  /**
579  * duration of the corresponding packet, expressed in
580  * AVStream->time_base units, 0 if unknown.
581  * - encoding: unused
582  * - decoding: Read by user.
583  */
584  int64_t pkt_duration;
585 
586  /**
587  * metadata.
588  * - encoding: Set by user.
589  * - decoding: Set by libavcodec.
590  */
592 
593  /**
594  * decode error flags of the frame, set to a combination of
595  * FF_DECODE_ERROR_xxx flags if the decoder produced a frame, but there
596  * were errors during the decoding.
597  * - encoding: unused
598  * - decoding: set by libavcodec, read by user.
599  */
601 #define FF_DECODE_ERROR_INVALID_BITSTREAM 1
602 #define FF_DECODE_ERROR_MISSING_REFERENCE 2
603 #define FF_DECODE_ERROR_CONCEALMENT_ACTIVE 4
604 #define FF_DECODE_ERROR_DECODE_SLICES 8
605 
606  /**
607  * number of audio channels, only used for audio.
608  * - encoding: unused
609  * - decoding: Read by user.
610  */
611  int channels;
612 
613  /**
614  * size of the corresponding packet containing the compressed
615  * frame.
616  * It is set to a negative value if unknown.
617  * - encoding: unused
618  * - decoding: set by libavcodec, read by user.
619  */
620  int pkt_size;
621 
622  /**
623  * For hwaccel-format frames, this should be a reference to the
624  * AVHWFramesContext describing the frame.
625  */
627 
628  /**
629  * AVBufferRef for free use by the API user. FFmpeg will never check the
630  * contents of the buffer ref. FFmpeg calls av_buffer_unref() on it when
631  * the frame is unreferenced. av_frame_copy_props() calls create a new
632  * reference with av_buffer_ref() for the target frame's opaque_ref field.
633  *
634  * This is unrelated to the opaque field, although it serves a similar
635  * purpose.
636  */
638 
639  /**
640  * @anchor cropping
641  * @name Cropping
642  * Video frames only. The number of pixels to discard from the the
643  * top/bottom/left/right border of the frame to obtain the sub-rectangle of
644  * the frame intended for presentation.
645  * @{
646  */
647  size_t crop_top;
648  size_t crop_bottom;
649  size_t crop_left;
650  size_t crop_right;
651  /**
652  * @}
653  */
654 
655  /**
656  * AVBufferRef for internal use by a single libav* library.
657  * Must not be used to transfer data between libraries.
658  * Has to be NULL when ownership of the frame leaves the respective library.
659  *
660  * Code outside the FFmpeg libs should never check or change the contents of the buffer ref.
661  *
662  * FFmpeg calls av_buffer_unref() on it when the frame is unreferenced.
663  * av_frame_copy_props() calls create a new reference with av_buffer_ref()
664  * for the target frame's private_ref field.
665  */
667 } AVFrame;
668 
669 
670 #if FF_API_COLORSPACE_NAME
671 /**
672  * Get the name of a colorspace.
673  * @return a static string identifying the colorspace; can be NULL.
674  * @deprecated use av_color_space_name()
675  */
677 const char *av_get_colorspace_name(enum AVColorSpace val);
678 #endif
679 /**
680  * Allocate an AVFrame and set its fields to default values. The resulting
681  * struct must be freed using av_frame_free().
682  *
683  * @return An AVFrame filled with default values or NULL on failure.
684  *
685  * @note this only allocates the AVFrame itself, not the data buffers. Those
686  * must be allocated through other means, e.g. with av_frame_get_buffer() or
687  * manually.
688  */
689 AVFrame *av_frame_alloc(void);
690 
691 /**
692  * Free the frame and any dynamically allocated objects in it,
693  * e.g. extended_data. If the frame is reference counted, it will be
694  * unreferenced first.
695  *
696  * @param frame frame to be freed. The pointer will be set to NULL.
697  */
698 void av_frame_free(AVFrame **frame);
699 
700 /**
701  * Set up a new reference to the data described by the source frame.
702  *
703  * Copy frame properties from src to dst and create a new reference for each
704  * AVBufferRef from src.
705  *
706  * If src is not reference counted, new buffers are allocated and the data is
707  * copied.
708  *
709  * @warning: dst MUST have been either unreferenced with av_frame_unref(dst),
710  * or newly allocated with av_frame_alloc() before calling this
711  * function, or undefined behavior will occur.
712  *
713  * @return 0 on success, a negative AVERROR on error
714  */
715 int av_frame_ref(AVFrame *dst, const AVFrame *src);
716 
717 /**
718  * Create a new frame that references the same data as src.
719  *
720  * This is a shortcut for av_frame_alloc()+av_frame_ref().
721  *
722  * @return newly created AVFrame on success, NULL on error.
723  */
725 
726 /**
727  * Unreference all the buffers referenced by frame and reset the frame fields.
728  */
730 
731 /**
732  * Move everything contained in src to dst and reset src.
733  *
734  * @warning: dst is not unreferenced, but directly overwritten without reading
735  * or deallocating its contents. Call av_frame_unref(dst) manually
736  * before calling this function to ensure that no memory is leaked.
737  */
738 void av_frame_move_ref(AVFrame *dst, AVFrame *src);
739 
740 /**
741  * Allocate new buffer(s) for audio or video data.
742  *
743  * The following fields must be set on frame before calling this function:
744  * - format (pixel format for video, sample format for audio)
745  * - width and height for video
746  * - nb_samples and channel_layout for audio
747  *
748  * This function will fill AVFrame.data and AVFrame.buf arrays and, if
749  * necessary, allocate and fill AVFrame.extended_data and AVFrame.extended_buf.
750  * For planar formats, one buffer will be allocated for each plane.
751  *
752  * @warning: if frame already has been allocated, calling this function will
753  * leak memory. In addition, undefined behavior can occur in certain
754  * cases.
755  *
756  * @param frame frame in which to store the new buffers.
757  * @param align Required buffer size alignment. If equal to 0, alignment will be
758  * chosen automatically for the current CPU. It is highly
759  * recommended to pass 0 here unless you know what you are doing.
760  *
761  * @return 0 on success, a negative AVERROR on error.
762  */
763 int av_frame_get_buffer(AVFrame *frame, int align);
764 
765 /**
766  * Check if the frame data is writable.
767  *
768  * @return A positive value if the frame data is writable (which is true if and
769  * only if each of the underlying buffers has only one reference, namely the one
770  * stored in this frame). Return 0 otherwise.
771  *
772  * If 1 is returned the answer is valid until av_buffer_ref() is called on any
773  * of the underlying AVBufferRefs (e.g. through av_frame_ref() or directly).
774  *
775  * @see av_frame_make_writable(), av_buffer_is_writable()
776  */
778 
779 /**
780  * Ensure that the frame data is writable, avoiding data copy if possible.
781  *
782  * Do nothing if the frame is writable, allocate new buffers and copy the data
783  * if it is not.
784  *
785  * @return 0 on success, a negative AVERROR on error.
786  *
787  * @see av_frame_is_writable(), av_buffer_is_writable(),
788  * av_buffer_make_writable()
789  */
791 
792 /**
793  * Copy the frame data from src to dst.
794  *
795  * This function does not allocate anything, dst must be already initialized and
796  * allocated with the same parameters as src.
797  *
798  * This function only copies the frame data (i.e. the contents of the data /
799  * extended data arrays), not any other properties.
800  *
801  * @return >= 0 on success, a negative AVERROR on error.
802  */
803 int av_frame_copy(AVFrame *dst, const AVFrame *src);
804 
805 /**
806  * Copy only "metadata" fields from src to dst.
807  *
808  * Metadata for the purpose of this function are those fields that do not affect
809  * the data layout in the buffers. E.g. pts, sample rate (for audio) or sample
810  * aspect ratio (for video), but not width/height or channel layout.
811  * Side data is also copied.
812  */
813 int av_frame_copy_props(AVFrame *dst, const AVFrame *src);
814 
815 /**
816  * Get the buffer reference a given data plane is stored in.
817  *
818  * @param plane index of the data plane of interest in frame->extended_data.
819  *
820  * @return the buffer reference that contains the plane or NULL if the input
821  * frame is not valid.
822  */
824 
825 /**
826  * Add a new side data to a frame.
827  *
828  * @param frame a frame to which the side data should be added
829  * @param type type of the added side data
830  * @param size size of the side data
831  *
832  * @return newly added side data on success, NULL on error
833  */
836  size_t size);
837 
838 /**
839  * Add a new side data to a frame from an existing AVBufferRef
840  *
841  * @param frame a frame to which the side data should be added
842  * @param type the type of the added side data
843  * @param buf an AVBufferRef to add as side data. The ownership of
844  * the reference is transferred to the frame.
845  *
846  * @return newly added side data on success, NULL on error. On failure
847  * the frame is unchanged and the AVBufferRef remains owned by
848  * the caller.
849  */
852  AVBufferRef *buf);
853 
854 /**
855  * @return a pointer to the side data of a given type on success, NULL if there
856  * is no side data with such type in this frame.
857  */
860 
861 /**
862  * Remove and free all side data instances of the given type.
863  */
865 
866 
867 /**
868  * Flags for frame cropping.
869  */
870 enum {
871  /**
872  * Apply the maximum possible cropping, even if it requires setting the
873  * AVFrame.data[] entries to unaligned pointers. Passing unaligned data
874  * to FFmpeg API is generally not allowed, and causes undefined behavior
875  * (such as crashes). You can pass unaligned data only to FFmpeg APIs that
876  * are explicitly documented to accept it. Use this flag only if you
877  * absolutely know what you are doing.
878  */
880 };
881 
882 /**
883  * Crop the given video AVFrame according to its crop_left/crop_top/crop_right/
884  * crop_bottom fields. If cropping is successful, the function will adjust the
885  * data pointers and the width/height fields, and set the crop fields to 0.
886  *
887  * In all cases, the cropping boundaries will be rounded to the inherent
888  * alignment of the pixel format. In some cases, such as for opaque hwaccel
889  * formats, the left/top cropping is ignored. The crop fields are set to 0 even
890  * if the cropping was rounded or ignored.
891  *
892  * @param frame the frame which should be cropped
893  * @param flags Some combination of AV_FRAME_CROP_* flags, or 0.
894  *
895  * @return >= 0 on success, a negative AVERROR on error. If the cropping fields
896  * were invalid, AVERROR(ERANGE) is returned, and nothing is changed.
897  */
899 
900 /**
901  * @return a string identifying the side data type
902  */
904 
905 /**
906  * @}
907  */
908 
909 #endif /* AVUTIL_FRAME_H */
AVFrame::extended_buf
AVBufferRef ** extended_buf
For planar audio which requires more than AV_NUM_DATA_POINTERS AVBufferRef pointers,...
Definition: frame.h:510
AVFrame::color_trc
enum AVColorTransferCharacteristic color_trc
Definition: frame.h:553
AV_AFD_14_9
@ AV_AFD_14_9
Definition: frame.h:203
AVFrame::color_range
enum AVColorRange color_range
MPEG vs JPEG YUV range.
Definition: frame.h:549
AVColorTransferCharacteristic
AVColorTransferCharacteristic
Color Transfer Characteristic.
Definition: pixfmt.h:494
av_frame_get_buffer
int av_frame_get_buffer(AVFrame *frame, int align)
Allocate new buffer(s) for audio or video data.
Definition: frame.c:246
av_frame_get_side_data
AVFrameSideData * av_frame_get_side_data(const AVFrame *frame, enum AVFrameSideDataType type)
Definition: frame.c:617
av_frame_new_side_data
AVFrameSideData * av_frame_new_side_data(AVFrame *frame, enum AVFrameSideDataType type, size_t size)
Add a new side data to a frame.
Definition: frame.c:605
AV_FRAME_DATA_A53_CC
@ AV_FRAME_DATA_A53_CC
ATSC A53 Part 4 Closed Captions.
Definition: frame.h:58
AVFrame::nb_side_data
int nb_side_data
Definition: frame.h:517
AVPictureType
AVPictureType
Definition: avutil.h:272
rational.h
AVFrame::coded_picture_number
int coded_picture_number
picture number in bitstream order
Definition: frame.h:427
AV_FRAME_DATA_FILM_GRAIN_PARAMS
@ AV_FRAME_DATA_FILM_GRAIN_PARAMS
Film grain parameters for a frame, described by AVFilmGrainParams.
Definition: frame.h:183
AVFrame::color_primaries
enum AVColorPrimaries color_primaries
Definition: frame.h:551
AV_FRAME_DATA_S12M_TIMECODE
@ AV_FRAME_DATA_S12M_TIMECODE
Timecode which conforms to SMPTE ST 12-1.
Definition: frame.h:151
av_frame_free
void av_frame_free(AVFrame **frame)
Free the frame and any dynamically allocated objects in it, e.g.
Definition: frame.c:112
AVFrame::opaque
void * opaque
for some private data of the user
Definition: frame.h:441
AVFrame::colorspace
enum AVColorSpace colorspace
YUV colorspace type.
Definition: frame.h:560
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:310
av_frame_make_writable
int av_frame_make_writable(AVFrame *frame)
Ensure that the frame data is writable, avoiding data copy if possible.
Definition: frame.c:490
AVFrameSideData::buf
AVBufferRef * buf
Definition: frame.h:221
AVFrame::pts
int64_t pts
Presentation timestamp in time_base units (time when frame should be shown to user).
Definition: frame.h:415
AVFrame::width
int width
Definition: frame.h:380
AVFrame::top_field_first
int top_field_first
If the content is interlaced, is top field displayed first.
Definition: frame.h:457
AV_FRAME_DATA_DOVI_RPU_BUFFER
@ AV_FRAME_DATA_DOVI_RPU_BUFFER
Dolby Vision RPU data, suitable for passing to x265 or other libraries.
Definition: frame.h:196
AVFrame::pkt_duration
int64_t pkt_duration
duration of the corresponding packet, expressed in AVStream->time_base units, 0 if unknown.
Definition: frame.h:584
AV_FRAME_CROP_UNALIGNED
@ AV_FRAME_CROP_UNALIGNED
Apply the maximum possible cropping, even if it requires setting the AVFrame.data[] entries to unalig...
Definition: frame.h:879
AV_FRAME_DATA_DISPLAYMATRIX
@ AV_FRAME_DATA_DISPLAYMATRIX
This side data contains a 3x3 transformation matrix describing an affine transformation that needs to...
Definition: frame.h:84
AV_AFD_16_9
@ AV_AFD_16_9
Definition: frame.h:202
AVDictionary
Definition: dict.c:30
AVFrame::flags
int flags
Frame flags, a combination of AV_FRAME_FLAGS.
Definition: frame.h:542
AVColorPrimaries
AVColorPrimaries
Chromaticity coordinates of the source primaries.
Definition: pixfmt.h:469
AVFrame::buf
AVBufferRef * buf[AV_NUM_DATA_POINTERS]
AVBuffer references backing the data for this frame.
Definition: frame.h:496
av_frame_apply_cropping
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:768
AVFrame::data
uint8_t * data[AV_NUM_DATA_POINTERS]
pointer to the picture/channel planes.
Definition: frame.h:329
AVFrame::opaque_ref
AVBufferRef * opaque_ref
AVBufferRef for free use by the API user.
Definition: frame.h:637
AVFrame::chroma_location
enum AVChromaLocation chroma_location
Definition: frame.h:562
AV_AFD_SAME
@ AV_AFD_SAME
Definition: frame.h:200
AV_FRAME_DATA_MATRIXENCODING
@ AV_FRAME_DATA_MATRIXENCODING
The data is the AVMatrixEncoding enum defined in libavutil/channel_layout.h.
Definition: frame.h:67
samplefmt.h
AVFrame::key_frame
int key_frame
1 -> keyframe, 0-> not
Definition: frame.h:400
val
static double val(void *priv, double ch)
Definition: aeval.c:76
type
it s the only field you need to keep assuming you have a context There is some magic you don t need to care about around this just let it vf type
Definition: writing_filters.txt:86
AVFrameSideDataType
AVFrameSideDataType
Definition: frame.h:48
av_frame_alloc
AVFrame * av_frame_alloc(void)
Allocate an AVFrame and set its fields to default values.
Definition: frame.c:99
AVFrameSideData::size
size_t size
Definition: frame.h:219
AVRegionOfInterest
Structure describing a single Region Of Interest.
Definition: frame.h:235
AVRegionOfInterest::bottom
int bottom
Definition: frame.h:251
AVFrame::channels
int channels
number of audio channels, only used for audio.
Definition: frame.h:611
AVFrame::pkt_pos
int64_t pkt_pos
reordered pos from the last AVPacket that has been input into the decoder
Definition: frame.h:576
AV_FRAME_DATA_AUDIO_SERVICE_TYPE
@ AV_FRAME_DATA_AUDIO_SERVICE_TYPE
This side data must be associated with an audio frame and corresponds to enum AVAudioServiceType defi...
Definition: frame.h:113
AV_AFD_SP_4_3
@ AV_AFD_SP_4_3
Definition: frame.h:206
av_frame_clone
AVFrame * av_frame_clone(const AVFrame *src)
Create a new frame that references the same data as src.
Definition: frame.c:424
AVFrame::crop_right
size_t crop_right
Definition: frame.h:650
AV_FRAME_DATA_SPHERICAL
@ AV_FRAME_DATA_SPHERICAL
The data represents the AVSphericalMapping structure defined in libavutil/spherical....
Definition: frame.h:130
av_frame_copy_props
int av_frame_copy_props(AVFrame *dst, const AVFrame *src)
Copy only "metadata" fields from src to dst.
Definition: frame.c:537
AVRational
Rational number (pair of numerator and denominator).
Definition: rational.h:58
AVRegionOfInterest::self_size
uint32_t self_size
Must be set to the size of this data structure (that is, sizeof(AVRegionOfInterest)).
Definition: frame.h:240
AVActiveFormatDescription
AVActiveFormatDescription
Definition: frame.h:199
src
#define src
Definition: vp8dsp.c:255
AV_FRAME_DATA_ICC_PROFILE
@ AV_FRAME_DATA_ICC_PROFILE
The data contains an ICC profile as an opaque octet buffer following the format described by ISO 1507...
Definition: frame.h:143
AV_FRAME_DATA_MASTERING_DISPLAY_METADATA
@ AV_FRAME_DATA_MASTERING_DISPLAY_METADATA
Mastering display metadata associated with a video frame.
Definition: frame.h:119
av_frame_new_side_data_from_buf
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:573
AVFrame::pkt_dts
int64_t pkt_dts
DTS copied from the AVPacket that triggered returning this frame.
Definition: frame.h:422
AV_FRAME_DATA_AFD
@ AV_FRAME_DATA_AFD
Active Format Description data consisting of a single byte as specified in ETSI TS 101 154 using AVAc...
Definition: frame.h:89
AV_AFD_4_3_SP_14_9
@ AV_AFD_4_3_SP_14_9
Definition: frame.h:204
AV_FRAME_DATA_SEI_UNREGISTERED
@ AV_FRAME_DATA_SEI_UNREGISTERED
User data unregistered metadata associated with a video frame.
Definition: frame.h:177
AVFrame::crop_bottom
size_t crop_bottom
Definition: frame.h:648
AVFrame::best_effort_timestamp
int64_t best_effort_timestamp
frame timestamp estimated using various heuristics, in stream time base
Definition: frame.h:569
AVFrame::crop_left
size_t crop_left
Definition: frame.h:649
AVFrame::pict_type
enum AVPictureType pict_type
Picture type of the frame.
Definition: frame.h:405
AV_FRAME_DATA_REPLAYGAIN
@ AV_FRAME_DATA_REPLAYGAIN
ReplayGain information in the form of the AVReplayGain struct.
Definition: frame.h:76
AV_FRAME_DATA_PANSCAN
@ AV_FRAME_DATA_PANSCAN
The data is the AVPanScan struct defined in libavcodec.
Definition: frame.h:52
av_frame_ref
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:327
av_frame_copy
int av_frame_copy(AVFrame *dst, const AVFrame *src)
Copy the frame data from src to dst.
Definition: frame.c:678
AVFrame::quality
int quality
quality (between 1 (good) and FF_LAMBDA_MAX (bad))
Definition: frame.h:436
AVFrame::sample_rate
int sample_rate
Sample rate of the audio data.
Definition: frame.h:477
size
int size
Definition: twinvq_data.h:10344
AV_NUM_DATA_POINTERS
#define AV_NUM_DATA_POINTERS
Definition: frame.h:311
av_get_colorspace_name
const attribute_deprecated char * av_get_colorspace_name(enum AVColorSpace val)
Get the name of a colorspace.
Definition: frame.c:37
AVFrameSideData::data
uint8_t * data
Definition: frame.h:218
av_frame_is_writable
int av_frame_is_writable(AVFrame *frame)
Check if the frame data is writable.
Definition: frame.c:473
AVFrame::format
int format
format of the frame, -1 if unknown or unset Values correspond to enum AVPixelFormat for video frames,...
Definition: frame.h:395
buffer.h
attribute_deprecated
#define attribute_deprecated
Definition: attributes.h:104
av_frame_remove_side_data
void av_frame_remove_side_data(AVFrame *frame, enum AVFrameSideDataType type)
Remove and free all side data instances of the given type.
Definition: frame.c:691
AVFrame::channel_layout
uint64_t channel_layout
Channel layout of the audio data.
Definition: frame.h:482
AVRegionOfInterest::right
int right
Definition: frame.h:253
AVFrame::private_ref
AVBufferRef * private_ref
AVBufferRef for internal use by a single libav* library.
Definition: frame.h:666
AV_FRAME_DATA_SKIP_SAMPLES
@ AV_FRAME_DATA_SKIP_SAMPLES
Recommmends skipping the specified number of samples.
Definition: frame.h:108
AVChromaLocation
AVChromaLocation
Location of chroma samples.
Definition: pixfmt.h:616
AVFrame::interlaced_frame
int interlaced_frame
The content of the picture is interlaced.
Definition: frame.h:452
AVRegionOfInterest::left
int left
Definition: frame.h:252
AVFrame::nb_samples
int nb_samples
number of audio samples (per channel) described by this frame
Definition: frame.h:388
AV_FRAME_DATA_CONTENT_LIGHT_LEVEL
@ AV_FRAME_DATA_CONTENT_LIGHT_LEVEL
Content light level (based on CTA-861.3).
Definition: frame.h:136
AVRegionOfInterest::top
int top
Distance in pixels from the top edge of the frame to the top and bottom edges and from the left edge ...
Definition: frame.h:250
AVFrame::extended_data
uint8_t ** extended_data
pointers to the data planes/channels.
Definition: frame.h:369
AVColorSpace
AVColorSpace
YUV colorspace type.
Definition: pixfmt.h:523
AV_FRAME_DATA_STEREO3D
@ AV_FRAME_DATA_STEREO3D
Stereoscopic 3d metadata.
Definition: frame.h:63
av_frame_move_ref
void av_frame_move_ref(AVFrame *dst, AVFrame *src)
Move everything contained in src to dst and reset src.
Definition: frame.c:461
av_frame_unref
void av_frame_unref(AVFrame *frame)
Unreference all the buffers referenced by frame and reset the frame fields.
Definition: frame.c:437
AVFrame::side_data
AVFrameSideData ** side_data
Definition: frame.h:516
version.h
AVFrame::decode_error_flags
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:600
AV_FRAME_DATA_GOP_TIMECODE
@ AV_FRAME_DATA_GOP_TIMECODE
The GOP timecode in 25 bit timecode format.
Definition: frame.h:124
pixfmt.h
frame
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
Definition: filter_design.txt:264
dict.h
AVFrame::sample_aspect_ratio
AVRational sample_aspect_ratio
Sample aspect ratio for the video frame, 0/1 if unknown/unspecified.
Definition: frame.h:410
AVFrame::hw_frames_ctx
AVBufferRef * hw_frames_ctx
For hwaccel-format frames, this should be a reference to the AVHWFramesContext describing the frame.
Definition: frame.h:626
AV_FRAME_DATA_DYNAMIC_HDR_PLUS
@ AV_FRAME_DATA_DYNAMIC_HDR_PLUS
HDR dynamic metadata associated with a video frame.
Definition: frame.h:158
AVFrame::height
int height
Definition: frame.h:380
AVFrame::palette_has_changed
int palette_has_changed
Tell user application that palette has changed from previous frame.
Definition: frame.h:462
AV_FRAME_DATA_VIDEO_ENC_PARAMS
@ AV_FRAME_DATA_VIDEO_ENC_PARAMS
Encoding parameters for a video frame, as described by AVVideoEncParams.
Definition: frame.h:169
AVFrame::metadata
AVDictionary * metadata
metadata.
Definition: frame.h:591
AVFrameSideData::type
enum AVFrameSideDataType type
Definition: frame.h:217
AVFrame::pkt_size
int pkt_size
size of the corresponding packet containing the compressed frame.
Definition: frame.h:620
AVFrame::reordered_opaque
int64_t reordered_opaque
reordered opaque 64 bits (generally an integer or a double precision float PTS but can be anything).
Definition: frame.h:472
avutil.h
AVBufferRef
A reference to a data buffer.
Definition: buffer.h:82
AVFrameSideData
Structure to hold side data for an AVFrame.
Definition: frame.h:216
AVFrame::crop_top
size_t crop_top
Definition: frame.h:647
av_frame_side_data_name
const char * av_frame_side_data_name(enum AVFrameSideDataType type)
Definition: frame.c:705
AV_FRAME_DATA_REGIONS_OF_INTEREST
@ AV_FRAME_DATA_REGIONS_OF_INTEREST
Regions Of Interest, the data is an array of AVRegionOfInterest type, the number of array element is ...
Definition: frame.h:164
flags
#define flags(name, subs,...)
Definition: cbs_av1.c:561
AVFrame::linesize
int linesize[AV_NUM_DATA_POINTERS]
For video, a positive or negative value, which is typically indicating the size in bytes of each pict...
Definition: frame.h:353
AVFrameSideData::metadata
AVDictionary * metadata
Definition: frame.h:220
AV_FRAME_DATA_MOTION_VECTORS
@ AV_FRAME_DATA_MOTION_VECTORS
Motion vectors exported by some codecs (on demand through the export_mvs flag set in the libavcodec A...
Definition: frame.h:96
av_frame_get_plane_buffer
AVBufferRef * av_frame_get_plane_buffer(AVFrame *frame, int plane)
Get the buffer reference a given data plane is stored in.
Definition: frame.c:542
AV_AFD_4_3
@ AV_AFD_4_3
Definition: frame.h:201
AVColorRange
AVColorRange
Visual content value range.
Definition: pixfmt.h:562
AVFrame::display_picture_number
int display_picture_number
picture number in display order
Definition: frame.h:431
AVRegionOfInterest::qoffset
AVRational qoffset
Quantisation offset.
Definition: frame.h:277
AV_FRAME_DATA_DOWNMIX_INFO
@ AV_FRAME_DATA_DOWNMIX_INFO
Metadata relevant to a downmix procedure.
Definition: frame.h:72
AVFrame::repeat_pict
int repeat_pict
When decoding, this signals how much the picture must be delayed.
Definition: frame.h:447
AV_FRAME_DATA_DETECTION_BBOXES
@ AV_FRAME_DATA_DETECTION_BBOXES
Bounding boxes for object detection and classification, as described by AVDetectionBBoxHeader.
Definition: frame.h:189
AVFrame::nb_extended_buf
int nb_extended_buf
Number of elements in extended_buf.
Definition: frame.h:514
AV_AFD_16_9_SP_14_9
@ AV_AFD_16_9_SP_14_9
Definition: frame.h:205