Add many new and improve existing doxy comments.

Commited in SoC by Bobby Bingham on 2007-08-14 16:39:26

Originally committed as revision 12095 to svn://svn.ffmpeg.org/ffmpeg/trunk

1 files changed, 207 insertions, 47 deletions

diff --git a/libavfilter/avfilter.h b/libavfilter/avfilter.h
index b0f41a9449..7c6b3616b7 100644
--- a/libavfilter/avfilter.h
+++ b/libavfilter/avfilter.h
@@ -39,12 +39,20 @@ typedef struct AVFilterPad     AVFilterPad;
  */
 typedef struct AVFilterPic
 {
-    uint8_t *data[4];
-    int linesize[4];    ///< number of bytes per line
-    enum PixelFormat format;
+    uint8_t *data[4];           ///< picture data for each plane
+    int linesize[4];            ///< number of bytes per line
+    enum PixelFormat format;    ///< colorspace
 
-    unsigned refcount;
+    unsigned refcount;          ///< number of references to this image
+
+    /** private data to be used by a custom free function */
     void *priv;
+    /**
+     * A pointer to the function to deallocate this image if the default
+     * function is not sufficient.  This could, for example, add the memory
+     * back into a memory pool to be reused later without the overhead of
+     * reallocating it from scratch.
+     */
     void (*free)(struct AVFilterPic *pic);
 } AVFilterPic;
 
