mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer-rs.git synced 2024-11-15 22:11:01 +00:00

Sebastian Dröge d09dd828d6 Update docs

2017-11-26 19:32:20 +02:00

62 KiB

Raw Blame History

This class is for elements that receive buffers in an undesired size. While for example raw video contains one image per buffer, the same is not true for a lot of other formats, especially those that come directly from a file. So if you have undefined buffer sizes and require a specific size, this object is for you.

An adapter is created with Adapter::new. It can be freed again with gobject::ObjectExt::unref.

The theory of operation is like this: All buffers received are put into the adapter using Adapter::push and the data is then read back in chunks of the desired size using Adapter::map/Adapter::unmap and/or Adapter::copy. After the data has been processed, it is freed using Adapter::unmap.

Other methods such as Adapter::take and Adapter::take_buffer combine Adapter::map and Adapter::unmap in one method and are potentially more convenient for some use cases.

For example, a sink pad's chain function that needs to pass data to a library in 512-byte chunks could be implemented like this:

static GstFlowReturn
sink_pad_chain (GstPad *pad, GstObject *parent, GstBuffer *buffer)
{
  MyElement *this;
  GstAdapter *adapter;
  GstFlowReturn ret = GST_FLOW_OK;

  this = MY_ELEMENT (parent);

  adapter = this->adapter;

  // put buffer into adapter
  gst_adapter_push (adapter, buffer);

  // while we can read out 512 bytes, process them
  while (gst_adapter_available (adapter) >= 512 && ret == GST_FLOW_OK) {
    const guint8 *data = gst_adapter_map (adapter, 512);
    // use flowreturn as an error value
    ret = my_library_foo (data);
    gst_adapter_unmap (adapter);
    gst_adapter_flush (adapter, 512);
  }
  return ret;
}

For another example, a simple element inside GStreamer that uses Adapter is the libvisual element.

An element using Adapter in its sink pad chain function should ensure that when the FLUSH_STOP event is received, that any queued data is cleared using Adapter::clear. Data should also be cleared or processed on EOS and when changing state from gst::State::Paused to gst::State::Ready.

Also check the GST_BUFFER_FLAG_DISCONT flag on the buffer. Some elements might need to clear the adapter after a discontinuity.

The adapter will keep track of the timestamps of the buffers that were pushed. The last seen timestamp before the current position can be queried with Adapter::prev_pts. This function can optionally return the number of bytes between the start of the buffer that carried the timestamp and the current adapter position. The distance is useful when dealing with, for example, raw audio samples because it allows you to calculate the timestamp of the current adapter position by using the last seen timestamp and the amount of bytes since. Additionally, the Adapter::prev_pts_at_offset can be used to determine the last seen timestamp at a particular offset in the adapter.

The adapter will also keep track of the offset of the buffers (GST_BUFFER_OFFSET) that were pushed. The last seen offset before the current position can be queried with Adapter::prev_offset. This function can optionally return the number of bytes between the start of the buffer that carried the offset and the current adapter position.

Additionally the adapter also keeps track of the PTS, DTS and buffer offset at the last discontinuity, which can be retrieved with Adapter::pts_at_discont, Adapter::dts_at_discont and Adapter::offset_at_discont. The number of bytes that were consumed since then can be queried with Adapter::distance_from_discont.

A last thing to note is that while Adapter is pretty optimized, merging buffers still might be an operation that requires a malloc and memcpy operation, and these operations are not the fastest. Because of this, some functions like Adapter::available_fast are provided to help speed up such cases should you want to. To avoid repeated memory allocations, Adapter::copy can be used to copy data into a (statically allocated) user provided buffer.

Adapter is not MT safe. All operations on an adapter must be serialized by the caller. This is not normally a problem, however, as the normal use case of Adapter is inside one pad's chain function, in which case access is serialized via the pad's STREAM_LOCK.

Note that Adapter::push takes ownership of the buffer passed. Use gst_buffer_ref before pushing it into the adapter if you still want to access the buffer later. The adapter will never modify the data in the buffer pushed in it.

Implements

ObjectExt

Creates a new Adapter. Free with gobject::ObjectExt::unref.

Returns

a new Adapter

Gets the maximum amount of bytes available, that is it returns the maximum value that can be supplied to Adapter::map without that function returning None.

Returns

number of bytes available in self

Gets the maximum number of bytes that are immediately available without requiring any expensive operations (like copying the data into a temporary buffer).

Returns

number of bytes that are available in self without expensive operations

Removes all buffers from self.

Copies size bytes of data starting at offset out of the buffers contained in Adapter into an array dest provided by the caller.

The array dest should be large enough to contain size bytes. The user should check that the adapter has (offset + size) bytes available before calling this function.

`dest`

the memory to copy into

`offset`

the bytes offset in the adapter to start from

`size`

the number of bytes to copy

Similar to gst_adapter_copy, but more suitable for language bindings. size bytes of data starting at offset will be copied out of the buffers contained in self and into a new glib::Bytes structure which is returned. Depending on the value of the size argument an empty glib::Bytes structure may be returned.

`offset`

the bytes offset in the adapter to start from

`size`

the number of bytes to copy

Returns

A new glib::Bytes structure containing the copied data.

Get the DTS that was on the last buffer with the GST_BUFFER_FLAG_DISCONT flag, or GST_CLOCK_TIME_NONE.

Feature: v1_10

Returns

The DTS at the last discont or GST_CLOCK_TIME_NONE.

Flushes the first flush bytes in the self. The caller must ensure that at least this many bytes are available.

See also: Adapter::map, Adapter::unmap

`flush`

the number of bytes to flush

Returns a gst::Buffer containing the first nbytes of the self, but does not flush them from the adapter. See Adapter::take_buffer for details.

Caller owns a reference to the returned buffer. gst_buffer_unref after usage.

