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