@@ -58,10 +66,11 @@ typedef struct AVFilterPic
  */
 typedef struct AVFilterPicRef
 {
-    AVFilterPic *pic;
-    uint8_t *data[4];
-    int linesize[4];
-    int w, h;
+    AVFilterPic *pic;           ///< the picture that this is a reference to
+    uint8_t *data[4];           ///< picture data for each plane
+    int linesize[4];            ///< number of bytes per line
+    int w;                      ///< image width
+    int h;                      ///< image height
 
     int64_t pts;                ///< presentation timestamp in milliseconds
 
@@ -74,9 +83,11 @@ typedef struct AVFilterPicRef
 
 /**
  * Add a new reference to a picture.
- * @param ref An existing reference to the picture
- * @param pmask A bitmask containing the allowable permissions in the new reference
- * @return A new reference to the picture with the same properties as the old
+ * @param ref   An existing reference to the picture
+ * @param pmask A bitmask containing the allowable permissions in the new
+ *              reference
+ * @return      A new reference to the picture with the same properties as the
+ *              old, excluding any permissions denied by pmask
  */
 AVFilterPicRef *avfilter_ref_pic(AVFilterPicRef *ref, int pmask);
 
@@ -87,11 +98,15 @@ AVFilterPicRef *avfilter_ref_pic(AVFilterPicRef *ref, int pmask);
  */
 void avfilter_unref_pic(AVFilterPicRef *ref);
 
+/**
+ * A filter pad used for either input or output
+ */
 struct AVFilterPad
 {
     /**
-     * Pad name.  The name is unique among inputs and among oututs, but an
-     * input may have the same name as an output.
+     * Pad name.  The name is unique among inputs and among outputs, but an
+     * input may have the same name as an output.  This may be NULL if this
+     * pad has no need to ever be referenced by name.
      */
     char *name;
 
@@ -100,12 +115,17 @@ struct AVFilterPad
      * add audio in the future.
      */
     int type;
-#define AV_PAD_VIDEO 0
+#define AV_PAD_VIDEO 0      ///< video pad
 
     /**
      * Callback to get a list of supported formats.  The returned list should
-     * be terminated by -1.  This is used for both input and output pads and
-     * is required for both.
+     * be terminated by -1 (see avfilter_make_format_list for an easy way to
+     * create such a list).
+     *
+     * This is used for both input and output pads.  If ommitted from an output
+     * pad, it is assumed that the only format supported is the same format
+     * that is being used for the filter's first input.  If the filter has no
+     * inputs, then this may not be ommitted for its output pads.
      */
     int *(*query_formats)(AVFilterLink *link);
 
@@ -113,12 +133,16 @@ struct AVFilterPad
      * Callback called before passing the first slice of a new frame.  If
      * NULL, the filter layer will default to storing a reference to the
      * picture inside the link structure.
+     *
+     * Input video pads only.
      */
     void (*start_frame)(AVFilterLink *link, AVFilterPicRef *picref);
 
     /**
      * Callback function to get a buffer.  If NULL, the filter system will
-     * handle buffer requests.  Only required for input video pads.
+     * handle buffer requests.
+     *
+     * Input video pads only.
      */
     AVFilterPicRef *(*get_video_buffer)(AVFilterLink *link, int perms);
 
@@ -126,48 +150,69 @@ struct AVFilterPad
      * Callback called after the slices of a frame are completely sent.  If
      * NULL, the filter layer will default to releasing the reference stored
      * in the link structure during start_frame().
+     *
+     * Input video pads only.
      */
     void (*end_frame)(AVFilterLink *link);
 
     /**
      * Slice drawing callback.  This is where a filter receives video data
-     * and should do its processing.  Only required for input video pads.
+     * and should do its processing.
+     *
+     * Input video pads only.
      */
     void (*draw_slice)(AVFilterLink *link, uint8_t *data[4], int y, int height);
 
     /**
      * Frame request callback.  A call to this should result in at least one
-     * frame being output over the given link.  Video output pads only.
+     * frame being output over the given link.  This should return zero on
+     * success, and another value on error.
+     *
+     * Output video pads only.
      */
     int (*request_frame)(AVFilterLink *link);
 
     /**
-     * Link configuration callback.  For output pads, this should set the link
-     * properties such as width/height.  NOTE: this should not set the format
-     * property - that is negotiated between filters by the filter system using
-     * the query_formats() callback.
+     * Link configuration callback.
+     *
+     * For output pads, this should set the link properties such as
+     * width/height.  This should NOT set the format property - that is
+     * negotiated between filters by the filter system using the
+     * query_formats() callback before this function is called.
      *
      * For input pads, this should check the properties of the link, and update
      * the filter's internal state as necessary.
+     *
+     * For both input and output filters, this should return zero on success,
+     * and another value on error.
      */
     int (*config_props)(AVFilterLink *link);
 };
 
-/* the default implementations of filter entry points */
+/** Default handler for start_frame() for video inputs */
 void avfilter_default_start_frame(AVFilterLink *link, AVFilterPicRef *picref);
+/** Default handler for end_frame() for video inputs */
 void avfilter_default_end_frame(AVFilterLink *link);
+/** Default handler for config_props() for video outputs */
 int avfilter_default_config_output_link(AVFilterLink *link);
+/** Default handler for config_props() for video inputs */
 int avfilter_default_config_input_link (AVFilterLink *link);
+/** Default handler for query_formats() for video outputs */
 int *avfilter_default_query_output_formats(AVFilterLink *link);
+/** Default handler for get_video_buffer() for video inputs */
 AVFilterPicRef *avfilter_default_get_video_buffer(AVFilterLink *link,
                                                   int perms);
 
+/**
+ * Filter definition.  This defines the pads a filter contains, and all the
+ * callback functions used to interact with the filter.
+ */
 typedef struct
 {
-    char *name;
-    char *author;
+    char *name;         ///< filter name
+    char *author;       ///< filter author
 
-    int priv_size;
+    int priv_size;      ///< size of private data to allocate for the filter
 
     /**
      * Filter initialization function.  Args contains the user-supplied
@@ -176,69 +221,184 @@ typedef struct
      * and is used to pass data to the filter.
      */
     int (*init)(AVFilterContext *ctx, const char *args, void *opaque);
+
+    /**
+     * Filter uninitialization function.  Should deallocate any memory held
+     * by the filter, release any picture references, etc.  This does not need
+     * to deallocate the AVFilterContext->priv memory itself.
+     */
     void (*uninit)(AVFilterContext *ctx);
 
-    const AVFilterPad *inputs;  /// NULL terminated list of inputs. NULL if none
-    const AVFilterPad *outputs; /// NULL terminated list of outputs. NULL if none
+    const AVFilterPad *inputs;  ///< NULL terminated list of inputs. NULL if none
+    const AVFilterPad *outputs; ///< NULL terminated list of outputs. NULL if none
 } AVFilter;
 
+/** An instance of a filter */
 struct AVFilterContext
 {
-    AVClass *av_class;
+    AVClass *av_class;              ///< Needed for av_log()
 
-    AVFilter *filter;
+    AVFilter *filter;               ///< The AVFilter of which this is an instance
 
-    char *name;
+    char *name;                     ///< name of this filter instance
 
-    unsigned input_count;
-    AVFilterPad   *input_pads;
-    AVFilterLink **inputs;
+    unsigned input_count;           ///< number of input pads
+    AVFilterPad   *input_pads;      ///< array of input pads
+    AVFilterLink **inputs;          ///< array of pointers to input links
 
-    unsigned output_count;
-    AVFilterPad   *output_pads;
-    AVFilterLink **outputs;
+    unsigned output_count;          ///< number of output pads
+    AVFilterPad   *output_pads;     ///< array of output pads
+    AVFilterLink **outputs;         ///< array of pointers to output links
 
-    void *priv;
+    void *priv;                     ///< private data for use by the filter
 };
 
+/**
+ * A links between two filters.  This contains pointers to the source and
+ * destination filters between which this link exists, and the indices of
+ * the pads involved.  In addition, this link also contains the parameters
+ * which have been negotiated and agreed upon between the filter, such as
+ * image dimensions, format, etc
+ */
 struct AVFilterLink
 {
-    AVFilterContext *src;
-    unsigned int srcpad;
+    AVFilterContext *src;       ///< source filter
+    unsigned int srcpad;        ///< index of the output pad on the source filter
 
-    AVFilterContext *dst;
-    unsigned int dstpad;
+    AVFilterContext *dst;       ///< dest filter
+    unsigned int dstpad;        ///< index of the input pad on the dest filter
 
-    int w, h;
-    enum PixelFormat format;
+    int w;                      ///< agreed upon image width
+    int h;                      ///< agreed upon image height
+    enum PixelFormat format;    ///< agreed upon image colorspace
 
     AVFilterPicRef *cur_pic;
     AVFilterPicRef *outpic;
 };
 
-/** Link two filters together */
+/**
+ * Link two filters together
+ * @param src    The source filter
+ * @param srcpad Index of the output pad on the source filter
+ * @param dst    The destination filter
+ * @param dstpad Index of the input pad on the destination filter
+ * @return       Zero on success
+ */
 int avfilter_link(AVFilterContext *src, unsigned srcpad,
                   AVFilterContext *dst, unsigned dstpad);
 
-/** Configure the colorspace, dimensions, etc of a link */
+/**
+ * Negotiate the colorspace, dimensions, etc of a link
+ * @param link The link to negotiate the properties of
+ * @return     Zero on successful negotiation
+ */
 int avfilter_config_link(AVFilterLink *link);
 
+/**
+ * Request a picture buffer with a specific set of permissions
+ * @param link  The output link to the filter from which the picture will
+ *              be requested
+ * @param perms The required access permissions
+ * @return      A reference to the picture.  This must be unreferenced with
+ *              avfilter_unref_pic when you are finished with it.
+ */
 AVFilterPicRef *avfilter_get_video_buffer(AVFilterLink *link, int perms);
+
+/**
+ * Request an input frame from the filter at the other end of the link.
+ * @param link The input link
+ * @return     Zero on success
+ */
 int  avfilter_request_frame(AVFilterLink *link);
+
+/**
+ * Notofy the next filter of the start of a frame.
+ * @param link   The output link the frame will be sent over
+ * @param picref A reference to the frame about to be sent.  The data for this
+ *               frame need only be valid once draw_slice() is called for that
+ *               portion.  The receiving filter will free this reference when
+ *               it no longer needs it.
+ */
 void avfilter_start_frame(AVFilterLink *link, AVFilterPicRef *picref);
+
+/**
+ * Notify the next filter that the current frame has finished
+ * @param link The output link the frame was sent over
+ */
 void avfilter_end_frame(AVFilterLink *link);
+
+/**
+ * Send a slice to the next filter
+ * @param link The output link over which the frame is being sent
+ * @param data Start of the picture data for this slice
+ * @param y    Offset in pixels from the top of the image for this slice
+ * @param h    Height of this slice in pixels
+ */
 void avfilter_draw_slice(AVFilterLink *link, uint8_t *data[4], int y, int h);
 
+/** Initialize the filter system.  Registers all builtin filters */
 void avfilter_init(void);
+
+/** Uninitialize the filter system.  Unregisters all filters */
 void avfilter_uninit(void);
+
+/**
+ * Register a filter.  This is only needed if you plan to create an instance of
+ * this filter by name later with avfilter_create_by_name.  A filter can still
+ * by created with acfilter_create even if it is not registered.
+ * @param filter The filter to register
+ */
 void avfilter_register(AVFilter *filter);
+
+/**
+ * Gets a filter definition matching the given name
+ * @param name The filter name to find
+ * @return     The filter definition, if any matching one is registered.
+ *             NULL if none found.
+ */
 AVFilter *avfilter_get_by_name(char *name);
 
+/**
+ * Create a filter instance
+ * @param filter    The filter to create an instance of
+ * @param inst_name Name to give to the new instance.  Can be NULL for none.
+ * @return          Pointer to the new instance on success.  NULL on failure.
+ */
 AVFilterContext *avfilter_create(AVFilter *filter, char *inst_name);
+
+/**
+ * Creates a filter instace
+ * @param name      The name of the filter type which is to be instantiated
+ * @param inst_name Name to give to the new instance.  Can be NULL for none.
+ * @return          Pointer to the new instance on success.  NULL in failure.
+ */
 AVFilterContext *avfilter_create_by_name(char *name, char *inst_name);
+
+/**
+ * Initialize a filter
+ * @param filter The filter to initialize
+ * @param args   A string of parameters to use when initializing the filter.
+ *               The format and meaning of this string varies by filter.
+ * @param opaque Any extra non-string data needed by the filter.  The meaning
+ *               of this parameter varies by filter.
+ * @return       Zero on success
+ */
 int avfilter_init_filter(AVFilterContext *filter, const char *args, void *opaque);
+
+/**
+ * Destroy a filter
+ * @param filter The filter to destroy
+ */
 void avfilter_destroy(AVFilterContext *filter);
 
+/**
+ * Helper function to create a list of supported formats.  This is intended
+ * for use in AVFilterPad->query_formats().
+ * @param len The number of formats supported
+ * @param ... A list of the supported formats
+ * @return    The format list in a form suitable for returning from
+ *            AVFilterPad->query_formats()
+ */
 int *avfilter_make_format_list(int len, ...);
 
 /**