* @short_description: Structure describing sets of media formats
* @see_also: #GstStructure
*
+ * Caps 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
+ * given pad can handle. They are also stored in the registry along with
+ * a description of the element.
+ *
+ * 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.
+ *
+ * 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
+ * a #GstBuffer allow for format negotiation upstream and downstream.
+ *
+ * A #GstCaps can be constructed with the following code fragment:
+ *
+ * <example>
+ * <title>Creating caps</title>
+ * <programlisting>
+ * GstCaps *caps;
+ * caps = gst_caps_new_simple ("video/x-raw-yuv",
+ * "format", GST_TYPE_FOURCC, GST_MAKE_FOURCC ('I', '4', '2', '0'),
+ * "framerate", G_TYPE_DOUBLE, 25.0,
+ * "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1,
+ * "width", G_TYPE_INT, 320,
+ * "height", G_TYPE_INT, 240,
+ * NULL);
+ * </programlisting>
+ * </example>
+ *
+ * A #GstCaps is fixed when it has no properties with ranges or lists. Use
+ * 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
+ * or intersecting.
+ *
+ * Last reviewed on 2005-11-09 (0.9.4)
*/
#ifdef HAVE_CONFIG_H
*
* Creates a new #GstCaps that contains one #GstStructure. The
* structure is defined by the arguments, which have the same format
- * as @gst_structure_new().
+ * as gst_structure_new().
* Caller is responsible for unreffing the returned caps.
*
* Returns: the new #GstCaps
* WARNING: This function takes a const GstCaps *, but returns a
* non-const GstStructure *. This is for programming convenience --
* the caller should be aware that structures inside a constant
- * @GstCaps should not be modified.
+ * #GstCaps should not be modified.
*
* Returns: a pointer to the #GstStructure corresponding to @index
*/
/**
* gst_caps_copy_nth:
- * @caps: the @GstCaps to copy
+ * @caps: the #GstCaps to copy
* @nth: the nth structure to copy
*
- * Creates a new @GstCaps and appends a copy of the nth structure
+ * Creates a new #GstCaps and appends a copy of the nth structure
* contained in @caps.
*
- * Returns: the new @GstCaps
+ * Returns: the new #GstCaps
*/
GstCaps *
gst_caps_copy_nth (const GstCaps * caps, guint nth)
/**
* gst_caps_truncate:
- * @caps: the @GstCaps to truncate
+ * @caps: the #GstCaps to truncate
*
* Destructively discard all but the first structure from @caps. Useful when
* fixating. @caps must be writable.
/**
* gst_caps_set_simple:
- * @caps: the @GstCaps to set
+ * @caps: the #GstCaps to set
* @field: first field to set
* @...: additional parameters
*
* Sets fields in a simple #GstCaps. A simple #GstCaps is one that
* only has one structure. The arguments must be passed in the same
- * manner as @gst_structure_set(), and be NULL-terminated.
+ * manner as gst_structure_set(), and be NULL-terminated.
*/
void
gst_caps_set_simple (GstCaps * caps, char *field, ...)
/**
* gst_caps_set_simple_valist:
- * @caps: the @GstCaps to copy
+ * @caps: the #GstCaps to copy
* @field: first field to set
* @varargs: additional parameters
*
* Sets fields in a simple #GstCaps. A simple #GstCaps is one that
* only has one structure. The arguments must be passed in the same
- * manner as @gst_structure_set(), and be NULL-terminated.
+ * manner as gst_structure_set(), and be NULL-terminated.
*/
void
gst_caps_set_simple_valist (GstCaps * caps, char *field, va_list varargs)
/**
* gst_caps_is_any:
- * @caps: the @GstCaps to test
+ * @caps: the #GstCaps to test
*
* Determines if @caps represents any media format.
*
/**
* gst_caps_is_empty:
- * @caps: the @GstCaps to test
+ * @caps: the #GstCaps to test
*
* Determines if @caps represents no media formats.
*
/**
* gst_caps_is_fixed:
- * @caps: the @GstCaps to test
+ * @caps: the #GstCaps to test
*
- * Fixed @GstCaps describe exactly one format, that is, they have exactly
+ * Fixed #GstCaps describe exactly one format, that is, they have exactly
* one structure, and each field in the structure describes a fixed type.
* Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.
*
*/
#define GST_CAPS_REFCOUNT_VALUE(caps) (g_atomic_int_get (&(GST_CAPS(caps))->refcount))
+/**
+ * GstCaps:
+ * @type: GType of the caps
+ * @refcount: the atomic refcount value
+ * @flags: extra flags for the caps
+ * @structs: array of #GstStructure for this caps
+ *
+ * Object describing media types.
+ */
struct _GstCaps {
GType type;
gpointer _gst_reserved[GST_PADDING];
};
+/**
+ * GstStaticCaps:
+ * @caps: the cached #GstCaps
+ * @string: a string describing a caps
+ *
+ * Datastructure to initialize #GstCaps from a string description usually
+ * used in conjunction with GST_STATIC_CAPS() and gst_static_caps_get() to
+ * instantiate a #GstCaps.
+ */
struct _GstStaticCaps {
/*< public >*/
GstCaps caps;
gboolean gst_caps_is_empty (const GstCaps *caps);
gboolean gst_caps_is_fixed (const GstCaps *caps);
gboolean gst_caps_is_always_compatible (const GstCaps *caps1,
- const GstCaps *caps2);
+ const GstCaps *caps2);
gboolean gst_caps_is_subset (const GstCaps *subset,
const GstCaps *superset);
gboolean gst_caps_is_equal (const GstCaps *caps1,
const GstCaps *caps2);
-gboolean gst_caps_is_equal_fixed (const GstCaps * caps1,
+gboolean gst_caps_is_equal_fixed (const GstCaps * caps1,
const GstCaps * caps2);
projects / platform / upstream / gstreamer.git / commitdiff