Free-function: gst_buffer_unref

`nbytes`

the number of bytes to get

Returns

a gst::Buffer containing the first nbytes of the adapter, or None if nbytes bytes are not available. gst_buffer_unref when no longer needed.

Returns a gst::Buffer containing the first nbytes of the self, but does not flush them from the adapter. See Adapter::take_buffer_fast for details.

Caller owns a reference to the returned buffer. gst_buffer_unref after usage.

Free-function: gst_buffer_unref

`nbytes`

the number of bytes to get

Returns

a gst::Buffer containing the first nbytes of the adapter, or None if nbytes bytes are not available. gst_buffer_unref when no longer needed.

Returns a gst::BufferList of buffers containing the first nbytes bytes of the self but does not flush them from the adapter. See Adapter::take_buffer_list for details.

Caller owns the returned list. Call gst_buffer_list_unref to free the list after usage.

`nbytes`

the number of bytes to get

Returns

a gst::BufferList of buffers containing the first nbytes of the adapter, or None if nbytes bytes are not available

Returns a glib::List of buffers containing the first nbytes bytes of the self, but does not flush them from the adapter. See Adapter::take_list for details.

Caller owns returned list and contained buffers. gst_buffer_unref each buffer in the list before freeing the list after usage.

`nbytes`

the number of bytes to get

Returns

a glib::List of buffers containing the first nbytes of the adapter, or None if nbytes bytes are not available

Gets the first size bytes stored in the self. The returned pointer is valid until the next function is called on the adapter.

Note that setting the returned pointer as the data of a gst::Buffer is incorrect for general-purpose plugins. The reason is that if a downstream element stores the buffer so that it has access to it outside of the bounds of its chain function, the buffer will have an invalid data pointer after your element flushes the bytes. In that case you should use Adapter::take, which returns a freshly-allocated buffer that you can set as gst::Buffer memory or the potentially more performant Adapter::take_buffer.

Returns None if size bytes are not available.

`size`

the number of bytes to map/peek

Returns

a pointer to the first size bytes of data, or None

Scan for pattern pattern with applied mask mask in the adapter data, starting from offset offset.

The bytes in pattern and mask are interpreted left-to-right, regardless of endianness. All four bytes of the pattern must be present in the adapter for it to match, even if the first or last bytes are masked out.

It is an error to call this function without making sure that there is enough data (offset+size bytes) in the adapter.

This function calls Adapter::masked_scan_uint32_peek passing None for value.

`mask`

mask to apply to data before matching against pattern

`pattern`

pattern to match (after mask is applied)

`offset`

offset into the adapter data from which to start scanning, returns the last scanned position.

`size`

number of bytes to scan from offset

Returns

offset of the first match, or -1 if no match was found.

Example:

// Assume the adapter contains 0x00 0x01 0x02 ... 0xfe 0xff

gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x00010203, 0, 256);
// -> returns 0
gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x00010203, 1, 255);
// -> returns -1
gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x01020304, 1, 255);
// -> returns 1
gst_adapter_masked_scan_uint32 (adapter, 0xffff, 0x0001, 0, 256);
// -> returns -1
gst_adapter_masked_scan_uint32 (adapter, 0xffff, 0x0203, 0, 256);
// -> returns 0
gst_adapter_masked_scan_uint32 (adapter, 0xffff0000, 0x02030000, 0, 256);
// -> returns 2
gst_adapter_masked_scan_uint32 (adapter, 0xffff0000, 0x02030000, 0, 4);
// -> returns -1

Scan for pattern pattern with applied mask mask in the adapter data, starting from offset offset. If a match is found, the value that matched is returned through value, otherwise value is left untouched.

It is an error to call this function without making sure that there is enough data (offset+size bytes) in the adapter.

`mask`

mask to apply to data before matching against pattern

`pattern`

pattern to match (after mask is applied)

`offset`

offset into the adapter data from which to start scanning, returns the last scanned position.

`size`

number of bytes to scan from offset

`value`

pointer to uint32 to return matching data

Returns

offset of the first match, or -1 if no match was found.

Get the offset that was on the last buffer with the GST_BUFFER_FLAG_DISCONT flag, or GST_BUFFER_OFFSET_NONE.

Feature: v1_10

Returns

The offset at the last discont or GST_BUFFER_OFFSET_NONE.

Get the dts that was before the current byte in the adapter. When distance is given, the amount of bytes between the dts and the current position is returned.

The dts is reset to GST_CLOCK_TIME_NONE and the distance is set to 0 when the adapter is first created or when it is cleared. This also means that before the first byte with a dts is removed from the adapter, the dts and distance returned are GST_CLOCK_TIME_NONE and 0 respectively.

`distance`

pointer to location for distance, or None

Returns

The previously seen dts.

Get the dts that was before the byte at offset offset in the adapter. When distance is given, the amount of bytes between the dts and the current position is returned.

`offset`

the offset in the adapter at which to get timestamp

`distance`

pointer to location for distance, or None

Returns

The previously seen dts at given offset.

Get the offset that was before the current byte in the adapter. When distance is given, the amount of bytes between the offset and the current position is returned.

The offset is reset to GST_BUFFER_OFFSET_NONE and the distance is set to 0 when the adapter is first created or when it is cleared. This also means that before the first byte with an offset is removed from the adapter, the offset and distance returned are GST_BUFFER_OFFSET_NONE and 0 respectively.

Feature: v1_10

`distance`

pointer to a location for distance, or None

Returns

The previous seen offset.

Get the pts that was before the current byte in the adapter. When distance is given, the amount of bytes between the pts and the current position is returned.

The pts is reset to GST_CLOCK_TIME_NONE and the distance is set to 0 when the adapter is first created or when it is cleared. This also means that before the first byte with a pts is removed from the adapter, the pts and distance returned are GST_CLOCK_TIME_NONE and 0 respectively.

