/* * AVPacket public API * * This file is part of FFmpeg. * * FFmpeg is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * FFmpeg is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with FFmpeg; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ #ifndef AVCODEC_PACKET_H #define AVCODEC_PACKET_H #include <stddef.h> #include <stdint.h> #include "libavutil/attributes.h" #include "libavutil/buffer.h" #include "libavutil/dict.h" #include "libavutil/rational.h" #include "libavutil/version.h" #include "libavcodec/version_major.h" /** * @defgroup lavc_packet_side_data AVPacketSideData * * Types and functions for working with AVPacketSideData. * @{ */ enum AVPacketSideDataType { … }; #if FF_API_QUALITY_FACTOR #define AV_PKT_DATA_QUALITY_FACTOR … #endif /** * This structure stores auxiliary information for decoding, presenting, or * otherwise processing the coded stream. It is typically exported by demuxers * and encoders and can be fed to decoders and muxers either in a per packet * basis, or as global side data (applying to the entire coded stream). * * Global side data is handled as follows: * - During demuxing, it may be exported through * @ref AVStream.codecpar.side_data "AVStream's codec parameters", which can * then be passed as input to decoders through the * @ref AVCodecContext.coded_side_data "decoder context's side data", for * initialization. * - For muxing, it can be fed through @ref AVStream.codecpar.side_data * "AVStream's codec parameters", typically the output of encoders through * the @ref AVCodecContext.coded_side_data "encoder context's side data", for * initialization. * * Packet specific side data is handled as follows: * - During demuxing, it may be exported through @ref AVPacket.side_data * "AVPacket's side data", which can then be passed as input to decoders. * - For muxing, it can be fed through @ref AVPacket.side_data "AVPacket's * side data", typically the output of encoders. * * Different modules may accept or export different types of side data * depending on media type and codec. Refer to @ref AVPacketSideDataType for a * list of defined types and where they may be found or used. */ AVPacketSideData; /** * Allocate a new packet side data. * * @param sd pointer to an array of side data to which the side data should * be added. *sd may be NULL, in which case the array will be * initialized. * @param nb_sd pointer to an integer containing the number of entries in * the array. The integer value will be increased by 1 on success. * @param type side data type * @param size desired side data size * @param flags currently unused. Must be zero * * @return pointer to freshly allocated side data on success, or NULL otherwise. */ AVPacketSideData *av_packet_side_data_new(AVPacketSideData **psd, int *pnb_sd, enum AVPacketSideDataType type, size_t size, int flags); /** * Wrap existing data as packet side data. * * @param sd pointer to an array of side data to which the side data should * be added. *sd may be NULL, in which case the array will be * initialized * @param nb_sd pointer to an integer containing the number of entries in * the array. The integer value will be increased by 1 on success. * @param type side data type * @param data a data array. It must be allocated with the av_malloc() family * of functions. The ownership of the data is transferred to the * side data array on success * @param size size of the data array * @param flags currently unused. Must be zero * * @return pointer to freshly allocated side data on success, or NULL otherwise * On failure, the side data array is unchanged and the data remains * owned by the caller. */ AVPacketSideData *av_packet_side_data_add(AVPacketSideData **sd, int *nb_sd, enum AVPacketSideDataType type, void *data, size_t size, int flags); /** * Get side information from a side data array. * * @param sd the array from which the side data should be fetched * @param nb_sd value containing the number of entries in the array. * @param type desired side information type * * @return pointer to side data if present or NULL otherwise */ const AVPacketSideData *av_packet_side_data_get(const AVPacketSideData *sd, int nb_sd, enum AVPacketSideDataType type); /** * Remove side data of the given type from a side data array. * * @param sd the array from which the side data should be removed * @param nb_sd pointer to an integer containing the number of entries in * the array. Will be reduced by the amount of entries removed * upon return * @param type side information type */ void av_packet_side_data_remove(AVPacketSideData *sd, int *nb_sd, enum AVPacketSideDataType type); /** * Convenience function to free all the side data stored in an array, and * the array itself. * * @param sd pointer to array of side data to free. Will be set to NULL * upon return. * @param nb_sd pointer to an integer containing the number of entries in * the array. Will be set to 0 upon return. */ void av_packet_side_data_free(AVPacketSideData **sd, int *nb_sd); const char *av_packet_side_data_name(enum AVPacketSideDataType type); /** * @} */ /** * @defgroup lavc_packet AVPacket * * Types and functions for working with AVPacket. * @{ */ /** * This structure stores compressed data. It is typically exported by demuxers * and then passed as input to decoders, or received as output from encoders and * then passed to muxers. * * For video, it should typically contain one compressed frame. For audio it may * contain several compressed frames. Encoders are allowed to output empty * packets, with no compressed data, containing only side data * (e.g. to update some stream parameters at the end of encoding). * * The semantics of data ownership depends on the buf field. * If it is set, the packet data is dynamically allocated and is * valid indefinitely until a call to av_packet_unref() reduces the * reference count to 0. * * If the buf field is not set av_packet_ref() would make a copy instead * of increasing the reference count. * * The side data is always allocated with av_malloc(), copied by * av_packet_ref() and freed by av_packet_unref(). * * sizeof(AVPacket) being a part of the public ABI is deprecated. once * av_init_packet() is removed, new packets will only be able to be allocated * with av_packet_alloc(), and new fields may be added to the end of the struct * with a minor bump. * * @see av_packet_alloc * @see av_packet_ref * @see av_packet_unref */ AVPacket; #if FF_API_INIT_PACKET attribute_deprecated; #endif #define AV_PKT_FLAG_KEY … #define AV_PKT_FLAG_CORRUPT … /** * Flag is used to discard packets which are required to maintain valid * decoder state but are not required for output and should be dropped * after decoding. **/ #define AV_PKT_FLAG_DISCARD … /** * The packet comes from a trusted source. * * Otherwise-unsafe constructs such as arbitrary pointers to data * outside the packet may be followed. */ #define AV_PKT_FLAG_TRUSTED … /** * Flag is used to indicate packets that contain frames that can * be discarded by the decoder. I.e. Non-reference frames. */ #define AV_PKT_FLAG_DISPOSABLE … enum AVSideDataParamChangeFlags { … }; /** * Allocate an AVPacket and set its fields to default values. The resulting * struct must be freed using av_packet_free(). * * @return An AVPacket filled with default values or NULL on failure. * * @note this only allocates the AVPacket itself, not the data buffers. Those * must be allocated through other means such as av_new_packet. * * @see av_new_packet */ AVPacket *av_packet_alloc(void); /** * Create a new packet that references the same data as src. * * This is a shortcut for av_packet_alloc()+av_packet_ref(). * * @return newly created AVPacket on success, NULL on error. * * @see av_packet_alloc * @see av_packet_ref */ AVPacket *av_packet_clone(const AVPacket *src); /** * Free the packet, if the packet is reference counted, it will be * unreferenced first. * * @param pkt packet to be freed. The pointer will be set to NULL. * @note passing NULL is a no-op. */ void av_packet_free(AVPacket **pkt); #if FF_API_INIT_PACKET /** * Initialize optional fields of a packet with default values. * * Note, this does not touch the data and size members, which have to be * initialized separately. * * @param pkt packet * * @see av_packet_alloc * @see av_packet_unref * * @deprecated This function is deprecated. Once it's removed, sizeof(AVPacket) will not be a part of the ABI anymore. */ attribute_deprecated void av_init_packet(AVPacket *pkt); #endif /** * Allocate the payload of a packet and initialize its fields with * default values. * * @param pkt packet * @param size wanted payload size * @return 0 if OK, AVERROR_xxx otherwise */ int av_new_packet(AVPacket *pkt, int size); /** * Reduce packet size, correctly zeroing padding * * @param pkt packet * @param size new size */ void av_shrink_packet(AVPacket *pkt, int size); /** * Increase packet size, correctly zeroing padding * * @param pkt packet * @param grow_by number of bytes by which to increase the size of the packet */ int av_grow_packet(AVPacket *pkt, int grow_by); /** * Initialize a reference-counted packet from av_malloc()ed data. * * @param pkt packet to be initialized. This function will set the data, size, * and buf fields, all others are left untouched. * @param data Data allocated by av_malloc() to be used as packet data. If this * function returns successfully, the data is owned by the underlying AVBuffer. * The caller may not access the data through other means. * @param size size of data in bytes, without the padding. I.e. the full buffer * size is assumed to be size + AV_INPUT_BUFFER_PADDING_SIZE. * * @return 0 on success, a negative AVERROR on error */ int av_packet_from_data(AVPacket *pkt, uint8_t *data, int size); /** * Allocate new information of a packet. * * @param pkt packet * @param type side information type * @param size side information size * @return pointer to fresh allocated data or NULL otherwise */ uint8_t* av_packet_new_side_data(AVPacket *pkt, enum AVPacketSideDataType type, size_t size); /** * Wrap an existing array as a packet side data. * * @param pkt packet * @param type side information type * @param data the side data array. It must be allocated with the av_malloc() * family of functions. The ownership of the data is transferred to * pkt. * @param size side information size * @return a non-negative number on success, a negative AVERROR code on * failure. On failure, the packet is unchanged and the data remains * owned by the caller. */ int av_packet_add_side_data(AVPacket *pkt, enum AVPacketSideDataType type, uint8_t *data, size_t size); /** * Shrink the already allocated side data buffer * * @param pkt packet * @param type side information type * @param size new side information size * @return 0 on success, < 0 on failure */ int av_packet_shrink_side_data(AVPacket *pkt, enum AVPacketSideDataType type, size_t size); /** * Get side information from packet. * * @param pkt packet * @param type desired side information type * @param size If supplied, *size will be set to the size of the side data * or to zero if the desired side data is not present. * @return pointer to data if present or NULL otherwise */ uint8_t* av_packet_get_side_data(const AVPacket *pkt, enum AVPacketSideDataType type, size_t *size); /** * Pack a dictionary for use in side_data. * * @param dict The dictionary to pack. * @param size pointer to store the size of the returned data * @return pointer to data if successful, NULL otherwise */ uint8_t *av_packet_pack_dictionary(AVDictionary *dict, size_t *size); /** * Unpack a dictionary from side_data. * * @param data data from side_data * @param size size of the data * @param dict the metadata storage dictionary * @return 0 on success, < 0 on failure */ int av_packet_unpack_dictionary(const uint8_t *data, size_t size, AVDictionary **dict); /** * Convenience function to free all the side data stored. * All the other fields stay untouched. * * @param pkt packet */ void av_packet_free_side_data(AVPacket *pkt); /** * Setup a new reference to the data described by a given packet * * If src is reference-counted, setup dst as a new reference to the * buffer in src. Otherwise allocate a new buffer in dst and copy the * data from src into it. * * All the other fields are copied from src. * * @see av_packet_unref * * @param dst Destination packet. Will be completely overwritten. * @param src Source packet * * @return 0 on success, a negative AVERROR on error. On error, dst * will be blank (as if returned by av_packet_alloc()). */ int av_packet_ref(AVPacket *dst, const AVPacket *src); /** * Wipe the packet. * * Unreference the buffer referenced by the packet and reset the * remaining packet fields to their default values. * * @param pkt The packet to be unreferenced. */ void av_packet_unref(AVPacket *pkt); /** * Move every field in src to dst and reset src. * * @see av_packet_unref * * @param src Source packet, will be reset * @param dst Destination packet */ void av_packet_move_ref(AVPacket *dst, AVPacket *src); /** * Copy only "properties" fields from src to dst. * * Properties for the purpose of this function are all the fields * beside those related to the packet data (buf, data, size) * * @param dst Destination packet * @param src Source packet * * @return 0 on success AVERROR on failure. */ int av_packet_copy_props(AVPacket *dst, const AVPacket *src); /** * Ensure the data described by a given packet is reference counted. * * @note This function does not ensure that the reference will be writable. * Use av_packet_make_writable instead for that purpose. * * @see av_packet_ref * @see av_packet_make_writable * * @param pkt packet whose data should be made reference counted. * * @return 0 on success, a negative AVERROR on error. On failure, the * packet is unchanged. */ int av_packet_make_refcounted(AVPacket *pkt); /** * Create a writable reference for the data described by a given packet, * avoiding data copy if possible. * * @param pkt Packet whose data should be made writable. * * @return 0 on success, a negative AVERROR on failure. On failure, the * packet is unchanged. */ int av_packet_make_writable(AVPacket *pkt); /** * Convert valid timing fields (timestamps / durations) in a packet from one * timebase to another. Timestamps with unknown values (AV_NOPTS_VALUE) will be * ignored. * * @param pkt packet on which the conversion will be performed * @param tb_src source timebase, in which the timing fields in pkt are * expressed * @param tb_dst destination timebase, to which the timing fields will be * converted */ void av_packet_rescale_ts(AVPacket *pkt, AVRational tb_src, AVRational tb_dst); /** * @} */ #endif // AVCODEC_PACKET_H
Codebase Browser
chromium