diff options
author | Wim Lewis <wiml@hhhh.org> | 2011-04-02 15:30:24 -0700 |
---|---|---|
committer | Michael Niedermayer <michaelni@gmx.at> | 2011-04-03 03:18:20 +0200 |
commit | f38fa75d976c06649cd67d0b581b199679c26470 (patch) | |
tree | a937da56f9f090d5a6d5e3af2e385d5e4f28ab9f | |
parent | 71aed40b56af81d46c19620af5c4579703167475 (diff) | |
download | ffmpeg-f38fa75d976c06649cd67d0b581b199679c26470.tar.gz |
Add or elaborate on some documentation comments in avcodec.h.
Signed-off-by: Michael Niedermayer <michaelni@gmx.at>
-rw-r--r-- | libavcodec/avcodec.h | 43 |
1 files changed, 38 insertions, 5 deletions
diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h index 712a34af31..6c7ec0e1c0 100644 --- a/libavcodec/avcodec.h +++ b/libavcodec/avcodec.h @@ -3308,7 +3308,9 @@ void av_resample_compensate(struct AVResampleContext *c, int sample_delta, int c void av_resample_close(struct AVResampleContext *c); /** - * Allocate memory for a picture. Call avpicture_free to free it. + * Allocate memory for a picture. Call avpicture_free() to free it. + * + * \see avpicture_fill() * * @param picture the picture to be filled in * @param pix_fmt the format of the picture @@ -3320,6 +3322,8 @@ int avpicture_alloc(AVPicture *picture, enum PixelFormat pix_fmt, int width, int /** * Free a picture previously allocated by avpicture_alloc(). + * The data buffer used by the AVPicture is freed, but the AVPicture structure + * itself is not. * * @param picture the AVPicture to be freed */ @@ -3335,6 +3339,9 @@ void avpicture_free(AVPicture *picture); * will be stored in the lines_sizes array. * Call with ptr == NULL to get the required size for the ptr buffer. * + * To allocate the buffer and fill in the AVPicture fields in one call, + * use avpicture_alloc(). + * * @param picture AVPicture whose fields are to be filled in * @param ptr Buffer which will contain or contains the actual image data * @param pix_fmt The format in which the picture data is stored. @@ -3344,6 +3351,22 @@ void avpicture_free(AVPicture *picture); */ int avpicture_fill(AVPicture *picture, uint8_t *ptr, enum PixelFormat pix_fmt, int width, int height); + +/** + * Copy pixel data from an AVPicture into a buffer. + * The data is stored compactly, without any gaps for alignment or padding + * which may be applied by avpicture_fill(). + * + * \see avpicture_get_size() + * + * @param[in] src AVPicture containing image data + * @param[in] pix_fmt The format in which the picture data is stored. + * @param[in] width the width of the image in pixels. + * @param[in] height the height of the image in pixels. + * @param[out] dest A buffer into which picture data will be copied. + * @param[in] dest_size The size of 'dest'. + * @return The number of bytes written to dest, or a negative value (error code) on error. + */ int avpicture_layout(const AVPicture* src, enum PixelFormat pix_fmt, int width, int height, unsigned char *dest, int dest_size); @@ -3351,8 +3374,8 @@ int avpicture_layout(const AVPicture* src, enum PixelFormat pix_fmt, int width, * Calculate the size in bytes that a picture of the given width and height * would occupy if stored in the given picture format. * Note that this returns the size of a compact representation as generated - * by avpicture_layout, which can be smaller than the size required for e.g. - * avpicture_fill. + * by avpicture_layout(), which can be smaller than the size required for e.g. + * avpicture_fill(). * * @param pix_fmt the given picture format * @param width the width of the image @@ -3361,7 +3384,14 @@ int avpicture_layout(const AVPicture* src, enum PixelFormat pix_fmt, int width, */ int avpicture_get_size(enum PixelFormat pix_fmt, int width, int height); void avcodec_get_chroma_sub_sample(enum PixelFormat pix_fmt, int *h_shift, int *v_shift); + +/** + * Return the short name for a pixel format. + * + * \see av_get_pix_fmt(), av_get_pix_fmt_string(). + */ const char *avcodec_get_pix_fmt_name(enum PixelFormat pix_fmt); + void avcodec_set_dimensions(AVCodecContext *s, int width, int height); #if LIBAVCODEC_VERSION_MAJOR < 53 @@ -3498,9 +3528,12 @@ const char *avcodec_license(void); /** * Initialize libavcodec. + * If called more than once, does nothing. * * @warning This function must be called before any other libavcodec * function. + * + * @warning This function is not thread-safe. */ void avcodec_init(void); @@ -3514,7 +3547,7 @@ attribute_deprecated void register_avcodec(AVCodec *codec); /** * Register the codec codec and initialize libavcodec. * - * @see avcodec_init() + * @see avcodec_init(), avcodec_register_all() */ void avcodec_register(AVCodec *codec); @@ -3702,7 +3735,7 @@ int avcodec_default_execute2(AVCodecContext *c, int (*func)(AVCodecContext *c2, * @param avctx The context which will be set up to use the given codec. * @param codec The codec to use within the context. * @return zero on success, a negative value on error - * @see avcodec_alloc_context, avcodec_find_decoder, avcodec_find_encoder + * @see avcodec_alloc_context, avcodec_find_decoder, avcodec_find_encoder, avcodec_close */ int avcodec_open(AVCodecContext *avctx, AVCodec *codec); |