`distance`

pointer to location for distance, or None

Returns

The previously seen pts.

Get the pts that was before the byte at offset offset in the adapter. When distance is given, the amount of bytes between the pts and the current position is returned.

`offset`

the offset in the adapter at which to get timestamp

`distance`

pointer to location for distance, or None

Returns

The previously seen pts at given offset.

Get the PTS that was on the last buffer with the GST_BUFFER_FLAG_DISCONT flag, or GST_CLOCK_TIME_NONE.

Feature: v1_10

Returns

The PTS at the last discont or GST_CLOCK_TIME_NONE.

Adds the data from buf to the data stored inside self and takes ownership of the buffer.

`buf`

a gst::Buffer to add to queue in the adapter

Returns a freshly allocated buffer containing the first nbytes bytes of the self. The returned bytes will be flushed from the adapter.

Caller owns returned value. g_free after usage.

Free-function: g_free

`nbytes`

the number of bytes to take

Returns

oven-fresh hot data, or None if nbytes bytes are not available

Returns a gst::Buffer containing the first nbytes bytes of the self. The returned bytes will be flushed from the adapter. This function is potentially more performant than Adapter::take since it can reuse the memory in pushed buffers by subbuffering or merging. This function will always return a buffer with a single memory region.

Note that no assumptions should be made as to whether certain buffer flags such as the DISCONT flag are set on the returned buffer, or not. The caller needs to explicitly set or unset flags that should be set or unset.

Since 1.6 this will also copy over all GstMeta of the input buffers except for meta with the gst::MetaFlags::Pooled flag or with the "memory" tag.

Caller owns a reference to the returned buffer. gst_buffer_unref after usage.

Free-function: gst_buffer_unref

`nbytes`

the number of bytes to take

Returns

a gst::Buffer containing the first nbytes of the adapter, or None if nbytes bytes are not available. gst_buffer_unref when no longer needed.

Returns a gst::Buffer containing the first nbytes of the self. The returned bytes will be flushed from the adapter. This function is potentially more performant than Adapter::take_buffer since it can reuse the memory in pushed buffers by subbuffering or merging. Unlike Adapter::take_buffer, the returned buffer may be composed of multiple non-contiguous gst::Memory objects, no copies are made.

This will also copy over all GstMeta of the input buffers except for meta with the gst::MetaFlags::Pooled flag or with the "memory" tag.

This function can return buffer up to the return value of Adapter::available without making copies if possible.

Caller owns a reference to the returned buffer. gst_buffer_unref after usage.

Free-function: gst_buffer_unref

`nbytes`

the number of bytes to take

Returns

a gst::Buffer containing the first nbytes of the adapter, or None if nbytes bytes are not available. gst_buffer_unref when no longer needed.

Returns a gst::BufferList of buffers containing the first nbytes bytes of the self. The returned bytes will be flushed from the adapter. When the caller can deal with individual buffers, this function is more performant because no memory should be copied.

Caller owns the returned list. Call gst_buffer_list_unref to free the list after usage.

`nbytes`

the number of bytes to take

Returns

a gst::BufferList of buffers containing the first nbytes of the adapter, or None if nbytes bytes are not available

Returns a glib::List of buffers containing the first nbytes bytes of the self. The returned bytes will be flushed from the adapter. When the caller can deal with individual buffers, this function is more performant because no memory should be copied.

Caller owns returned list and contained buffers. gst_buffer_unref each buffer in the list before freeing the list after usage.

`nbytes`

the number of bytes to take

Returns

a glib::List of buffers containing the first nbytes of the adapter, or None if nbytes bytes are not available

Releases the memory obtained with the last Adapter::map.

BaseSink is the base class for sink elements in GStreamer, such as xvimagesink or filesink. It is a layer on top of gst::Element that provides a simplified interface to plugin writers. BaseSink handles many details for you, for example: preroll, clock synchronization, state changes, activation in push or pull mode, and queries.

In most cases, when writing sink elements, there is no need to implement class methods from gst::Element or to set functions on pads, because the BaseSink infrastructure should be sufficient.

BaseSink provides support for exactly one sink pad, which should be named "sink". A sink implementation (subclass of BaseSink) should install a pad template in its class_init function, like so:

static void
my_element_class_init (GstMyElementClass *klass)
{
  GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass);

  // sinktemplate should be a #GstStaticPadTemplate with direction
  // %GST_PAD_SINK and name "sink"
  gst_element_class_add_static_pad_template (gstelement_class, &amp;sinktemplate);

  gst_element_class_set_static_metadata (gstelement_class,
      "Sink name",
      "Sink",
      "My Sink element",
      "The author <my.sink@my.email>");
}

BaseSink will handle the prerolling correctly. This means that it will return gst::StateChangeReturn::Async from a state change to PAUSED until the first buffer arrives in this element. The base class will call the BaseSinkClass.preroll() vmethod with this preroll buffer and will then commit the state change to the next asynchronously pending state.

When the element is set to PLAYING, BaseSink will synchronise on the clock using the times returned from BaseSinkClass.get_times(). If this function returns GST_CLOCK_TIME_NONE for the start time, no synchronisation will be done. Synchronisation can be disabled entirely by setting the object BaseSink:sync property to false.

After synchronisation the virtual method BaseSinkClass.render() will be called. Subclasses should minimally implement this method.

Subclasses that synchronise on the clock in the BaseSinkClass.render() method are supported as well. These classes typically receive a buffer in the render method and can then potentially block on the clock while rendering. A typical example is an audiosink. These subclasses can use BaseSinkExt::wait_preroll to perform the blocking wait.

Upon receiving the EOS event in the PLAYING state, BaseSink will wait for the clock to reach the time indicated by the stop time of the last BaseSinkClass.get_times() call before posting an EOS message. When the element receives EOS in PAUSED, preroll completes, the event is queued and an EOS message is posted when going to PLAYING.

