From 2cab15c9f6370db5b068ee8c1dd9717655d6c3f5 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Fri, 15 Jun 2012 12:55:20 +0200 Subject: [PATCH] docs: improve API docs --- docs/gst/gstreamer-sections.txt | 20 ++++- gst/gstbuffer.c | 129 +++++++++++++++++++++++++++++++- gst/gstbuffer.h | 23 +----- gst/gstbufferlist.c | 7 ++ gst/gstelementfactory.c | 4 +- gst/gstevent.c | 1 - gst/gstghostpad.c | 3 +- gst/gstminiobject.c | 1 - gst/gstminiobject.h | 1 - gst/gstpad.c | 80 ++++++++++++++++++++ gst/gstquery.c | 16 ++++ gst/gstquery.h | 2 - 12 files changed, 253 insertions(+), 34 deletions(-) diff --git a/docs/gst/gstreamer-sections.txt b/docs/gst/gstreamer-sections.txt index 8c9e017915..cd6e57042e 100644 --- a/docs/gst/gstreamer-sections.txt +++ b/docs/gst/gstreamer-sections.txt @@ -188,9 +188,13 @@ gst_buffer_unref gst_buffer_get_sizes gst_buffer_get_size +gst_buffer_get_sizes_range +gst_buffer_resize_range gst_buffer_resize gst_buffer_set_size +gst_buffer_peek_memory + gst_buffer_n_memory gst_buffer_insert_memory gst_buffer_replace_memory_range @@ -208,6 +212,7 @@ gst_buffer_remove_memory gst_buffer_remove_all_memory gst_buffer_map +gst_buffer_map_range gst_buffer_unmap gst_buffer_memcmp @@ -1282,6 +1287,7 @@ GST_MEMORY_FLAGS GST_MEMORY_FLAG_IS_SET GST_MEMORY_FLAG_UNSET GST_MEMORY_IS_READONLY +GST_MEMORY_IS_NO_SHARE GST_MEMORY_IS_ZERO_PADDED GST_MEMORY_IS_ZERO_PREFIXED @@ -1425,6 +1431,8 @@ gst_message_parse_qos_values gst_message_parse_qos_stats gst_message_new_toc gst_message_parse_toc +gst_message_new_reset_time +gst_message_parse_reset_time GstStructureChangeType gst_message_new_structure_change @@ -1487,7 +1495,6 @@ GST_MINI_OBJECT_FLAG_SET GST_MINI_OBJECT_FLAG_UNSET GST_MINI_OBJECT_REFCOUNT GST_MINI_OBJECT_REFCOUNT_VALUE -GST_MINI_OBJECT_SIZE GST_DEFINE_MINI_OBJECT_TYPE gst_mini_object_init @@ -1502,6 +1509,9 @@ gst_mini_object_unref gst_mini_object_weak_ref gst_mini_object_weak_unref +gst_mini_object_get_qdata +gst_mini_object_set_qdata + gst_mini_object_replace gst_mini_object_steal gst_mini_object_take @@ -1837,6 +1847,7 @@ GST_PAD_EVENTFUNC GST_PAD_GETRANGEFUNC GST_PAD_ITERINTLINKFUNC GST_PAD_IS_FLUSHING +GST_PAD_IS_EOS GST_PAD_LINKFUNC GST_PAD_UNLINKFUNC GST_PAD_QUERYFUNC @@ -2185,7 +2196,6 @@ gst_query_new_caps gst_query_parse_caps gst_query_set_caps_result gst_query_parse_caps_result -gst_query_intersect_caps_result gst_query_new_accept_caps gst_query_parse_accept_caps @@ -2532,6 +2542,7 @@ gst_tag_list_new gst_tag_list_new_empty gst_tag_list_new_valist gst_tag_list_new_from_string +gst_tag_list_free gst_tag_list_to_string gst_tag_list_is_empty gst_tag_list_is_equal @@ -2709,8 +2720,12 @@ gst_toc_entry_get_start_stop gst_toc_entry_set_start_stop gst_toc_entry_type_get_nick +GST_TYPE_TOC +GST_TYPE_TOC_ENTRY GST_TYPE_TOC_ENTRY_TYPE +gst_toc_get_type +gst_toc_entry_get_type gst_toc_entry_type_get_type @@ -2764,6 +2779,7 @@ GstTypeFindFactory gst_type_find_factory_get_list gst_type_find_factory_get_extensions gst_type_find_factory_get_caps +gst_type_find_factory_has_function gst_type_find_factory_call_function GstTypeFindFactoryClass diff --git a/gst/gstbuffer.c b/gst/gstbuffer.c index 41bfe37cbf..eb42c510a1 100644 --- a/gst/gstbuffer.c +++ b/gst/gstbuffer.c @@ -742,6 +742,22 @@ gst_buffer_n_memory (GstBuffer * buffer) return GST_BUFFER_MEM_LEN (buffer); } +/** + * gst_buffer_prepend_memory: + * @b: a #GstBuffer. + * @m: (transfer full): a #GstMemory. + * + * Prepend the memory block @m to @b. This function takes ownership + * of @m and thus doesn't increase its refcount. + */ +/** + * gst_buffer_append_memory: + * @b: a #GstBuffer. + * @m: (transfer full): a #GstMemory. + * + * Append the memory block @m to @b. This function takes ownership + * of @m and thus doesn't increase its refcount. + */ /** * gst_buffer_insert_memory: * @buffer: a #GstBuffer. @@ -810,6 +826,26 @@ gst_buffer_peek_memory (GstBuffer * buffer, guint idx) return GST_BUFFER_MEM_PTR (buffer, idx); } +/** + * gst_buffer_get_memory: + * @b: a #GstBuffer. + * @i: an index + * + * Get the memory block at index @i in @buffer. + * + * Returns: (transfer full): a #GstMemory that contains the data of the + * memory block at @idx. Use gst_memory_unref () after usage. + */ +/** + * gst_buffer_get_all_memory: + * @b: a #GstBuffer. + * + * Get all the memory block in @buffer. The memory blocks will be merged + * into one large #GstMemory. + * + * Returns: (transfer full): a #GstMemory that contains the merged memory. + * Use gst_memory_unref () after usage. + */ /** * gst_buffer_get_memory_range: * @buffer: a #GstBuffer. @@ -842,6 +878,21 @@ gst_buffer_get_memory_range (GstBuffer * buffer, guint idx, gint length) return _get_merged_memory (buffer, idx, length); } +/** + * gst_buffer_replace_memory: + * @b: a #GstBuffer. + * @i: an index + * @m: (transfer full): a #GstMemory + * + * Replaces the memory block at index @i in @b with @m. + */ +/** + * gst_buffer_replace_all_memory: + * @b: a #GstBuffer. + * @m: (transfer full): a #GstMemory + * + * Replaces all memory in @b with @m. + */ /** * gst_buffer_replace_memory_range: * @buffer: a #GstBuffer. @@ -874,6 +925,19 @@ gst_buffer_replace_memory_range (GstBuffer * buffer, guint idx, gint length, _replace_memory (buffer, len, idx, length, mem); } +/** + * gst_buffer_remove_memory: + * @b: a #GstBuffer. + * @i: an index + * + * Remove the memory block in @b at index @i. + */ +/** + * gst_buffer_remove_all_memory: + * @b: a #GstBuffer. + * + * Remove all the memory blocks in @b. + */ /** * gst_buffer_remove_memory_range: * @buffer: a #GstBuffer. @@ -975,6 +1039,30 @@ gst_buffer_find_memory (GstBuffer * buffer, gsize offset, gsize size, return FALSE; } +/** + * gst_buffer_get_sizes: + * @b: a #GstBuffer. + * @of: a pointer to the offset + * @ms: a pointer to the maxsize + * + * Get the total size of the memory blocks in @b. + * + * When not %NULL, @of will contain the offset of the data in the first + * memory block in @buffer and @maxsize will contain the sum of the size + * and @of and the amount of extra padding on the last memory block. + * @of and @ms can be used to resize the buffer memory blocks with + * gst_buffer_resize(). + * + * Returns: total size of the memory blocks in @b. + */ +/** + * gst_buffer_get_size: + * @b: a #GstBuffer. + * + * Get the total size of the memory blocks in @b. + * + * Returns: total size of the memory blocks in @b. + */ /** * gst_buffer_get_sizes_range: * @buffer: a #GstBuffer. @@ -992,7 +1080,7 @@ gst_buffer_find_memory (GstBuffer * buffer, gsize offset, gsize size, * @offset and @maxsize can be used to resize the buffer memory blocks with * gst_buffer_resize_range(). * - * Returns: total size @length memory blocks starting at @idx in @buffer. + * Returns: total size of @length memory blocks starting at @idx in @buffer. */ gsize gst_buffer_get_sizes_range (GstBuffer * buffer, guint idx, gint length, @@ -1047,6 +1135,21 @@ gst_buffer_get_sizes_range (GstBuffer * buffer, guint idx, gint length, return size; } +/** + * gst_buffer_resize: + * @b: a #GstBuffer. + * @of: the offset adjustement + * @s: the new size or -1 to just adjust the offset + * + * Set the offset and total size of the memory blocks in @b. + */ +/** + * gst_buffer_set_size: + * @b: a #GstBuffer. + * @s: the new size + * + * Set the total size of the memory blocks in @b. + */ /** * gst_buffer_resize_range: * @buffer: a #GstBuffer. @@ -1139,6 +1242,27 @@ gst_buffer_resize_range (GstBuffer * buffer, guint idx, gint length, } } +/** + * gst_buffer_map: + * @b: a #GstBuffer. + * @i: (out): info about the mapping + * @f: flags for the mapping + * + * This function fills @i with the #GstMapInfo of all merged memory blocks + * in @buffer. + * + * @flags describe the desired access of the memory. When @flags is + * #GST_MAP_WRITE, @buffer should be writable (as returned from + * gst_buffer_is_writable()). + * + * When @buffer is writable but the memory isn't, a writable copy will + * automatically be created and returned. The readonly copy of the buffer memory + * will then also be replaced with this writable copy. + * + * The memory in @i should be unmapped with gst_buffer_unmap() after usage. + * + * Returns: %TRUE if the map succeeded and @i contains valid data. + */ /** * gst_buffer_map_range: * @buffer: a #GstBuffer. @@ -1150,6 +1274,7 @@ gst_buffer_resize_range (GstBuffer * buffer, guint idx, gint length, * This function fills @info with the #GstMapInfo of @length merged memory blocks * starting at @idx in @buffer. When @length is -1, all memory blocks starting * from @idx are merged and mapped. + * * @flags describe the desired access of the memory. When @flags is * #GST_MAP_WRITE, @buffer should be writable (as returned from * gst_buffer_is_writable()). @@ -1160,7 +1285,7 @@ gst_buffer_resize_range (GstBuffer * buffer, guint idx, gint length, * * The memory in @info should be unmapped with gst_buffer_unmap() after usage. * - * Returns: (transfer full): %TRUE if the map succeeded and @info contains valid + * Returns: %TRUE if the map succeeded and @info contains valid * data. */ gboolean diff --git a/gst/gstbuffer.h b/gst/gstbuffer.h index 5b0a854bc0..df4647faf1 100644 --- a/gst/gstbuffer.h +++ b/gst/gstbuffer.h @@ -276,16 +276,9 @@ void gst_buffer_remove_memory_range (GstBuffer *buffer, guint idx, gint #define gst_buffer_prepend_memory(b,m) gst_buffer_insert_memory ((b), 0, (m)) #define gst_buffer_append_memory(b,m) gst_buffer_insert_memory ((b), -1, (m)) #define gst_buffer_replace_memory(b,i,m) gst_buffer_replace_memory_range ((b), (i), 1, (m)) -#define gst_buffer_replace_all_memory(b,m) gst_buffer_replace_memory ((b), 0, -1, (m)) +#define gst_buffer_replace_all_memory(b,m) gst_buffer_replace_memory_range ((b), 0, -1, (m)) #define gst_buffer_get_memory(b,i) gst_buffer_get_memory_range ((b), (i), 1) #define gst_buffer_get_all_memory(b) gst_buffer_get_memory_range ((b), 0, -1) -/** - * gst_buffer_remove_memory: - * @b: a #GstBuffer. - * @i: an index - * - * Remove the memory block in @b at @i. - */ #define gst_buffer_remove_memory(b,i) gst_buffer_remove_memory_range ((b), (i), 1) #define gst_buffer_remove_all_memory(b) gst_buffer_remove_memory_range ((b), 0, -1) @@ -307,22 +300,8 @@ void gst_buffer_resize_range (GstBuffer *buffer, guint idx, gint l gssize offset, gssize size); #define gst_buffer_get_sizes(b,of,ms) gst_buffer_get_sizes_range ((b), 0, -1, (of), (ms)) -/** - * gst_buffer_get_size: - * @b: a #GstBuffer. - * - * Get the size of @b. - */ #define gst_buffer_get_size(b) gst_buffer_get_sizes_range ((b), 0, -1, NULL, NULL) #define gst_buffer_resize(b,of,s) gst_buffer_resize_range ((b), 0, -1, (of), (s)) -/** - * gst_buffer_set_size: - * @b: a #GstBuffer. - * @s: a new size - * - * Set the size of @b to @s. This will remove or trim the memory blocks - * in the buffer. - */ #define gst_buffer_set_size(b,s) gst_buffer_resize_range ((b), 0, -1, 0, (s)) gboolean gst_buffer_map_range (GstBuffer *buffer, guint idx, gint length, diff --git a/gst/gstbufferlist.c b/gst/gstbufferlist.c index 8955e29ba6..31b8bae465 100644 --- a/gst/gstbufferlist.c +++ b/gst/gstbufferlist.c @@ -254,6 +254,13 @@ gst_buffer_list_get (GstBufferList * list, guint idx) return buf; } +/** + * gst_buffer_list_add: + * @l: a #GstBufferList + * @b: a #GstBuffer + * + * Append @b at the end of @l. + */ /** * gst_buffer_list_insert: * @list: a #GstBufferList diff --git a/gst/gstelementfactory.c b/gst/gstelementfactory.c index a8ef9fe36d..3a7bd40fc6 100644 --- a/gst/gstelementfactory.c +++ b/gst/gstelementfactory.c @@ -494,7 +494,7 @@ gst_element_factory_get_element_type (GstElementFactory * factory) /** * gst_element_factory_get_metadata: - * @factory,: a #GstElementFactory + * @factory: a #GstElementFactory * @key: a key * * Get the metadata on @factory with @key. @@ -511,7 +511,7 @@ gst_element_factory_get_metadata (GstElementFactory * factory, /** * gst_element_factory_get_metadata_keys: - * @factory,: a #GstElementFactory + * @factory: a #GstElementFactory * * Get the available keys for the metadata on @factory. * diff --git a/gst/gstevent.c b/gst/gstevent.c index 965ccb315a..637996241a 100644 --- a/gst/gstevent.c +++ b/gst/gstevent.c @@ -1633,7 +1633,6 @@ gst_event_new_stream_start (void) /** * gst_event_new_toc: - * @name: a name for the event * @toc: #GstToc structure. * @updated: whether @toc was updated or not. * diff --git a/gst/gstghostpad.c b/gst/gstghostpad.c index f9b8368d4a..50a35fb982 100644 --- a/gst/gstghostpad.c +++ b/gst/gstghostpad.c @@ -322,8 +322,9 @@ gst_proxy_pad_chain_list_default (GstPad * pad, GstObject * parent, } /** - * gst_proxy_pad_get_range_default: + * gst_proxy_pad_getrange_default: * @pad: a src #GstPad, returns #GST_FLOW_ERROR if not. + * @parent: the parent of @pad * @offset: The start offset of the buffer * @size: The length of the buffer * @buffer: (out callee-allocates): a pointer to hold the #GstBuffer, diff --git a/gst/gstminiobject.c b/gst/gstminiobject.c index d7816a3014..9e3bdd6983 100644 --- a/gst/gstminiobject.c +++ b/gst/gstminiobject.c @@ -82,7 +82,6 @@ _priv_gst_mini_object_initialize (void) * gst_mini_object_init: * @mini_object: a #GstMiniObject * @type: the #GType of the mini-object to create - * @size: the size of the data * * Initializes a mini-object with the desired type and size. * diff --git a/gst/gstminiobject.h b/gst/gstminiobject.h index c2d3435bf7..5c4c7d17b3 100644 --- a/gst/gstminiobject.h +++ b/gst/gstminiobject.h @@ -154,7 +154,6 @@ typedef enum * @type: the GType of the object * @refcount: atomic refcount * @flags: extra flags. - * @size: the size of the structure * @copy: a copy function * @dispose: a dispose function * @free: the free function diff --git a/gst/gstpad.c b/gst/gstpad.c index 73981f3320..2a0069b6eb 100644 --- a/gst/gstpad.c +++ b/gst/gstpad.c @@ -1374,6 +1374,14 @@ gst_pad_mark_reconfigure (GstPad * pad) GST_OBJECT_UNLOCK (pad); } +/** + * gst_pad_set_activate_function: + * @p: a #GstPad. + * @f: the #GstPadActivateFunction to set. + * + * Calls gst_pad_set_activate_function_full() with NULL for the user_data and + * notify. + */ /** * gst_pad_set_activate_function_full: * @pad: a #GstPad. @@ -1403,6 +1411,14 @@ gst_pad_set_activate_function_full (GstPad * pad, GST_DEBUG_FUNCPTR_NAME (activate)); } +/** + * gst_pad_set_activatemode_function: + * @p: a #GstPad. + * @f: the #GstPadActivateModeFunction to set. + * + * Calls gst_pad_set_activatemode_function_full() with NULL for the user_data and + * notify. + */ /** * gst_pad_set_activatemode_function_full: * @pad: a #GstPad. @@ -1430,6 +1446,14 @@ gst_pad_set_activatemode_function_full (GstPad * pad, GST_DEBUG_FUNCPTR_NAME (activatemode)); } +/** + * gst_pad_set_chain_function: + * @p: a sink #GstPad. + * @f: the #GstPadChainFunction to set. + * + * Calls gst_pad_set_chain_function_full() with NULL for the user_data and + * notify. + */ /** * gst_pad_set_chain_function_full: * @pad: a sink #GstPad. @@ -1457,6 +1481,14 @@ gst_pad_set_chain_function_full (GstPad * pad, GstPadChainFunction chain, GST_DEBUG_FUNCPTR_NAME (chain)); } +/** + * gst_pad_set_chain_list_function: + * @p: a sink #GstPad. + * @f: the #GstPadChainListFunction to set. + * + * Calls gst_pad_set_chain_list_function_full() with NULL for the user_data and + * notify. + */ /** * gst_pad_set_chain_list_function_full: * @pad: a sink #GstPad. @@ -1488,6 +1520,14 @@ gst_pad_set_chain_list_function_full (GstPad * pad, GST_DEBUG_FUNCPTR_NAME (chainlist)); } +/** + * gst_pad_set_getrange_function: + * @p: a source #GstPad. + * @f: the #GstPadGetRangeFunction to set. + * + * Calls gst_pad_set_getrange_function_full() with NULL for the user_data and + * notify. + */ /** * gst_pad_set_getrange_function_full: * @pad: a source #GstPad. @@ -1516,6 +1556,14 @@ gst_pad_set_getrange_function_full (GstPad * pad, GstPadGetRangeFunction get, GST_DEBUG_FUNCPTR_NAME (get)); } +/** + * gst_pad_set_event_function: + * @p: a #GstPad of either direction. + * @f: the #GstPadEventFunction to set. + * + * Calls gst_pad_set_event_function_full() with NULL for the user_data and + * notify. + */ /** * gst_pad_set_event_function_full: * @pad: a #GstPad of either direction. @@ -1541,6 +1589,14 @@ gst_pad_set_event_function_full (GstPad * pad, GstPadEventFunction event, GST_DEBUG_FUNCPTR_NAME (event)); } +/** + * gst_pad_set_query_function: + * @p: a #GstPad of either direction. + * @f: the #GstPadQueryFunction to set. + * + * Calls gst_pad_set_query_function_full() with NULL for the user_data and + * notify. + */ /** * gst_pad_set_query_function_full: * @pad: a #GstPad of either direction. @@ -1566,6 +1622,14 @@ gst_pad_set_query_function_full (GstPad * pad, GstPadQueryFunction query, GST_DEBUG_FUNCPTR_NAME (query)); } +/** + * gst_pad_set_iterate_internal_links_function: + * @p: a #GstPad of either direction. + * @f: the #GstPadIterIntLinkFunction to set. + * + * Calls gst_pad_set_iterate_internal_links_function_full() with NULL + * for the user_data and notify. + */ /** * gst_pad_set_iterate_internal_links_function_full: * @pad: a #GstPad of either direction. @@ -1594,6 +1658,14 @@ gst_pad_set_iterate_internal_links_function_full (GstPad * pad, GST_DEBUG_FUNCPTR_NAME (iterintlink)); } +/** + * gst_pad_set_link_function: + * @p: a #GstPad. + * @f: the #GstPadLinkFunction to set. + * + * Calls gst_pad_set_link_function_full() with NULL + * for the user_data and notify. + */ /** * gst_pad_set_link_function_full: * @pad: a #GstPad. @@ -1629,6 +1701,14 @@ gst_pad_set_link_function_full (GstPad * pad, GstPadLinkFunction link, GST_DEBUG_FUNCPTR_NAME (link)); } +/** + * gst_pad_set_unlink_function: + * @p: a #GstPad. + * @f: the #GstPadUnlinkFunction to set. + * + * Calls gst_pad_set_unlink_function_full() with NULL + * for the user_data and notify. + */ /** * gst_pad_set_unlink_function_full: * @pad: a #GstPad. diff --git a/gst/gstquery.c b/gst/gstquery.c index 9304742548..161cd43b55 100644 --- a/gst/gstquery.c +++ b/gst/gstquery.c @@ -2166,6 +2166,13 @@ gst_query_parse_accept_caps (GstQuery * query, GstCaps ** caps) GST_QUARK (CAPS))); } +/** + * gst_query_set_accept_caps_result: + * @query: a GST_QUERY_ACCEPT_CAPS type query #GstQuery + * @result: the result to set + * + * Set @result as the result for the @query. + */ void gst_query_set_accept_caps_result (GstQuery * query, gboolean result) { @@ -2179,6 +2186,13 @@ gst_query_set_accept_caps_result (GstQuery * query, gboolean result) GST_QUARK (RESULT), G_TYPE_BOOLEAN, result, NULL); } +/** + * gst_query_parse_accept_caps_result: + * @query: a GST_QUERY_ACCEPT_CAPS type query #GstQuery + * @result: location for the result + * + * Parse the result from @query and store in @result. + */ void gst_query_parse_accept_caps_result (GstQuery * query, gboolean * result) { @@ -2293,6 +2307,7 @@ gst_query_parse_caps_result (GstQuery * query, GstCaps ** caps) GST_QUARK (CAPS))); } +#if 0 void gst_query_intersect_caps_result (GstQuery * query, GstCaps * filter, GstCapsIntersectMode mode) @@ -2304,6 +2319,7 @@ gst_query_intersect_caps_result (GstQuery * query, GstCaps * filter, gst_query_set_caps_result (query, res); gst_caps_unref (res); } +#endif /** * gst_query_new_drain: diff --git a/gst/gstquery.h b/gst/gstquery.h index c060ce05a0..ba25cf0879 100644 --- a/gst/gstquery.h +++ b/gst/gstquery.h @@ -475,8 +475,6 @@ void gst_query_parse_caps (GstQuery *query, GstCaps **f void gst_query_set_caps_result (GstQuery *query, GstCaps *caps); void gst_query_parse_caps_result (GstQuery *query, GstCaps **caps); -void gst_query_intersect_caps_result (GstQuery *query, GstCaps *filter, - GstCapsIntersectMode mode); /* drain query */ GstQuery * gst_query_new_drain (void) G_GNUC_MALLOC;