+2005-10-08 Stefan Kost <ensonic@users.sf.net>
+ * docs/gst/gstreamer-sections.txt:
+ * gst/gstmessage.c:
+ * gst/gstmessage.h:
+ * gst/gstminiobject.c:
+ * gst/gstminiobject.h:
+ * gst/gstobject.h:
+ * gst/gstpad.h:
+ * gst/gstutils.h:
+ lots of new docs and doc fixes
+
2005-10-08 Thomas Vander Stichele <thomas at apestaart dot org>
* gst/gstplugin.c: (gst_plugin_finalize), (gst_plugin_load_file):
gst_index_add_id
gst_index_get_assoc_entry
gst_index_get_assoc_entry_full
-gst_index_entry_get_type
gst_index_entry_copy
gst_index_entry_free
gst_index_entry_assoc_map
gst_index_get_type
gst_assoc_flags_get_type
gst_index_certainty_get_type
+gst_index_entry_get_type
gst_index_entry_type_get_type
gst_index_flags_get_type
gst_index_lookup_method_get_type
gst_message_parse_tag
gst_message_parse_warning
gst_message_ref
-gst_message_type_get_type
gst_message_unref
<SUBSECTION Standard>
GstMessageClass
GST_TYPE_MESSAGE_TYPE
<SUBSECTION Private>
gst_message_get_type
+gst_message_type_get_type
</SECTION>
gst_task_cleanup_all
gst_task_create
gst_task_get_state
-gst_task_get_type
gst_task_join
gst_task_pause
gst_task_set_lock
{0, NULL, 0}
};
+/**
+ * gst_message_type_get_name:
+ * @type: the message type
+ *
+ * Get a printable name for the given message type. Do not modify or free.
+ *
+ * Returns: a reference to the static name of the message.
+ */
const gchar *
gst_message_type_get_name (GstMessageType type)
{
return "unknown";
}
+/**
+ * gst_message_type_to_quark:
+ * @type: the message type
+ *
+ * Get the unique quark for the given message type.
+ *
+ * Returns: the quark associated with the message type
+ */
GQuark
gst_message_type_to_quark (GstMessageType type)
{
}
/**
- * gst_message_new_state_change:
+ * gst_message_new_state_changed:
* @src: The object originating the message.
* @old: The previous state.
* @new: The new (current) state.
* Create a new application-typed message. GStreamer will never create these
* messages; they are a gift from us to you. Enjoy.
*
+ * Returns: The new application message.
+ *
* MT safe.
*/
GstMessage *
* "the firewire cable was unplugged". The format of the message should be
* documented in the element's documentation. The structure field can be NULL.
*
+ * Returns: The new element message.
+ *
* MT safe.
*/
GstMessage *
/**
* gst_message_parse_tag:
* @message: A valid #GstMessage of type GST_MESSAGE_TAG.
+ * @tag_list: Return location for the tag-list.
*
* Extracts the tag list from the GstMessage. The tag list returned in the
* output argument is a copy; the caller must free it when done.
/**
* gst_message_parse_error:
* @message: A valid #GstMessage of type GST_MESSAGE_ERROR.
+ * @gerror: Location for the GError
+ * @debug: Location for the debug message
*
* Extracts the GError and debug string from the GstMessage. The values returned
* in the output arguments are copies; the caller must free them when done.
/**
* gst_message_parse_warning:
* @message: A valid #GstMessage of type GST_MESSAGE_WARNING.
+ * @gerror: Location for the GError
+ * @debug: Location for the debug message
*
* Extracts the GError and debug string from the GstMessage. The values returned
* in the output arguments are copies; the caller must free them when done.
/**
* gst_message_parse_segment_start:
* @message: A valid #GstMessage of type GST_MESSAGE_SEGMENT_START.
+ * @timestamp: Result location for the timestamp
*
* Extracts the timestamp from the segment start message.
*
/**
* gst_message_parse_segment_done:
* @message: A valid #GstMessage of type GST_MESSAGE_SEGMENT_DONE.
+ * @timestamp: Result location for the timestamp
*
* Extracts the timestamp from the segment done message.
*
GQuark gst_message_type_to_quark (GstMessageType type);
/* refcounting */
+/**
+ * gst_message_ref:
+ * @msg: the message to ref
+ *
+ * Convinience macro to increase the reference count of the message.
+ *
+ * Returns: the refed message.
+ */
#define gst_message_ref(msg) GST_MESSAGE (gst_mini_object_ref (GST_MINI_OBJECT (msg)))
+/**
+ * gst_message_unref:
+ * @msg: the message to unref
+ *
+ * Convinience macro to decrease the reference count of the message, possibly freeing
+ * the it.
+ */
#define gst_message_unref(msg) gst_mini_object_unref (GST_MINI_OBJECT (msg))
/* copy message */
+/**
+ * gst_message_copy:
+ * @msg: the message to copy
+ *
+ * Creates a copy of the message.
+ *
+ * MT safe
+ *
+ * Returns: the new message.
+ */
#define gst_message_copy(msg) GST_MESSAGE (gst_mini_object_copy (GST_MINI_OBJECT (msg)))
+/**
+ * gst_message_make_writable:
+ * @msg: the message to make writable
+ *
+ * Checks if a message is writable. If not, a writable copy is made and
+ * returned.
+ *
+ * MT safe
+ *
+ * Returns: a message (possibly a duplicate) that it writable.
+ */
#define gst_message_make_writable(msg) GST_MESSAGE (gst_mini_object_make_writable (GST_MINI_OBJECT (msg)))
GstMessage * gst_message_new_eos (GstObject * src);
GstMessage * gst_message_new_error (GstObject * src, GError * error, gchar * debug);
GstMessage * gst_message_new_warning (GstObject * src, GError * error, gchar * debug);
GstMessage * gst_message_new_tag (GstObject * src, GstTagList * tag_list);
-GstMessage * gst_message_new_state_changed (GstObject * src, GstState old_state,
- GstState new_state, GstState pending);
+GstMessage * gst_message_new_state_changed (GstObject * src, GstState old,
+ GstState new, GstState pending);
GstMessage * gst_message_new_clock_provide (GstObject * src, GstClock *clock, gboolean ready);
GstMessage * gst_message_new_clock_lost (GstObject * src, GstClock *clock);
GstMessage * gst_message_new_new_clock (GstObject * src, GstClock *clock);
void gst_message_parse_error (GstMessage *message, GError **gerror, gchar **debug);
void gst_message_parse_warning (GstMessage *message, GError **gerror, gchar **debug);
void gst_message_parse_tag (GstMessage *message, GstTagList **tag_list);
-void gst_message_parse_state_changed (GstMessage *message, GstState *old_state,
- GstState *new_state, GstState *pending);
+void gst_message_parse_state_changed (GstMessage *message, GstState *old,
+ GstState *new, GstState *pending);
void gst_message_parse_clock_provide (GstMessage *message, GstClock **clock, gboolean *ready);
void gst_message_parse_clock_lost (GstMessage *message, GstClock **clock);
void gst_message_parse_new_clock (GstMessage *message, GstClock **clock);
* gst_mini_object_make_writable:
* @mini_object: the mini-object to make writable
*
- * Checks if a mini-object is writable. If not, a copy is made and
- * the copy is returned.
+ * Checks if a mini-object is writable. If not, a witeable copy is made and
+ * returned.
*
* MT safe
*
typedef GstMiniObject * (*GstMiniObjectCopyFunction) (const GstMiniObject *);
typedef void (*GstMiniObjectFinalizeFunction) (GstMiniObject *);
+/**
+ * GST_MINI_OBJECT_FLAGS:
+ * @obj: MiniObject to return flags for.
+ *
+ * This macro returns the entire set of flags for the mini-object.
+ */
#define GST_MINI_OBJECT_FLAGS(obj) (GST_MINI_OBJECT(obj)->flags)
+/**
+ * GST_MINI_OBJECT_FLAG_IS_SET:
+ * @obj: MiniObject to check for flags.
+ * @flag: Flag to check for
+ *
+ * This macro checks to see if the given flag is set.
+ */
#define GST_MINI_OBJECT_FLAG_IS_SET(obj,flag) (GST_MINI_OBJECT_FLAGS(obj) & (flag))
+/**
+ * GST_MINI_OBJECT_FLAG_SET:
+ * @obj: MiniObject to set flag in.
+ * @flag: Flag to set, can by any number of bits in guint32.
+ *
+ * This macro sets the given bits.
+ */
#define GST_MINI_OBJECT_FLAG_SET(obj,flag) (GST_MINI_OBJECT_FLAGS (obj) |= (flag))
+/**
+ * GST_MINI_OBJECT_FLAG_UNSET:
+ * @obj: MiniObject to unset flag in.
+ * @flag: Flag to set, must be a single bit in guint32.
+ *
+ * This macro usets the given bits.
+ */
#define GST_MINI_OBJECT_FLAG_UNSET(obj,flag) (GST_MINI_OBJECT_FLAGS (obj) &= ~(flag))
+/**
+ * GST_VALUE_HOLDS_MINI_OBJECT:
+ * @value: the #GValue to check
+ *
+ * Checks if the given #GValue contains a #GST_TYPE_MINI_OBJECT value.
+ */
#define GST_VALUE_HOLDS_MINI_OBJECT(value) (G_VALUE_HOLDS(value, GST_TYPE_MINI_OBJECT))
typedef enum
} GstObjectFlags;
#ifdef GST_HAVE_GLIB_2_8
+/**
+ * GST_OBJECT_REFCOUNT:
+ * @obj: Object get the refcount for.
+ *
+ * Get access to the reference count field of the object.
+ */
#define GST_OBJECT_REFCOUNT(obj) (((GObject*)(obj))->ref_count)
+/**
+ * GST_OBJECT_REFCOUNT_VALUE:
+ * @obj: Object get the refcount value for.
+ *
+ * Get the reference count value of the object.
+ */
#define GST_OBJECT_REFCOUNT_VALUE(obj) GST_OBJECT_REFCOUNT(obj)
#else
#define GST_OBJECT_REFCOUNT(obj) ((GST_OBJECT_CAST(obj))->refcount)
GstPad* gst_pad_new (const gchar *name, GstPadDirection direction);
GstPad* gst_pad_new_from_template (GstPadTemplate *templ, const gchar *name);
+/**
+ * gst_pad_get_name:
+ * @pad: the pad to get the name from
+ *
+ * Returns a copy of the name of the pad.
+ *
+ * Returns: the name of the pad. g_free() after usage.
+ *
+ * MT safe.
+ */
#define gst_pad_get_name(pad) gst_object_get_name (GST_OBJECT_CAST (pad))
+/**
+ * gst_pad_get_parent:
+ * @pad: the pad to get the parent of
+ *
+ * Returns the parent of @pad. This function increases the refcount
+ * of the parent object so you should gst_object_unref() it after usage.
+ *
+ * Returns: parent of the object, this can be NULL if the pad has no
+ * parent. unref after usage.
+ *
+ * MT safe.
+ */
#define gst_pad_get_parent(pad) gst_object_get_parent (GST_OBJECT_CAST (pad))
GstPadDirection gst_pad_get_direction (GstPad *pad);
#define _GST_GET(__data, __size, __end) \
(GUINT##__size##_FROM_##__end (* ((guint##__size *) (__data))))
+/**
+ * GST_READ_UINT64_BE:
+ * @data: memory location
+ *
+ * Read a 64 bit unsigned integer value in big endian format from the memory buffer.
+ */
#define GST_READ_UINT64_BE(data) _GST_GET (data, 64, BE)
+/**
+ * GST_READ_UINT64_LE:
+ * @data: memory location
+ *
+ * Read a 64 bit unsigned integer value in little endian format from the memory buffer.
+ */
#define GST_READ_UINT64_LE(data) _GST_GET (data, 64, LE)
+/**
+ * GST_READ_UINT32_BE:
+ * @data: memory location
+ *
+ * Read a 32 bit unsigned integer value in big endian format from the memory buffer.
+ */
#define GST_READ_UINT32_BE(data) _GST_GET (data, 32, BE)
+/**
+ * GST_READ_UINT32_LE:
+ * @data: memory location
+ *
+ * Read a 32 bit unsigned integer value in little endian format from the memory buffer.
+ */
#define GST_READ_UINT32_LE(data) _GST_GET (data, 32, LE)
+/**
+ * GST_READ_UINT16_BE:
+ * @data: memory location
+ *
+ * Read a 16 bit unsigned integer value in big endian format from the memory buffer.
+ */
#define GST_READ_UINT16_BE(data) _GST_GET (data, 16, BE)
+/**
+ * GST_READ_UINT16_LE:
+ * @data: memory location
+ *
+ * Read a 16 bit unsigned integer value in little endian format from the memory buffer.
+ */
#define GST_READ_UINT16_LE(data) _GST_GET (data, 16, LE)
+/**
+ * GST_READ_UINT8:
+ * @data: memory location
+ *
+ * Read an 8 bit unsigned integer value from the memory buffer.
+ */
#define GST_READ_UINT8(data) (* ((guint8 *) (data)))
#define _GST_PUT(__data, __size, __end, __num) \
((* (guint##__size *) (__data)) = GUINT##__size##_TO_##__end (__num))
+/**
+ * GST_WRITE_UINT64_BE:
+ * @data: memory location
+ * @num: value to store
+ *
+ * Store a 64 bit unsigned integer value in big endian format into the memory buffer.
+ */
#define GST_WRITE_UINT64_BE(data, num) _GST_PUT(data, 64, BE, num)
+/**
+ * GST_WRITE_UINT64_LE:
+ * @data: memory location
+ * @num: value to store
+ *
+ * Store a 64 bit unsigned integer value in little endian format into the memory buffer.
+ */
#define GST_WRITE_UINT64_LE(data, num) _GST_PUT(data, 64, LE, num)
+/**
+ * GST_WRITE_UINT32_BE:
+ * @data: memory location
+ * @num: value to store
+ *
+ * Store a 32 bit unsigned integer value in big endian format into the memory buffer.
+ */
#define GST_WRITE_UINT32_BE(data, num) _GST_PUT(data, 32, BE, num)
+/**
+ * GST_WRITE_UINT32_LE:
+ * @data: memory location
+ * @num: value to store
+ *
+ * Store a 32 bit unsigned integer value in little endian format into the memory buffer.
+ */
#define GST_WRITE_UINT32_LE(data, num) _GST_PUT(data, 32, LE, num)
+/**
+ * GST_WRITE_UINT16_BE:
+ * @data: memory location
+ * @num: value to store
+ *
+ * Store a 16 bit unsigned integer value in big endian format into the memory buffer.
+ */
#define GST_WRITE_UINT16_BE(data, num) _GST_PUT(data, 16, BE, num)
+/**
+ * GST_WRITE_UINT16_LE:
+ * @data: memory location
+ * @num: value to store
+ *
+ * Store a 16 bit unsigned integer value in little endian format into the memory buffer.
+ */
#define GST_WRITE_UINT16_LE(data, num) _GST_PUT(data, 16, LE, num)
+/**
+ * GST_WRITE_UINT8:
+ * @data: memory location
+ * @num: value to store
+ *
+ * Store an 8 bit unsigned integer value into the memory buffer.
+ */
#define GST_WRITE_UINT8(data, num) ((* (guint8 *) (data)) = (num))
#else /* GST_HAVE_UNALIGNED_ACCESS */
/* Miscellaneous utility macros */
+
+/**
+ * GST_ROUND_UP_2:
+ * @num: value round up
+ *
+ * Make number divideable by two without a rest.
+ */
#define GST_ROUND_UP_2(num) (((num)+1)&~1)
+/**
+ * GST_ROUND_UP_4:
+ * @num: value round up
+ *
+ * Make number divideable by four without a rest.
+ */
#define GST_ROUND_UP_4(num) (((num)+3)&~3)
+/**
+ * GST_ROUND_UP_8:
+ * @num: value round up
+ *
+ * Make number divideable by eight without a rest.
+ */
#define GST_ROUND_UP_8(num) (((num)+7)&~7)
+/**
+ * GST_ROUND_UP_16:
+ * @num: value round up
+ *
+ * Make number divideable by 16 without a rest.
+ */
#define GST_ROUND_UP_16(num) (((num)+15)&~15)
+/**
+ * GST_ROUND_UP_32:
+ * @num: value round up
+ *
+ * Make number divideable by 32 without a rest.
+ */
#define GST_ROUND_UP_32(num) (((num)+31)&~31)
+/**
+ * GST_ROUND_UP_64:
+ * @num: value round up
+ *
+ * Make number divideable by 64 without a rest.
+ */
#define GST_ROUND_UP_64(num) (((num)+63)&~63)
void gst_object_default_error (GstObject * source,