BaseSink will internally use the gst::EventType::Segment events to schedule synchronisation and clipping of buffers. Buffers that fall completely outside of the current segment are dropped. Buffers that fall partially in the segment are rendered (and prerolled). Subclasses should do any subbuffer clipping themselves when needed.

BaseSink will by default report the current playback position in gst::Format::Time based on the current clock time and segment information. If no clock has been set on the element, the query will be forwarded upstream.

The BaseSinkClass.set_caps() function will be called when the subclass should configure itself to process a specific media type.

The BaseSinkClass.start() and BaseSinkClass.stop() virtual methods will be called when resources should be allocated. Any BaseSinkClass.preroll(), BaseSinkClass.render() and BaseSinkClass.set_caps() function will be called between the BaseSinkClass.start() and BaseSinkClass.stop() calls.

The BaseSinkClass.event() virtual method will be called when an event is received by BaseSink. Normally this method should only be overridden by very specific elements (such as file sinks) which need to handle the newsegment event specially.

The BaseSinkClass.unlock() method is called when the elements should unblock any blocking operations they perform in the BaseSinkClass.render() method. This is mostly useful when the BaseSinkClass.render() method performs a blocking write on a file descriptor, for example.

The BaseSink:max-lateness property affects how the sink deals with buffers that arrive too late in the sink. A buffer arrives too late in the sink when the presentation time (as a combination of the last segment, buffer timestamp and element base_time) plus the duration is before the current time of the clock. If the frame is later than max-lateness, the sink will drop the buffer without calling the render method. This feature is disabled if sync is disabled, the BaseSinkClass.get_times() method does not return a valid start time or max-lateness is set to -1 (the default). Subclasses can use BaseSinkExt::set_max_lateness to configure the max-lateness value.

The BaseSink:qos property will enable the quality-of-service features of the basesink which gather statistics about the real-time performance of the clock synchronisation. For each buffer received in the sink, statistics are gathered and a QOS event is sent upstream with these numbers. This information can then be used by upstream elements to reduce their processing rate, for example.

The BaseSink:async property can be used to instruct the sink to never perform an ASYNC state change. This feature is mostly usable when dealing with non-synchronized streams or sparse streams.

Implements

BaseSinkExt, ElementExt, ObjectExt, ObjectExt

Trait containing all BaseSink methods.

Implementors

BaseSink

If the self spawns its own thread for pulling buffers from upstream it should call this method after it has pulled a buffer. If the element needed to preroll, this function will perform the preroll and will then block until the element state is changed.

This function should be called with the PREROLL_LOCK held.

`obj`

the mini object that caused the preroll

Returns

gst::FlowReturn::Ok if the preroll completed and processing can continue. Any other return value should be returned from the render vmethod.

Get the number of bytes that the sink will pull when it is operating in pull mode.

Returns

the number of bytes self will pull in pull mode.

Checks if self is currently configured to drop buffers which are outside the current segment

Feature: v1_12

Returns

true if the sink is configured to drop buffers outside the current segment.

Get the last sample that arrived in the sink and was used for preroll or for rendering. This property can be used to generate thumbnails.

The gst::Caps on the sample can be used to determine the type of the buffer.

Free-function: gst_sample_unref

Returns

a gst::Sample. gst_sample_unref after usage. This function returns None when no buffer has arrived in the sink yet or when the sink is not in PAUSED or PLAYING.

Get the currently configured latency.

Returns

The configured latency.

Get the maximum amount of bits per second that the sink will render.

Returns

the maximum number of bits per second self will render.

Gets the max lateness value. See BaseSinkExt::set_max_lateness for more details.

Returns

The maximum time in nanoseconds that a buffer can be late before it is dropped and not rendered. A value of -1 means an unlimited time.

Get the render delay of self. see BaseSinkExt::set_render_delay for more information about the render delay.

Returns

the render delay of self.

Checks if self is currently configured to synchronize against the clock.

Returns

true if the sink is configured to synchronize against the clock.

Get the time that will be inserted between frames to control the maximum buffers per second.

Returns

the number of nanoseconds self will put between frames.

Get the synchronisation offset of self.

Returns

The synchronisation offset.

Checks if self is currently configured to perform asynchronous state changes to PAUSED.

Returns

true if the sink is configured to perform asynchronous state changes.

Checks if self is currently configured to store the last received sample in the last-sample property.

Returns

true if the sink is configured to store the last received sample.

Checks if self is currently configured to send Quality-of-Service events upstream.

Returns

true if the sink is configured to perform Quality-of-Service.

Query the sink for the latency parameters. The latency will be queried from the upstream elements. live will be true if self is configured to synchronize against the clock. upstream_live will be true if an upstream element is live.

If both live and upstream_live are true, the sink will want to compensate for the latency introduced by the upstream elements by setting the min_latency to a strictly positive value.

This function is mostly used by subclasses.

`live`

if the sink is live

`upstream_live`

if an upstream element is live

`min_latency`

the min latency of the upstream elements

`max_latency`

the max latency of the upstream elements

Returns

true if the query succeeded.

Configures self to perform all state changes asynchronously. When async is disabled, the sink will immediately go to PAUSED instead of waiting for a preroll buffer. This feature is useful if the sink does not synchronize against the clock or when it is dealing with sparse streams.

`enabled`

the new async value.

Set the number of bytes that the sink will pull when it is operating in pull mode.

`blocksize`

the blocksize in bytes

Configure self to drop buffers which are outside the current segment

Feature: v1_12

`drop_out_of_segment`

drop buffers outside the segment

Configures self to store the last received sample in the last-sample property.

`enabled`

the new enable-last-sample value.

Set the maximum amount of bits per second that the sink will render.

