On Tue, Jan 08, 2013 at 03:35:04PM +0100, Anton Khirnov wrote:
> --- a/libavutil/Makefile
> +++ b/libavutil/Makefile
> @@ -11,6 +11,7 @@ HEADERS = adler32.h
> \
> avutil.h \
> base64.h \
> blowfish.h \
> + buffer.h \
> bswap.h \
> channel_layout.h \
> common.h \
order
> --- /dev/null
> +++ b/libavutil/buffer.h
> @@ -0,0 +1,183 @@
> +
> + * @{
> + * AVBuffer is an API for reference counted data buffers.
reference-counted
> + * There are two core objects in this API -- AVBuffer and AVBufferRef.
> AVBuffer
> + * represents the data buffer itself; it is opaque and not meant to be
> accessed
> + * by the caller directly, but only through AVBufferRef. However the caller
> may
However,
> + * e.g. compare two AVBuffer pointers to check whether two different
> references
> + * are describing the same data buffer (note that the two references may
> point
> + * to different parts of the buffer, so comparing the data pointers won't
> work).
won't --> will not
> + * The convention throughout this API and the rest of Libav is such that the
> + * buffer is considered writable if there exists only one reference to it
> (and
> + * it has not been marked as read-only). The av_buffer_is_writable()
> function is
> + * provided to check whether this is true() and av_buffer_make_writable()
> will
true()?
> + * Note that referencing and unreferencing the buffers is thread safe and
> thus
thread-safe
> +/**
> + * Create an AVBuffer from an existing array.
> + *
> + * @param data data array.
> + * If this function is successful, data is owned by the AVBuffer. The caller
> may
> + * only access data through the returned AVBufferRef and references derived
> from
> + * it.
> + * If this function fails, data is left untouched.
> + * @param size size of data in bytes
> + * @param free a callback for freeing data
> + * @param opaque parameter to be passed to free
> + * @param flags a combination of AV_BUFFER_FLAG_*
> + *
> + * @return an AVBufferRef referring to data on success, NULL on failure.
> + */
> +AVBufferRef *av_buffer_create(uint8_t *data, int size,
> + void (*free)(void *opaque, uint8_t *data),
> + void *opaque, int flags);
The data parameter description appears misplaced.
> +/**
> + * Default free callback, which calls av_free() on the buffer data.
> + * This function is meant to be passed to av_buffer_create(), not called
> + * directly.
> + */
> +void av_buffer_default_free(void *opaque, uint8_t *data);
> +
> +/**
> + * Create a new reference to an AVBuffer.
> + *
> + * @return a new AVBufferRef referring to the same AVBuffer as buf or NULL on
> + * failure.
> + */
> +AVBufferRef *av_buffer_ref(AVBufferRef *buf);
> +
> +/**
> + * Free a given reference and automatically free the buffer if there are no
> more
> + * references to it.
> + *
> + * @param buf the reference to be freed. The pointer is set to NULL on
> return.
> + */
> +void av_buffer_unref(AVBufferRef **buf);
> +
> +/**
> + * @return 1 if the caller may write to the data referred to by buf (which is
> + * true if and only if buf is the only reference to the underlying AVBuffer).
> + * Return 0 otherwise.
> + * A positive answer is valid until av_buffer_ref() is called on buf.
> + */
> +int av_buffer_is_writable(const AVBufferRef *buf);
These have incomplete parameter documentation.
> +/**
> + * Create a writable reference from a given buffer reference, avoiding data
> copy
> + * if possible.
> + *
> + * @param buf buffer reference to make writable. On success, buf is either
> left
> + * untouched, or it is unreferenced and a new writable AVBufferRef is
> written in
> + * its place. On failure, buf is left untouched.
> + * @return 0 on success, a negative AVERROR on failure.
> + */
> +int av_buffer_make_writable(AVBufferRef **buf);
> +
> +/**
> + * Reallocate a given buffer.
> + *
> + * @param buf a buffer reference to reallocate. On success, buf will be
> + * unreferenced and a new reference with the required size will be written in
> + * its place. On failure buf will be left untouched.
> + * @param size required new buffer size.
> + * @return 0 on success, a negative AVERROR on failure.
> + */
> +int av_buffer_realloc(AVBufferRef **buf, int size);
Both of these would be more readable with the parameter descriptions aligned.
> --- /dev/null
> +++ b/libavutil/buffer_internal.h
> @@ -0,0 +1,51 @@
> +
> + /**
> + * if non-0, this buffer is always considered to be read-only
> + */
> + int readonly;
This is a complete sentence, so capitalize and end in a period.
Optionally replace "non-0" by "nonzero".
Diego
_______________________________________________
libav-devel mailing list
[email protected]
https://lists.libav.org/mailman/listinfo/libav-devel
