1 | /* |
2 | * AVPacket public API |
3 | * |
4 | * This file is part of FFmpeg. |
5 | * |
6 | * FFmpeg is free software; you can redistribute it and/or |
7 | * modify it under the terms of the GNU Lesser General Public |
8 | * License as published by the Free Software Foundation; either |
9 | * version 2.1 of the License, or (at your option) any later version. |
10 | * |
11 | * FFmpeg is distributed in the hope that it will be useful, |
12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | * Lesser General Public License for more details. |
15 | * |
16 | * You should have received a copy of the GNU Lesser General Public |
17 | * License along with FFmpeg; if not, write to the Free Software |
18 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
19 | */ |
20 | |
21 | #ifndef AVCODEC_PACKET_H |
22 | #define AVCODEC_PACKET_H |
23 | |
24 | #include <stddef.h> |
25 | #include <stdint.h> |
26 | |
27 | #include "libavutil/attributes.h" |
28 | #include "libavutil/buffer.h" |
29 | #include "libavutil/dict.h" |
30 | #include "libavutil/rational.h" |
31 | #include "libavutil/version.h" |
32 | |
33 | #include "libavcodec/version_major.h" |
34 | |
35 | /** |
36 | * @defgroup lavc_packet_side_data AVPacketSideData |
37 | * |
38 | * Types and functions for working with AVPacketSideData. |
39 | * @{ |
40 | */ |
41 | enum AVPacketSideDataType { |
42 | /** |
43 | * An AV_PKT_DATA_PALETTE side data packet contains exactly AVPALETTE_SIZE |
44 | * bytes worth of palette. This side data signals that a new palette is |
45 | * present. |
46 | */ |
47 | AV_PKT_DATA_PALETTE, |
48 | |
49 | /** |
50 | * The AV_PKT_DATA_NEW_EXTRADATA is used to notify the codec or the format |
51 | * that the extradata buffer was changed and the receiving side should |
52 | * act upon it appropriately. The new extradata is embedded in the side |
53 | * data buffer and should be immediately used for processing the current |
54 | * frame or packet. |
55 | */ |
56 | , |
57 | |
58 | /** |
59 | * An AV_PKT_DATA_PARAM_CHANGE side data packet is laid out as follows: |
60 | * @code |
61 | * u32le param_flags |
62 | * if (param_flags & AV_SIDE_DATA_PARAM_CHANGE_CHANNEL_COUNT) |
63 | * s32le channel_count |
64 | * if (param_flags & AV_SIDE_DATA_PARAM_CHANGE_CHANNEL_LAYOUT) |
65 | * u64le channel_layout |
66 | * if (param_flags & AV_SIDE_DATA_PARAM_CHANGE_SAMPLE_RATE) |
67 | * s32le sample_rate |
68 | * if (param_flags & AV_SIDE_DATA_PARAM_CHANGE_DIMENSIONS) |
69 | * s32le width |
70 | * s32le height |
71 | * @endcode |
72 | */ |
73 | AV_PKT_DATA_PARAM_CHANGE, |
74 | |
75 | /** |
76 | * An AV_PKT_DATA_H263_MB_INFO side data packet contains a number of |
77 | * structures with info about macroblocks relevant to splitting the |
78 | * packet into smaller packets on macroblock edges (e.g. as for RFC 2190). |
79 | * That is, it does not necessarily contain info about all macroblocks, |
80 | * as long as the distance between macroblocks in the info is smaller |
81 | * than the target payload size. |
82 | * Each MB info structure is 12 bytes, and is laid out as follows: |
83 | * @code |
84 | * u32le bit offset from the start of the packet |
85 | * u8 current quantizer at the start of the macroblock |
86 | * u8 GOB number |
87 | * u16le macroblock address within the GOB |
88 | * u8 horizontal MV predictor |
89 | * u8 vertical MV predictor |
90 | * u8 horizontal MV predictor for block number 3 |
91 | * u8 vertical MV predictor for block number 3 |
92 | * @endcode |
93 | */ |
94 | AV_PKT_DATA_H263_MB_INFO, |
95 | |
96 | /** |
97 | * This side data should be associated with an audio stream and contains |
98 | * ReplayGain information in form of the AVReplayGain struct. |
99 | */ |
100 | AV_PKT_DATA_REPLAYGAIN, |
101 | |
102 | /** |
103 | * This side data contains a 3x3 transformation matrix describing an affine |
104 | * transformation that needs to be applied to the decoded video frames for |
105 | * correct presentation. |
106 | * |
107 | * See libavutil/display.h for a detailed description of the data. |
108 | */ |
109 | AV_PKT_DATA_DISPLAYMATRIX, |
110 | |
111 | /** |
112 | * This side data should be associated with a video stream and contains |
113 | * Stereoscopic 3D information in form of the AVStereo3D struct. |
114 | */ |
115 | AV_PKT_DATA_STEREO3D, |
116 | |
117 | /** |
118 | * This side data should be associated with an audio stream and corresponds |
119 | * to enum AVAudioServiceType. |
120 | */ |
121 | AV_PKT_DATA_AUDIO_SERVICE_TYPE, |
122 | |
123 | /** |
124 | * This side data contains quality related information from the encoder. |
125 | * @code |
126 | * u32le quality factor of the compressed frame. Allowed range is between 1 (good) and FF_LAMBDA_MAX (bad). |
127 | * u8 picture type |
128 | * u8 error count |
129 | * u16 reserved |
130 | * u64le[error count] sum of squared differences between encoder in and output |
131 | * @endcode |
132 | */ |
133 | AV_PKT_DATA_QUALITY_STATS, |
134 | |
135 | /** |
136 | * This side data contains an integer value representing the stream index |
137 | * of a "fallback" track. A fallback track indicates an alternate |
138 | * track to use when the current track can not be decoded for some reason. |
139 | * e.g. no decoder available for codec. |
140 | */ |
141 | AV_PKT_DATA_FALLBACK_TRACK, |
142 | |
143 | /** |
144 | * This side data corresponds to the AVCPBProperties struct. |
145 | */ |
146 | AV_PKT_DATA_CPB_PROPERTIES, |
147 | |
148 | /** |
149 | * Recommmends skipping the specified number of samples |
150 | * @code |
151 | * u32le number of samples to skip from start of this packet |
152 | * u32le number of samples to skip from end of this packet |
153 | * u8 reason for start skip |
154 | * u8 reason for end skip (0=padding silence, 1=convergence) |
155 | * @endcode |
156 | */ |
157 | AV_PKT_DATA_SKIP_SAMPLES, |
158 | |
159 | /** |
160 | * An AV_PKT_DATA_JP_DUALMONO side data packet indicates that |
161 | * the packet may contain "dual mono" audio specific to Japanese DTV |
162 | * and if it is true, recommends only the selected channel to be used. |
163 | * @code |
164 | * u8 selected channels (0=main/left, 1=sub/right, 2=both) |
165 | * @endcode |
166 | */ |
167 | AV_PKT_DATA_JP_DUALMONO, |
168 | |
169 | /** |
170 | * A list of zero terminated key/value strings. There is no end marker for |
171 | * the list, so it is required to rely on the side data size to stop. |
172 | */ |
173 | AV_PKT_DATA_STRINGS_METADATA, |
174 | |
175 | /** |
176 | * Subtitle event position |
177 | * @code |
178 | * u32le x1 |
179 | * u32le y1 |
180 | * u32le x2 |
181 | * u32le y2 |
182 | * @endcode |
183 | */ |
184 | AV_PKT_DATA_SUBTITLE_POSITION, |
185 | |
186 | /** |
187 | * Data found in BlockAdditional element of matroska container. There is |
188 | * no end marker for the data, so it is required to rely on the side data |
189 | * size to recognize the end. 8 byte id (as found in BlockAddId) followed |
190 | * by data. |
191 | */ |
192 | AV_PKT_DATA_MATROSKA_BLOCKADDITIONAL, |
193 | |
194 | /** |
195 | * The optional first identifier line of a WebVTT cue. |
196 | */ |
197 | AV_PKT_DATA_WEBVTT_IDENTIFIER, |
198 | |
199 | /** |
200 | * The optional settings (rendering instructions) that immediately |
201 | * follow the timestamp specifier of a WebVTT cue. |
202 | */ |
203 | AV_PKT_DATA_WEBVTT_SETTINGS, |
204 | |
205 | /** |
206 | * A list of zero terminated key/value strings. There is no end marker for |
207 | * the list, so it is required to rely on the side data size to stop. This |
208 | * side data includes updated metadata which appeared in the stream. |
209 | */ |
210 | AV_PKT_DATA_METADATA_UPDATE, |
211 | |
212 | /** |
213 | * MPEGTS stream ID as uint8_t, this is required to pass the stream ID |
214 | * information from the demuxer to the corresponding muxer. |
215 | */ |
216 | AV_PKT_DATA_MPEGTS_STREAM_ID, |
217 | |
218 | /** |
219 | * Mastering display metadata (based on SMPTE-2086:2014). This metadata |
220 | * should be associated with a video stream and contains data in the form |
221 | * of the AVMasteringDisplayMetadata struct. |
222 | */ |
223 | AV_PKT_DATA_MASTERING_DISPLAY_METADATA, |
224 | |
225 | /** |
226 | * This side data should be associated with a video stream and corresponds |
227 | * to the AVSphericalMapping structure. |
228 | */ |
229 | AV_PKT_DATA_SPHERICAL, |
230 | |
231 | /** |
232 | * Content light level (based on CTA-861.3). This metadata should be |
233 | * associated with a video stream and contains data in the form of the |
234 | * AVContentLightMetadata struct. |
235 | */ |
236 | AV_PKT_DATA_CONTENT_LIGHT_LEVEL, |
237 | |
238 | /** |
239 | * ATSC A53 Part 4 Closed Captions. This metadata should be associated with |
240 | * a video stream. A53 CC bitstream is stored as uint8_t in AVPacketSideData.data. |
241 | * The number of bytes of CC data is AVPacketSideData.size. |
242 | */ |
243 | AV_PKT_DATA_A53_CC, |
244 | |
245 | /** |
246 | * This side data is encryption initialization data. |
247 | * The format is not part of ABI, use av_encryption_init_info_* methods to |
248 | * access. |
249 | */ |
250 | AV_PKT_DATA_ENCRYPTION_INIT_INFO, |
251 | |
252 | /** |
253 | * This side data contains encryption info for how to decrypt the packet. |
254 | * The format is not part of ABI, use av_encryption_info_* methods to access. |
255 | */ |
256 | AV_PKT_DATA_ENCRYPTION_INFO, |
257 | |
258 | /** |
259 | * Active Format Description data consisting of a single byte as specified |
260 | * in ETSI TS 101 154 using AVActiveFormatDescription enum. |
261 | */ |
262 | AV_PKT_DATA_AFD, |
263 | |
264 | /** |
265 | * Producer Reference Time data corresponding to the AVProducerReferenceTime struct, |
266 | * usually exported by some encoders (on demand through the prft flag set in the |
267 | * AVCodecContext export_side_data field). |
268 | */ |
269 | AV_PKT_DATA_PRFT, |
270 | |
271 | /** |
272 | * ICC profile data consisting of an opaque octet buffer following the |
273 | * format described by ISO 15076-1. |
274 | */ |
275 | AV_PKT_DATA_ICC_PROFILE, |
276 | |
277 | /** |
278 | * DOVI configuration |
279 | * ref: |
280 | * dolby-vision-bitstreams-within-the-iso-base-media-file-format-v2.1.2, section 2.2 |
281 | * dolby-vision-bitstreams-in-mpeg-2-transport-stream-multiplex-v1.2, section 3.3 |
282 | * Tags are stored in struct AVDOVIDecoderConfigurationRecord. |
283 | */ |
284 | AV_PKT_DATA_DOVI_CONF, |
285 | |
286 | /** |
287 | * Timecode which conforms to SMPTE ST 12-1:2014. The data is an array of 4 uint32_t |
288 | * where the first uint32_t describes how many (1-3) of the other timecodes are used. |
289 | * The timecode format is described in the documentation of av_timecode_get_smpte_from_framenum() |
290 | * function in libavutil/timecode.h. |
291 | */ |
292 | AV_PKT_DATA_S12M_TIMECODE, |
293 | |
294 | /** |
295 | * HDR10+ dynamic metadata associated with a video frame. The metadata is in |
296 | * the form of the AVDynamicHDRPlus struct and contains |
297 | * information for color volume transform - application 4 of |
298 | * SMPTE 2094-40:2016 standard. |
299 | */ |
300 | AV_PKT_DATA_DYNAMIC_HDR10_PLUS, |
301 | |
302 | /** |
303 | * The number of side data types. |
304 | * This is not part of the public API/ABI in the sense that it may |
305 | * change when new side data types are added. |
306 | * This must stay the last enum value. |
307 | * If its value becomes huge, some code using it |
308 | * needs to be updated as it assumes it to be smaller than other limits. |
309 | */ |
310 | AV_PKT_DATA_NB |
311 | }; |
312 | |
313 | #define AV_PKT_DATA_QUALITY_FACTOR AV_PKT_DATA_QUALITY_STATS //DEPRECATED |
314 | |
315 | /** |
316 | * This structure stores auxiliary information for decoding, presenting, or |
317 | * otherwise processing the coded stream. It is typically exported by demuxers |
318 | * and encoders and can be fed to decoders and muxers either in a per packet |
319 | * basis, or as global side data (applying to the entire coded stream). |
320 | * |
321 | * Global side data is handled as follows: |
322 | * - During demuxing, it may be exported through |
323 | * @ref AVStream.codecpar.side_data "AVStream's codec parameters", which can |
324 | * then be passed as input to decoders through the |
325 | * @ref AVCodecContext.coded_side_data "decoder context's side data", for |
326 | * initialization. |
327 | * - For muxing, it can be fed through @ref AVStream.codecpar.side_data |
328 | * "AVStream's codec parameters", typically the output of encoders through |
329 | * the @ref AVCodecContext.coded_side_data "encoder context's side data", for |
330 | * initialization. |
331 | * |
332 | * Packet specific side data is handled as follows: |
333 | * - During demuxing, it may be exported through @ref AVPacket.side_data |
334 | * "AVPacket's side data", which can then be passed as input to decoders. |
335 | * - For muxing, it can be fed through @ref AVPacket.side_data "AVPacket's |
336 | * side data", typically the output of encoders. |
337 | * |
338 | * Different modules may accept or export different types of side data |
339 | * depending on media type and codec. Refer to @ref AVPacketSideDataType for a |
340 | * list of defined types and where they may be found or used. |
341 | */ |
342 | typedef struct AVPacketSideData { |
343 | uint8_t *data; |
344 | size_t size; |
345 | enum AVPacketSideDataType type; |
346 | } AVPacketSideData; |
347 | |
348 | /** |
349 | * Allocate a new packet side data. |
350 | * |
351 | * @param sd pointer to an array of side data to which the side data should |
352 | * be added. *sd may be NULL, in which case the array will be |
353 | * initialized. |
354 | * @param nb_sd pointer to an integer containing the number of entries in |
355 | * the array. The integer value will be increased by 1 on success. |
356 | * @param type side data type |
357 | * @param size desired side data size |
358 | * @param flags currently unused. Must be zero |
359 | * |
360 | * @return pointer to freshly allocated side data on success, or NULL otherwise. |
361 | */ |
362 | AVPacketSideData *av_packet_side_data_new(AVPacketSideData **psd, int *pnb_sd, |
363 | enum AVPacketSideDataType type, |
364 | size_t size, int flags); |
365 | |
366 | /** |
367 | * Wrap existing data as packet side data. |
368 | * |
369 | * @param sd pointer to an array of side data to which the side data should |
370 | * be added. *sd may be NULL, in which case the array will be |
371 | * initialized |
372 | * @param nb_sd pointer to an integer containing the number of entries in |
373 | * the array. The integer value will be increased by 1 on success. |
374 | * @param type side data type |
375 | * @param data a data array. It must be allocated with the av_malloc() family |
376 | * of functions. The ownership of the data is transferred to the |
377 | * side data array on success |
378 | * @param size size of the data array |
379 | * @param flags currently unused. Must be zero |
380 | * |
381 | * @return pointer to freshly allocated side data on success, or NULL otherwise |
382 | * On failure, the side data array is unchanged and the data remains |
383 | * owned by the caller. |
384 | */ |
385 | AVPacketSideData *av_packet_side_data_add(AVPacketSideData **sd, int *nb_sd, |
386 | enum AVPacketSideDataType type, |
387 | void *data, size_t size, int flags); |
388 | |
389 | /** |
390 | * Get side information from a side data array. |
391 | * |
392 | * @param sd the array from which the side data should be fetched |
393 | * @param nb_sd value containing the number of entries in the array. |
394 | * @param type desired side information type |
395 | * |
396 | * @return pointer to side data if present or NULL otherwise |
397 | */ |
398 | const AVPacketSideData *av_packet_side_data_get(const AVPacketSideData *sd, |
399 | int nb_sd, |
400 | enum AVPacketSideDataType type); |
401 | |
402 | /** |
403 | * Remove side data of the given type from a side data array. |
404 | * |
405 | * @param sd the array from which the side data should be removed |
406 | * @param nb_sd pointer to an integer containing the number of entries in |
407 | * the array. Will be reduced by the amount of entries removed |
408 | * upon return |
409 | * @param type side information type |
410 | */ |
411 | void av_packet_side_data_remove(AVPacketSideData *sd, int *nb_sd, |
412 | enum AVPacketSideDataType type); |
413 | |
414 | /** |
415 | * Convenience function to free all the side data stored in an array, and |
416 | * the array itself. |
417 | * |
418 | * @param sd pointer to array of side data to free. Will be set to NULL |
419 | * upon return. |
420 | * @param nb_sd pointer to an integer containing the number of entries in |
421 | * the array. Will be set to 0 upon return. |
422 | */ |
423 | void av_packet_side_data_free(AVPacketSideData **sd, int *nb_sd); |
424 | |
425 | const char *av_packet_side_data_name(enum AVPacketSideDataType type); |
426 | |
427 | /** |
428 | * @} |
429 | */ |
430 | |
431 | /** |
432 | * @defgroup lavc_packet AVPacket |
433 | * |
434 | * Types and functions for working with AVPacket. |
435 | * @{ |
436 | */ |
437 | |
438 | /** |
439 | * This structure stores compressed data. It is typically exported by demuxers |
440 | * and then passed as input to decoders, or received as output from encoders and |
441 | * then passed to muxers. |
442 | * |
443 | * For video, it should typically contain one compressed frame. For audio it may |
444 | * contain several compressed frames. Encoders are allowed to output empty |
445 | * packets, with no compressed data, containing only side data |
446 | * (e.g. to update some stream parameters at the end of encoding). |
447 | * |
448 | * The semantics of data ownership depends on the buf field. |
449 | * If it is set, the packet data is dynamically allocated and is |
450 | * valid indefinitely until a call to av_packet_unref() reduces the |
451 | * reference count to 0. |
452 | * |
453 | * If the buf field is not set av_packet_ref() would make a copy instead |
454 | * of increasing the reference count. |
455 | * |
456 | * The side data is always allocated with av_malloc(), copied by |
457 | * av_packet_ref() and freed by av_packet_unref(). |
458 | * |
459 | * sizeof(AVPacket) being a part of the public ABI is deprecated. once |
460 | * av_init_packet() is removed, new packets will only be able to be allocated |
461 | * with av_packet_alloc(), and new fields may be added to the end of the struct |
462 | * with a minor bump. |
463 | * |
464 | * @see av_packet_alloc |
465 | * @see av_packet_ref |
466 | * @see av_packet_unref |
467 | */ |
468 | typedef struct AVPacket { |
469 | /** |
470 | * A reference to the reference-counted buffer where the packet data is |
471 | * stored. |
472 | * May be NULL, then the packet data is not reference-counted. |
473 | */ |
474 | AVBufferRef *buf; |
475 | /** |
476 | * Presentation timestamp in AVStream->time_base units; the time at which |
477 | * the decompressed packet will be presented to the user. |
478 | * Can be AV_NOPTS_VALUE if it is not stored in the file. |
479 | * pts MUST be larger or equal to dts as presentation cannot happen before |
480 | * decompression, unless one wants to view hex dumps. Some formats misuse |
481 | * the terms dts and pts/cts to mean something different. Such timestamps |
482 | * must be converted to true pts/dts before they are stored in AVPacket. |
483 | */ |
484 | int64_t pts; |
485 | /** |
486 | * Decompression timestamp in AVStream->time_base units; the time at which |
487 | * the packet is decompressed. |
488 | * Can be AV_NOPTS_VALUE if it is not stored in the file. |
489 | */ |
490 | int64_t dts; |
491 | uint8_t *data; |
492 | int size; |
493 | int stream_index; |
494 | /** |
495 | * A combination of AV_PKT_FLAG values |
496 | */ |
497 | int flags; |
498 | /** |
499 | * Additional packet data that can be provided by the container. |
500 | * Packet can contain several types of side information. |
501 | */ |
502 | AVPacketSideData *side_data; |
503 | int side_data_elems; |
504 | |
505 | /** |
506 | * Duration of this packet in AVStream->time_base units, 0 if unknown. |
507 | * Equals next_pts - this_pts in presentation order. |
508 | */ |
509 | int64_t duration; |
510 | |
511 | int64_t pos; ///< byte position in stream, -1 if unknown |
512 | |
513 | /** |
514 | * for some private data of the user |
515 | */ |
516 | void *opaque; |
517 | |
518 | /** |
519 | * AVBufferRef for free use by the API user. FFmpeg will never check the |
520 | * contents of the buffer ref. FFmpeg calls av_buffer_unref() on it when |
521 | * the packet is unreferenced. av_packet_copy_props() calls create a new |
522 | * reference with av_buffer_ref() for the target packet's opaque_ref field. |
523 | * |
524 | * This is unrelated to the opaque field, although it serves a similar |
525 | * purpose. |
526 | */ |
527 | AVBufferRef *opaque_ref; |
528 | |
529 | /** |
530 | * Time base of the packet's timestamps. |
531 | * In the future, this field may be set on packets output by encoders or |
532 | * demuxers, but its value will be by default ignored on input to decoders |
533 | * or muxers. |
534 | */ |
535 | AVRational time_base; |
536 | } AVPacket; |
537 | |
538 | #if FF_API_INIT_PACKET |
539 | attribute_deprecated |
540 | typedef struct AVPacketList { |
541 | AVPacket pkt; |
542 | struct AVPacketList *next; |
543 | } AVPacketList; |
544 | #endif |
545 | |
546 | #define AV_PKT_FLAG_KEY 0x0001 ///< The packet contains a keyframe |
547 | #define AV_PKT_FLAG_CORRUPT 0x0002 ///< The packet content is corrupted |
548 | /** |
549 | * Flag is used to discard packets which are required to maintain valid |
550 | * decoder state but are not required for output and should be dropped |
551 | * after decoding. |
552 | **/ |
553 | #define AV_PKT_FLAG_DISCARD 0x0004 |
554 | /** |
555 | * The packet comes from a trusted source. |
556 | * |
557 | * Otherwise-unsafe constructs such as arbitrary pointers to data |
558 | * outside the packet may be followed. |
559 | */ |
560 | #define AV_PKT_FLAG_TRUSTED 0x0008 |
561 | /** |
562 | * Flag is used to indicate packets that contain frames that can |
563 | * be discarded by the decoder. I.e. Non-reference frames. |
564 | */ |
565 | #define AV_PKT_FLAG_DISPOSABLE 0x0010 |
566 | |
567 | enum AVSideDataParamChangeFlags { |
568 | #if FF_API_OLD_CHANNEL_LAYOUT |
569 | /** |
570 | * @deprecated those are not used by any decoder |
571 | */ |
572 | AV_SIDE_DATA_PARAM_CHANGE_CHANNEL_COUNT = 0x0001, |
573 | AV_SIDE_DATA_PARAM_CHANGE_CHANNEL_LAYOUT = 0x0002, |
574 | #endif |
575 | AV_SIDE_DATA_PARAM_CHANGE_SAMPLE_RATE = 0x0004, |
576 | AV_SIDE_DATA_PARAM_CHANGE_DIMENSIONS = 0x0008, |
577 | }; |
578 | |
579 | /** |
580 | * Allocate an AVPacket and set its fields to default values. The resulting |
581 | * struct must be freed using av_packet_free(). |
582 | * |
583 | * @return An AVPacket filled with default values or NULL on failure. |
584 | * |
585 | * @note this only allocates the AVPacket itself, not the data buffers. Those |
586 | * must be allocated through other means such as av_new_packet. |
587 | * |
588 | * @see av_new_packet |
589 | */ |
590 | AVPacket *av_packet_alloc(void); |
591 | |
592 | /** |
593 | * Create a new packet that references the same data as src. |
594 | * |
595 | * This is a shortcut for av_packet_alloc()+av_packet_ref(). |
596 | * |
597 | * @return newly created AVPacket on success, NULL on error. |
598 | * |
599 | * @see av_packet_alloc |
600 | * @see av_packet_ref |
601 | */ |
602 | AVPacket *av_packet_clone(const AVPacket *src); |
603 | |
604 | /** |
605 | * Free the packet, if the packet is reference counted, it will be |
606 | * unreferenced first. |
607 | * |
608 | * @param pkt packet to be freed. The pointer will be set to NULL. |
609 | * @note passing NULL is a no-op. |
610 | */ |
611 | void av_packet_free(AVPacket **pkt); |
612 | |
613 | #if FF_API_INIT_PACKET |
614 | /** |
615 | * Initialize optional fields of a packet with default values. |
616 | * |
617 | * Note, this does not touch the data and size members, which have to be |
618 | * initialized separately. |
619 | * |
620 | * @param pkt packet |
621 | * |
622 | * @see av_packet_alloc |
623 | * @see av_packet_unref |
624 | * |
625 | * @deprecated This function is deprecated. Once it's removed, |
626 | sizeof(AVPacket) will not be a part of the ABI anymore. |
627 | */ |
628 | attribute_deprecated |
629 | void av_init_packet(AVPacket *pkt); |
630 | #endif |
631 | |
632 | /** |
633 | * Allocate the payload of a packet and initialize its fields with |
634 | * default values. |
635 | * |
636 | * @param pkt packet |
637 | * @param size wanted payload size |
638 | * @return 0 if OK, AVERROR_xxx otherwise |
639 | */ |
640 | int av_new_packet(AVPacket *pkt, int size); |
641 | |
642 | /** |
643 | * Reduce packet size, correctly zeroing padding |
644 | * |
645 | * @param pkt packet |
646 | * @param size new size |
647 | */ |
648 | void av_shrink_packet(AVPacket *pkt, int size); |
649 | |
650 | /** |
651 | * Increase packet size, correctly zeroing padding |
652 | * |
653 | * @param pkt packet |
654 | * @param grow_by number of bytes by which to increase the size of the packet |
655 | */ |
656 | int av_grow_packet(AVPacket *pkt, int grow_by); |
657 | |
658 | /** |
659 | * Initialize a reference-counted packet from av_malloc()ed data. |
660 | * |
661 | * @param pkt packet to be initialized. This function will set the data, size, |
662 | * and buf fields, all others are left untouched. |
663 | * @param data Data allocated by av_malloc() to be used as packet data. If this |
664 | * function returns successfully, the data is owned by the underlying AVBuffer. |
665 | * The caller may not access the data through other means. |
666 | * @param size size of data in bytes, without the padding. I.e. the full buffer |
667 | * size is assumed to be size + AV_INPUT_BUFFER_PADDING_SIZE. |
668 | * |
669 | * @return 0 on success, a negative AVERROR on error |
670 | */ |
671 | int av_packet_from_data(AVPacket *pkt, uint8_t *data, int size); |
672 | |
673 | /** |
674 | * Allocate new information of a packet. |
675 | * |
676 | * @param pkt packet |
677 | * @param type side information type |
678 | * @param size side information size |
679 | * @return pointer to fresh allocated data or NULL otherwise |
680 | */ |
681 | uint8_t* av_packet_new_side_data(AVPacket *pkt, enum AVPacketSideDataType type, |
682 | size_t size); |
683 | |
684 | /** |
685 | * Wrap an existing array as a packet side data. |
686 | * |
687 | * @param pkt packet |
688 | * @param type side information type |
689 | * @param data the side data array. It must be allocated with the av_malloc() |
690 | * family of functions. The ownership of the data is transferred to |
691 | * pkt. |
692 | * @param size side information size |
693 | * @return a non-negative number on success, a negative AVERROR code on |
694 | * failure. On failure, the packet is unchanged and the data remains |
695 | * owned by the caller. |
696 | */ |
697 | int av_packet_add_side_data(AVPacket *pkt, enum AVPacketSideDataType type, |
698 | uint8_t *data, size_t size); |
699 | |
700 | /** |
701 | * Shrink the already allocated side data buffer |
702 | * |
703 | * @param pkt packet |
704 | * @param type side information type |
705 | * @param size new side information size |
706 | * @return 0 on success, < 0 on failure |
707 | */ |
708 | int av_packet_shrink_side_data(AVPacket *pkt, enum AVPacketSideDataType type, |
709 | size_t size); |
710 | |
711 | /** |
712 | * Get side information from packet. |
713 | * |
714 | * @param pkt packet |
715 | * @param type desired side information type |
716 | * @param size If supplied, *size will be set to the size of the side data |
717 | * or to zero if the desired side data is not present. |
718 | * @return pointer to data if present or NULL otherwise |
719 | */ |
720 | uint8_t* av_packet_get_side_data(const AVPacket *pkt, enum AVPacketSideDataType type, |
721 | size_t *size); |
722 | |
723 | /** |
724 | * Pack a dictionary for use in side_data. |
725 | * |
726 | * @param dict The dictionary to pack. |
727 | * @param size pointer to store the size of the returned data |
728 | * @return pointer to data if successful, NULL otherwise |
729 | */ |
730 | uint8_t *av_packet_pack_dictionary(AVDictionary *dict, size_t *size); |
731 | /** |
732 | * Unpack a dictionary from side_data. |
733 | * |
734 | * @param data data from side_data |
735 | * @param size size of the data |
736 | * @param dict the metadata storage dictionary |
737 | * @return 0 on success, < 0 on failure |
738 | */ |
739 | int av_packet_unpack_dictionary(const uint8_t *data, size_t size, |
740 | AVDictionary **dict); |
741 | |
742 | /** |
743 | * Convenience function to free all the side data stored. |
744 | * All the other fields stay untouched. |
745 | * |
746 | * @param pkt packet |
747 | */ |
748 | void av_packet_free_side_data(AVPacket *pkt); |
749 | |
750 | /** |
751 | * Setup a new reference to the data described by a given packet |
752 | * |
753 | * If src is reference-counted, setup dst as a new reference to the |
754 | * buffer in src. Otherwise allocate a new buffer in dst and copy the |
755 | * data from src into it. |
756 | * |
757 | * All the other fields are copied from src. |
758 | * |
759 | * @see av_packet_unref |
760 | * |
761 | * @param dst Destination packet. Will be completely overwritten. |
762 | * @param src Source packet |
763 | * |
764 | * @return 0 on success, a negative AVERROR on error. On error, dst |
765 | * will be blank (as if returned by av_packet_alloc()). |
766 | */ |
767 | int av_packet_ref(AVPacket *dst, const AVPacket *src); |
768 | |
769 | /** |
770 | * Wipe the packet. |
771 | * |
772 | * Unreference the buffer referenced by the packet and reset the |
773 | * remaining packet fields to their default values. |
774 | * |
775 | * @param pkt The packet to be unreferenced. |
776 | */ |
777 | void av_packet_unref(AVPacket *pkt); |
778 | |
779 | /** |
780 | * Move every field in src to dst and reset src. |
781 | * |
782 | * @see av_packet_unref |
783 | * |
784 | * @param src Source packet, will be reset |
785 | * @param dst Destination packet |
786 | */ |
787 | void av_packet_move_ref(AVPacket *dst, AVPacket *src); |
788 | |
789 | /** |
790 | * Copy only "properties" fields from src to dst. |
791 | * |
792 | * Properties for the purpose of this function are all the fields |
793 | * beside those related to the packet data (buf, data, size) |
794 | * |
795 | * @param dst Destination packet |
796 | * @param src Source packet |
797 | * |
798 | * @return 0 on success AVERROR on failure. |
799 | */ |
800 | int av_packet_copy_props(AVPacket *dst, const AVPacket *src); |
801 | |
802 | /** |
803 | * Ensure the data described by a given packet is reference counted. |
804 | * |
805 | * @note This function does not ensure that the reference will be writable. |
806 | * Use av_packet_make_writable instead for that purpose. |
807 | * |
808 | * @see av_packet_ref |
809 | * @see av_packet_make_writable |
810 | * |
811 | * @param pkt packet whose data should be made reference counted. |
812 | * |
813 | * @return 0 on success, a negative AVERROR on error. On failure, the |
814 | * packet is unchanged. |
815 | */ |
816 | int av_packet_make_refcounted(AVPacket *pkt); |
817 | |
818 | /** |
819 | * Create a writable reference for the data described by a given packet, |
820 | * avoiding data copy if possible. |
821 | * |
822 | * @param pkt Packet whose data should be made writable. |
823 | * |
824 | * @return 0 on success, a negative AVERROR on failure. On failure, the |
825 | * packet is unchanged. |
826 | */ |
827 | int av_packet_make_writable(AVPacket *pkt); |
828 | |
829 | /** |
830 | * Convert valid timing fields (timestamps / durations) in a packet from one |
831 | * timebase to another. Timestamps with unknown values (AV_NOPTS_VALUE) will be |
832 | * ignored. |
833 | * |
834 | * @param pkt packet on which the conversion will be performed |
835 | * @param tb_src source timebase, in which the timing fields in pkt are |
836 | * expressed |
837 | * @param tb_dst destination timebase, to which the timing fields will be |
838 | * converted |
839 | */ |
840 | void av_packet_rescale_ts(AVPacket *pkt, AVRational tb_src, AVRational tb_dst); |
841 | |
842 | /** |
843 | * @} |
844 | */ |
845 | |
846 | #endif // AVCODEC_PACKET_H |
847 | |