`max_bitrate`

the max_bitrate in bits per second

Sets the new max lateness value to max_lateness. This value is used to decide if a buffer should be dropped or not based on the buffer timestamp and the current clock time. A value of -1 means an unlimited time.

`max_lateness`

the new max lateness value.

Configures self to send Quality-of-Service events upstream.

`enabled`

the new qos value.

Set the render delay in self to delay. The render delay is the time between actual rendering of a buffer and its synchronisation time. Some devices might delay media rendering which can be compensated for with this function.

After calling this function, this sink will report additional latency and other sinks will adjust their latency to delay the rendering of their media.

This function is usually called by subclasses.

`delay`

the new delay

Configures self to synchronize on the clock or not. When sync is false, incoming samples will be played as fast as possible. If sync is true, the timestamps of the incoming buffers will be used to schedule the exact render time of its contents.

`sync`

the new sync value.

Set the time that will be inserted between rendered buffers. This can be used to control the maximum buffers per second that the sink will render.

`throttle`

the throttle time in nanoseconds

Adjust the synchronisation of self with offset. A negative value will render buffers earlier than their timestamp. A positive value will delay rendering. This function can be used to fix playback of badly timestamped buffers.

`offset`

the new offset

This function will wait for preroll to complete and will then block until time is reached. It is usually called by subclasses that use their own internal synchronisation but want to let some synchronization (like EOS) be handled by the base class.

This function should only be called with the PREROLL_LOCK held (like when receiving an EOS event in the ::event vmethod or when handling buffers in ::render).

The time argument should be the running_time of when the timeout should happen and will be adjusted with any latency and offset configured in the sink.

`time`

the running_time to be reached

`jitter`

the jitter to be filled with time diff, or None

Returns

gst::FlowReturn

This function will block until time is reached. It is usually called by subclasses that use their own internal synchronisation.

If time is not valid, no synchronisation is done and gst::ClockReturn::Badtime is returned. Likewise, if synchronisation is disabled in the element or there is no clock, no synchronisation is done and gst::ClockReturn::Badtime is returned.

This function should only be called with the PREROLL_LOCK held, like when receiving an EOS event in the BaseSinkClass.event() vmethod or when receiving a buffer in the BaseSinkClass.render() vmethod.

The time argument should be the running_time of when this method should return and is not adjusted with any latency or offset configured in the sink.

`time`

the running_time to be reached

`jitter`

the jitter to be filled with time diff, or None

Returns

gst::ClockReturn

If the BaseSinkClass.render() method performs its own synchronisation against the clock it must unblock when going from PLAYING to the PAUSED state and call this method before continuing to render the remaining data.

If the BaseSinkClass.render() method can block on something else than the clock, it must also be ready to unblock immediately on the BaseSinkClass.unlock() method and cause the BaseSinkClass.render() method to immediately call this function. In this case, the subclass must be prepared to continue rendering where it left off if this function returns gst::FlowReturn::Ok.

This function will block until a state change to PLAYING happens (in which case this function returns gst::FlowReturn::Ok) or the processing must be stopped due to a state change to READY or a FLUSH event (in which case this function returns gst::FlowReturn::Flushing).

This function should only be called with the PREROLL_LOCK held, like in the render function.

Returns

gst::FlowReturn::Ok if the preroll completed and processing can continue. Any other return value should be returned from the render vmethod.

If set to true, the basesink will perform asynchronous state changes. When set to false, the sink will not signal the parent when it prerolls. Use this option when dealing with sparse streams or when synchronisation is not required.

The amount of bytes to pull when operating in pull mode.

Enable the last-sample property. If false, basesink doesn't keep a reference to the last buffer arrived and the last-sample property is always set to None. This can be useful if you need buffers to be released as soon as possible, eg. if you're using a buffer pool.

The last buffer that arrived in the sink and was used for preroll or for rendering. This property can be used to generate thumbnails. This property can be None when the sink has not yet received a buffer.

Control the maximum amount of bits that will be rendered per second. Setting this property to a value bigger than 0 will make the sink delay rendering of the buffers when it would exceed to max-bitrate.

The additional delay between synchronisation and actual rendering of the media. This property will add additional latency to the device in order to make other sinks compensate for the delay.

The time to insert between buffers. This property can be used to control the maximum amount of buffers per second to render. Setting this property to a value bigger than 0 will make the sink create THROTTLE QoS events.

Controls the final synchronisation, a negative value will render the buffer earlier while a positive value delays playback. This property can be used to fix synchronisation in bad files.

This is a generic base class for source elements. The following types of sources are supported:

random access sources like files
seekable sources
live sources

The source can be configured to operate in any gst::Format with the BaseSrcExt::set_format method. The currently set format determines the format of the internal gst::Segment and any gst::EventType::Segment events. The default format for BaseSrc is gst::Format::Bytes.

BaseSrc always supports push mode scheduling. If the following conditions are met, it also supports pull mode scheduling:

The format is set to gst::Format::Bytes (default).
BaseSrcClass.is_seekable() returns true.

If all the conditions are met for operating in pull mode, BaseSrc is automatically seekable in push mode as well. The following conditions must be met to make the element seekable in push mode when the format is not gst::Format::Bytes:

BaseSrcClass.is_seekable() returns true.
BaseSrcClass.query() can convert all supported seek formats to the internal format as set with BaseSrcExt::set_format.
BaseSrcClass.do_seek() is implemented, performs the seek and returns true.

When the element does not meet the requirements to operate in pull mode, the offset and length in the BaseSrcClass.create() method should be ignored. It is recommended to subclass PushSrc instead, in this situation. If the element can operate in pull mode but only with specific offsets and lengths, it is allowed to generate an error when the wrong values are passed to the BaseSrcClass.create() function.

