X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=libavcodec%2Favcodec.h;h=8727c60842e35a911d8d7359ab6da6738203e741;hb=cb9b39fba937b7eee69968ba1310ab694a439fc3;hp=183d8e63ade4189d7c41601574417d0528181756;hpb=11491503c492f3a3ce190e2ee8cec660d3b91e1d;p=ffmpeg diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h index 183d8e63ade..8727c60842e 100644 --- a/libavcodec/avcodec.h +++ b/libavcodec/avcodec.h @@ -22,7 +22,7 @@ #define AVCODEC_AVCODEC_H /** - * @file libavcodec/avcodec.h + * @file * external API header */ @@ -30,8 +30,8 @@ #include "libavutil/avutil.h" #define LIBAVCODEC_VERSION_MAJOR 52 -#define LIBAVCODEC_VERSION_MINOR 64 -#define LIBAVCODEC_VERSION_MICRO 0 +#define LIBAVCODEC_VERSION_MINOR 78 +#define LIBAVCODEC_VERSION_MICRO 1 #define LIBAVCODEC_VERSION_INT AV_VERSION_INT(LIBAVCODEC_VERSION_MAJOR, \ LIBAVCODEC_VERSION_MINOR, \ @@ -48,7 +48,7 @@ #define AV_TIME_BASE_Q (AVRational){1, AV_TIME_BASE} /** - * Identifies the syntax and semantics of the bitstream. + * Identify the syntax and semantics of the bitstream. * The principle is roughly: * Two decoders with the same ID can decode the same streams. * Two encoders with the same ID can encode compatible streams. @@ -210,6 +210,8 @@ enum CodecID { CODEC_ID_IFF_BYTERUN1, CODEC_ID_KGV1, CODEC_ID_YOP, + CODEC_ID_VP8, + CODEC_ID_PICTOR, /* various PCM "codecs" */ CODEC_ID_PCM_S16LE= 0x10000, @@ -597,6 +599,7 @@ typedef struct RcOverride{ #define CODEC_FLAG2_MBTREE 0x00040000 ///< Use macroblock tree ratecontrol (x264 only) #define CODEC_FLAG2_PSY 0x00080000 ///< Use psycho visual optimizations. #define CODEC_FLAG2_SSIM 0x00100000 ///< Compute SSIM during encoding, error[] values are undefined. +#define CODEC_FLAG2_INTRA_REFRESH 0x00200000 ///< Use periodic insertion of intra blocks instead of keyframes. /* Unsupported options : * Syntax Arithmetic coding (SAC) @@ -643,6 +646,11 @@ typedef struct RcOverride{ * as a last resort. */ #define CODEC_CAP_SUBFRAMES 0x0100 +/** + * Codec is experimental and is thus avoided in favor of non experimental + * encoders + */ +#define CODEC_CAP_EXPERIMENTAL 0x0200 //The following defines may change, don't expect compatibility if you use them. #define MB_TYPE_INTRA4x4 0x0001 @@ -1113,8 +1121,10 @@ typedef struct AVCodecContext { /** * Pixel format, see PIX_FMT_xxx. + * May be set by the demuxer if known from headers. + * May be overriden by the decoder if it knows better. * - encoding: Set by user. - * - decoding: Set by libavcodec. + * - decoding: Set by user if known, overridden by libavcodec if known */ enum PixelFormat pix_fmt; @@ -1340,15 +1350,15 @@ typedef struct AVCodecContext { * - encoding: Set by user. * - decoding: Set by user. * Setting this to STRICT or higher means the encoder and decoder will - * generally do stupid things. While setting it to inofficial or lower - * will mean the encoder might use things that are not supported by all - * spec compliant decoders. Decoders make no difference between normal, - * inofficial and experimental, that is they always try to decode things - * when they can unless they are explicitly asked to behave stupid + * generally do stupid things, whereas setting it to inofficial or lower + * will mean the encoder might produce output that is not supported by all + * spec-compliant decoders. Decoders don't differentiate between normal, + * inofficial and experimental (that is, they always try to decode things + * when they can) unless they are explicitly asked to behave stupidly * (=strictly conform to the specs) */ int strict_std_compliance; -#define FF_COMPLIANCE_VERY_STRICT 2 ///< Strictly conform to a older more strict version of the spec or reference software. +#define FF_COMPLIANCE_VERY_STRICT 2 ///< Strictly conform to an older more strict version of the spec or reference software. #define FF_COMPLIANCE_STRICT 1 ///< Strictly conform to all the things in the spec no matter what consequences. #define FF_COMPLIANCE_NORMAL 0 #define FF_COMPLIANCE_INOFFICIAL -1 ///< Allow inofficial extensions. @@ -2646,6 +2656,17 @@ typedef struct AVCodecContext { * - decoding: unused */ int rc_lookahead; + + /** + * Constant rate factor maximum + * With CRF encoding mode and VBV restrictions enabled, prevents quality from being worse + * than crf_max, even if doing so would violate VBV restrictions. + * - encoding: Set by user. + * - decoding: unused + */ + float crf_max; + + int log_level_offset; } AVCodecContext; /** @@ -2930,7 +2951,7 @@ attribute_deprecated ReSampleContext *audio_resample_init(int output_channels, i int output_rate, int input_rate); #endif /** - * Initializes audio resampling context + * Initialize audio resampling context * * @param output_channels number of output channels * @param input_channels number of input channels @@ -2957,7 +2978,7 @@ void audio_resample_close(ReSampleContext *s); /** - * Initializes an audio resampler. + * Initialize an audio resampler. * Note, if either rate is not an integer then simply scale both rates up so they are. * @param filter_length length of each FIR filter in the filterbank relative to the cutoff freq * @param log2_phase_count log2 of the number of entries in the polyphase filterbank @@ -2968,7 +2989,7 @@ void audio_resample_close(ReSampleContext *s); struct AVResampleContext *av_resample_init(int out_rate, int in_rate, int filter_length, int log2_phase_count, int linear, double cutoff); /** - * resamples. + * Resample an array of samples using a previously configured context. * @param src an array of unconsumed samples * @param consumed the number of samples of src which have been consumed are returned here * @param src_size the number of unconsumed samples available @@ -2980,7 +3001,7 @@ int av_resample(struct AVResampleContext *c, short *dst, short *src, int *consum /** - * Compensates samplerate/timestamp drift. The compensation is done by changing + * Compensate samplerate/timestamp drift. The compensation is done by changing * the resampler parameters, so no audible clicks or similar distortions occur * @param compensation_distance distance in output samples over which the compensation should be performed * @param sample_delta number of output samples which should be output less @@ -3053,15 +3074,15 @@ void avcodec_set_dimensions(AVCodecContext *s, int width, int height); #if LIBAVCODEC_VERSION_MAJOR < 53 /** - * Returns the pixel format corresponding to the name name. + * Return the pixel format corresponding to the name name. * - * If there is no pixel format with name name, then looks for a + * If there is no pixel format with name name, then look for a * pixel format with the name corresponding to the native endian * format of name. - * For example in a little-endian system, first looks for "gray16", + * For example in a little-endian system, first look for "gray16", * then for "gray16le". * - * Finally if no pixel format has been found, returns PIX_FMT_NONE. + * Finally if no pixel format has been found, return PIX_FMT_NONE. * * @deprecated Deprecated in favor of av_get_pix_fmt(). */ @@ -3069,12 +3090,21 @@ attribute_deprecated enum PixelFormat avcodec_get_pix_fmt(const char* name); #endif /** - * Returns a value representing the fourCC code associated to the + * Return a value representing the fourCC code associated to the * pixel format pix_fmt, or 0 if no associated fourCC code can be * found. */ unsigned int avcodec_pix_fmt_to_codec_tag(enum PixelFormat pix_fmt); +/** + * Put a string representing the codec tag codec_tag in buf. + * + * @param buf_size size in bytes of buf + * @return the length of the string that would have been generated if + * enough space had been available, excluding the trailing null + */ +size_t av_get_codec_tag_string(char *buf, size_t buf_size, unsigned int codec_tag); + #define FF_LOSS_RESOLUTION 0x0001 /**< loss due to resolution change */ #define FF_LOSS_DEPTH 0x0002 /**< loss due to color depth change */ #define FF_LOSS_COLORSPACE 0x0004 /**< loss due to color space conversion */ @@ -3083,7 +3113,7 @@ unsigned int avcodec_pix_fmt_to_codec_tag(enum PixelFormat pix_fmt); #define FF_LOSS_CHROMA 0x0020 /**< loss of chroma (e.g. RGB to gray conversion) */ /** - * Computes what kind of losses will occur when converting from one specific + * Compute what kind of losses will occur when converting from one specific * pixel format to another. * When converting from one pixel format to another, information loss may occur. * For example, when converting from RGB24 to GRAY, the color information will @@ -3103,7 +3133,7 @@ int avcodec_get_pix_fmt_loss(enum PixelFormat dst_pix_fmt, enum PixelFormat src_ int has_alpha); /** - * Finds the best pixel format to convert to given a certain source pixel + * Find the best pixel format to convert to given a certain source pixel * format. When converting from one pixel format to another, information loss * may occur. For example, when converting from RGB24 to GRAY, the color * information will be lost. Similarly, other losses occur when converting from @@ -3165,22 +3195,22 @@ int avpicture_deinterlace(AVPicture *dst, const AVPicture *src, AVCodec *av_codec_next(AVCodec *c); /** - * Returns the LIBAVCODEC_VERSION_INT constant. + * Return the LIBAVCODEC_VERSION_INT constant. */ unsigned avcodec_version(void); /** - * Returns the libavcodec build-time configuration. + * Return the libavcodec build-time configuration. */ const char *avcodec_configuration(void); /** - * Returns the libavcodec license. + * Return the libavcodec license. */ const char *avcodec_license(void); /** - * Initializes libavcodec. + * Initialize libavcodec. * * @warning This function must be called before any other libavcodec * function. @@ -3202,7 +3232,7 @@ attribute_deprecated void register_avcodec(AVCodec *codec); void avcodec_register(AVCodec *codec); /** - * Finds a registered encoder with a matching codec ID. + * Find a registered encoder with a matching codec ID. * * @param id CodecID of the requested encoder * @return An encoder if one was found, NULL otherwise. @@ -3210,7 +3240,7 @@ void avcodec_register(AVCodec *codec); AVCodec *avcodec_find_encoder(enum CodecID id); /** - * Finds a registered encoder with the specified name. + * Find a registered encoder with the specified name. * * @param name name of the requested encoder * @return An encoder if one was found, NULL otherwise. @@ -3218,7 +3248,7 @@ AVCodec *avcodec_find_encoder(enum CodecID id); AVCodec *avcodec_find_encoder_by_name(const char *name); /** - * Finds a registered decoder with a matching codec ID. + * Find a registered decoder with a matching codec ID. * * @param id CodecID of the requested decoder * @return A decoder if one was found, NULL otherwise. @@ -3226,7 +3256,7 @@ AVCodec *avcodec_find_encoder_by_name(const char *name); AVCodec *avcodec_find_decoder(enum CodecID id); /** - * Finds a registered decoder with the specified name. + * Find a registered decoder with the specified name. * * @param name name of the requested decoder * @return A decoder if one was found, NULL otherwise. @@ -3235,7 +3265,7 @@ AVCodec *avcodec_find_decoder_by_name(const char *name); void avcodec_string(char *buf, int buf_size, AVCodecContext *enc, int encode); /** - * Sets the fields of the given AVCodecContext to default values. + * Set the fields of the given AVCodecContext to default values. * * @param s The AVCodecContext of which the fields should be set to default values. */ @@ -3246,7 +3276,7 @@ void avcodec_get_context_defaults(AVCodecContext *s); void avcodec_get_context_defaults2(AVCodecContext *s, enum AVMediaType); /** - * Allocates an AVCodecContext and sets its fields to default values. The + * Allocate an AVCodecContext and set its fields to default values. The * resulting struct can be deallocated by simply calling av_free(). * * @return An AVCodecContext filled with default values or NULL on failure. @@ -3259,14 +3289,27 @@ AVCodecContext *avcodec_alloc_context(void); AVCodecContext *avcodec_alloc_context2(enum AVMediaType); /** - * Sets the fields of the given AVFrame to default values. + * Copy the settings of the source AVCodecContext into the destination + * AVCodecContext. The resulting destination codec context will be + * unopened, i.e. you are required to call avcodec_open() before you + * can use this AVCodecContext to decode/encode video/audio data. + * + * @param dest target codec context, should be initialized with + * avcodec_alloc_context(), but otherwise uninitialized + * @param src source codec context + * @return AVERROR() on error (e.g. memory allocation error), 0 on success + */ +int avcodec_copy_context(AVCodecContext *dest, const AVCodecContext *src); + +/** + * Set the fields of the given AVFrame to default values. * * @param pic The AVFrame of which the fields should be set to default values. */ void avcodec_get_frame_defaults(AVFrame *pic); /** - * Allocates an AVFrame and sets its fields to default values. The resulting + * Allocate an AVFrame and set its fields to default values. The resulting * struct can be deallocated by simply calling av_free(). * * @return An AVFrame filled with default values or NULL on failure. @@ -3277,22 +3320,39 @@ AVFrame *avcodec_alloc_frame(void); int avcodec_default_get_buffer(AVCodecContext *s, AVFrame *pic); void avcodec_default_release_buffer(AVCodecContext *s, AVFrame *pic); int avcodec_default_reget_buffer(AVCodecContext *s, AVFrame *pic); + /** - * Modifies width and height values so that they will result in a memory + * Return the amount of padding in pixels which the get_buffer callback must + * provide around the edge of the image for codecs which do not have the + * CODEC_FLAG_EMU_EDGE flag. + * + * @return Required padding in pixels. + */ +unsigned avcodec_get_edge_width(void); +/** + * Modify width and height values so that they will result in a memory * buffer that is acceptable for the codec if you do not use any horizontal * padding. + * + * May only be used if a codec with CODEC_CAP_DR1 has been opened. + * If CODEC_FLAG_EMU_EDGE is not set, the dimensions must have been increased + * according to avcodec_get_edge_width() before. */ void avcodec_align_dimensions(AVCodecContext *s, int *width, int *height); /** - * Modifies width and height values so that they will result in a memory + * Modify width and height values so that they will result in a memory * buffer that is acceptable for the codec if you also ensure that all * line sizes are a multiple of the respective linesize_align[i]. + * + * May only be used if a codec with CODEC_CAP_DR1 has been opened. + * If CODEC_FLAG_EMU_EDGE is not set, the dimensions must have been increased + * according to avcodec_get_edge_width() before. */ void avcodec_align_dimensions2(AVCodecContext *s, int *width, int *height, int linesize_align[4]); /** - * Checks if the given dimension of a picture is valid, meaning that all + * Check if the given dimension of a picture is valid, meaning that all * bytes of the picture can be addressed with a signed int. * * @param[in] w Width of the picture. @@ -3309,7 +3369,7 @@ int avcodec_default_execute2(AVCodecContext *c, int (*func)(AVCodecContext *c2, //FIXME func typedef /** - * Initializes the AVCodecContext to use the given AVCodec. Prior to using this + * Initialize the AVCodecContext to use the given AVCodec. Prior to using this * function the context has to be allocated. * * The functions avcodec_find_decoder_by_name(), avcodec_find_encoder_by_name(), @@ -3339,7 +3399,7 @@ int avcodec_open(AVCodecContext *avctx, AVCodec *codec); #if LIBAVCODEC_VERSION_MAJOR < 53 /** - * Decodes an audio frame from buf into samples. + * Decode an audio frame from buf into samples. * Wrapper function which calls avcodec_decode_audio3. * * @deprecated Use avcodec_decode_audio3 instead. @@ -3357,7 +3417,7 @@ attribute_deprecated int avcodec_decode_audio2(AVCodecContext *avctx, int16_t *s #endif /** - * Decodes the audio frame of size avpkt->size from avpkt->data into samples. + * Decode the audio frame of size avpkt->size from avpkt->data into samples. * Some decoders may support multiple frames in a single AVPacket, such * decoders would then just decode the first frame. In this case, * avcodec_decode_audio3 has to be called again with an AVPacket that contains @@ -3401,7 +3461,7 @@ int avcodec_decode_audio3(AVCodecContext *avctx, int16_t *samples, #if LIBAVCODEC_VERSION_MAJOR < 53 /** - * Decodes a video frame from buf into picture. + * Decode a video frame from buf into picture. * Wrapper function which calls avcodec_decode_video2. * * @deprecated Use avcodec_decode_video2 instead. @@ -3419,7 +3479,7 @@ attribute_deprecated int avcodec_decode_video(AVCodecContext *avctx, AVFrame *pi #endif /** - * Decodes the video frame of size avpkt->size from avpkt->data into picture. + * Decode the video frame of size avpkt->size from avpkt->data into picture. * Some decoders may support multiple frames in a single AVPacket, such * decoders would then just decode the first frame. * @@ -3442,10 +3502,17 @@ attribute_deprecated int avcodec_decode_video(AVCodecContext *avctx, AVFrame *pi * * @param avctx the codec context * @param[out] picture The AVFrame in which the decoded video frame will be stored. + * Use avcodec_alloc_frame to get an AVFrame, the codec will + * allocate memory for the actual bitmap. + * with default get/release_buffer(), the decoder frees/reuses the bitmap as it sees fit. + * with overridden get/release_buffer() (needs CODEC_CAP_DR1) the user decides into what buffer the decoder + * decodes and the decoder tells the user once it does not need the data anymore, + * the user app can at this point free/reuse/keep the memory as it sees fit. + * * @param[in] avpkt The input AVpacket containing the input buffer. * You can create such packet with av_init_packet() and by then setting * data and size, some decoders might in addition need other fields like - * flags&PKT_FLAG_KEY. All decoders are designed to use the least + * flags&AV_PKT_FLAG_KEY. All decoders are designed to use the least * fields possible. * @param[in,out] got_picture_ptr Zero if no frame could be decompressed, otherwise, it is nonzero. * @return On error a negative value is returned, otherwise the number of bytes @@ -3465,8 +3532,8 @@ attribute_deprecated int avcodec_decode_subtitle(AVCodecContext *avctx, AVSubtit #endif /** - * Decodes a subtitle message. - * Returns a negative value on error, otherwise returns the number of bytes used. + * Decode a subtitle message. + * Return a negative value on error, otherwise return the number of bytes used. * If no subtitle could be decompressed, got_sub_ptr is zero. * Otherwise, the subtitle is stored in *sub. * @@ -3483,7 +3550,7 @@ int avcodec_parse_frame(AVCodecContext *avctx, uint8_t **pdata, uint8_t *buf, int buf_size); /** - * Encodes an audio frame from samples into buf. + * Encode an audio frame from samples into buf. * * @note The output buffer should be at least FF_MIN_BUFFER_SIZE bytes large. * However, for PCM audio the user will know how much space is needed @@ -3505,7 +3572,7 @@ int avcodec_encode_audio(AVCodecContext *avctx, uint8_t *buf, int buf_size, const short *samples); /** - * Encodes a video frame from pict into buf. + * Encode a video frame from pict into buf. * The input picture should be * stored using a specific format, namely avctx.pix_fmt. * @@ -3545,7 +3612,7 @@ void avcodec_default_free_buffers(AVCodecContext *s); /* misc useful functions */ /** - * Returns a single letter to describe the given picture type pict_type. + * Return a single letter to describe the given picture type pict_type. * * @param[in] pict_type the picture type * @return A single character representing the picture type. @@ -3553,7 +3620,7 @@ void avcodec_default_free_buffers(AVCodecContext *s); char av_get_pict_type_char(int pict_type); /** - * Returns codec bits per sample. + * Return codec bits per sample. * * @param[in] codec_id the codec * @return Number of bits per sample or zero if unknown for the given codec. @@ -3561,7 +3628,7 @@ char av_get_pict_type_char(int pict_type); int av_get_bits_per_sample(enum CodecID codec_id); /** - * Returns sample format bits per sample. + * Return sample format bits per sample. * * @param[in] sample_fmt the sample format * @return Number of bits per sample or zero if unknown for the given sample format. @@ -3604,6 +3671,7 @@ typedef struct AVCodecParserContext { int flags; #define PARSER_FLAG_COMPLETE_FRAMES 0x0001 +#define PARSER_FLAG_ONCE 0x0002 int64_t offset; ///< byte offset from starting packet start int64_t cur_frame_end[AV_PARSER_PTS_NB]; @@ -3793,15 +3861,14 @@ AVBitStreamFilter *av_bitstream_filter_next(AVBitStreamFilter *f); /* memory */ /** - * Reallocates the given block if it is not large enough, otherwise it - * does nothing. + * Reallocate the given block if it is not large enough, otherwise do nothing. * * @see av_realloc */ void *av_fast_realloc(void *ptr, unsigned int *size, unsigned int min_size); /** - * Allocates a buffer, reusing the given one if large enough. + * Allocate a buffer, reusing the given one if large enough. * * Contrary to av_fast_realloc the current buffer contents might not be * preserved and on error the old buffer is freed, thus no special @@ -3833,7 +3900,7 @@ int av_picture_pad(AVPicture *dst, const AVPicture *src, int height, int width, int padtop, int padbottom, int padleft, int padright, int *color); /** - * Encodes extradata length to a buffer. Used by xiph codecs. + * Encode extradata length to a buffer. Used by xiph codecs. * * @param s buffer to write to; must be at least (v/255+1) bytes long * @param v size of extradata in bytes @@ -3842,7 +3909,7 @@ int av_picture_pad(AVPicture *dst, const AVPicture *src, int height, int width, unsigned int av_xiphlacing(unsigned char *s, unsigned int v); /** - * Parses str and put in width_ptr and height_ptr the detected values. + * Parse str and put in width_ptr and height_ptr the detected values. * * @return 0 in case of a successful parsing, a negative value otherwise * @param[in] str the string to parse: it has to be a string in the format @@ -3855,7 +3922,7 @@ unsigned int av_xiphlacing(unsigned char *s, unsigned int v); int av_parse_video_frame_size(int *width_ptr, int *height_ptr, const char *str); /** - * Parses str and put in frame_rate the detected values. + * Parse str and store the detected values in *frame_rate. * * @return 0 in case of a successful parsing, a negative value otherwise * @param[in] str the string to parse: it has to be a string in the format @@ -3880,7 +3947,7 @@ int av_parse_video_frame_rate(AVRational *frame_rate, const char *str); void av_log_missing_feature(void *avc, const char *feature, int want_sample); /** - * Logs a generic warning message asking for a sample. This function is + * Log a generic warning message asking for a sample. This function is * intended to be used internally by FFmpeg (libavcodec, libavformat, etc.) * only, and would normally not be used by applications. * @param[in] avc a pointer to an arbitrary struct of which the first field is @@ -3890,7 +3957,7 @@ void av_log_missing_feature(void *avc, const char *feature, int want_sample); void av_log_ask_for_sample(void *avc, const char *msg); /** - * Registers the hardware accelerator hwaccel. + * Register the hardware accelerator hwaccel. */ void av_register_hwaccel(AVHWAccel *hwaccel);