mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-27 04:01:08 +00:00
review some docs
This commit is contained in:
Wim Taymans
parent
3e6238135d
commit
9aa9751938
14 changed files with 100 additions and 55 deletions
|
|
@ -210,13 +210,13 @@ gst_my_filter_sink_event (GstPad *pad, GstEvent * event)
|
|||
It is important to note that <emphasis>only elements driving the
|
||||
pipeline should ever send an EOS event</emphasis>. If your element
|
||||
is chain-based, it is not driving the pipeline. Chain-based elements
|
||||
should just return GST_FLOW_UNEXPECTED from their chain function at
|
||||
should just return GST_FLOW_EOS from their chain function at
|
||||
the end of the stream (or the configured segment), the upstream
|
||||
element that is driving the pipeline will then take care of
|
||||
sending the EOS event (or alternatively post a SEGMENT_DONE message
|
||||
on the bus depending on the mode of operation). If you are implementing
|
||||
your own source element, you also do not need to ever manually send
|
||||
an EOS event, you should also just return GST_FLOW_UNEXPECTED in
|
||||
an EOS event, you should also just return GST_FLOW_EOS in
|
||||
your create function (assuming your element derives from GstBaseSrc
|
||||
or GstPushSrc).
|
||||
</para>
|
||||
|
|
|
|||
|
|
@ -154,7 +154,7 @@
|
|||
* </para>
|
||||
* </refsect2>
|
||||
*
|
||||
* Last reviewed on 2006-04-28 (0.10.6)
|
||||
* Last reviewed on 2012-03-28 (0.11.3)
|
||||
*/
|
||||
|
||||
#include "gst_private.h"
|
||||
|
|
|
|||
|
|
@ -22,14 +22,12 @@
|
|||
|
||||
/**
|
||||
* SECTION:gstbuffer
|
||||
* @short_description: Data-passing buffer type, supporting sub-buffers.
|
||||
* @see_also: #GstPad, #GstMiniObject, #GstBufferPool
|
||||
* @short_description: Data-passing buffer type
|
||||
* @see_also: #GstPad, #GstMiniObject, #GstMemory, #GstMeta, #GstBufferPool
|
||||
*
|
||||
* Buffers are the basic unit of data transfer in GStreamer. The #GstBuffer
|
||||
* type provides all the state necessary to define the regions of memory as
|
||||
* part of a stream. Region copies 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 prematurely.
|
||||
* Buffers are the basic unit of data transfer in GStreamer. They contain the
|
||||
* timing and offset along with other arbitrary metadata that is associated
|
||||
* with the #GstMemory blocks that the buffer contains.
|
||||
*
|
||||
* Buffers are usually created with gst_buffer_new(). After a buffer has been
|
||||
* created one will typically allocate memory for it and add it to the buffer.
|
||||
|
|
@ -62,21 +60,29 @@
|
|||
* meaningful value can be given for these, they should be set. The timestamps
|
||||
* and duration are measured in nanoseconds (they are #GstClockTime values).
|
||||
*
|
||||
* The buffer DTS refers to the timestamp when the buffer should be decoded and
|
||||
* is usually monotonically increasing. The buffer PTS refers to the timestamp when
|
||||
* the buffer content should be presented to the user and is not always
|
||||
* monotonically increasing.
|
||||
*
|
||||
* A buffer can also have one or both of a start and an end offset. These are
|
||||
* media-type specific. For video buffers, the start offset will generally be
|
||||
* the frame number. For audio buffers, it will be the number of samples
|
||||
* produced so far. For compressed data, it could be the byte offset in a
|
||||
* source or destination file. Likewise, the end offset will be the offset of
|
||||
* the end of the buffer. These can only be meaningfully interpreted if you
|
||||
* know the media type of the buffer (the #GstCaps set on it). Either or both
|
||||
* know the media type of the buffer (the preceeding CAPS event). Either or both
|
||||
* can be set to #GST_BUFFER_OFFSET_NONE.
|
||||
*
|
||||
* gst_buffer_ref() is used to increase the refcount of a buffer. This must be
|
||||
* done when you want to keep a handle to the buffer after pushing it to the
|
||||
* next element.
|
||||
* next element. The buffer refcount determines the writability of the buffer, a
|
||||
* buffer is only writable when the refcount is exactly 1, i.e. when the caller
|
||||
* has the only reference to the buffer.
|
||||
*
|
||||
* To efficiently create a smaller buffer out of an existing one, you can
|
||||
* use gst_buffer_copy_region().
|
||||
* use gst_buffer_copy_region(). This method tries to share the memory objects
|
||||
* between the two buffers.
|
||||
*
|
||||
* If a plug-in wants to modify the buffer data or metadata in-place, it should
|
||||
* first obtain a buffer that is safe to modify by using
|
||||
|
|
@ -91,14 +97,18 @@
|
|||
* gst_buffer_append(). Copying of memory will only be done when absolutely
|
||||
* needed.
|
||||
*
|
||||
* Arbitrary extra metadata can be set on a buffer with gst_buffer_add_meta().
|
||||
* Metadata can be retrieved with gst_buffer_get_meta(). See also #GstMeta
|
||||
*
|
||||
* An element should either unref the buffer or push it out on a src pad
|
||||
* using gst_pad_push() (see #GstPad).
|
||||
*
|
||||
* Buffers are usually freed by unreffing them with gst_buffer_unref(). When
|
||||
* the refcount drops to 0, any data pointed to by the buffer is unreffed as
|
||||
* well.
|
||||
* the refcount drops to 0, any memory and metadata pointed to by the buffer is
|
||||
* unreffed as well. Buffers allocated from a #GstBufferPool will be returned to
|
||||
* the pool when the refcount drops to 0.
|
||||
*
|
||||
* Last reviewed on November 8, 2011 (0.11.2)
|
||||
* Last reviewed on 2012-03-28 (0.11.3)
|
||||
*/
|
||||
#include "gst_private.h"
|
||||
|
||||
|
|
|
|||
|
|
@ -30,6 +30,11 @@
|
|||
* Buffer lists are created with gst_buffer_list_new() and filled with data
|
||||
* using a gst_buffer_list_insert().
|
||||
*
|
||||
* Buffer lists can be pushed on a srcpad with gst_pad_push_list(). This is
|
||||
* interesting when multiple buffers need to be pushed in one go because it
|
||||
* can reduce the amount of overhead for pushing each buffer individually.
|
||||
*
|
||||
* Last reviewed on 2012-03-28 (0.11.3)
|
||||
*/
|
||||
#include "gst_private.h"
|
||||
|
||||
|
|
|
|||
|
|
@ -24,6 +24,45 @@
|
|||
* @short_description: Pool for buffers
|
||||
* @see_also: #GstBuffer
|
||||
*
|
||||
* a #GstBufferPool is an object that can be used to pre-allocate and recycle
|
||||
* buffers of the same size and with the same properties.
|
||||
*
|
||||
* A #GstBufferPool is created with gst_buffer_pool_new().
|
||||
*
|
||||
* After the buffer is created, it needs to be configured.
|
||||
* gst_buffer_pool_get_config() get the current configuration structure from the
|
||||
* pool. With gst_buffer_pool_config_set_params() and
|
||||
* gst_buffer_pool_config_set_allocator() the bufferpool parameters and allocator
|
||||
* can be configured. Other properties can be configured in the pool depending
|
||||
* on the pool implementation.
|
||||
*
|
||||
* A bufferpool can have extra options that can be enabled with
|
||||
* gst_buffer_pool_config_add_option(). The available options can be retrieved
|
||||
* with gst_buffer_pool_get_options(). Some options allow for additional
|
||||
* configuration properties to be set.
|
||||
*
|
||||
* After the configuration structure has been configured,
|
||||
* gst_buffer_pool_set_config() updates the configuration in the pool. This can
|
||||
* fail when the configuration structure is not accepted.
|
||||
*
|
||||
* After the a pool has been configured, it can be activated with
|
||||
* gst_buffer_pool_set_active(). This will preallocate the configured resources
|
||||
* in the pool.
|
||||
*
|
||||
* When the pool is active, gst_buffer_pool_acquire_buffer() can be used to
|
||||
* retrieve a buffer from the pool.
|
||||
*
|
||||
* Buffer allocated from a bufferpool will automatically be returned to the pool
|
||||
* with gst_buffer_pool_release_buffer() when their refcount drops to 0.
|
||||
*
|
||||
* The bufferpool can be deactivated again with gst_buffer_pool_set_active().
|
||||
* All further gst_buffer_pool_acquire_buffer() calls will return an error. When
|
||||
* all buffers are returned to the pool they will be freed.
|
||||
*
|
||||
* Use gst_object_unref() to release the reference to a bufferpool. If the
|
||||
* refcount of the pool reaches 0, the pool will be freed.
|
||||
*
|
||||
* Last reviewed on 2012-03-28 (0.11.3)
|
||||
*/
|
||||
|
||||
#include "gst_private.h"
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ typedef struct _GstBufferPoolClass GstBufferPoolClass;
|
|||
* @GST_BUFFER_POOL_ACQUIRE_FLAG_NONE: no flags
|
||||
* @GST_BUFFER_POOL_ACQUIRE_FLAG_KEY_UNIT: buffer is keyframe
|
||||
* @GST_BUFFER_POOL_ACQUIRE_FLAG_DONTWAIT: don't wait for buffer. This makes the
|
||||
* acquire_buffer method return GST_FLOW_UNEXPECTED.
|
||||
* acquire_buffer method return GST_FLOW_EOS.
|
||||
* @GST_BUFFER_POOL_ACQUIRE_FLAG_DISCONT: buffer is discont
|
||||
* @GST_BUFFER_POOL_ACQUIRE_FLAG_LAST: last flag, subclasses can use private flags
|
||||
* starting from this value.
|
||||
|
|
@ -127,13 +127,13 @@ struct _GstBufferPool {
|
|||
* will take a buffer from the queue and optionally wait for a buffer to
|
||||
* be released when there are no buffers available.
|
||||
* @alloc_buffer: allocate a buffer. the default implementation allocates
|
||||
* buffers from the default memory allocator and with the configured
|
||||
* size, prefix, padding and alignment. All metadata that is present on the
|
||||
* allocated buffer will be marked as #GST_META_FLAG_POOLED and will not
|
||||
* be removed from the buffer in @reset_buffer.
|
||||
* buffers from the configured memory allocator and with the configured
|
||||
* parameters. All metadata that is present on the allocated buffer will
|
||||
* be marked as #GST_META_FLAG_POOLED and will not be removed from the
|
||||
* buffer in @reset_buffer.
|
||||
* @reset_buffer: reset the buffer to its state when it was freshly allocated.
|
||||
* The default implementation will clear the flags, timestamps and
|
||||
* will remove the metadata added after alloc_buffer.
|
||||
* will remove the metadata without the #GST_META_FLAG_POOLED flag.
|
||||
* @release_buffer: release a buffer back in the pool. The default
|
||||
* implementation will put the buffer back in the queue and notify any
|
||||
* blocking acquire_buffer calls.
|
||||
|
|
|
|||
|
|
@ -64,7 +64,7 @@
|
|||
* Note that a #GstPipeline will set its bus into flushing state when changing
|
||||
* from READY to NULL state.
|
||||
*
|
||||
* Last reviewed on 2006-03-12 (0.10.5)
|
||||
* Last reviewed on 2012-03-28 (0.11.3)
|
||||
*/
|
||||
|
||||
#include "gst_private.h"
|
||||
|
|
|
|||
|
|
@ -20,9 +20,9 @@
|
|||
/**
|
||||
* SECTION:gstcaps
|
||||
* @short_description: Structure describing sets of media formats
|
||||
* @see_also: #GstStructure
|
||||
* @see_also: #GstStructure, #GstMiniObject
|
||||
*
|
||||
* Caps (capabilities) are lighweight refcounted objects describing media types.
|
||||
* Caps (capabilities) are lightweight refcounted objects describing media types.
|
||||
* They are composed of an array of #GstStructure.
|
||||
*
|
||||
* Caps are exposed on #GstPadTemplate to describe all possible types a
|
||||
|
|
@ -33,10 +33,6 @@
|
|||
* function. This function describes the possible types that the pad can
|
||||
* handle or produce at runtime.
|
||||
*
|
||||
* Caps are also attached to buffers to describe to content of the data
|
||||
* pointed to by the buffer with gst_buffer_set_caps(). Caps attached to
|
||||
* a #GstBuffer allow for format negotiation upstream and downstream.
|
||||
*
|
||||
* A #GstCaps can be constructed with the following code fragment:
|
||||
*
|
||||
* <example>
|
||||
|
|
@ -54,13 +50,13 @@
|
|||
* </example>
|
||||
*
|
||||
* A #GstCaps is fixed when it has no properties with ranges or lists. Use
|
||||
* gst_caps_is_fixed() to test for fixed caps. Only fixed caps can be
|
||||
* set on a #GstPad or #GstBuffer.
|
||||
* gst_caps_is_fixed() to test for fixed caps. Fixed caps can be used in a
|
||||
* caps event to notify downstream elements of the current media type.
|
||||
*
|
||||
* Various methods exist to work with the media types such as subtracting
|
||||
* or intersecting.
|
||||
*
|
||||
* Last reviewed on 2007-02-13 (0.10.10)
|
||||
* Last reviewed on 2011-03-28 (0.11.3)
|
||||
*/
|
||||
|
||||
#ifdef HAVE_CONFIG_H
|
||||
|
|
|
|||
|
|
@ -99,7 +99,7 @@
|
|||
* number of samples to use when calibrating and #GstClock:window-threshold
|
||||
* defines the minimum number of samples before the calibration is performed.
|
||||
*
|
||||
* Last reviewed on 2009-05-21 (0.10.24)
|
||||
* Last reviewed on 2012-03-28 (0.11.3)
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@
|
|||
* core when using the appropriate locking. Do not use this in plug-ins or
|
||||
* applications in order to retain ABI compatibility.
|
||||
*
|
||||
* All elements have pads (of the type #GstPad). These pads link to pads on
|
||||
* Elements can have pads (of the type #GstPad). These pads link to pads on
|
||||
* other elements. #GstBuffer flow between these linked pads.
|
||||
* A #GstElement has a #GList of #GstPad structures for all their input (or sink)
|
||||
* and output (or source) pads.
|
||||
|
|
@ -44,7 +44,7 @@
|
|||
* An existing pad of an element can be retrieved by name with
|
||||
* gst_element_get_static_pad(). A new dynamic pad can be created using
|
||||
* gst_element_request_pad() with a #GstPadTemplate or
|
||||
* gst_element_get_request_pad() with the template name such as "src_\%d".
|
||||
* gst_element_get_request_pad() with the template name such as "src_\%u".
|
||||
* An iterator of all pads can be retrieved with gst_element_iterate_pads().
|
||||
*
|
||||
* Elements can be linked through their pads.
|
||||
|
|
@ -65,18 +65,18 @@
|
|||
* You can get and set a #GstClock on an element using gst_element_get_clock()
|
||||
* and gst_element_set_clock().
|
||||
* Some elements can provide a clock for the pipeline if
|
||||
* gst_element_provides_clock() returns %TRUE. With the
|
||||
* the #GST_ELEMENT_FLAG_PROVIDE_CLOCK flag is set. With the
|
||||
* gst_element_provide_clock() method one can retrieve the clock provided by
|
||||
* such an element.
|
||||
* Not all elements require a clock to operate correctly. If
|
||||
* gst_element_requires_clock() returns %TRUE, a clock should be set on the
|
||||
* Not all elements require a clock to operate correctly. If the
|
||||
* #GST_ELEMENT_FLAG_REQUIRE_CLOCK() flag is set, a clock should be set on the
|
||||
* element with gst_element_set_clock().
|
||||
*
|
||||
* Note that clock slection and distribution is normally handled by the
|
||||
* toplevel #GstPipeline so the clock functions are only to be used in very
|
||||
* specific situations.
|
||||
*
|
||||
* Last reviewed on 2009-05-29 (0.10.24)
|
||||
* Last reviewed on 2012-03-28 (0.11.3)
|
||||
*/
|
||||
|
||||
#include "gst_private.h"
|
||||
|
|
|
|||
|
|
@ -36,19 +36,19 @@
|
|||
* elements will use gst_pad_send_event() or gst_pad_push_event().
|
||||
* The event should be unreffed with gst_event_unref() if it has not been sent.
|
||||
*
|
||||
* Events that have been received can be parsed with their respective
|
||||
* Events that have been received can be parsed with their respective
|
||||
* gst_event_parse_*() functions. It is valid to pass %NULL for unwanted details.
|
||||
*
|
||||
* Events are passed between elements in parallel to the data stream. Some events
|
||||
* are serialized with buffers, others are not. Some events only travel downstream,
|
||||
* others only upstream. Some events can travel both upstream and downstream.
|
||||
*
|
||||
* others only upstream. Some events can travel both upstream and downstream.
|
||||
*
|
||||
* The events are used to signal special conditions in the datastream such as
|
||||
* EOS (end of stream) or the start of a new stream-segment.
|
||||
* Events are also used to flush the pipeline of any pending data.
|
||||
*
|
||||
* Most of the event API is used inside plugins. Applications usually only
|
||||
* construct and use seek events.
|
||||
* Most of the event API is used inside plugins. Applications usually only
|
||||
* construct and use seek events.
|
||||
* To do that gst_event_new_seek() is used to create a seek event. It takes
|
||||
* the needed parameters to specify seeking time and mode.
|
||||
* <example>
|
||||
|
|
@ -72,7 +72,7 @@
|
|||
* </programlisting>
|
||||
* </example>
|
||||
*
|
||||
* Last reviewed on 2006-09-6 (0.10.10)
|
||||
* Last reviewed on 2012-03-28 (0.11.3)
|
||||
*/
|
||||
|
||||
|
||||
|
|
@ -452,10 +452,6 @@ gst_event_set_seqnum (GstEvent * event, guint32 seqnum)
|
|||
GST_EVENT_SEQNUM (event) = seqnum;
|
||||
}
|
||||
|
||||
/* FIXME 0.11: It would be nice to have flush events
|
||||
* that don't reset the running time in the sinks
|
||||
*/
|
||||
|
||||
/**
|
||||
* gst_event_new_flush_start:
|
||||
*
|
||||
|
|
@ -540,7 +536,7 @@ gst_event_parse_flush_stop (GstEvent * event, gboolean * reset_time)
|
|||
*
|
||||
* Create a new EOS event. The eos event can only travel downstream
|
||||
* synchronized with the buffer flow. Elements that receive the EOS
|
||||
* event on a pad can return #GST_FLOW_UNEXPECTED as a #GstFlowReturn
|
||||
* event on a pad can return #GST_FLOW_EOS as a #GstFlowReturn
|
||||
* when data after the EOS event arrives.
|
||||
*
|
||||
* The EOS event will travel down to the sink elements in the pipeline
|
||||
|
|
|
|||
|
|
@ -111,9 +111,8 @@ gst_mini_object_copy (const GstMiniObject * mini_object)
|
|||
* @mini_object: the mini-object to check
|
||||
*
|
||||
* Checks if a mini-object is writable. A mini-object is writable
|
||||
* if the reference count is one and the #GST_MINI_OBJECT_FLAG_READONLY
|
||||
* flag is not set. Modification of a mini-object should only be
|
||||
* done after verifying that it is writable.
|
||||
* if the reference count is one. Modification of a mini-object should
|
||||
* only be done after verifying that it is writable.
|
||||
*
|
||||
* MT safe
|
||||
*
|
||||
|
|
|
|||
|
|
@ -325,7 +325,7 @@ typedef GstFlowReturn (*GstPadChainListFunction) (GstPad *pad, GstObject *paren
|
|||
* #GST_QUERY_SEEKING.
|
||||
*
|
||||
* Any @offset larger or equal than the length will make the function return
|
||||
* #GST_FLOW_UNEXPECTED, which corresponds to EOS. In this case @buffer does not
|
||||
* #GST_FLOW_EOS, which corresponds to EOS. In this case @buffer does not
|
||||
* contain a valid buffer.
|
||||
*
|
||||
* The buffer size of @buffer will only be smaller than @length when @offset is
|
||||
|
|
|
|||
|
|
@ -149,7 +149,7 @@ struct _GstBaseSrc {
|
|||
* When the subclass returns GST_FLOW_OK, it MUST return a buffer of the
|
||||
* requested size unless fewer bytes are available because an EOS condition
|
||||
* is near. No buffer should be returned when the return value is different
|
||||
* from GST_FLOW_OK. A return value of GST_FLOW_UNEXPECTED signifies that the
|
||||
* from GST_FLOW_OK. A return value of GST_FLOW_EOS signifies that the
|
||||
* end of stream is reached. The default implementation will call @alloc and
|
||||
* then call @fill.
|
||||
* @alloc: Ask the subclass to allocate a buffer with for offset and size. The
|
||||
|
|
|
|||
Loading…
Reference in a new issue