From 8167fcdd7813ab004c5b3435b52d44acf18bd720 Mon Sep 17 00:00:00 2001 From: Stefan Kost Date: Sat, 8 Oct 2005 14:48:17 +0000 Subject: [PATCH] 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 --- ChangeLog | 11 +++ docs/gst/gstreamer-sections.txt | 5 +- gst/gstmessage.c | 29 +++++++- gst/gstmessage.h | 44 ++++++++++- gst/gstminiobject.c | 4 +- gst/gstminiobject.h | 33 ++++++++ gst/gstobject.h | 12 +++ gst/gstpad.h | 22 ++++++ gst/gstutils.h | 128 ++++++++++++++++++++++++++++++++ 9 files changed, 278 insertions(+), 10 deletions(-) diff --git a/ChangeLog b/ChangeLog index 701e76e776..c7aef813db 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,14 @@ +2005-10-08 Stefan Kost + * 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 * gst/gstplugin.c: (gst_plugin_finalize), (gst_plugin_load_file): diff --git a/docs/gst/gstreamer-sections.txt b/docs/gst/gstreamer-sections.txt index 14b7c6901a..e4f914a67b 100644 --- a/docs/gst/gstreamer-sections.txt +++ b/docs/gst/gstreamer-sections.txt @@ -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 GstMessageClass @@ -1014,6 +1013,7 @@ GST_MESSAGE_GET_CLASS GST_TYPE_MESSAGE_TYPE gst_message_get_type +gst_message_type_get_type @@ -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 diff --git a/gst/gstmessage.c b/gst/gstmessage.c index 2a9cec62f3..3a0fad832a 100644 --- a/gst/gstmessage.c +++ b/gst/gstmessage.c @@ -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. * diff --git a/gst/gstmessage.h b/gst/gstmessage.h index ca435b947e..bf49becab3 100644 --- a/gst/gstmessage.h +++ b/gst/gstmessage.h @@ -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); diff --git a/gst/gstminiobject.c b/gst/gstminiobject.c index 7f6f8ed922..37838e1196 100644 --- a/gst/gstminiobject.c +++ b/gst/gstminiobject.c @@ -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 * diff --git a/gst/gstminiobject.h b/gst/gstminiobject.h index ce24f79e90..cf2c92a138 100644 --- a/gst/gstminiobject.h +++ b/gst/gstminiobject.h @@ -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 diff --git a/gst/gstobject.h b/gst/gstobject.h index c6b0e96440..8e4d36a974 100644 --- a/gst/gstobject.h +++ b/gst/gstobject.h @@ -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) diff --git a/gst/gstpad.h b/gst/gstpad.h index 77189fcd1b..49d456abc6 100644 --- a/gst/gstpad.h +++ b/gst/gstpad.h @@ -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); diff --git a/gst/gstutils.h b/gst/gstutils.h index bcfddad619..3d84d65c2e 100644 --- a/gst/gstutils.h +++ b/gst/gstutils.h @@ -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,