BaseSrc has support for live sources. Live sources are sources that when paused discard data, such as audio or video capture devices. A typical live source also produces data at a fixed rate and thus provides a clock to publish this rate. Use BaseSrcExt::set_live to activate the live source mode.

A live source does not produce data in the PAUSED state. This means that the BaseSrcClass.create() method will not be called in PAUSED but only in PLAYING. To signal the pipeline that the element will not produce data, the return value from the READY to PAUSED state will be gst::StateChangeReturn::NoPreroll.

A typical live source will timestamp the buffers it creates with the current running time of the pipeline. This is one reason why a live source can only produce data in the PLAYING state, when the clock is actually distributed and running.

Live sources that synchronize and block on the clock (an audio source, for example) can use BaseSrcExt::wait_playing when the BaseSrcClass.create() function was interrupted by a state change to PAUSED.

The BaseSrcClass.get_times() method can be used to implement pseudo-live sources. It only makes sense to implement the BaseSrcClass.get_times() function if the source is a live source. The BaseSrcClass.get_times() function should return timestamps starting from 0, as if it were a non-live source. The base class will make sure that the timestamps are transformed into the current running_time. The base source will then wait for the calculated running_time before pushing out the buffer.

For live sources, the base class will by default report a latency of 0. For pseudo live sources, the base class will by default measure the difference between the first buffer timestamp and the start time of get_times and will report this value as the latency. Subclasses should override the query function when this behaviour is not acceptable.

There is only support in BaseSrc for exactly one source pad, which should be named "src". A source implementation (subclass of BaseSrc) should install a pad template in its class_init function, like so:

static void
my_element_class_init (GstMyElementClass *klass)
{
  GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass);
  // srctemplate should be a #GstStaticPadTemplate with direction
  // %GST_PAD_SRC and name "src"
  gst_element_class_add_static_pad_template (gstelement_class, &amp;srctemplate);

  gst_element_class_set_static_metadata (gstelement_class,
     "Source name",
     "Source",
     "My Source element",
     "The author <my.sink@my.email>");
}

Controlled shutdown of live sources in applications

Applications that record from a live source may want to stop recording in a controlled way, so that the recording is stopped, but the data already in the pipeline is processed to the end (remember that many live sources would go on recording forever otherwise). For that to happen the application needs to make the source stop recording and send an EOS event down the pipeline. The application would then wait for an EOS message posted on the pipeline's bus to know when all data has been processed and the pipeline can safely be stopped.

An application may send an EOS event to a source element to make it perform the EOS logic (send EOS event downstream or post a gst::MessageType::SegmentDone on the bus). This can typically be done with the gst::ElementExt::send_event function on the element or its parent bin.

After the EOS has been sent to the element, the application should wait for an EOS message to be posted on the pipeline's bus. Once this EOS message is received, it may safely shut down the entire pipeline.

Implements

BaseSrcExt, ElementExt, ObjectExt, ObjectExt

Trait containing all BaseSrc methods.

Implementors

BaseSrc, PushSrc

Lets BaseSrc sub-classes to know the memory allocator used by the base class and its params.

Unref the allocator after usage.

`allocator`

the gst::Allocator used

`params`

the gst::AllocationParams of allocator

Get the number of bytes that self will push out with each buffer.

Returns

the number of bytes pushed with each buffer.

Returns

the instance of the gst::BufferPool used by the src; unref it after usage.

Query if self timestamps outgoing buffers based on the current running_time.

Returns

true if the base class will automatically timestamp outgoing buffers.

Get the current async behaviour of self. See also BaseSrcExt::set_async.

Returns

true if self is operating in async mode.

Check if an element is in live mode.

Returns

true if element is in live mode.

Prepare a new seamless segment for emission downstream. This function must only be called by derived sub-classes, and only from the create function, as the stream-lock needs to be held.

The format for the new segment will be the current format of the source, as configured with BaseSrcExt::set_format

`start`

The new start value for the segment

`stop`

Stop value for the new segment

`time`

The new time value for the start of the new segment

Returns

true if preparation of the seamless segment succeeded.

Query the source for the latency parameters. live will be true when self is configured as a live source. min_latency and max_latency will be set to the difference between the running time and the timestamp of the first buffer.

This function is mostly used by subclasses.

`live`

if the source is live

`min_latency`

the min latency of the source

`max_latency`

the max latency of the source

Returns

true if the query succeeded.

Configure async behaviour in self, no state change will block. The open, close, start, stop, play and pause virtual methods will be executed in a different thread and are thus allowed to perform blocking operations. Any blocking operation should be unblocked with the unlock vmethod.

`async`

new async mode

If automatic_eos is true, self will automatically go EOS if a buffer after the total size is returned. By default this is true but sources that can't return an authoritative size and only know that they're EOS when trying to read more should set this to false.

`automatic_eos`

automatic eos

Set the number of bytes that self will push out with each buffer. When blocksize is set to -1, a default length will be used.

`blocksize`

the new blocksize in bytes

Set new caps on the basesrc source pad.

`caps`

a gst::Caps

Returns

true if the caps could be set

Configure self to automatically timestamp outgoing buffers based on the current running_time of the pipeline. This property is mostly useful for live sources.

`timestamp`

enable or disable timestamping

If not dynamic, size is only updated when needed, such as when trying to read past current tracked size. Otherwise, size is checked for upon each read.

`dynamic`

new dynamic size mode

Sets the default format of the source. This will be the format used for sending SEGMENT events and for performing seeks.

If a format of GST_FORMAT_BYTES is set, the element will be able to operate in pull mode if the BaseSrcClass.is_seekable() returns true.

This function must only be called in states < gst::State::Paused.

`format`

the format to use

If the element listens to a live source, live should be set to true.

A live source will not produce data in the PAUSED state and will therefore not be able to participate in the PREROLL phase of a pipeline. To signal this fact to the application and the pipeline, the state change return value of the live source will be GST_STATE_CHANGE_NO_PREROLL.

`live`

new live-mode

Complete an asynchronous start operation. When the subclass overrides the start method, it should call BaseSrcExt::start_complete when the start operation completes either from the same thread or from an asynchronous helper thread.

`ret`

a gst::FlowReturn

Wait until the start operation completes.

Returns

a gst::FlowReturn.

If the BaseSrcClass.create() method performs its own synchronisation against the clock it must unblock when going from PLAYING to the PAUSED state and call this method before continuing to produce the remaining data.

Returns

gst::FlowReturn::Ok if self is PLAYING and processing can continue. Any other return value should be returned from the create vmethod.

This base class is for filter elements that process data. Elements that are suitable for implementation using BaseTransform are ones where the size and caps of the output is known entirely from the input caps and buffer sizes. These include elements that directly transform one buffer into another, modify the contents of a buffer in-place, as well as elements that collate multiple input buffers into one output buffer, or that expand one input buffer into multiple output buffers. See below for more concrete use cases.

It provides for:

one sinkpad and one srcpad
Possible formats on sink and source pad implemented with custom transform_caps function. By default uses same format on sink and source.
Handles state changes
Does flushing
Push mode
Pull mode if the sub-class transform can operate on arbitrary data

Use Cases

Passthrough mode

Element has no interest in modifying the buffer. It may want to inspect it, in which case the element should have a transform_ip function. If there is no transform_ip function in passthrough mode, the buffer is pushed intact.
The BaseTransformClass.passthrough_on_same_caps variable will automatically set/unset passthrough based on whether the element negotiates the same caps on both pads.
BaseTransformClass.passthrough_on_same_caps on an element that doesn't implement a transform_caps function is useful for elements that only inspect data (such as level)
Example elements
Level
Videoscale, audioconvert, videoconvert, audioresample in certain modes.

Modifications in-place - input buffer and output buffer are the same thing.

The element must implement a transform_ip function.
Output buffer size must <= input buffer size
If the always_in_place flag is set, non-writable buffers will be copied and passed to the transform_ip function, otherwise a new buffer will be created and the transform function called.
Incoming writable buffers will be passed to the transform_ip function immediately.
only implementing transform_ip and not transform implies always_in_place = true
Example elements:
Volume
Audioconvert in certain modes (signed/unsigned conversion)
videoconvert in certain modes (endianness swapping)

Modifications only to the caps/metadata of a buffer

The element does not require writable data, but non-writable buffers should be subbuffered so that the meta-information can be replaced.
Elements wishing to operate in this mode should replace the prepare_output_buffer method to create subbuffers of the input buffer and set always_in_place to true
Example elements
Capsfilter when setting caps on outgoing buffers that have none.
identity when it is going to re-timestamp buffers by datarate.

Normal mode

always_in_place flag is not set, or there is no transform_ip function
Element will receive an input buffer and output buffer to operate on.
Output buffer is allocated by calling the prepare_output_buffer function.
Example elements:
Videoscale, videoconvert, audioconvert when doing scaling/conversions

Special output buffer allocations

Elements which need to do special allocation of their output buffers beyond allocating output buffers via the negotiated allocator or buffer pool should implement the prepare_output_buffer method.
Example elements:
efence

Sub-class settable flags on GstBaseTransform

passthrough
Implies that in the current configuration, the sub-class is not interested in modifying the buffers.
Elements which are always in passthrough mode whenever the same caps has been negotiated on both pads can set the class variable passthrough_on_same_caps to have this behaviour automatically.
always_in_place
Determines whether a non-writable buffer will be copied before passing to the transform_ip function.
Implied true if no transform function is implemented.
Implied false if ONLY transform function is implemented.

Implements

BaseTransformExt, ElementExt, ObjectExt, ObjectExt

Trait containing all BaseTransform methods.

Implementors

BaseTransform

Lets BaseTransform sub-classes to know the memory allocator used by the base class and its params.

Unref the allocator after use it.

`allocator`

the gst::Allocator used

`params`

the gst::AllocationParams of allocator

Returns

the instance of the gst::BufferPool used by self; free it after use it

See if self is configured as a in_place transform.

Returns

true is the transform is configured in in_place mode.

MT safe.

See if self is configured as a passthrough transform.

Returns

true is the transform is configured in passthrough mode.

MT safe.

Queries if the transform will handle QoS.

Returns

true if QoS is enabled.

MT safe.

Instructs self to request renegotiation upstream. This function is typically called after properties on the transform were set that influence the input format.

Instructs self to renegotiate a new downstream transform on the next buffer. This function is typically called after properties on the transform were set that influence the output format.

If gap_aware is false (the default), output buffers will have the gst::BufferFlags::Gap flag unset.

If set to true, the element must handle output buffers with this flag set correctly, i.e. it can assume that the buffer contains neutral data but must unset the flag if the output is no neutral data.

MT safe.

`gap_aware`

New state

Determines whether a non-writable buffer will be copied before passing to the transform_ip function.

Always true if no transform function is implemented.
Always false if ONLY transform function is implemented.

MT safe.

`in_place`

Boolean value indicating that we would like to operate on in_place buffers.

Set passthrough mode for this filter by default. This is mostly useful for filters that do not care about negotiation.

Always true for filters which don't implement either a transform or transform_ip method.

MT safe.

`passthrough`

boolean indicating passthrough mode.

If prefer_passthrough is true (the default), self will check and prefer passthrough caps from the list of caps returned by the transform_caps vmethod.

If set to false, the element must order the caps returned from the transform_caps function in such a way that the preferred format is first in the list. This can be interesting for transforms that can do passthrough transforms but prefer to do something else, like a capsfilter.

MT safe.

`prefer_passthrough`

New state

