Commit 8167fcdd authored by Stefan Kost's avatar Stefan Kost

lots of new docs and doc fixes

Original commit message from CVS:
* 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
parent c7d09f7c
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):
......
......@@ -754,7 +754,6 @@ gst_index_add_object
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
......@@ -777,6 +776,7 @@ GST_TYPE_INDEX_RESOLVER_METHOD
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
......@@ -1001,7 +1001,6 @@ gst_message_parse_state_changed
gst_message_parse_tag
gst_message_parse_warning
gst_message_ref
gst_message_type_get_type
gst_message_unref
<SUBSECTION Standard>
GstMessageClass
......@@ -1014,6 +1013,7 @@ GST_MESSAGE_GET_CLASS
GST_TYPE_MESSAGE_TYPE
<SUBSECTION Private>
gst_message_get_type
gst_message_type_get_type
</SECTION>
......@@ -1854,7 +1854,6 @@ GST_TASK_WAIT
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
......
......@@ -93,6 +93,14 @@ static GstMessageQuarks message_quarks[] = {
{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)
{
......@@ -105,6 +113,14 @@ 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)
{
......@@ -364,7 +380,7 @@ gst_message_new_tag (GstObject * src, GstTagList * tag_list)
}
/**
* 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.
......@@ -536,6 +552,8 @@ gst_message_new_segment_done (GstObject * src, GstClockTime timestamp)
* 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 *
......@@ -555,6 +573,8 @@ gst_message_new_application (GstObject * src, GstStructure * structure)
* "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 *
......@@ -586,6 +606,7 @@ gst_message_get_structure (GstMessage * message)
/**
* 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.
......@@ -715,6 +736,8 @@ gst_message_parse_new_clock (GstMessage * message, GstClock ** clock)
/**
* 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.
......@@ -745,6 +768,8 @@ gst_message_parse_error (GstMessage * message, GError ** gerror, gchar ** debug)
/**
* 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.
......@@ -777,6 +802,7 @@ gst_message_parse_warning (GstMessage * message, GError ** gerror,
/**
* 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.
*
......@@ -801,6 +827,7 @@ gst_message_parse_segment_start (GstMessage * message, GstClockTime * timestamp)
/**
* 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.
*
......
......@@ -142,18 +142,54 @@ const gchar* gst_message_type_get_name (GstMessageType type);
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);
......@@ -168,8 +204,8 @@ GstMessage * gst_message_new_custom (GstMessageType type,
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);
......
......@@ -208,8 +208,8 @@ gst_mini_object_is_writable (const GstMiniObject * mini_object)
* 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
*
......
......@@ -43,11 +43,44 @@ typedef struct _GstMiniObjectClass GstMiniObjectClass;
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
......
......@@ -65,7 +65,19 @@ 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)
......
......@@ -437,7 +437,29 @@ GType gst_pad_get_type (void);
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);
......
......@@ -202,23 +202,114 @@ GST_BOILERPLATE_FULL (type, type_as_function, parent_type, \
#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 */
......@@ -319,11 +410,48 @@ GST_BOILERPLATE_FULL (type, type_as_function, parent_type, \
/* 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,
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment