Commit b5c170f4 authored by Wim Taymans's avatar Wim Taymans

API docs updates

Original commit message from CVS:
API docs updates
parent efafdb2a
......@@ -104,7 +104,6 @@ with some more specialized elements.</para>
&GstUtils;
&GstXML;
&cothreads;
</chapter>
<chapter id="element-types">
......
......@@ -37,6 +37,8 @@ gst_init_with_popt_table
gst_version
gst_main
gst_main_quit
gst_has_threads
gst_use_threads
g_log_domain_gstreamer
GST_VERSION_MAJOR
GST_VERSION_MINOR
......@@ -102,6 +104,7 @@ GstSchedulerState
GstSchedulerFlags
gst_scheduler_destroy
gst_scheduler_setup
gst_scheduler_get_preferred_stack
gst_scheduler_reset
gst_scheduler_add_element
gst_scheduler_remove_element
......@@ -212,7 +215,32 @@ GST_ARCH_PRESETJMP
<SECTION>
<FILE>gstdata</FILE>
<TITLE>GstData</TITLE>
GST_DATA
GST_DATA_TYPE
GST_DATA_FLAGS
GST_DATA_FLAG_SHIFT
GST_DATA_FLAG_IS_SET
GST_DATA_FLAG_SET
GST_DATA_FLAG_UNSET
GstData
GstDataFreeFunction
GstDataCopyFunction
GstDataFlags
GST_DATA_IS_READONLY
GST_DATA_REFCOUNT
GST_DATA_REFCOUNT_VALUE
GST_DATA_REFCOUNT_READ
GST_DATA_COPY_FUNC
GST_DATA_FREE_FUNC
gst_data_init
gst_data_dispose
gst_data_copy_into
gst_data_copy
gst_data_copy_on_write
gst_data_free
gst_data_ref
gst_data_ref_by_count
gst_data_unref
<SUBSECTION Standard>
GST_DATA
GST_DATA_TYPE
......@@ -221,41 +249,41 @@ GST_DATA_TYPE
<SECTION>
<FILE>gstbuffer</FILE>
<TITLE>GstBuffer</TITLE>
GST_IS_BUFFER
GST_BUFFER
GST_IS_BUFFER
GST_BUFFER_REFCOUNT
GST_BUFFER_REFCOUNT_VALUE
GST_BUFFER_COPY_FUNC
GST_BUFFER_FREE_FUNC
GST_BUFFER_FLAGS
GST_BUFFER_FLAG_IS_SET
GST_BUFFER_FLAG_SET
GST_BUFFER_FLAG_UNSET
GST_BUFFER_DATA
GST_BUFFER_SIZE
GST_BUFFER_OFFSET
GST_BUFFER_MAXSIZE
GST_BUFFER_TIMESTAMP
GST_BUFFER_OFFSET
GST_BUFFER_BUFFERPOOL
GST_BUFFER_POOL_PRIVATE
GST_BUFFER_LOCK
GST_BUFFER_TRYLOCK
GST_BUFFER_UNLOCK
GST_BUFFER_PARENT
GST_BUFFER_MAXAGE
GST_BUFFER_COPY_FUNC
GST_BUFFER_FREE_FUNC
GstBufferCopyFunc
GstBufferFreeFunc
GstBufferFlag
GstBuffer
gst_buffer_new
gst_buffer_new_and_alloc
gst_buffer_new_from_pool
gst_buffer_copy
gst_buffer_create_sub
gst_buffer_append
gst_buffer_default_free
gst_buffer_default_copy
gst_buffer_ref
gst_buffer_ref_by_count
gst_buffer_unref
gst_buffer_destroy
gst_buffer_is_span_fast
gst_buffer_copy
gst_buffer_copy_on_write
gst_buffer_free
gst_buffer_create_sub
gst_buffer_merge
gst_buffer_is_span_fast
gst_buffer_span
gst_buffer_print_stats
<SUBSECTION Standard>
......@@ -265,25 +293,25 @@ GST_TYPE_BUFFER
<SECTION>
<FILE>gstbufferpool</FILE>
<TITLE>GstBufferPool</TITLE>
GST_BUFFER_POOL
GST_IS_BUFFER_POOL
GstBufferPool
GstBufferPoolBufferNewFunction
GstBufferPoolDestroyHook
GST_BUFFER_POOL_UNLOCK
GST_BUFFER_POOL_LOCK
GstBufferPoolBufferCopyFunction
GstBufferPoolBufferFreeFunction
gst_buffer_pool_new
gst_buffer_pool_is_active
gst_buffer_pool_set_active
gst_buffer_pool_ref
gst_buffer_pool_ref_by_count
gst_buffer_pool_unref
gst_buffer_pool_destroy
gst_buffer_pool_get_default
gst_buffer_pool_copy
gst_buffer_pool_copy_on_write
gst_buffer_pool_free
gst_buffer_pool_set_user_data
gst_buffer_pool_get_user_data
gst_buffer_pool_set_buffer_copy_function
gst_buffer_pool_set_buffer_free_function
gst_buffer_pool_set_buffer_new_function
gst_buffer_pool_set_destroy_hook
gst_buffer_pool_get_default
<SUBSECTION Standard>
GST_BUFFER_POOL
</SECTION>
<SECTION>
......@@ -310,15 +338,24 @@ GST_SEEK_METHOD_SHIFT
GST_EVENT_DISCONT_NEW_MEDIA
GST_EVENT_DISCONT_OFFSET
GST_EVENT_DISCONT_OFFSET_LEN
GST_EVENT_RATE_VALUE
GST_EVENT_SEEK_ENDOFFSET
GST_EVENT_SIZE_FORMAT
GST_EVENT_SIZE_VALUE
GstEvent
gst_event_new
gst_event_copy
gst_event_free
gst_event_ref
gst_event_ref_by_count
gst_event_unref
gst_event_new_seek
gst_event_new_segment_seek
gst_event_new_size
gst_event_new_discontinuous
gst_event_discont_get_value
gst_event_new_filler
gst_event_new_flush
gst_event_print_stats
<SUBSECTION Standard>
GST_EVENT
GST_IS_EVENT
......@@ -551,6 +588,7 @@ GST_IS_CLOCK_CLASS
GstRegistryReturn
GstRegistryFlags
<TITLE>GstRegistry</TITLE>
GstRegistry
gst_registry_load
gst_registry_is_loaded
gst_registry_save
......@@ -599,6 +637,7 @@ GST_IS_REGISTRY_CLASS
<TITLE>GstSystemClock</TITLE>
gst_system_clock_obtain
<SUBSECTION Standard>
GstSystemClock
GST_SYSTEM_CLOCK
GST_IS_SYSTEM_CLOCK
GST_TYPE_SYSTEM_CLOCK
......@@ -685,7 +724,7 @@ GstPadEventFunction
GstPadConnectFunction
GstPadConnectReturn
GstPadConvertFunction
GstPadDispatcherFunc
GstPadDispatcherFunction
GstPadIntConnFunction
GstPadQueryType
......@@ -987,6 +1026,8 @@ GstTypeFindFunc
gst_type_factory_new
gst_type_factory_find
<SUBSECTION Standard>
GstTypeFind
GstTypeFindClass
GST_TYPE_FACTORY
GST_IS_TYPE_FACTORY
GST_TYPE_TYPE_FACTORY
......
......@@ -9,8 +9,8 @@ Media library supporting arbitrary formats and filter graphs.
GStreamer is a framework for constructing graphs of various filters
(termed elements here) that will handle streaming media. Any discreet
(packetizable) media type is supported, with provisions for automatically
determining source type. Metadata can be passed with all data to provide
formatting/framing information. Plugins are heavily used to provide for
determining source type. Formatting/framing information is provided with
a powerful negotiation framework. Plugins are heavily used to provide for
all elements, allowing one to construct plugins outside of the GST
library, even released binary-only if license require (please don't).
</para>
......@@ -19,9 +19,8 @@ library, even released binary-only if license require (please don't).
GStreamer borrows heavily from both the <ulink
url="http://www.cse.ogi.edu/sysl/">OGI media pipeline</ulink> and
Microsoft's DirectShow, hopefully taking the best of both and leaving the
cruft behind. Its interface is still very fluid (I've redesigned the
metadata handling twice already), and thus can be changed to increase the
sanity/noise ratio.
cruft behind. Its interface is still very fluid and thus can be changed
to increase the sanity/noise ratio.
</para>
<para>
......@@ -39,6 +38,10 @@ process its own command line options, as shown in the following example.
}
</programlisting>
</para>
<para>
It's allowed to pass two NULL pointers to gst_init() in case you don't want to pass the command
line args to GStreamer.
</para>
<para>
You can also use a popt table to initialize your own parameters as shown in the next code
......@@ -68,7 +71,7 @@ fragment:
to find the version at compile time.
</para>
<para>
gst_main() and gst_main_quit() enter and exit the main loop.
gst_main() and gst_main_quit() enter and exit the main loop.
</para>
<!-- ##### SECTION See_Also ##### -->
......@@ -120,6 +123,22 @@ pipeline</ulink> and Microsoft's DirectShow for some background.
<!-- ##### FUNCTION gst_has_threads ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION gst_use_threads ##### -->
<para>
</para>
@use_threads:
<!-- ##### VARIABLE g_log_domain_gstreamer ##### -->
<para>
......
......@@ -55,10 +55,10 @@ get the current clock of the bin and gst_bin_use_clock() to specify a clock expl
Flags for a bin.
</para>
@GST_BIN_FLAG_MANAGER:
@GST_BIN_SELF_SCHEDULABLE:
@GST_BIN_FLAG_PREFER_COTHREADS:
@GST_BIN_FLAG_FIXED_CLOCK:
@GST_BIN_FLAG_MANAGER: This bin has a scheduler and can be used as a toplevel bin.
@GST_BIN_SELF_SCHEDULABLE: This bin iterates itself, so no calls to gst_bin_iterate() should be made.
@GST_BIN_FLAG_PREFER_COTHREADS: This bin preferes to have its elements scheduled with cothreads
@GST_BIN_FLAG_FIXED_CLOCK: This bin uses a fixed clock, possibly the one set with gst_bin_use_clock().
@GST_BIN_FLAG_LAST:
<!-- ##### STRUCT GstBin ##### -->
......
......@@ -2,7 +2,7 @@
GstBuffer
<!-- ##### SECTION Short_Description ##### -->
Data-passing buffer type, supporting sub-buffers and metadata
Data-passing buffer type, supporting sub-buffers.
<!-- ##### SECTION Long_Description ##### -->
<para>
......@@ -10,8 +10,7 @@ Buffers are the basic unit of data transfer in GStreamer. The GstBuffer type
provides all the state necessary to define a region of memory as part of a
stream. Sub-buffers are also supported, allowing a smaller region of a
buffer to become its own buffer, with mechanisms in place to ensure that
neither memory space goes away. Metadata is supported as a list of
pointers to arbitrary metadata.
neither memory space goes away.
</para>
<para>
Buffers are usually created with gst_buffer_new(). After a buffer has been
......@@ -30,7 +29,11 @@ buffer data.
</programlisting>
</para>
<para>
GstBuffers can also be created from a GstBufferPool with
Alternatively, use gst_buffer_new_and_alloc() to create a buffer with preallocated
data of a given size.
</para>
<para>
GstBuffers can also be created from a #GstBufferPool with
gst_buffer_new_from_pool(). The bufferpool can be obtained from a
peer element with gst_pad_get_bufferpool().
</para>
......@@ -49,8 +52,12 @@ and GST_BUFFER_FLAG_UNSET() macros. Use GST_BUFFER_FLAG_IS_SET() to test it
a certain flag is set.
</para>
<para>
Buffers can be efficiently merged into a larger buffer with gst_buffer_merge() and
gst_buffer_span() if the gst_buffer_is_span_fast() function returns TRUE.
</para>
<para>
Buffers usually are freed by unreffing them with gst_buffer_unref().
gst_buffer_destroy() can also be used to effectively destroy the buffer
gst_buffer_free() can also be used to effectively free the buffer
regardless of the refcount (dangerous).
</para>
......@@ -59,20 +66,52 @@ regardless of the refcount (dangerous).
#GstBufferPool, #GstPad, #GstData
</para>
<!-- ##### MACRO GST_BUFFER ##### -->
<para>
Casts an object to a GstBuffer.
</para>
@buf: object to cast
<!-- ##### MACRO GST_IS_BUFFER ##### -->
<para>
Checks if the object is a buffer.
Checks if the pointer is a GstBuffer
</para>
@buf: object to check
@buf: The buffer to query
<!-- ##### MACRO GST_BUFFER ##### -->
<!-- ##### MACRO GST_BUFFER_REFCOUNT ##### -->
<para>
Casts an object to a GstBuffer.
Get a handle to the refcount structure of the buffer
</para>
@buf: object to cast
@buf: The buffer to query
<!-- ##### MACRO GST_BUFFER_REFCOUNT_VALUE ##### -->
<para>
Get the current refcount value of the buffer
</para>
@buf: The buffer to query
<!-- ##### MACRO GST_BUFFER_COPY_FUNC ##### -->
<para>
Calls the buffer-specific copy function on the given buffer.
</para>
@buf: a #GstBuffer to copy
<!-- ##### MACRO GST_BUFFER_FREE_FUNC ##### -->
<para>
Calls the buffer-specific free function on the given buffer.
</para>
@buf: a #GstBuffer to free
<!-- ##### MACRO GST_BUFFER_FLAGS ##### -->
......@@ -126,14 +165,6 @@ Gets the size of the data in this buffer.
@buf: a #GstBuffer to get data size of
<!-- ##### MACRO GST_BUFFER_OFFSET ##### -->
<para>
Gets the offset in the source file of this buffer.
</para>
@buf: a #GstBuffer to get offset of
<!-- ##### MACRO GST_BUFFER_MAXSIZE ##### -->
<para>
Gets the maximum size of this buffer.
......@@ -150,6 +181,14 @@ Gets the timestamp for this buffer.
@buf: a #GstBuffer to get timestamp of
<!-- ##### MACRO GST_BUFFER_OFFSET ##### -->
<para>
Gets the offset in the source file of this buffer.
</para>
@buf: a #GstBuffer to get offset of
<!-- ##### MACRO GST_BUFFER_BUFFERPOOL ##### -->
<para>
Gets the bufferpool for this buffer.
......@@ -166,25 +205,31 @@ Gets the bufferpool private data.
@buf: a #GstBuffer to get bufferpool's private data of
<!-- ##### MACRO GST_BUFFER_COPY_FUNC ##### -->
<para>
Calls the buffer-specific copy function on the given buffer.
</para>
@buf: a #GstBuffer to copy
<<<<<<< gstbuffer.sgml
<!-- ##### MACRO GST_BUFFER_FREE_FUNC ##### -->
<!-- ##### ENUM GstBufferFlag ##### -->
<para>
Calls the buffer-specific free function on the given buffer.
This enumeration type describes the flags that can be used for a buffer.
</para>
@buf: a #GstBuffer to free
@GST_BUFFER_READONLY: buffer is read-only
@GST_BUFFER_SUBBUFFER: This buffer is a subbuffer, the parent buffer can be found with the
GST_BUFFER_POOL_PRIVATE() macro.
@GST_BUFFER_ORIGINAL: buffer is not a copy of another buffer
@GST_BUFFER_DONTFREE: do not try to free the data when this buffer is unreferenced
@GST_BUFFER_DISCONTINOUS: This buffer is the first one after a discontinuity in the stream
@GST_BUFFER_KEY_UNIT: This buffer holds a key unit, a unit that can be decoded independently
of other buffers
@GST_BUFFER_PREROLL: This buffer should be decoded but not rendered, it is mainly used
to resynchronise the stream
@GST_BUFFER_FLAG_LAST: Additional flags can be added starting from this flag.
=======
<!-- ##### STRUCT GstBuffer ##### -->
<para>
The basic structure of a buffer
</para>
@data_type:
......@@ -204,6 +249,15 @@ Calls the buffer-specific free function on the given buffer.
@Returns:
<!-- ##### FUNCTION gst_buffer_new_and_alloc ##### -->
<para>
</para>
@size:
@Returns:
<!-- ##### FUNCTION gst_buffer_new_from_pool ##### -->
<para>
......@@ -213,63 +267,90 @@ Calls the buffer-specific free function on the given buffer.
@offset:
@size:
@Returns:
<!-- # Unused Parameters # -->
@location:
<!-- ##### MACRO gst_buffer_copy ##### -->
<!-- ##### FUNCTION gst_buffer_default_free ##### -->
<para>
</para>
@buffer:
@Returns:
<!-- ##### FUNCTION gst_buffer_create_sub ##### -->
<!-- ##### FUNCTION gst_buffer_default_copy ##### -->
<para>
</para>
@parent:
@offset:
@size:
@buffer:
@Returns:
<!-- ##### MACRO gst_buffer_ref ##### -->
<para>
Increase the refcount of the given buffer
</para>
@buf:
<!-- # Unused Parameters # -->
@buffer:
@buf: The buffer to refcount
<!-- ##### MACRO gst_buffer_ref_by_count ##### -->
<para>
Increase the refcount of the buffer with the given value.
</para>
@buf:
@c:
<!-- # Unused Parameters # -->
@buffer:
@count:
@buf: The buffer to refcount
@c: The value to add to the refcount.
<!-- ##### MACRO gst_buffer_unref ##### -->
<para>
Decrease the refcount of the buffer. If the refcount reaches 0, the buffer
will be freed.
</para>
@buf: The buffer to unref
<!-- ##### MACRO gst_buffer_copy ##### -->
<para>
Copy the given buffer using the copy function of the parent GstData structure.
</para>
@buffer: The buffer to copy
@Returns: A new copy of the buffer
<!-- ##### MACRO gst_buffer_copy_on_write ##### -->
<para>
Copy the buffer if the refcount > 1 so that the newly created buffer can be safely
written to. If the refcount is 1, this function just returns the original buffer.
</para>
@buffer: The buffer to copy.
<!-- ##### MACRO gst_buffer_free ##### -->
<para>
Free the given buffer. It is dangerous to use this function, use gst_buffer_unref()
instead.
</para>
@buf:
<!-- # Unused Parameters # -->
@buffer:
@buffer: The buffer to free.
<!-- ##### FUNCTION gst_buffer_is_span_fast ##### -->
<!-- ##### FUNCTION gst_buffer_create_sub ##### -->
<para>
</para>
@parent:
@offset:
@size:
@Returns:
<!-- ##### FUNCTION gst_buffer_merge ##### -->
<para>
</para>
......@@ -279,7 +360,7 @@ Calls the buffer-specific free function on the given buffer.
@Returns:
<!-- ##### FUNCTION gst_buffer_merge ##### -->
<!-- ##### FUNCTION gst_buffer_is_span_fast ##### -->
<para>
</para>
......
......@@ -6,9 +6,9 @@ Create buffers from a pool
<!-- ##### SECTION Long_Description ##### -->
<para>
A bufferpool is used to create buffers in an efficient way. En element
can maintain a bufferpool with a fixed number of buffers. This will reduce
the g_malloc and g_free overhead.
A bufferpool is used to create buffers in an efficient way. An element
can, for example, maintain a bufferpool with a fixed number of buffers.
This will reduce the g_malloc and g_free overhead.
</para>
<para>
A bufferpool can also be used to implement direct access. A bufferpool can be
......@@ -17,21 +17,19 @@ the memory of the element that maintains the bufferpool. This can greatly reduce
the number of memcpy operations.
</para>
<para>
A bufferpool is created with gst_buffer_pool_new(). You'll have to set the
buffer new and free function afterwards with gst_buffer_pool_set_buffer_new_function() and
gst_buffer_pool_set_buffer_free_function() so that all buffers created
from this pool will be allocated/freed with these functions.
</para>
<para>
Optionally the default buffer copy function of the buffers allocated from this pool
can be overridden with gst_buffer_pool_set_buffer_copy_function().
A bufferpool is created with gst_buffer_pool_new(). You'll have to provide a
free and copy function to handle the refcounting of the bufferpool as well as
functions to create, free and copy buffers created from this pool. All buffer
functions will receive the user_data you provide in the constructor.
When no free and copy function is provided for the pool, a default implementation
will be used.
</para>
<para>
To create a buffer from the bufferpool use gst_buffer_new_from_pool().
</para>
<para>
When the buffer is unreffed and has reached a refcount of 0, the bufferpools free
function is called with the buffer as an argument.
function is called with the pool, the buffer and the user_data as arguments.
</para>
<para>
A bufferpool can store private data in the buffer it creates with the GST_BUFFER_POOL_PRIVATE()
......@@ -39,13 +37,8 @@ macro. To check it a buffer was made by a specific bufferpool, use the GST_BUFFE
macro to get its bufferpool.
</para>
<para>
Destroy the bufferpool with gst_buffer_pool_destroy(), optional cleanup of the bufferpool can
be triggered in the GstBufferPoolDestroyHook which you can install with
gst_buffer_pool_set_destroy_hook().
</para>
<para>
The owner of the bufferpool can add user data to the pool with
gst_buffer_pool_set_user_data() and gst_buffer_pool_get_user_data().
All plugins should unref the bufferpool if it is no longer required. When the bufferpool
reaches a refcount of 0, the free function will be called.
</para>
<para>
If your plugin is going to need a lot of equally sized memory areas you can use
......@@ -57,6 +50,7 @@ quite efficient since it reduces the number of memory allocations.
<para>
A bufferpool can be requested from a pad with the gst_pad_get_bufferpool() function. This function
is typically used when a plugin wants to write into a memory area provided by another plugin.
Use gst_buffer_pool_unref() is you no longer require the bufferpool.