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