mirrors/gstreamer-rs
mirrors/gstreamer-rs
1
1
Fork 1
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer-rs.git synced 2024-12-23 00:26:31 +00:00
Code Issues Projects Releases Wiki Activity

Update documentation

Browse source
This commit is contained in:
Sebastian Dröge 2018-11-26 15:57:25 +01:00
parent 12c3d1e911
commit 7a7984a6c6
6 changed files with 3784 additions and 448 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

181
docs/gstreamer-base/docs.md
View file

@ -546,6 +546,187 @@ a `glib::List` of
bytes are not available
<!-- impl Adapter::fn unmap -->
Releases the memory obtained with the last `Adapter::map`.
<!-- struct Aggregator -->
Manages a set of pads with the purpose of aggregating their buffers.
Control is given to the subclass when all pads have data.
* Base class for mixers and muxers. Subclasses should at least implement
the `AggregatorClass.aggregate`() virtual method.
* Installs a `GstPadChainFunction`, a `GstPadEventFullFunction` and a
`GstPadQueryFunction` to queue all serialized data packets per sink pad.
Subclasses should not overwrite those, but instead implement
`AggregatorClass.sink_event`() and `AggregatorClass.sink_query`() as
needed.
* When data is queued on all pads, the aggregate vmethod is called.
* One can peek at the data on any given GstAggregatorPad with the
gst_aggregator_pad_peek_buffer () method, and remove it from the pad
with the gst_aggregator_pad_pop_buffer () method. When a buffer
has been taken with pop_buffer (), a new buffer can be queued
on that pad.
* If the subclass wishes to push a buffer downstream in its aggregate
implementation, it should do so through the
gst_aggregator_finish_buffer () method. This method will take care
of sending and ordering mandatory events such as stream start, caps
and segment.
* Same goes for EOS events, which should not be pushed directly by the
subclass, it should instead return GST_FLOW_EOS in its aggregate
implementation.
* Note that the aggregator logic regarding gap event handling is to turn
these into gap buffers with matching PTS and duration. It will also
flag these buffers with GST_BUFFER_FLAG_GAP and GST_BUFFER_FLAG_DROPPABLE
to ease their identification and subsequent processing.
* Subclasses must use (a subclass of) `AggregatorPad` for both their
sink and source pads.
See `gst::ElementClass::add_static_pad_template_with_gtype`.
This class used to live in gst-plugins-bad and was moved to core.
Feature: `v1_14`
# Implements
[`AggregatorExt`](trait.AggregatorExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait AggregatorExt -->
Trait containing all `Aggregator` methods.
Feature: `v1_14`
# Implementors
[`Aggregator`](struct.Aggregator.html)
<!-- trait AggregatorExt::fn finish_buffer -->
This method will push the provided output buffer downstream. If needed,
mandatory events such as stream-start, caps, and segment events will be
sent before pushing the buffer.
Feature: `v1_14`
## `buffer`
the `gst::Buffer` to push.
<!-- trait AggregatorExt::fn get_allocator -->
Lets `Aggregator` sub-classes get the memory `allocator`
acquired by the base class and its `params`.
Unref the `allocator` after use it.
Feature: `v1_14`
## `allocator`
the `gst::Allocator`
used
## `params`
the
`gst::AllocationParams` of `allocator`
<!-- trait AggregatorExt::fn get_buffer_pool -->
Feature: `v1_14`
# Returns
the instance of the `gst::BufferPool` used
by `trans`; free it after use it
<!-- trait AggregatorExt::fn get_latency -->
Retrieves the latency values reported by `self` in response to the latency
query, or `GST_CLOCK_TIME_NONE` if there is not live source connected and the element
will not wait for the clock.
Typically only called by subclasses.
Feature: `v1_14`
# Returns
The latency or `GST_CLOCK_TIME_NONE` if the element does not sync
<!-- trait AggregatorExt::fn set_latency -->
Lets `Aggregator` sub-classes tell the baseclass what their internal
latency is. Will also post a LATENCY message on the bus so the pipeline
can reconfigure its global latency.
Feature: `v1_14`
## `min_latency`
minimum latency
## `max_latency`
maximum latency
<!-- trait AggregatorExt::fn set_src_caps -->
Sets the caps to be used on the src pad.
Feature: `v1_14`
## `caps`
The `gst::Caps` to set on the src pad.
<!-- struct AggregatorPad -->
Pads managed by a `GstAggregor` subclass.
This class used to live in gst-plugins-bad and was moved to core.
Feature: `v1_14`
# Implements
[`AggregatorPadExt`](trait.AggregatorPadExt.html), [`gst::PadExt`](../gst/trait.PadExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait AggregatorPadExt -->
Trait containing all `AggregatorPad` methods.
Feature: `v1_14`
# Implementors
[`AggregatorPad`](struct.AggregatorPad.html)
<!-- trait AggregatorPadExt::fn drop_buffer -->
Drop the buffer currently queued in `self`.
Feature: `v1_14`
# Returns
TRUE if there was a buffer queued in `self`, or FALSE if not.
<!-- trait AggregatorPadExt::fn has_buffer -->
Feature: `v1_14_1`
# Returns
`true` if the pad has a buffer available as the next thing.
<!-- trait AggregatorPadExt::fn is_eos -->
Feature: `v1_14`
# Returns
`true` if the pad is EOS, otherwise `false`.
<!-- trait AggregatorPadExt::fn peek_buffer -->
Feature: `v1_14`
# Returns
A reference to the buffer in `self` or
NULL if no buffer was queued. You should unref the buffer after
usage.
<!-- trait AggregatorPadExt::fn pop_buffer -->
Steal the ref to the buffer currently queued in `self`.
Feature: `v1_14`
# Returns
The buffer in `self` or NULL if no buffer was
queued. You should unref the buffer after usage.
<!-- struct BaseSink -->
`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

308
docs/gstreamer-check/docs.md
View file

@ -0,0 +1,308 @@
<!-- file * -->
<!-- struct TestClock -->
GstTestClock is an implementation of `gst::Clock` which has different
behaviour compared to `gst::SystemClock`. Time for `gst::SystemClock` advances
according to the system time, while time for `TestClock` changes only
when `TestClock::set_time` or `TestClock::advance_time` are
called. `TestClock` provides unit tests with the possibility to
precisely advance the time in a deterministic manner, independent of the
system time or any other external factors.
## Advancing the time of a `TestClock`
```C
#include <gst/gst.h>
#include <gst/check/gsttestclock.h>
GstClock *clock;
GstTestClock *test_clock;
clock = gst_test_clock_new ();
test_clock = GST_TEST_CLOCK (clock);
GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock)));
gst_test_clock_advance_time ( test_clock, 1 * GST_SECOND);
GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock)));
g_usleep (10 * G_USEC_PER_SEC);
GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock)));
gst_test_clock_set_time (test_clock, 42 * GST_SECOND);
GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock)));
...
```
`gst::Clock` allows for setting up single shot or periodic clock notifications
as well as waiting for these notifications synchronously (using
`gst::Clock::id_wait`) or asynchronously (using `gst::Clock::id_wait_async` or
`gst::Clock::id_wait_async`). This is used by many GStreamer elements,
among them `GstBaseSrc` and `GstBaseSink`.
`TestClock` keeps track of these clock notifications. By calling
`TestClock::wait_for_next_pending_id` or
`TestClock::wait_for_multiple_pending_ids` a unit tests may wait for the
next one or several clock notifications to be requested. Additionally unit
tests may release blocked waits in a controlled fashion by calling
`TestClock::process_next_clock_id`. This way a unit test can control the
inaccuracy (jitter) of clock notifications, since the test can decide to
release blocked waits when the clock time has advanced exactly to, or past,
the requested clock notification time.
There are also interfaces for determining if a notification belongs to a
`TestClock` or not, as well as getting the number of requested clock
notifications so far.
N.B.: When a unit test waits for a certain amount of clock notifications to
be requested in `TestClock::wait_for_next_pending_id` or
`TestClock::wait_for_multiple_pending_ids` then these functions may block
for a long time. If they block forever then the expected clock notifications
were never requested from `TestClock`, and so the assumptions in the code
of the unit test are wrong. The unit test case runner in gstcheck is
expected to catch these cases either by the default test case timeout or the
one set for the unit test by calling tcase_set_timeout\(\).
The sample code below assumes that the element under test will delay a
buffer pushed on the source pad by some latency until it arrives on the sink
pad. Moreover it is assumed that the element will at some point call
`gst::Clock::id_wait` to synchronously wait for a specific time. The first
buffer sent will arrive exactly on time only delayed by the latency. The
second buffer will arrive a little late (7ms) due to simulated jitter in the
clock notification.
## Demonstration of how to work with clock notifications and `TestClock`
```C
#include <gst/gst.h>
#include <gst/check/gstcheck.h>
#include <gst/check/gsttestclock.h>
GstClockTime latency;
GstElement *element;
GstPad *srcpad;
GstClock *clock;
GstTestClock *test_clock;
GstBuffer buf;
GstClockID pending_id;
GstClockID processed_id;
latency = 42 * GST_MSECOND;
element = create_element (latency, ...);
srcpad = get_source_pad (element);
clock = gst_test_clock_new ();
test_clock = GST_TEST_CLOCK (clock);
gst_element_set_clock (element, clock);
GST_INFO ("Set time, create and push the first buffer\n");
gst_test_clock_set_time (test_clock, 0);
buf = create_test_buffer (gst_clock_get_time (clock), ...);
gst_assert_cmpint (gst_pad_push (srcpad, buf), ==, GST_FLOW_OK);
GST_INFO ("Block until element is waiting for a clock notification\n");
gst_test_clock_wait_for_next_pending_id (test_clock, &pending_id);
GST_INFO ("Advance to the requested time of the clock notification\n");
gst_test_clock_advance_time (test_clock, latency);
GST_INFO ("Release the next blocking wait and make sure it is the one from element\n");
processed_id = gst_test_clock_process_next_clock_id (test_clock);
g_assert (processed_id == pending_id);
g_assert_cmpint (GST_CLOCK_ENTRY_STATUS (processed_id), ==, GST_CLOCK_OK);
gst_clock_id_unref (pending_id);
gst_clock_id_unref (processed_id);
GST_INFO ("Validate that element produced an output buffer and check its timestamp\n");
g_assert_cmpint (get_number_of_output_buffer (...), ==, 1);
buf = get_buffer_pushed_by_element (element, ...);
g_assert_cmpint (GST_BUFFER_TIMESTAMP (buf), ==, latency);
gst_buffer_unref (buf);
GST_INFO ("Check that element does not wait for any clock notification\n");
g_assert (!gst_test_clock_peek_next_pending_id (test_clock, NULL));
GST_INFO ("Set time, create and push the second buffer\n");
gst_test_clock_advance_time (test_clock, 10 * GST_SECOND);
buf = create_test_buffer (gst_clock_get_time (clock), ...);
gst_assert_cmpint (gst_pad_push (srcpad, buf), ==, GST_FLOW_OK);
GST_INFO ("Block until element is waiting for a new clock notification\n");
(gst_test_clock_wait_for_next_pending_id (test_clock, &pending_id);
GST_INFO ("Advance past 7ms beyond the requested time of the clock notification\n");
gst_test_clock_advance_time (test_clock, latency + 7 * GST_MSECOND);
GST_INFO ("Release the next blocking wait and make sure it is the one from element\n");
processed_id = gst_test_clock_process_next_clock_id (test_clock);
g_assert (processed_id == pending_id);
g_assert_cmpint (GST_CLOCK_ENTRY_STATUS (processed_id), ==, GST_CLOCK_OK);
gst_clock_id_unref (pending_id);
gst_clock_id_unref (processed_id);
GST_INFO ("Validate that element produced an output buffer and check its timestamp\n");
g_assert_cmpint (get_number_of_output_buffer (...), ==, 1);
buf = get_buffer_pushed_by_element (element, ...);
g_assert_cmpint (GST_BUFFER_TIMESTAMP (buf), ==,
10 * GST_SECOND + latency + 7 * GST_MSECOND);
gst_buffer_unref (buf);
GST_INFO ("Check that element does not wait for any clock notification\n");
g_assert (!gst_test_clock_peek_next_pending_id (test_clock, NULL));
...
```
Since `TestClock` is only supposed to be used in unit tests it calls
`g_assert`, `g_assert_cmpint` or `g_assert_cmpuint` to validate all function
arguments. This will highlight any issues with the unit test code itself.
# Implements
[`gst::ClockExt`](../gst/trait.ClockExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl TestClock::fn new -->
Creates a new test clock with its time set to zero.
MT safe.
# Returns
a `TestClock` cast to `gst::Clock`.
<!-- impl TestClock::fn new_with_start_time -->
Creates a new test clock with its time set to the specified time.
MT safe.
## `start_time`
a `gst::ClockTime` set to the desired start time of the clock.
# Returns
a `TestClock` cast to `gst::Clock`.
<!-- impl TestClock::fn id_list_get_latest_time -->
Finds the latest time inside the list.
MT safe.
## `pending_list`
List
of of pending `GstClockIDs`
<!-- impl TestClock::fn advance_time -->
Advances the time of the `self` by the amount given by `delta`. The
time of `self` is monotonically increasing, therefore providing a
`delta` which is negative or zero is a programming error.
MT safe.
## `delta`
a positive `gst::ClockTimeDiff` to be added to the time of the clock
<!-- impl TestClock::fn crank -->
A "crank" consists of three steps:
1: Wait for a `gst::ClockID` to be registered with the `TestClock`.
2: Advance the `TestClock` to the time the `gst::ClockID` is waiting for.
3: Release the `gst::ClockID` wait.
A "crank" can be though of as the notion of
manually driving the clock forward to its next logical step.
# Returns
`true` if the crank was successful, `false` otherwise.
MT safe.
<!-- impl TestClock::fn get_next_entry_time -->
Retrieve the requested time for the next pending clock notification.
MT safe.
# Returns
a `gst::ClockTime` set to the time of the next pending clock
notification. If no clock notifications have been requested
`GST_CLOCK_TIME_NONE` will be returned.
<!-- impl TestClock::fn has_id -->
Checks whether `self` was requested to provide the clock notification
given by `id`.
MT safe.
## `id`
a `gst::ClockID` clock notification
# Returns
`true` if the clock has been asked to provide the given clock
notification, `false` otherwise.
<!-- impl TestClock::fn peek_id_count -->
Determine the number of pending clock notifications that have been
requested from the `self`.
MT safe.
# Returns
the number of pending clock notifications.
<!-- impl TestClock::fn peek_next_pending_id -->
Determines if the `pending_id` is the next clock notification scheduled to
be triggered given the current time of the `self`.
MT safe.
## `pending_id`
a `gst::ClockID` clock
notification to look for
# Returns
`true` if `pending_id` is the next clock notification to be
triggered, `false` otherwise.
<!-- impl TestClock::fn process_id_list -->
Processes and releases the pending IDs in the list.
MT safe.
## `pending_list`
List
of pending `GstClockIDs`
<!-- impl TestClock::fn process_next_clock_id -->
MT safe.
# Returns
a `gst::ClockID` containing the next pending clock
notification.
<!-- impl TestClock::fn set_time -->
Sets the time of `self` to the time given by `new_time`. The time of
`self` is monotonically increasing, therefore providing a `new_time`
which is earlier or equal to the time of the clock as given by
`gst::ClockExt::get_time` is a programming error.
MT safe.
## `new_time`
a `gst::ClockTime` later than that returned by `gst::ClockExt::get_time`
<!-- impl TestClock::fn wait_for_multiple_pending_ids -->
Blocks until at least `count` clock notifications have been requested from
`self`. There is no timeout for this wait, see the main description of
`TestClock`.
MT safe.
## `count`
the number of pending clock notifications to wait for
## `pending_list`
Address
of a `glib::List` pointer variable to store the list of pending `GstClockIDs`
that expired, or `None`
<!-- impl TestClock::fn wait_for_next_pending_id -->
Waits until a clock notification is requested from `self`. There is no
timeout for this wait, see the main description of `TestClock`. A reference
to the pending clock notification is stored in `pending_id`.
MT safe.
## `pending_id`
`gst::ClockID`
with information about the pending clock notification
<!-- impl TestClock::fn wait_for_pending_id_count -->
Blocks until at least `count` clock notifications have been requested from
`self`. There is no timeout for this wait, see the main description of
`TestClock`.
# Deprecated
use `TestClock::wait_for_multiple_pending_ids` instead.
## `count`
the number of pending clock notifications to wait for
<!-- trait TestClockExt::fn get_property_start-time -->
When a `TestClock` is constructed it will have a certain start time set.
If the clock was created using `TestClock::new_with_start_time` then
this property contains the value of the `start_time` argument. If
`TestClock::new` was called the clock started at time zero, and thus
this property contains the value 0.
<!-- trait TestClockExt::fn set_property_start-time -->
When a `TestClock` is constructed it will have a certain start time set.
If the clock was created using `TestClock::new_with_start_time` then
this property contains the value of the `start_time` argument. If
`TestClock::new` was called the clock started at time zero, and thus
this property contains the value 0.

2562
docs/gstreamer-editing-services/docs.md
View file

File diff suppressed because it is too large Load diff

1135
docs/gstreamer-pbutils/docs.md
View file

File diff suppressed because it is too large Load diff

38
docs/gstreamer-webrtc/docs.md
View file

@ -1,4 +1,9 @@
<!-- file * -->
<!-- enum WebRTCDTLSSetup -->
GST_WEBRTC_DTLS_SETUP_NONE: none
GST_WEBRTC_DTLS_SETUP_ACTPASS: actpass
GST_WEBRTC_DTLS_SETUP_ACTIVE: sendonly
GST_WEBRTC_DTLS_SETUP_PASSIVE: recvonly
<!-- struct WebRTCDTLSTransport -->
@ -37,6 +42,14 @@ GST_WEBRTC_ICE_ROLE_CONTROLLING: controlling
# Implements
[`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- enum WebRTCPeerConnectionState -->
GST_WEBRTC_PEER_CONNECTION_STATE_NEW: new
GST_WEBRTC_PEER_CONNECTION_STATE_CONNECTING: connecting
GST_WEBRTC_PEER_CONNECTION_STATE_CONNECTED: connected
GST_WEBRTC_PEER_CONNECTION_STATE_DISCONNECTED: disconnected
GST_WEBRTC_PEER_CONNECTION_STATE_FAILED: failed
GST_WEBRTC_PEER_CONNECTION_STATE_CLOSED: closed
See <ulink url="http://w3c.github.io/webrtc-pc/`dom`-rtcpeerconnectionstate">http://w3c.github.io/webrtc-pc/`dom`-rtcpeerconnectionstate`</ulink>`
<!-- struct WebRTCRTPReceiver -->
@ -55,6 +68,7 @@ GST_WEBRTC_ICE_ROLE_CONTROLLING: controlling
# Implements
[`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- enum WebRTCRTPTransceiverDirection -->
<!-- enum WebRTCSDPType -->
GST_WEBRTC_SDP_TYPE_OFFER: offer
GST_WEBRTC_SDP_TYPE_PRANSWER: pranswer
@ -62,7 +76,6 @@ GST_WEBRTC_SDP_TYPE_ANSWER: answer
GST_WEBRTC_SDP_TYPE_ROLLBACK: rollback
See <ulink url="http://w3c.github.io/webrtc-pc/`rtcsdptype`">http://w3c.github.io/webrtc-pc/`rtcsdptype``</ulink>`
<!-- struct WebRTCSessionDescription -->
sdp: the `gst_sdp::SDPMessage` of the description
See <ulink url="https://www.w3.org/TR/webrtc/`rtcsessiondescription`-class">https://www.w3.org/TR/webrtc/`rtcsessiondescription`-class`</ulink>`
<!-- impl WebRTCSessionDescription::fn new -->
## `type_`
@ -81,3 +94,26 @@ a new `WebRTCSessionDescription` from `type_`
a new copy of `self`
<!-- impl WebRTCSessionDescription::fn free -->
Free `self` and all associated resources
<!-- enum WebRTCSignalingState -->
GST_WEBRTC_SIGNALING_STATE_STABLE: stable
GST_WEBRTC_SIGNALING_STATE_CLOSED: closed
GST_WEBRTC_SIGNALING_STATE_HAVE_LOCAL_OFFER: have-local-offer
GST_WEBRTC_SIGNALING_STATE_HAVE_REMOTE_OFFER: have-remote-offer
GST_WEBRTC_SIGNALING_STATE_HAVE_LOCAL_PRANSWER: have-local-pranswer
GST_WEBRTC_SIGNALING_STATE_HAVE_REMOTE_PRANSWER: have-remote-pranswer
See <ulink url="http://w3c.github.io/webrtc-pc/`dom`-rtcsignalingstate">http://w3c.github.io/webrtc-pc/`dom`-rtcsignalingstate`</ulink>`
<!-- enum WebRTCStatsType -->
GST_WEBRTC_STATS_CODEC: codec
GST_WEBRTC_STATS_INBOUND_RTP: inbound-rtp
GST_WEBRTC_STATS_OUTBOUND_RTP: outbound-rtp
GST_WEBRTC_STATS_REMOTE_INBOUND_RTP: remote-inbound-rtp
GST_WEBRTC_STATS_REMOTE_OUTBOUND_RTP: remote-outbound-rtp
GST_WEBRTC_STATS_CSRC: csrc
GST_WEBRTC_STATS_PEER_CONNECTION: peer-connectiion
GST_WEBRTC_STATS_DATA_CHANNEL: data-channel
GST_WEBRTC_STATS_STREAM: stream
GST_WEBRTC_STATS_TRANSPORT: transport
GST_WEBRTC_STATS_CANDIDATE_PAIR: candidate-pair
GST_WEBRTC_STATS_LOCAL_CANDIDATE: local-candidate
GST_WEBRTC_STATS_REMOTE_CANDIDATE: remote-candidate
GST_WEBRTC_STATS_CERTIFICATE: certificate

8
docs/gstreamer/docs.md
View file

@ -693,7 +693,8 @@ Copy `size` bytes starting from `offset` in `self` to `dest`.
## `offset`
the offset to extract
## `dest`
the destination address
the destination address
## `size`
the size to extract
@ -12157,8 +12158,9 @@ outside of the segment is extrapolated.
When 1 is returned, `running_time` resulted in a positive position returned
in `position`.
When this function returns -1, the returned `position` should be negated
to get the real negative segment position.
When this function returns -1, the returned `position` was < 0, and the value
in the position variable should be negated to get the real negative segment
position.
## `format`
the format of the segment.
## `running_time`