Enable or disable QoS handling in the transform.

MT safe.

`enabled`

new state

Set the QoS parameters in the transform. This function is called internally when a QOS event is received but subclasses can provide custom information when needed.

MT safe.

`proportion`

the proportion

`diff`

the diff against the clock

`timestamp`

the timestamp of the buffer generating the QoS expressed in running_time.

Updates the srcpad caps and send the caps downstream. This function can be used by subclasses when they have already negotiated their caps but found a change in them (or computed new informations). This way, they can notify downstream about that change without loosing any buffer.

`updated_caps`

An updated version of the srcpad caps to be pushed downstream

Returns

true if the caps could be send downstream false otherwise

Utility struct to help handling gst::FlowReturn combination. Useful for gst::Elements that have multiple source pads and need to combine the different gst::FlowReturn for those pads.

FlowCombiner works by using the last gst::FlowReturn for all gst::Pad it has in its list and computes the combined return value and provides it to the caller.

To add a new pad to the FlowCombiner use FlowCombiner::add_pad. The new gst::Pad is stored with a default value of gst::FlowReturn::Ok.

In case you want a gst::Pad to be removed, use FlowCombiner::remove_pad.

Please be aware that this struct isn't thread safe as its designed to be used by demuxers, those usually will have a single thread operating it.

These functions will take refs on the passed gst::Pads.

Aside from reducing the user's code size, the main advantage of using this helper struct is to follow the standard rules for gst::FlowReturn combination. These rules are:

gst::FlowReturn::Eos: only if all returns are EOS too
gst::FlowReturn::NotLinked: only if all returns are NOT_LINKED too
gst::FlowReturn::Error or below: if at least one returns an error return
gst::FlowReturn::NotNegotiated: if at least one returns a not-negotiated return
gst::FlowReturn::Flushing: if at least one returns flushing
gst::FlowReturn::Ok: otherwise

gst::FlowReturn::Error or below, GST_FLOW_NOT_NEGOTIATED and GST_FLOW_FLUSHING are returned immediatelly from the FlowCombiner::update_flow function.

Creates a new FlowCombiner, use FlowCombiner::free to free it.

Returns

A new FlowCombiner

Adds a new gst::Pad to the FlowCombiner.

`pad`

the gst::Pad that is being added

Removes all pads from a FlowCombiner and resets it to its initial state.

Frees a FlowCombiner struct and all its internal data.

Removes a gst::Pad from the FlowCombiner.

`pad`

the gst::Pad to remove

Reset flow combiner and all pads to their initial state without removing pads.

Computes the combined flow return for the pads in it.

The gst::FlowReturn parameter should be the last flow return update for a pad in this FlowCombiner. It will use this value to be able to shortcut some combinations and avoid looking over all pads again. e.g. The last combined return is the same as the latest obtained gst::FlowReturn.

`fret`

the latest gst::FlowReturn received for a pad in this FlowCombiner

Returns

The combined gst::FlowReturn

Sets the provided pad's last flow return to provided value and computes the combined flow return for the pads in it.

`pad`

the gst::Pad whose gst::FlowReturn to update

`fret`

the latest gst::FlowReturn received for a pad in this FlowCombiner

Returns

The combined gst::FlowReturn

This class is mostly useful for elements that cannot do random access, or at least very slowly. The source usually prefers to push out a fixed size buffer.

Subclasses usually operate in a format that is different from the default GST_FORMAT_BYTES format of BaseSrc.

Classes extending this base class will usually be scheduled in a push based mode. If the peer accepts to operate without offsets and within the limits of the allowed block size, this class can operate in getrange based mode automatically. To make this possible, the subclass should implement and override the SCHEDULING query.

The subclass should extend the methods from the baseclass in addition to the ::create method.

Seeking, flushing, scheduling and sync is all handled by this base class.

Implements

BaseSrcExt, ElementExt, ObjectExt, ObjectExt

62 KiB Raw Blame History

Implements

Returns

Returns

Returns

dest

offset

size

offset

size

Returns

Returns

flush

nbytes

Returns

nbytes

Returns

nbytes

Returns

nbytes

Returns

size

Returns

mask

pattern

offset

size

Returns

mask

pattern

offset

size

value

Returns

Returns

distance

Returns

offset

distance

Returns

distance

Returns

distance

Returns

offset

distance

Returns

Returns

buf

nbytes

Returns

nbytes

Returns

nbytes

Returns

nbytes

Returns

nbytes

Returns

Implements

Implementors

obj

Returns

Returns

Returns

Returns

Returns

Returns

Returns

Returns

Returns

Returns

Returns

Returns

Returns

Returns

live

upstream_live

min_latency

max_latency

62 KiB

Raw Blame History

`dest`

`offset`

`size`

`offset`

`size`

`flush`

`nbytes`

`nbytes`

`nbytes`

`nbytes`

`size`

`mask`

`pattern`

`offset`

`size`

`mask`

`pattern`

`offset`

`size`

`value`

`distance`

`offset`

`distance`

`distance`

`distance`

`offset`

`distance`

`buf`

`nbytes`

`nbytes`

`nbytes`

`nbytes`

`nbytes`

`obj`

`live`

`upstream_live`

`min_latency`

`max_latency`

`enabled`

`blocksize`

`drop_out_of_segment`

`enabled`

`max_bitrate`

`max_lateness`

`enabled`

`delay`

`sync`

`throttle`

`offset`

`time`

`jitter`

`time`

`jitter`

`allocator`

`params`

`start`

`stop`

`time`

`live`

`min_latency`

`max_latency`

`async`

`automatic_eos`

`blocksize`

`caps`

`timestamp`

`dynamic`

`format`

`live`

`ret`

`allocator`

`params`

`gap_aware`

`in_place`

`passthrough`

`prefer_passthrough`

`enabled`

`proportion`