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