+2005-11-18 Stefan Kost <ensonic@users.sf.net>
+
+ * gst/gstcaps.c:
+ * gst/gstghostpad.c:
+ * gst/gsttrace.c:
+ * gst/gstvalue.c:
+ * gst/gstvalue.h:
+ docs fixes
+
2005-11-18 Andy Wingo <wingo@pobox.com>
* gst/net/gstnetclientclock.c: Turn off debugging.
* @short_description: Structure describing sets of media formats
* @see_also: #GstStructure
*
- * Caps are lighweight refcounted objects describing media types.
+ * Caps (capabilities) are lighweight refcounted objects describing media types.
* They are composed of an array of #GstStructure.
*
* Caps are exposed on #GstPadTemplate to describe all possible types a
*
* Caps are exposed on the element pads using the gst_pad_get_caps() pad
* function. This function describes the possible types that the pad can
- * handle or produce at runtime.
+ * handle or produce at runtime.
*
* Caps are also attached to buffers to describe to content of the data
* pointed to by the buffer with gst_buffer_set_caps(). Caps attached to
* gst_caps_is_fixed() to test for fixed caps. Only fixed caps can be
* set on a #GstPad or #GstBuffer.
*
- * Various methods exist to work with the media types such as substracting
+ * Various methods exist to work with the media types such as subtracting
* or intersecting.
*
* Last reviewed on 2005-11-09 (0.9.4)
* @short_description: Pseudo link pads
* @see_also: #GstPad
*
+ * GhostPads are useful when organizing pipelines with #GstBin like elements.
+ * The idea here is to create hierarchical element graphs. The bin element
+ * contains a sub-graph. Now one would like to treat the bin-element like other
+ * #GstElements. This is where GhostPads come into play. A GhostPad acts as a
+ * proxy for another pad. Thus the bin can have sink and source ghost-pads that
+ * are accociated with sink and source pads of the child elements.
+ *
+ * If the target pad is known at creation time, gst_ghost_pad_new() is the
+ * function to use to get a ghost-pad. Otherwise one can use gst_ghost_pad_new_notarget()
+ * to create the ghost-pad and use gst_ghost_pad_set_target() to establish the
+ * accociation later on.
+ *
+ * Last reviewed on 2005-11-18 (0.9.5)
*/
#include "gst_private.h"
* SECTION:gsttrace
* @short_description: Tracing functionality
*
+ * Traces allows to track object allocation. They provide a instance counter per
+ * #GType. The counter is incremented for each object allocated and decremented
+ * it when it's freed.
+ *
+ * (FIXME: add example - see jamboree/tests/read-tags.c)
+ *
+ * Last reviewed on 2005-11-18 (0.9.5)
*/
#ifdef HAVE_CONFIG_H
*
* Creates a GValue cooresponding to the union of @value1 and @value2.
*
- * Returns: TRUE if the values could be unioned
+ * Returns: %TRUE if a union was successful
*/
+/* FIXME: change return type to 'void'? */
gboolean
gst_value_union (GValue * dest, const GValue * value1, const GValue * value2)
{
* Subtracts @subtrahend from @minuend and stores the result in @dest.
* Note that this means subtraction as in sets, not as in mathematics.
*
- * Returns: TRUE if the subtraction is not empty
+ * Returns: %TRUE if the subtraction is not empty
*/
gboolean
gst_value_subtract (GValue * dest, const GValue * minuend,
typedef int (* GstValueCompareFunc) (const GValue *value1,
const GValue *value2);
+/**
+ * GstValueSerializeFunc:
+ * @value1: a #GValue
+ *
+ * Used by gst_value_serialize() to obtain a non-binary form of the #GValue.
+ *
+ * Returns: the string representation of the value
+ */
typedef char * (* GstValueSerializeFunc) (const GValue *value1);
+/**
+ * GstValueDeserializeFunc:
+ * @dest: a #GValue
+ * @s: a string
+ *
+ * Used by gst_value_deserialize() to parse a non-binary form into the #GValue.
+ *
+ * Returns: %TRUE for success
+ */
typedef gboolean (* GstValueDeserializeFunc) (GValue *dest,
const char *s);
+/**
+ * GstValueUnionFunc:
+ * @dest: a #GValue for the result
+ * @value1: a #GValue operand
+ * @value2: a #GValue operand
+ *
+ * Used by gst_value_union() to perform unification for a specific #GValue
+ * type. Register a new implementation with gst_value_register_union_func().
+ *
+ * Returns: %TRUE if a union was successful
+ */
+/* FIXME: shouldn't the return value be gboolean ? */
typedef int (* GstValueUnionFunc) (GValue *dest,
const GValue *value1,
const GValue *value2);
+/**
+ * GstValueIntersectFunc:
+ * @dest: a #GValue for the result
+ * @value1: a #GValue operand
+ * @value2: a #GValue operand
+ *
+ * Used by gst_value_intersect() to perform intersection for a specific #GValue
+ * type. Register a new implementation with gst_value_register_intersection_func().
+ *
+ * Returns: %TRUE if the values can intersect
+ */
+/* FIXME: shouldn't the return value be gboolean ? */
typedef int (* GstValueIntersectFunc) (GValue *dest,
const GValue *value1,
const GValue *value2);
+/**
+ * GstValueSubtractFunc:
+ * @dest: a #GValue for the result
+ * @minuend: a #GValue operand
+ * @subtrahend: a #GValue operand
+ *
+ * Used by gst_value_subtract() to perform subtraction for a specific #GValue
+ * type. Register a new implementation with gst_value_register_subtract_func().
+ *
+ * Returns: %TRUE if the subtraction is not empty
+ */
+/* FIXME: shouldn't the return value be gboolean ? */
typedef int (* GstValueSubtractFunc) (GValue *dest,
const GValue *minuend,
const GValue *subtrahend);
typedef struct _GstValueTable GstValueTable;
+/**
+ * GstValueTable:
+ * @type: a #GType
+ * @compare: a #GstValueCompareFunc
+ * @serialize: a #GstValueSerializeFunc
+ * @deserialize: a #GstValueDeserializeFunc
+ *
+ * VTable for the #GValue @type.
+ */
struct _GstValueTable {
GType type;
GstValueCompareFunc compare;