From be0075647ae5629dceb8701b30324d38b9eb4241 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Dr=C3=B6ge?= Date: Mon, 24 Jun 2019 20:28:25 +0300 Subject: [PATCH] Update documentation --- docs/gstreamer-app/docs.md | 3 + docs/gstreamer-audio/docs.md | 51 +- docs/gstreamer-base/docs.md | 471 +++++++++++- docs/gstreamer-check/docs.md | 23 +- docs/gstreamer-editing-services/docs.md | 73 +- docs/gstreamer-gl/docs.md | 179 ++++- docs/gstreamer-pbutils/docs.md | 21 +- docs/gstreamer-player/docs.md | 39 +- docs/gstreamer-rtsp-server/docs.md | 399 +++++++++- docs/gstreamer-rtsp/docs.md | 1 + docs/gstreamer-sdp/docs.md | 564 --------------- docs/gstreamer-video/docs.md | 926 +++++++++++++++++++++++- docs/gstreamer/docs.md | 368 ++++++++-- 13 files changed, 2421 insertions(+), 697 deletions(-) diff --git a/docs/gstreamer-app/docs.md b/docs/gstreamer-app/docs.md index d95949c02..17436d4a3 100644 --- a/docs/gstreamer-app/docs.md +++ b/docs/gstreamer-app/docs.md @@ -532,6 +532,9 @@ buffers that the appsrc element will push to its source pad. Any previous caps that were set on appsrc will be replaced by the caps associated with the sample if not equal. +This function does not take ownership of the +sample so the sample needs to be unreffed after calling this function. + When the block property is TRUE, this function can block until free space becomes available in the queue. ## `sample` diff --git a/docs/gstreamer-audio/docs.md b/docs/gstreamer-audio/docs.md index e08580192..ddaff50e0 100644 --- a/docs/gstreamer-audio/docs.md +++ b/docs/gstreamer-audio/docs.md @@ -278,7 +278,7 @@ Feature: `v1_14` Allocate a new `AudioStreamAlign` with the given configuration. All processing happens according to sample rate `rate`, until -`gst_audio_discont_wait_set_rate` is called with a new `rate`. +`AudioStreamAlign::set_rate` is called with a new `rate`. A negative rate can be used for reverse playback. `alignment_threshold` gives the tolerance in nanoseconds after which a @@ -315,6 +315,33 @@ or `AudioStreamAlign::copy`. Feature: `v1_14` + +Gets the currently configured alignment threshold. + +Feature: `v1_14` + + +# Returns + +The currently configured alignment threshold + +Gets the currently configured discont wait. + +Feature: `v1_14` + + +# Returns + +The currently configured discont wait + +Gets the currently configured sample rate. + +Feature: `v1_14` + + +# Returns + +The currently configured sample rate Returns the number of samples that were processed since the last discontinuity was detected. @@ -376,6 +403,28 @@ output sample position of the start of the data # Returns `true` if a discontinuity was detected, `false` otherwise. + +Sets `alignment_treshold` as new alignment threshold for the following processing. + +Feature: `v1_14` + +## `alignment_threshold` +a new alignment threshold + +Sets `alignment_treshold` as new discont wait for the following processing. + +Feature: `v1_14` + +## `discont_wait` +a new discont wait + +Sets `rate` as new sample rate for the following processing. If the sample +rate differs this implicitely marks the next data as discontinuous. + +Feature: `v1_14` + +## `rate` +a new sample rate This interface is implemented by elements that provide a stream volume. Examples for such elements are `volume` and `playbin`. diff --git a/docs/gstreamer-base/docs.md b/docs/gstreamer-base/docs.md index ba6ce92c0..a5ee06a6f 100644 --- a/docs/gstreamer-base/docs.md +++ b/docs/gstreamer-base/docs.md @@ -664,6 +664,38 @@ Feature: `v1_14` ## `caps` The `gst::Caps` to set on the src pad. + +This is a simple `Aggregator::get_next_time` implementation that +just looks at the `gst::Segment` on the srcpad of the aggregator and bases +the next time on the running time there. + +This is the desired behaviour in most cases where you have a live source +and you have a dead line based aggregator subclass. + +Feature: `v1_16` + + +# Returns + +The running time based on the position + +Force minimum upstream latency (in nanoseconds). When sources with a +higher latency are expected to be plugged in dynamically after the +aggregator has started playing, this allows overriding the minimum +latency reported by the initial source(s). This is only taken into +account when larger than the actually reported minimum latency. + +Feature: `v1_16` + + +Force minimum upstream latency (in nanoseconds). When sources with a +higher latency are expected to be plugged in dynamically after the +aggregator has started playing, this allows overriding the minimum +latency reported by the initial source(s). This is only taken into +account when larger than the actually reported minimum latency. + +Feature: `v1_16` + Pads managed by a `GstAggregor` subclass. @@ -692,6 +724,9 @@ Feature: `v1_14` TRUE if there was a buffer queued in `self`, or FALSE if not. +This checks if a pad has a buffer available that will be returned by +a call to `AggregatorPadExt::peek_buffer` or +`AggregatorPadExt::pop_buffer`. Feature: `v1_14_1` @@ -727,6 +762,394 @@ Feature: `v1_14` The buffer in `self` or NULL if no buffer was queued. You should unref the buffer after usage. + +Enables the emission of signals such as `AggregatorPad::buffer-consumed` + +Feature: `v1_16` + + +Enables the emission of signals such as `AggregatorPad::buffer-consumed` + +Feature: `v1_16` + + +This base class is for parser elements that process data and splits it +into separate audio/video/whatever frames. + +It provides for: + + * provides one sink pad and one source pad + * handles state changes + * can operate in pull mode or push mode + * handles seeking in both modes + * handles events (SEGMENT/EOS/FLUSH) + * handles queries (POSITION/DURATION/SEEKING/FORMAT/CONVERT) + * handles flushing + +The purpose of this base class is to provide the basic functionality of +a parser and share a lot of rather complex code. + +# Description of the parsing mechanism: + +## Set-up phase + + * `BaseParse` calls `BaseParseClass.start`() to inform subclass + that data processing is about to start now. + + * `BaseParse` class calls `BaseParseClass.set_sink_caps`() to + inform the subclass about incoming sinkpad caps. Subclass could + already set the srcpad caps accordingly, but this might be delayed + until calling `BaseParse::finish_frame` with a non-queued frame. + + * At least at this point subclass needs to tell the `BaseParse` class + how big data chunks it wants to receive (minimum frame size ). It can + do this with `BaseParseExt::set_min_frame_size`. + + * `BaseParse` class sets up appropriate data passing mode (pull/push) + and starts to process the data. + +## Parsing phase + + * `BaseParse` gathers at least min_frame_size bytes of data either + by pulling it from upstream or collecting buffers in an internal + `Adapter`. + + * A buffer of (at least) min_frame_size bytes is passed to subclass + with `BaseParseClass.handle_frame`(). Subclass checks the contents + and can optionally return `gst::FlowReturn::Ok` along with an amount of data + to be skipped to find a valid frame (which will result in a + subsequent DISCONT). If, otherwise, the buffer does not hold a + complete frame, `BaseParseClass.handle_frame`() can merely return + and will be called again when additional data is available. In push + mode this amounts to an additional input buffer (thus minimal + additional latency), in pull mode this amounts to some arbitrary + reasonable buffer size increase. + + Of course, `BaseParseExt::set_min_frame_size` could also be used if + a very specific known amount of additional data is required. If, + however, the buffer holds a complete valid frame, it can pass the + size of this frame to `BaseParse::finish_frame`. + + If acting as a converter, it can also merely indicate consumed input + data while simultaneously providing custom output data. Note that + baseclass performs some processing (such as tracking overall consumed + data rate versus duration) for each finished frame, but other state + is only updated upon each call to `BaseParseClass.handle_frame`() + (such as tracking upstream input timestamp). + + Subclass is also responsible for setting the buffer metadata + (e.g. buffer timestamp and duration, or keyframe if applicable). + (although the latter can also be done by `BaseParse` if it is + appropriately configured, see below). Frame is provided with + timestamp derived from upstream (as much as generally possible), + duration obtained from configuration (see below), and offset + if meaningful (in pull mode). + + Note that `BaseParseClass.handle_frame`() might receive any small + amount of input data when leftover data is being drained (e.g. at + EOS). + + * As part of finish frame processing, just prior to actually pushing + the buffer in question, it is passed to + `BaseParseClass.pre_push_frame`() which gives subclass yet one last + chance to examine buffer metadata, or to send some custom (tag) + events, or to perform custom (segment) filtering. + + * During the parsing process `BaseParseClass` will handle both srcpad + and sinkpad events. They will be passed to subclass if + `BaseParseClass.event`() or `BaseParseClass.src_event`() + implementations have been provided. + +## Shutdown phase + +* `BaseParse` class calls `BaseParseClass.stop`() to inform the + subclass that data parsing will be stopped. + +Subclass is responsible for providing pad template caps for source and +sink pads. The pads need to be named "sink" and "src". It also needs to +set the fixed caps on srcpad, when the format is ensured (e.g. when +base class calls subclass' `BaseParseClass.set_sink_caps`() function). + +This base class uses `gst::Format::Default` as a meaning of frames. So, +subclass conversion routine needs to know that conversion from +`gst::Format::Time` to `gst::Format::Default` must return the +frame number that can be found from the given byte position. + +`BaseParse` uses subclasses conversion methods also for seeking (or +otherwise uses its own default one, see also below). + +Subclass `start` and `stop` functions will be called to inform the beginning +and end of data processing. + +Things that subclass need to take care of: + +* Provide pad templates +* Fixate the source pad caps when appropriate +* Inform base class how big data chunks should be retrieved. This is + done with `BaseParseExt::set_min_frame_size` function. +* Examine data chunks passed to subclass with + `BaseParseClass.handle_frame`() and pass proper frame(s) to + `BaseParse::finish_frame`, and setting src pad caps and timestamps + on frame. +* Provide conversion functions +* Update the duration information with `BaseParse::set_duration` +* Optionally passthrough using `BaseParseExt::set_passthrough` +* Configure various baseparse parameters using + `BaseParseExt::set_average_bitrate`, `BaseParseExt::set_syncable` + and `BaseParse::set_frame_rate`. + +* In particular, if subclass is unable to determine a duration, but + parsing (or specs) yields a frames per seconds rate, then this can be + provided to `BaseParse` to enable it to cater for buffer time + metadata (which will be taken from upstream as much as + possible). Internally keeping track of frame durations and respective + sizes that have been pushed provides `BaseParse` with an estimated + bitrate. A default `BaseParseClass.convert`() (used if not + overridden) will then use these rates to perform obvious conversions. + These rates are also used to update (estimated) duration at regular + frame intervals. + +# Implements + +[`BaseParseExt`](trait.BaseParseExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) + +Trait containing all `BaseParse` methods. + +# Implementors + +[`BaseParse`](struct.BaseParse.html) + +Adds an entry to the index associating `offset` to `ts`. It is recommended +to only add keyframe entries. `force` allows to bypass checks, such as +whether the stream is (upstream) seekable, another entry is already "close" +to the new entry, etc. +## `offset` +offset of entry +## `ts` +timestamp associated with offset +## `key` +whether entry refers to keyframe +## `force` +add entry disregarding sanity checks + +# Returns + +`gboolean` indicating whether entry was added + +Default implementation of `BaseParseClass.convert`(). +## `src_format` +`gst::Format` describing the source format. +## `src_value` +Source value to be converted. +## `dest_format` +`gst::Format` defining the converted format. +## `dest_value` +Pointer where the conversion result will be put. + +# Returns + +`true` if conversion was successful. + +Drains the adapter until it is empty. It decreases the min_frame_size to +match the current adapter size and calls chain method until the adapter +is emptied or chain returns with error. + +Feature: `v1_12` + + +Collects parsed data and pushes this downstream. +Source pad caps must be set when this is called. + +If `frame`'s out_buffer is set, that will be used as subsequent frame data. +Otherwise, `size` samples will be taken from the input and used for output, +and the output's metadata (timestamps etc) will be taken as (optionally) +set by the subclass on `frame`'s (input) buffer (which is otherwise +ignored for any but the above purpose/information). + +Note that the latter buffer is invalidated by this call, whereas the +caller retains ownership of `frame`. +## `frame` +a `BaseParseFrame` +## `size` +consumed input data represented by frame + +# Returns + +a `gst::FlowReturn` that should be escalated to caller (of caller) + +Sets the parser subclass's tags and how they should be merged with any +upstream stream tags. This will override any tags previously-set +with `BaseParseExt::merge_tags`. + +Note that this is provided for convenience, and the subclass is +not required to use this and can still do tag handling on its own. +## `tags` +a `gst::TagList` to merge, or NULL to unset + previously-set tags +## `mode` +the `gst::TagMergeMode` to use, usually `gst::TagMergeMode::Replace` + +Pushes the frame's buffer downstream, sends any pending events and +does some timestamp and segment handling. Takes ownership of +frame's buffer, though caller retains ownership of `frame`. + +This must be called with sinkpad STREAM_LOCK held. +## `frame` +a `BaseParseFrame` + +# Returns + +`gst::FlowReturn` + +Optionally sets the average bitrate detected in media (if non-zero), +e.g. based on metadata, as it will be posted to the application. + +By default, announced average bitrate is estimated. The average bitrate +is used to estimate the total duration of the stream and to estimate +a seek position, if there's no index and the format is syncable +(see `BaseParseExt::set_syncable`). +## `bitrate` +average bitrate in bits/second + +Sets the duration of the currently playing media. Subclass can use this +when it is able to determine duration and/or notices a change in the media +duration. Alternatively, if `interval` is non-zero (default), then stream +duration is determined based on estimated bitrate, and updated every `interval` +frames. +## `fmt` +`gst::Format`. +## `duration` +duration value. +## `interval` +how often to update the duration estimate based on bitrate, or 0. + +If frames per second is configured, parser can take care of buffer duration +and timestamping. When performing segment clipping, or seeking to a specific +location, a corresponding decoder might need an initial `lead_in` and a +following `lead_out` number of frames to ensure the desired segment is +entirely filled upon decoding. +## `fps_num` +frames per second (numerator). +## `fps_den` +frames per second (denominator). +## `lead_in` +frames needed before a segment for subsequent decode +## `lead_out` +frames needed after a segment + +Set if frames carry timing information which the subclass can (generally) +parse and provide. In particular, intrinsic (rather than estimated) time +can be obtained following a seek. +## `has_timing` +whether frames carry timing information + +By default, the base class might try to infer PTS from DTS and vice +versa. While this is generally correct for audio data, it may not +be otherwise. Sub-classes implementing such formats should disable +timestamp inferring. +## `infer_ts` +`true` if parser should infer DTS/PTS from each other + +Sets the minimum and maximum (which may likely be equal) latency introduced +by the parsing process. If there is such a latency, which depends on the +particular parsing of the format, it typically corresponds to 1 frame duration. +## `min_latency` +minimum parse latency +## `max_latency` +maximum parse latency + +Subclass can use this function to tell the base class that it needs to +be given buffers of at least `min_size` bytes. +## `min_size` +Minimum size in bytes of the data that this base class should + give to subclass. + +Set if the nature of the format or configuration does not allow (much) +parsing, and the parser should operate in passthrough mode (which only +applies when operating in push mode). That is, incoming buffers are +pushed through unmodified, i.e. no `BaseParseClass.handle_frame`() +will be invoked, but `BaseParseClass.pre_push_frame`() will still be +invoked, so subclass can perform as much or as little is appropriate for +passthrough semantics in `BaseParseClass.pre_push_frame`(). +## `passthrough` +`true` if parser should run in passthrough mode + +By default, the base class will guess PTS timestamps using a simple +interpolation (previous timestamp + duration), which is incorrect for +data streams with reordering, where PTS can go backward. Sub-classes +implementing such formats should disable PTS interpolation. +## `pts_interpolate` +`true` if parser should interpolate PTS timestamps + +Set if frame starts can be identified. This is set by default and +determines whether seeking based on bitrate averages +is possible for a format/stream. +## `syncable` +set if frame starts can be identified + +This function should only be called from a `handle_frame` implementation. + +`BaseParse` creates initial timestamps for frames by using the last +timestamp seen in the stream before the frame starts. In certain +cases, the correct timestamps will occur in the stream after the +start of the frame, but before the start of the actual picture data. +This function can be used to set the timestamps based on the offset +into the frame data that the picture starts. +## `offset` +offset into current buffer + +If set to `true`, baseparse will unconditionally force parsing of the +incoming data. This can be required in the rare cases where the incoming +side-data (caps, pts, dts, ...) is not trusted by the user and wants to +force validation and parsing of the incoming data. +If set to `false`, decision of whether to parse the data or not is up to +the implementation (standard behaviour). + +If set to `true`, baseparse will unconditionally force parsing of the +incoming data. This can be required in the rare cases where the incoming +side-data (caps, pts, dts, ...) is not trusted by the user and wants to +force validation and parsing of the incoming data. +If set to `false`, decision of whether to parse the data or not is up to +the implementation (standard behaviour). + +Frame (context) data passed to each frame parsing virtual methods. In +addition to providing the data to be checked for a valid frame or an already +identified frame, it conveys additional metadata or control information +from and to the subclass w.r.t. the particular frame in question (rather +than global parameters). Some of these may apply to each parsing stage, others +only to some a particular one. These parameters are effectively zeroed at start +of each frame's processing, i.e. parsing virtual method invocation sequence. + +Allocates a new `BaseParseFrame`. This function is mainly for bindings, +elements written in C should usually allocate the frame on the stack and +then use `BaseParseFrame::init` to initialise it. +## `buffer` +a `gst::Buffer` +## `flags` +the flags +## `overhead` +number of bytes in this frame which should be counted as + metadata overhead, ie. not used to calculate the average bitrate. + Set to -1 to mark the entire frame as metadata. If in doubt, set to 0. + +# Returns + +a newly-allocated `BaseParseFrame`. Free with + `BaseParseFrame::free` when no longer needed. + +Copies a `BaseParseFrame`. + +# Returns + +A copy of `self` + +Frees the provided `self`. + +Sets a `BaseParseFrame` to initial state. Currently this means +all public fields are zero-ed and a private flag is set to make +sure `BaseParseFrame::free` only frees the contents but not +the actual frame. Use this function to initialise a `BaseParseFrame` +allocated on the stack. `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 @@ -918,6 +1341,17 @@ more details. 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 processing deadline of `self`. see +`BaseSinkExt::set_processing_deadline` for more information about +the processing deadline. + +Feature: `v1_16` + + +# Returns + +the processing deadline Get the render delay of `self`. see `BaseSinkExt::set_render_delay` for more information about the render delay. @@ -1025,6 +1459,17 @@ buffer timestamp and the current clock time. A value of -1 means an unlimited time. ## `max_lateness` the new max lateness value. + +Maximum amount of time (in nanoseconds) that the pipeline can take +for processing the buffer. This is added to the latency of live +pipelines. + +This function is usually called by subclasses. + +Feature: `v1_16` + +## `processing_deadline` +the new processing deadline in nanoseconds. Configures `self` to send Quality-of-Service events upstream. ## `enabled` @@ -1166,6 +1611,20 @@ rendering of the buffers when it would exceed to max-bitrate. 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. + +Maximum amount of time (in nanoseconds) that the pipeline can take +for processing the buffer. This is added to the latency of live +pipelines. + +Feature: `v1_16` + + +Maximum amount of time (in nanoseconds) that the pipeline can take +for processing the buffer. This is added to the latency of live +pipelines. + +Feature: `v1_16` + The additional delay between synchronisation and actual rendering of the media. This property will add additional latency to the device in order to @@ -1401,6 +1860,12 @@ 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`. + +When `self` operates in `gst::Format::Time`, `BaseSrc` will send an EOS +when a buffer outside of the currently configured segment is pushed if +`automatic_eos` is `true`. Since 1.16, if `automatic_eos` is `false` an +EOS will be pushed only when the `BaseSrc.create` implementation +returns `gst::FlowReturn::Eos`. ## `automatic_eos` automatic eos @@ -1730,8 +2195,8 @@ 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 +but found a change in them (or computed new information). This way, +they can notify downstream about that change without losing any buffer. ## `updated_caps` An updated version of the srcpad caps to be pushed @@ -1771,7 +2236,7 @@ These rules are: * `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. +returned immediately from the `FlowCombiner::update_flow` function. Creates a new `FlowCombiner`, use `FlowCombiner::free` to free it. diff --git a/docs/gstreamer-check/docs.md b/docs/gstreamer-check/docs.md index ef6a68027..9583a1467 100644 --- a/docs/gstreamer-check/docs.md +++ b/docs/gstreamer-check/docs.md @@ -876,7 +876,7 @@ a `guint` describing how many seconds to wait for `waits` to be true # Returns a `gboolean` `true` if the waits have been registered, `false` if not. -(Could be that it timed out waiting or that more waits then waits was found) +(Could be that it timed out waiting or that more waits than waits was found) Creates a new harness. Works like `Harness::new_with_padnames`, except it assumes the `gst::Element` sinkpad is named "sink" and srcpad is named "src" @@ -1266,6 +1266,27 @@ which is earlier or equal to the time of the clock as given by MT safe. ## `new_time` a `gst::ClockTime` later than that returned by `gst::ClockExt::get_time` + +Blocks until at least `count` clock notifications have been requested from +`self`, or the timeout expires. + +MT safe. + +Feature: `v1_16` + +## `count` +the number of pending clock notifications to wait for +## `timeout_ms` +the timeout in milliseconds +## `pending_list` +Address + of a `glib::List` pointer variable to store the list of pending `GstClockIDs` + that expired, or `None` + +# Returns + +a `gboolean` `true` if the waits have been registered, `false` if not. +(Could be that it timed out waiting or that more waits than waits was found) Blocks until at least `count` clock notifications have been requested from `self`. There is no timeout for this wait, see the main description of diff --git a/docs/gstreamer-editing-services/docs.md b/docs/gstreamer-editing-services/docs.md index 32e1c2958..db9160af0 100644 --- a/docs/gstreamer-editing-services/docs.md +++ b/docs/gstreamer-editing-services/docs.md @@ -105,6 +105,14 @@ The Identifier or `None` A reference to the wanted `Asset` or `None` +The `callback` will be called from a running `glib::MainLoop` which is iterating a `glib::MainContext`. +Note that, users should ensure the `glib::MainContext`, since this method will notify +`callback` from the thread which was associated with a thread default +`glib::MainContext` at calling `ges_init`. +For example, if a user wants non-default `glib::MainContext` to be associated +with `callback`, `ges_init` must be called after g_main_context_push_thread_default () +with custom `glib::MainContext`. + Request a new `Asset` asyncronously, `callback` will be called when the materail is ready to be used or if an error occured. @@ -1163,7 +1171,7 @@ Informs you that a `Asset` could not be created. In case of missing GStreamer plugins, the error will be set to `GST_CORE_ERROR` `gst::CoreError::MissingPlugin` ## `error` -The `glib::Error` defining the error that accured, might be `None` +The `glib::Error` defining the error that occured, might be `None` ## `id` The `id` of the asset that failed loading ## `extractable_type` @@ -1515,6 +1523,22 @@ The `TrackElement` for which to choose the tracks it should land into # Returns a `glib::PtrArray` of `Track`-s where that object should be added + +Will be emitted when the 2 `TrackElement` ended to snap +## `obj1` +the first `TrackElement` that was snapping. +## `obj2` +the second `TrackElement` that was snapping. +## `position` +the position where the two objects finally snapping. + +Will be emitted when the 2 `TrackElement` first snapped +## `obj1` +the first `TrackElement` that was snapping. +## `obj2` +the second `TrackElement` that was snapping. +## `position` +the position where the two objects finally snapping. Will be emitted after the track was added to the timeline. ## `track` @@ -1606,6 +1630,13 @@ The `duration` of `self` # Returns The `inpoint` of `self` + + +# Returns + +The priority of the first layer the element is in (note that only +groups can span over several layers). `GES_TIMELINE_ELEMENT_NO_LAYER_PRIORITY` +means that the element is not in a layer. # Returns @@ -1787,15 +1818,27 @@ Note that if the timeline snap-distance property of the timeline containing `self` is set, `self` will properly snap to its neighboors. ## `duration` the duration in `gst::ClockTime` + +# Returns + +`true` if `duration` could be set. Set the in-point, that is the moment at which the `self` will start outputting data from its contents. ## `inpoint` the in-point in `gst::ClockTime` + +# Returns + +`true` if `inpoint` could be set. Set the maximun duration of the object ## `maxduration` the maximum duration in `gst::ClockTime` + +# Returns + +`true` if `maxduration` could be set. Sets the name of object, or gives `self` a guaranteed unique name (if name is NULL). This function makes a copy of the provided name, so the caller retains ownership @@ -1822,6 +1865,10 @@ To set `Effect` priorities `ClipExt::set_top_effect_index` should be used. ## `priority` the priority + +# Returns + +`true` if `priority` could be set. Set the position of the object in its containing layer. @@ -1829,6 +1876,10 @@ Note that if the snapping-distance property of the timeline containing `self` is set, `self` will properly snap to the edges around `start`. ## `start` the position in `gst::ClockTime` + +# Returns + +`true` if `start` could be set. Sets the timeline of `self` to `timeline`. ## `timeline` @@ -2358,7 +2409,9 @@ the `gst::ControlSource` to set on the binding. ## `property_name` The name of the property to control. ## `binding_type` -The type of binding to create. Only "direct" is available for now. +The type of binding to create. Currently the following values are valid: + - "direct": See `gst_direct_control_binding_new` + - "direct-absolute": See `gst_direct_control_binding_new_absolute` # Returns @@ -2446,7 +2499,7 @@ The location of the file/resource to use. The `UriClipAsset` is a special `Asset` that lets you handle the media file to use inside the GStreamer Editing Services. It has APIs that let you get information about the medias. Also, the tags found in the media file are -set as Metadatas of the Asser. +set as Metadata of the Asset. # Implements @@ -2457,6 +2510,14 @@ Trait containing all `UriClipAsset` methods. # Implementors [`UriClipAsset`](struct.UriClipAsset.html) + +Finalize the request of an async `UriClipAsset` +## `res` +The `gio::AsyncResult` from which to get the newly created `UriClipAsset` + +# Returns + +The `UriClipAsset` previously requested Creates a `UriClipAsset` for `uri` @@ -2470,7 +2531,7 @@ filesource_asset_loaded_cb (GESAsset * source, GAsyncResult * res, gpointer user GError *error = NULL; GESUriClipAsset *filesource_asset; - filesource_asset = GES_URI_CLIP_ASSET (ges_asset_request_finish (res, &error)); + filesource_asset = ges_uri_clip_asset_finish (res, &error); if (filesource_asset) { g_print ("The file: %s is usable as a FileSource, it is%s an image and lasts %" GST_TIME_FORMAT, ges_asset_get_id (GES_ASSET (filesource_asset)) @@ -2504,8 +2565,8 @@ You can also use multi file uris for `MultiFileSource`. # Returns -A reference to the requested asset or -`None` if an error happened +A reference to the requested asset or `None` if +an error happened Gets duration of the file represented by `self` diff --git a/docs/gstreamer-gl/docs.md b/docs/gstreamer-gl/docs.md index 368f1dd5f..19f815c33 100644 --- a/docs/gstreamer-gl/docs.md +++ b/docs/gstreamer-gl/docs.md @@ -5,15 +5,27 @@ context. It also provided some wrappers around `gst_base::BaseTransform`'s `start`, `stop` and `set_caps` virtual methods that ensure an OpenGL context is available and current in the calling thread. +Feature: `v1_16` + # Implements [`GLBaseFilterExt`](trait.GLBaseFilterExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `GLBaseFilter` methods. +Feature: `v1_16` + # Implementors [`GLBaseFilter`](struct.GLBaseFilter.html) + + +Feature: `v1_16` + + +# Returns + +Whether an OpenGL context could be retrieved or created successfully GstGLBuffer is a `gst::Memory` subclass providing support for the mapping of GL buffers. @@ -44,7 +56,7 @@ a `GLContext` a new `GLColorConvert` object -Provides an implementation of `gst_base::BaseTransformClass::fixate_caps`() +Provides an implementation of `gst_base::BaseTransformClass.fixate_caps`() ## `context` a `GLContext` to use for transforming `caps` ## `direction` @@ -58,7 +70,7 @@ the `gst::Caps` to fixate the fixated `gst::Caps` -Provides an implementation of `gst_base::BaseTransformClass::transform_caps`() +Provides an implementation of `gst_base::BaseTransformClass.transform_caps`() ## `context` a `GLContext` to use for transforming `caps` ## `direction` @@ -72,7 +84,7 @@ a set of filter `gst::Caps` the converted `gst::Caps` -Provides an implementation of `GstBaseTransfromClass::decide_allocation`() +Provides an implementation of `gst_base::BaseTransformClass.decide_allocation`() ## `query` a completed ALLOCATION `gst::Query` @@ -299,7 +311,7 @@ Gets the OpenGL platform that used by `self`. The platform specific backing OpenGL context Get the version of the OpenGL platform (GLX, EGL, etc) used. Only valid -after a call to `gst_gl_context_create_context`. +after a call to `GLContextExt::create`. ## `major` return for the major version ## `minor` @@ -377,6 +389,30 @@ a `GLSLProfile` # Returns Whether `self` supports the combination of `version` with `profile` + + +Feature: `v1_16` + +## `version` +a `GLSLVersion` +## `profile` +a `GLSLProfile` + +# Returns + +whether `self` supports the 'precision' specifier in GLSL shaders + + +Feature: `v1_16` + +## `version` +a `GLSLVersion` +## `profile` +a `GLSLProfile` + +# Returns + +whether `self` supports the 'precision highp' specifier in GLSL shaders Swap the front and back buffers on the window attached to `self`. This will display the frame on the next refresh cycle. @@ -432,7 +468,7 @@ Trait containing all `GLDisplay` methods. # Implementors -[`GLDisplayEGL`](struct.GLDisplayEGL.html), [`GLDisplay`](struct.GLDisplay.html) +[`GLDisplayEGL`](struct.GLDisplayEGL.html), [`GLDisplayWayland`](struct.GLDisplayWayland.html), [`GLDisplayX11`](struct.GLDisplayX11.html), [`GLDisplay`](struct.GLDisplay.html) # Returns @@ -551,6 +587,54 @@ pointer to a display (or 0) # Returns A `EGLDisplay` or `EGL_NO_DISPLAY` + +the contents of a `GLDisplayWayland` are private and should only be accessed +through the provided API + +# Implements + +[`GLDisplayExt`](trait.GLDisplayExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) + +Create a new `GLDisplayWayland` from the wayland display name. See `wl_display_connect` +for details on what is a valid name. +## `name` +a display name + +# Returns + +a new `GLDisplayWayland` or `None` + +Creates a new display connection from a wl_display Display. +## `display` +an existing, wayland display + +# Returns + +a new `GLDisplayWayland` + +the contents of a `GLDisplayX11` are private and should only be accessed +through the provided API + +# Implements + +[`GLDisplayExt`](trait.GLDisplayExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) + +Create a new `GLDisplayX11` from the x11 display name. See XOpenDisplay() +for details on what is a valid name. +## `name` +a display name + +# Returns + +a new `GLDisplayX11` or `None` + +Creates a new display connection from a X11 Display. +## `display` +an existing, x11 display + +# Returns + +a new `GLDisplayX11` Single component replicated across R, G, and B textures @@ -575,12 +659,18 @@ Three 8-bit components stored in the R, G, and B Three components of bit depth 5, 6 and 5 stored in the R, G, and B texture components respectively. + +Three 16-bit components stored in the R, G, and B + texture components Four components stored in the R, G, B, and A texture components respectively. Four 8-bit components stored in the R, G, B, and A texture components respectively. + +Four 16-bit components stored in the R, G, B, and A texture + components respectively. A single 16-bit component for depth information. @@ -895,6 +985,58 @@ a `glib::Error` # Returns a new `shader` with the specified stages. + + +Feature: `v1_16` + +## `context` +a `GLContext` +## `version` +a `GLSLVersion` +## `profile` +a `GLSLProfile` + +# Returns + +a passthrough shader string for copying an input external-oes + texture to the output + + +Feature: `v1_16` + +## `context` +a `GLContext` +## `version` +a `GLSLVersion` +## `profile` +a `GLSLProfile` + +# Returns + +a passthrough shader string for copying an input texture to + the output + +Generates a shader string that defines the precision of float types in +GLSL shaders. This is particularly needed for fragment shaders in a +GLSL ES context where there is no default precision specified. + +Practically, this will return the string 'precision mediump float' +or 'precision highp float' depending on if high precision floats are +determined to be supported. + +Feature: `v1_16` + +## `context` +a `GLContext` +## `version` +a `GLSLVersion` +## `profile` +a `GLSLProfile` + +# Returns + +a shader string defining the precision of float types based on + `context`, `version` and `profile` Attaches `stage` to `self`. `stage` must have been successfully compiled with `GLSLStage::compile`. @@ -1221,6 +1363,12 @@ Mark's `self` as being used for the next GL draw command. Note: must be called in the GL thread and `self` must have been linked. Output anaglyph type to generate when downmixing to mono + +Dubois optimised Green-Magenta anaglyph + +Dubois optimised Red-Cyan anaglyph + +Dubois optimised Amber-Blue anaglyph no texture target @@ -1298,7 +1446,7 @@ Convert stereoscopic/multiview video using fragment shaders. a new `GLViewConvert` -Provides an implementation of `gst_base::BaseTransformClass::fixate_caps`() +Provides an implementation of `gst_base::BaseTransformClass.fixate_caps`() ## `direction` a `gst::PadDirection` ## `caps` @@ -1350,7 +1498,7 @@ a `gst::Buffer` a `gst::FlowReturn` -Provides an implementation of `gst_base::BaseTransformClass::transform_caps`() +Provides an implementation of `gst_base::BaseTransformClass.transform_caps`() ## `direction` a `gst::PadDirection` ## `caps` @@ -1381,6 +1529,15 @@ a `GLDisplay` # Returns a new `GLWindow` using `display`'s connection + +Checks if `self` controls the GL viewport. + +Feature: `v1_16` + + +# Returns + +`true` if `self` controls the GL viewport, otherwise `false` Redraw the window contents. Implementations should invoke the draw callback. @@ -1411,8 +1568,16 @@ for them. This method allows you to disable events handling completely from the `self`. ## `handle_events` a `gboolean` indicating if events should be handled or not. + +Queue resizing of `self`. Quit the runloop's execution. + +Resize `self` to the given `width` and `height`. +## `width` +new width +## `height` +new height Start the execution of the runloop. diff --git a/docs/gstreamer-pbutils/docs.md b/docs/gstreamer-pbutils/docs.md index 6cda12fb7..50bdc1251 100644 --- a/docs/gstreamer-pbutils/docs.md +++ b/docs/gstreamer-pbutils/docs.md @@ -522,13 +522,7 @@ Encoding profiles for containers. Keeps track of a list of `EncodingProfile` # Implements -[`EncodingContainerProfileExt`](trait.EncodingContainerProfileExt.html), [`EncodingProfileExt`](trait.EncodingProfileExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) - -Trait containing all `EncodingContainerProfile` methods. - -# Implementors - -[`EncodingContainerProfile`](struct.EncodingContainerProfile.html) +[`EncodingProfileExt`](trait.EncodingProfileExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates a new `EncodingContainerProfile`. ## `name` @@ -544,7 +538,7 @@ The preset to use for this profile. # Returns The newly created `EncodingContainerProfile`. - + Add a `EncodingProfile` to the list of profiles handled by `self`. No copy of `profile` will be made, if you wish to use it elsewhere after this @@ -555,7 +549,7 @@ the `EncodingProfile` to add. # Returns `true` if the `stream` was properly added, else `false`. - + Checks if `self` contains a `EncodingProfile` identical to `profile`. ## `profile` @@ -565,7 +559,7 @@ a `EncodingProfile` `true` if `self` contains a `EncodingProfile` identical to `profile`, else `false`. - + # Returns @@ -610,11 +604,12 @@ The new `EncodingProfile` or `None`. Makes a deep copy of `self` +Feature: `v1_12` + + # Returns The copy of `self` - -Since 1.12 Get whether the format that has been negotiated in at some point can be renegotiated later during the encoding. @@ -699,8 +694,6 @@ Set `description` as the given description for the `self`. A copy of the description to set on the profile Set whether the profile should be used or not. - -Since 1.6 ## `enabled` `false` to disable `profile`, `true` to enable it diff --git a/docs/gstreamer-player/docs.md b/docs/gstreamer-player/docs.md index a3d723109..78ff84f0d 100644 --- a/docs/gstreamer-player/docs.md +++ b/docs/gstreamer-player/docs.md @@ -28,8 +28,6 @@ a `Player` configuration # Returns current position update interval in milliseconds - -Since 1.10 ## `config` a `Player` configuration @@ -37,8 +35,6 @@ a `Player` configuration # Returns `true` if accurate seeking is enabled - -Since 1.12 Return the user agent which has been configured using `Player::config_set_user_agent` if any. @@ -48,11 +44,9 @@ a `Player` configuration # Returns the configured agent, or `None` -Since 1.10 set interval in milliseconds between two position-updated signals. pass 0 to stop updating the position. -Since 1.10 ## `config` a `Player` configuration ## `interval` @@ -75,8 +69,6 @@ accurate seek or not Set the user agent to pass to the server if `player` needs to connect to a server during playback. This is typically used when playing HTTP or RTSP streams. - -Since 1.10 ## `config` a `Player` configuration ## `agent` @@ -123,8 +115,6 @@ Retrieve the current value of audio-video-offset property # Returns The current value of audio-video-offset in nanoseconds - -Since 1.10 Retrieve the current value of the indicated `type_`. ## `type_` @@ -143,8 +133,6 @@ or it must be freed after usage. a copy of the current configuration of `self`. Use `gst::Structure::free` after usage or `Player::set_config`. - -Since 1.10 A Function to get current audio `PlayerAudioInfo` instance. @@ -230,6 +218,15 @@ current subtitle URI URI of the current external subtitle. `g_free` after usage. + +Retrieve the current value of subtitle-video-offset property + +Feature: `v1_16` + + +# Returns + +The current value of subtitle-video-offset in nanoseconds Gets the URI of the currently-playing stream. @@ -252,8 +249,6 @@ Additional configuration # Returns Current video snapshot sample or `None` on failure - -Since 1.12 Returns the current volume level, as a percentage between 0 and 1. @@ -291,8 +286,6 @@ Enable or disable the current audio track. TRUE or FALSE Sets audio-video-offset property by value of `offset` - -Since 1.10 ## `offset` `gint64` in nanoseconds @@ -318,7 +311,6 @@ a `gst::Structure` # Returns `true` when the configuration could be set. -Since 1.10 Sets the current value of the indicated mode `type_` to the passed value. @@ -356,6 +348,13 @@ gst_player_set_subtitle_track_enabled(`self`, TRUE) so the subtitles are actuall rendered. ## `uri` subtitle URI + +Sets subtitle-video-offset property by value of `offset` + +Feature: `v1_16` + +## `offset` +`gint64` in nanoseconds Sets the next URI to play. ## `uri` @@ -672,12 +671,6 @@ Window handle to use or `None` Window handle to use or `None` ## `video_sink` the custom video_sink element to be set for the video renderer - -# Returns - - - -Since 1.12 Tell an overlay that it has been exposed. This will redraw the current frame in the drawable even if the pipeline is PAUSED. diff --git a/docs/gstreamer-rtsp-server/docs.md b/docs/gstreamer-rtsp-server/docs.md index adee7f8c5..5022fa44f 100644 --- a/docs/gstreamer-rtsp-server/docs.md +++ b/docs/gstreamer-rtsp-server/docs.md @@ -177,6 +177,14 @@ users. the `RTSPToken` of `self`. `gst_rtsp_token_unref` after usage. + + +Feature: `v1_16` + + +# Returns + +the `realm` of `self` Gets the supported authentication methods of `self`. @@ -206,6 +214,24 @@ Get the `gio::TlsDatabase` used for verifying client certificate. the `gio::TlsDatabase` of `self`. `gobject::ObjectExt::unref` after usage. + +Parse the contents of the file at `path` and enable the privileges +listed in `token` for the users it describes. + +The format of the file is expected to match the format described by +, +as output by the `htdigest` command. + +Feature: `v1_16` + +## `path` +Path to the htdigest file +## `token` +authorisation token + +# Returns + +`true` if the file was successfully parsed, `false` otherwise. Removes `basic` authentication token. ## `basic` @@ -222,6 +248,11 @@ Set the default `RTSPToken` to `token` in `self`. The default token will be used for unauthenticated users. ## `token` a `RTSPToken` + +Set the `realm` of `self` + +Feature: `v1_16` + Sets the supported authentication `methods` for `self`. @@ -244,8 +275,6 @@ a `gio::TlsCertificate` Sets the certificate database that is used to verify peer certificates. If set to `None` (the default), then peer certificate validation will always set the `gio::TlsCertificateFlags::UnknownCa` error. - -Since 1.6 ## `database` a `gio::TlsDatabase` @@ -397,12 +426,34 @@ sent to the client. `user_data` is passed to `func` and `notify` is called when By default, the client will send the messages on the `gst_rtsp::RTSPConnection` that was configured with `RTSPClient::attach` was called. + +It is only allowed to set either a `send_func` or a `send_messages_func` +but not both at the same time. ## `func` a `GstRTSPClientSendFunc` ## `user_data` user data passed to `func` ## `notify` called when `user_data` is no longer in use + +Set `func` as the callback that will be called when new messages needs to be +sent to the client. `user_data` is passed to `func` and `notify` is called when +`user_data` is no longer in use. + +By default, the client will send the messages on the `gst_rtsp::RTSPConnection` that +was configured with `RTSPClient::attach` was called. + +It is only allowed to set either a `send_func` or a `send_messages_func` +but not both at the same time. + +Feature: `v1_16` + +## `func` +a `GstRTSPClientSendMessagesFunc` +## `user_data` +user data passed to `func` +## `notify` +called when `user_data` is no longer in use Set `pool` as the sessionpool for `self` which it will use to find or allocate sessions. the sessionpool is usually inherited from the server @@ -587,6 +638,14 @@ current thread that is handling the request for a client. # Returns a `RTSPContext` + +Possible return values for `RTSPSessionPoolExt::filter`. + +Remove session + +Keep session in the pool + +Ref session in the result list A class that contains the GStreamer element along with a list of `RTSPStream` objects that can produce data. @@ -627,6 +686,9 @@ element of `self`, and create `GstRTSPStreams` for them. Add a receiver and sender parts to the pipeline based on the transport from SETUP. + +Feature: `v1_14` + ## `transports` a list of `gst_rtsp::RTSPTransport` @@ -684,6 +746,14 @@ Get the clock that is used by the pipeline in `self`. # Returns the `gst::Clock` used by `self`. unref after usage. + + +Feature: `v1_16` + + +# Returns + +Whether retransmission requests will be sent Get the element that was used when constructing `self`. @@ -696,6 +766,15 @@ Get the latency that is used for receiving media. # Returns latency in milliseconds + +Get the the maximum time-to-live value of outgoing multicast packets. + +Feature: `v1_16` + + +# Returns + +the maximum time-to-live value of outgoing multicast packets. Get the multicast interface used for `self`. @@ -791,6 +870,15 @@ a `gst_sdp::SDPMessage` # Returns TRUE on success. + +Check if multicast sockets are configured to be bound to multicast addresses. + +Feature: `v1_16` + + +# Returns + +`true` if multicast sockets are configured to be bound to multicast addresses. Check if the pipeline for `self` will send an EOS down the pipeline before unpreparing. @@ -857,7 +945,11 @@ a `gst_rtsp::RTSPTimeRange` `true` on success. Seek the pipeline of `self` to `range`. `self` must be prepared with -`RTSPMediaExt::prepare`. +`RTSPMediaExt::prepare`. In order to perform the seek operation, +the pipeline must contain all needed transport parts (transport sinks). + +Feature: `v1_14` + ## `range` a `gst_rtsp::RTSPTimeRange` ## `flags` @@ -866,10 +958,30 @@ The minimal set of `gst::SeekFlags` to use # Returns `true` on success. + +Check if the pipeline for `self` seek and up to what point in time, +it can seek. + +Feature: `v1_14` + + +# Returns + +-1 if the stream is not seekable, 0 if seekable only to the beginning +and > 0 to indicate the longest duration between any two random access points. +`G_MAXINT64` means any value is possible. configure `pool` to be used as the address pool of `self`. ## `pool` a `RTSPAddressPool` + +Decide whether the multicast socket should be bound to a multicast address or +INADDR_ANY. + +Feature: `v1_16` + +## `bind_mcast_addr` +the new value Set the kernel UDP buffer size. ## `size` @@ -878,6 +990,11 @@ the new value Configure the clock used for the media. ## `clock` `gst::Clock` to be used + +Set whether retransmission requests will be sent + +Feature: `v1_16` + Set or unset if an EOS event will be sent to the pipeline for `self` before it is unprepared. @@ -887,6 +1004,17 @@ the new value Configure the latency used for receiving media. ## `latency` latency in milliseconds + +Set the maximum time-to-live value of outgoing multicast packets. + +Feature: `v1_16` + +## `ttl` +the new multicast ttl value + +# Returns + +`true` if the requested ttl has been set successfully. configure `multicast_iface` to be used for `self`. ## `multicast_iface` @@ -1083,6 +1211,14 @@ of all medias created from this factory. # Returns The GstClock + + +Feature: `v1_16` + + +# Returns + +Whether retransmission requests will be sent for receiving media Get the latency that is used for receiving media @@ -1097,6 +1233,15 @@ default prepare vmethod. the configured launch description. `g_free` after usage. + +Get the the maximum time-to-live value of outgoing multicast packets. + +Feature: `v1_16` + + +# Returns + +the maximum time-to-live value of outgoing multicast packets. Return the GType of the GstRTSPMedia subclass this factory will create. @@ -1150,6 +1295,15 @@ methods. # Returns The transport mode. + +Check if multicast sockets are configured to be bound to multicast addresses. + +Feature: `v1_16` + + +# Returns + +`true` if multicast sockets are configured to be bound to multicast addresses. Get if media created from this factory will have an EOS event sent to the pipeline before shutdown. @@ -1167,6 +1321,14 @@ Get if media created from this factory can be shared between clients. configure `pool` to be used as the address pool of `self`. ## `pool` a `RTSPAddressPool` + +Decide whether the multicast socket should be bound to a multicast address or +INADDR_ANY. + +Feature: `v1_16` + +## `bind_mcast_addr` +the new value Set the kernel UDP buffer size. ## `size` @@ -1176,6 +1338,12 @@ Configures a specific clock to be used by the pipelines of all medias created from this factory. ## `clock` the clock to be used by the media factory + +Set whether retransmission requests will be sent for +receiving media + +Feature: `v1_16` + Configure if media created from this factory will have an EOS sent to the pipeline before shutdown. @@ -1197,6 +1365,17 @@ The description should return a pipeline with payloaders named pay0, pay1, etc.. Each of the payloaders will result in a stream. ## `launch` the launch description + +Set the maximum time-to-live value of outgoing multicast packets. + +Feature: `v1_16` + +## `ttl` +the new multicast ttl value + +# Returns + +`true` if the requested ttl has been set successfully. Configure the GType of the GstRTSPMedia subclass to create (by default, overridden construct vmethods @@ -1787,6 +1966,9 @@ valid until the session of `self` is unreffed. Get a list of all available `RTSPStreamTransport` in this session. +Feature: `v1_14` + + # Returns a @@ -1952,6 +2134,25 @@ a `gst::Pad` # Returns a new `RTSPStream` + +Add multicast client address to stream. At this point, the sockets that +will stream RTP and RTCP data to `destination` are supposed to be +allocated. + +Feature: `v1_16` + +## `destination` +a multicast address to add +## `rtp_port` +RTP port +## `rtcp_port` +RTCP port +## `family` +socket family + +# Returns + +`true` if `destination` can be addedd and handled by `self`. Add the transport in `trans` to `self`. The media of `self` will then also be send to the values configured in `trans`. @@ -1980,6 +2181,9 @@ Whether to use client settings or not Add a receiver and sender part to the pipeline based on the transport from SETUP. + +Feature: `v1_14` + ## `transport` a `gst_rtsp::RTSPTransport` @@ -2030,6 +2234,15 @@ Get the previous joined bin with `RTSPStreamExt::join_bin` or NULL. # Returns the joined bin or NULL. + +Get the the maximum time-to-live value of outgoing multicast packets. + +Feature: `v1_16` + + +# Returns + +the maximum time-to-live value of outgoing multicast packets. Get the configured MTU in the payloader of `self`. @@ -2048,6 +2261,15 @@ the `gio::SocketFamily` the `RTSPAddress` of `self` or `None` when no address could be allocated. `RTSPAddress::free` after usage. + +Get all multicast client addresses that RTP data will be sent to + +Feature: `v1_16` + + +# Returns + +A comma separated list of host:port pairs with destinations Get the multicast interface used for `self`. @@ -2093,6 +2315,9 @@ Get the amount of time to store retransmission data. the amount of time to store retransmission data. Get the multicast RTCP socket from `self` for a `family`. + +Feature: `v1_14` + ## `family` the socket family @@ -2119,6 +2344,7 @@ the socket family # Returns the multicast RTP socket or `None` if no + socket could be allocated for `family`. Unref after usage Get the RTP socket from `self` for a `family`. @@ -2182,6 +2408,30 @@ Get the SSRC used by the RTP session of this stream. This function can only be called when `self` has been joined. ## `ssrc` result ssrc + + +Feature: `v1_16` + + +# Returns + +the amount of redundancy applied when creating ULPFEC +protection packets. + + +Feature: `v1_16` + + +# Returns + +the payload type used for ULPFEC protection packets + +Parse and handle a KeyMgmt header. + +Feature: `v1_16` + +## `keymgmt` +a keymgmt header Check if `self` has the control string `control`. ## `control` @@ -2190,6 +2440,15 @@ a control string # Returns `true` is `self` has `control` as the control string + +Check if multicast sockets are configured to be bound to multicast addresses. + +Feature: `v1_16` + + +# Returns + +`true` if multicast sockets are configured to be bound to multicast addresses. Check if `self` is blocking on a `gst::Buffer`. @@ -2207,18 +2466,27 @@ Checks whether the stream is complete, contains the receiver and the sender parts. As the stream contains sink(s) element(s), it's possible to perform seek operations on it. +Feature: `v1_14` + + # Returns `true` if the stream contains at least one sink element. Checks whether the stream is a receiver. +Feature: `v1_14` + + # Returns `true` if the stream is a receiver and `false` otherwise. Checks whether the stream is a sender. +Feature: `v1_14` + + # Returns `true` if the stream is a sender and `false` otherwise. @@ -2308,11 +2576,40 @@ a `RTSPStreamTransport` # Returns `true` if `trans` was removed + +Creating a rtxreceive bin + +Feature: `v1_16` + +## `sessid` +the session id + +# Returns + +a `gst::Element`. Creating a rtxsend bin ## `sessid` the session id +# Returns + +a `gst::Element`. + +Creating a rtpulpfecdec element + +Feature: `v1_16` + + +# Returns + +a `gst::Element`. + +Creating a rtpulpfecenc element + +Feature: `v1_16` + + # Returns a `gst::Element`. @@ -2332,10 +2629,14 @@ a TTL # Returns the `RTSPAddress` of `self` or `None` when -the address could be reserved. `RTSPAddress::free` after usage. +the address could not be reserved. `RTSPAddress::free` after +usage. Checks whether the individual `self` is seekable. +Feature: `v1_14` + + # Returns `true` if `self` is seekable, else `false`. @@ -2343,6 +2644,14 @@ Checks whether the individual `self` is seekable. configure `pool` to be used as the address pool of `self`. ## `pool` a `RTSPAddressPool` + +Decide whether the multicast socket should be bound to a multicast address or +INADDR_ANY. + +Feature: `v1_16` + +## `bind_mcast_addr` +the new value Blocks or unblocks the dataflow on `self`. ## `blocked` @@ -2373,6 +2682,17 @@ a control string Configure the dscp qos of the outgoing sockets to `dscp_qos`. ## `dscp_qos` a new dscp qos value (0-63, or -1 to disable) + +Set the maximum time-to-live value of outgoing multicast packets. + +Feature: `v1_16` + +## `ttl` +the new multicast ttl value + +# Returns + +`true` if the requested ttl has been set successfully. Configure the mtu in the payloader of `self` to `mtu`. ## `mtu` @@ -2407,6 +2727,17 @@ a `guint` Set the amount of time to store retransmission packets. ## `time` a `gst::ClockTime` + +Sets the amount of redundancy to apply when creating ULPFEC +protection packets. + +Feature: `v1_16` + + +Set the payload type to be used for ULPFEC protection packets + +Feature: `v1_16` + Call `func` for each transport managed by `self`. The result value of `func` determines what happens to the transport. `func` will be called with `self` @@ -2445,6 +2776,17 @@ a `gst::Caps` with crypto info # Returns `true` if `crypto` could be updated + +Check if the requested multicast ttl value is allowed. + +Feature: `v1_16` + +## `ttl` +a requested multicast ttl + +# Returns + +TRUE if the requested ttl value is allowed. A Transport description for a stream @@ -2506,6 +2848,11 @@ Check if `self` is timed out. `true` if `self` timed out. Signal the installed keep_alive callback for `self`. + +Signal the installed message_sent callback for `self`. + +Feature: `v1_16` + Receive `buffer` on `channel` `self`. ## `channel` @@ -2524,6 +2871,17 @@ a `gst::Buffer` # Returns +`true` on success + +Send `buffer_list` to the installed RTCP callback for `self`. + +Feature: `v1_16` + +## `buffer_list` +a `gst::Buffer` + +# Returns + `true` on success Send `buffer` to the installed RTP callback for `self`. @@ -2532,6 +2890,17 @@ a `gst::Buffer` # Returns +`true` on success + +Send `buffer_list` to the installed RTP callback for `self`. + +Feature: `v1_16` + +## `buffer_list` +a `gst::BufferList` + +# Returns + `true` on success Activate or deactivate datatransfer configured in `self`. @@ -2561,6 +2930,28 @@ a callback called when the receiver is active user data passed to callback ## `notify` called with the user_data when no longer needed. + +Install callbacks that will be called when data for a stream should be sent +to a client. This is usually used when sending RTP/RTCP over TCP. + +Feature: `v1_16` + +## `send_rtp_list` +a callback called when RTP should be sent +## `send_rtcp_list` +a callback called when RTCP should be sent +## `user_data` +user data passed to callbacks +## `notify` +called with the user_data when no longer needed. + +Install a callback that will be called when a message has been sent on `self`. +## `message_sent` +a callback called when a message has been sent +## `user_data` +user data passed to callback +## `notify` +called with the user_data when no longer needed Set the timed out state of `self` to `timedout` ## `timedout` diff --git a/docs/gstreamer-rtsp/docs.md b/docs/gstreamer-rtsp/docs.md index a6b222bfc..df553f7d9 100644 --- a/docs/gstreamer-rtsp/docs.md +++ b/docs/gstreamer-rtsp/docs.md @@ -8,6 +8,7 @@ basic authentication digest authentication +RTSP Authentication parameter The possible network families. diff --git a/docs/gstreamer-sdp/docs.md b/docs/gstreamer-sdp/docs.md index d4d349159..d4fffaed4 100644 --- a/docs/gstreamer-sdp/docs.md +++ b/docs/gstreamer-sdp/docs.md @@ -1,565 +1 @@ - -The different cache types - -The envelope key MUST NOT be cached - -The envelope key MUST be cached - -The envelope key MUST be cached, but only - to be used for the specific CSB. - -The encryption algorithm used to encrypt the Encr data field - -no encryption - -AES-CM using a 128-bit key - -AES Key Wrap using a 128-bit key - -The key validity type - -No specific usage rule - -The key is associated with the SPI/MKI - -The key has a start and expiration time - -The type of key. - -a TEK Generation Key - -Traffic-Encrypting Key - -Specifies the authentication algorithm used - -no authentication - -HMAC-SHA-1-160 - -Specifies the method of uniquely mapping Crypto Sessions to the security -protocol sessions. - -Structure holding the information of the MIKEY message - -Make a new MIKEY message. - -# Returns - -a new `MIKEYMessage` on success - -Make a new `MIKEYMessage` from `bytes`. -## `bytes` -a `glib::Bytes` -## `info` -a `MIKEYDecryptInfo` - -# Returns - -a new `MIKEYMessage` - -Makes mikey message including: - - Security Policy Payload - - Key Data Transport Payload - - Key Data Sub-Payload -## `caps` -a `gst::Caps`, including SRTP parameters (srtp/srtcp cipher, authorization, key data) - -# Returns - -a `MIKEYMessage`, -or `None` if there is no srtp information in the caps. - -Parse `size` bytes from `data` into a `MIKEYMessage`. `info` contains the -parameters to decrypt and verify the data. -## `data` -bytes to read -## `size` -length of `data` -## `info` -`MIKEYDecryptInfo` - -# Returns - -a `MIKEYMessage` on success or `None` when parsing failed and -`error` will be set. - -Add a Crypto policy for SRTP to `self`. -## `policy` -The security policy applied for the stream with `ssrc` -## `ssrc` -the SSRC that must be used for the stream -## `roc` -current rollover counter - -# Returns - -`true` on success - -Add a new payload to `self`. -## `payload` -a `MIKEYPayload` - -# Returns - -`true` on success - -Add a new PKE payload to `self` with the given parameters. -## `C` -envelope key cache indicator -## `data_len` -the length of `data` -## `data` -the encrypted envelope key - -# Returns - -`true` on success - -Add a new RAND payload to `self` with the given parameters. -## `len` -the length of `rand` -## `rand` -random data - -# Returns - -`true` on success - -Add a new RAND payload to `self` with `len` random bytes. -## `len` -length - -# Returns - -`true` on success - -Add a new T payload to `self` with the given parameters. -## `type_` -specifies the timestamp type used -## `ts_value` -The timestamp value of the specified `type_` - -# Returns - -`true` on success - -Add a new T payload to `self` that contains the current time -in NTP-UTC format. - -# Returns - -`true` on success - - -# Returns - -a `gchar`, base64-encoded data - -Find the `nth` occurence of the payload with `type_` in `self`. -## `type_` -a `MIKEYPayloadType` -## `nth` -payload to find - -# Returns - -the `nth` `MIKEYPayload` of `type_`. - -Get the policy information of `self` at `idx`. -## `idx` -an index - -# Returns - -a `MIKEYMapSRTP` - -Get the number of crypto sessions in `self`. - -# Returns - -the number of crypto sessions - -Get the number of payloads in `self`. - -# Returns - -the number of payloads in `self` - -Get the `MIKEYPayload` at `idx` in `self` -## `idx` -an index - -# Returns - -the `MIKEYPayload` at `idx`. The payload -remains valid for as long as it is part of `self`. - -Insert a Crypto Session map for SRTP in `self` at `idx` - -When `idx` is -1, the policy will be appended. -## `idx` -the index to insert at -## `map` -the map info - -# Returns - -`true` on success - -Insert the `payload` at index `idx` in `self`. If `idx` is -1, the payload -will be appended to `self`. -## `idx` -an index -## `payload` -a `MIKEYPayload` - -# Returns - -`true` on success - -Remove the SRTP policy at `idx`. -## `idx` -the index to remove - -# Returns - -`true` on success - -Remove the payload in `self` at `idx` -## `idx` -an index - -# Returns - -`true` on success - -Replace a Crypto Session map for SRTP in `self` at `idx` with `map`. -## `idx` -the index to insert at -## `map` -the map info - -# Returns - -`true` on success - -Replace the payload at `idx` in `self` with `payload`. -## `idx` -an index -## `payload` -a `MIKEYPayload` - -# Returns - -`true` on success - -Set the information in `self`. -## `version` -a version -## `type_` -a `MIKEYType` -## `V` -verify flag -## `prf_func` -the `MIKEYPRFFunc` function to use -## `CSB_id` -the Crypto Session Bundle id -## `map_type` -the `GstMIKEYCSIDMapType` - -# Returns - -`true` on success - -Convert `self` to a `glib::Bytes`. -## `info` -a `MIKEYEncryptInfo` - -# Returns - -a new `glib::Bytes` for `self`. - - -Feature: `v1_8_1` - -## `caps` -a `gst::Caps` to be filled with SRTP parameters (srtp/srtcp cipher, authorization, key data) - -# Returns - -`true` on success - -The PRF function that has been/will be used for key derivation - -MIKEY-1 PRF function - -Hold the common fields for all payloads - -Make a new `MIKEYPayload` with `type_`. -## `type_` -a `MIKEYPayloadType` - -# Returns - -a new `MIKEYPayload` or `None` on failure. - -Add a new sub payload to `self`. -## `newpay` -a `MIKEYPayload` to add - -# Returns - -`true` on success. - -Get the number of sub payloads of `self`. `self` should be of type -`MIKEYPayloadType::Kemac`. - -# Returns - -the number of sub payloads in `self` - -Get the sub payload of `self` at `idx`. `self` should be of type -`MIKEYPayloadType::Kemac`. -## `idx` -an index - -# Returns - -the `MIKEYPayload` at `idx`. - -Remove the sub payload at `idx` in `self`. -## `idx` -the index to remove - -# Returns - -`true` on success. - -Set the KEMAC parameters. `self` should point to a `MIKEYPayloadType::Kemac` -payload. -## `enc_alg` -the `MIKEYEncAlg` -## `mac_alg` -a `MIKEYMacAlg` - -# Returns - -`true` on success - -Set the key validity period in the `MIKEYPayloadType::KeyData` `self`. -## `vf_len` -the length of `vf_data` -## `vf_data` -the Valid From data -## `vt_len` -the length of `vt_data` -## `vt_data` -the Valid To data - -# Returns - -`true` on success - -Set `key_len` bytes of `key_data` of type `key_type` as the key for the -`MIKEYPayloadType::KeyData` `self`. -## `key_type` -a `MIKEYKeyDataType` -## `key_len` -the length of `key_data` -## `key_data` -the key of type `key_type` - -# Returns - -`true` on success - -Set the salt key data. If `salt_len` is 0 and `salt_data` is `None`, the -salt data will be removed. -## `salt_len` -the length of `salt_data` -## `salt_data` -the salt - -# Returns - -`true` on success - -Set the SPI/MKI validity in the `MIKEYPayloadType::KeyData` `self`. -## `spi_len` -the length of `spi_data` -## `spi_data` -the SPI/MKI data - -# Returns - -`true` on success - -Set the PKE values in `self`. `self` must be of type -`MIKEYPayloadType::Pke`. -## `C` -envelope key cache indicator -## `data_len` -the length of `data` -## `data` -the encrypted envelope key - -# Returns - -`true` on success - -Set the random values in a `MIKEYPayloadType::Rand` `self`. -## `len` -the length of `rand` -## `rand` -random values - -# Returns - -`true` on success - -Add a new parameter to the `MIKEYPayloadType::Sp` `self` with `type_`, `len` -and `val`. -## `type_` -a type -## `len` -a length -## `val` -`len` bytes of data - -# Returns - -`true` on success - -Get the number of security policy parameters in a `MIKEYPayloadType::Sp` -`self`. - -# Returns - -the number of parameters in `self` - -Get the Security Policy parameter in a `MIKEYPayloadType::Sp` `self` -at `idx`. -## `idx` -an index - -# Returns - -the `MIKEYPayloadSPParam` at `idx` in `self` - -Remove the Security Policy parameters from a `MIKEYPayloadType::Sp` -`self` at `idx`. -## `idx` -an index - -# Returns - -`true` on success - -Set the Security Policy parameters for `self`. -## `policy` -the policy number -## `proto` -a `MIKEYSecProto` - -# Returns - -`true` on success - -Set the timestamp in a `MIKEYPayloadType::T` `self`. -## `type_` -the `MIKEYTSType` -## `ts_value` -the timestamp value - -# Returns - -`true` on success - -Different MIKEY Payload types. - -Last payload - -Key data transport payload - -Envelope data payload - -DH data payload - -Signature payload - -Timestamp payload - -ID payload - -Certificate Payload - -Cert hash payload - -Verfication message payload - -Security Policy payload - -RAND payload - -Error payload - -Key data sub-payload - -General Extension Payload - -Specifies the security protocol - -This policy specifies the parameters for SRTP and SRTCP - -Encryption algorithm - -Session Encr. key length - -Authentication algorithm - -Session Auth. key length - -Session Salt key length - -SRTP Pseudo Random Function - -Key derivation rate - -SRTP encryption off/on, 0 if off, 1 if on - -SRTCP encryption off/on, 0 if off, 1 if on - -sender's FEC order - -SRTP authentication off/on, 0 if off, 1 if on - -Authentication tag length - -SRTP prefix length - -Specifies the timestamp type. - -an NTP time in UTC timezone - -an NTP time - -a counter - -Different MIKEY data types. - -Invalid type - -Initiator's pre-shared key message - -Verification message of a Pre-shared key message - -Initiator's public-key transport message - -Verification message of a public-key message - -Initiator's DH exchange message - -Responder's DH exchange message - -Error message diff --git a/docs/gstreamer-video/docs.md b/docs/gstreamer-video/docs.md index 641690bf0..f13c87576 100644 --- a/docs/gstreamer-video/docs.md +++ b/docs/gstreamer-video/docs.md @@ -1,4 +1,97 @@ + + + +# Implements + +[`gst::BufferPoolExt`](../gst/trait.BufferPoolExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) + +Create a new bufferpool that can allocate video frames. This bufferpool +supports all the video bufferpool options. + +# Returns + +a new `gst::BufferPool` to allocate video frames + +The various known types of Closed Caption (CC). + +Unknown type of CC + +CEA-608 as byte pairs. Note that + this format is not recommended since is does not specify to + which field the caption comes from and therefore assumes + it comes from the first field (and that there is no information + on the second field). Use `VideoCaptionType::Cea708Raw` + if you wish to store CEA-608 from two fields and prefix each byte pair + with 0xFC for the first field and 0xFD for the second field. + +CEA-608 as byte triplets as defined + in SMPTE S334-1 Annex A. The second and third byte of the byte triplet + is the raw CEA608 data, the first byte is a bitfield: The top/7th bit is + 0 for the second field, 1 for the first field, bit 6 and 5 are 0 and + bits 4 to 0 are a 5 bit unsigned integer that represents the line + offset relative to the base-line of the original image format (line 9 + for 525-line field 1, line 272 for 525-line field 2, line 5 for + 625-line field 1 and line 318 for 625-line field 2). + +CEA-708 as cc_data byte triplets. They + can also contain 608-in-708 and the first byte of each triplet has to + be inspected for detecting the type. + +CEA-708 (and optionally CEA-608) in + a CDP (Caption Distribution Packet) defined by SMPTE S-334-2. + Contains the whole CDP (starting with 0x9669). + +Feature: `v1_16` + + +A `VideoCodecFrame` represents a video frame both in raw and +encoded form. + +Gets private data set on the frame by the subclass via +`VideoCodecFrame::set_user_data` previously. + +# Returns + +The previously set user_data + +Increases the refcount of the given frame by one. + +# Returns + +`buf` + +Sets `user_data` on the frame and the `GDestroyNotify` that will be called when +the frame is freed. Allows to attach private data by the subclass to frames. + +If a `user_data` was previously set, then the previous set `notify` will be called +before the `user_data` is replaced. +## `user_data` +private data +## `notify` +a `GDestroyNotify` + +Decreases the refcount of the frame. If the refcount reaches 0, the frame +will be freed. + +Structure representing the state of an incoming or outgoing video +stream for encoders and decoders. + +Decoders and encoders will receive such a state through their +respective `set_format` vmethods. + +Decoders and encoders can set the downstream state, by using the +`VideoDecoder::set_output_state`() or +`VideoEncoder::set_output_state`() methods. + +Increases the refcount of the given state by one. + +# Returns + +`buf` + +Decreases the refcount of the state. If the refcount reaches 0, the state +will be freed. The color matrix is used to convert between Y'PbPr and non-linear RGB (R'G'B') @@ -37,6 +130,14 @@ Generic film BT2020 primaries. Since: 1.6 Adobe RGB primaries. Since: 1.8 + +SMPTE ST 428 primaries. Since: 1.16 + +SMPTE RP 431 primaries. Since: 1.16 + +SMPTE EG 432 primaries. Since: 1.16 + +EBU 3213 primaries. Since: 1.16 Possible color range values. These constants are defined for 8 bit color values and can be scaled for other bit depths. @@ -82,6 +183,690 @@ Make a string representation of `self`. # Returns a string representation of `self`. + +This base class is for video decoders turning encoded data into raw video +frames. + +The GstVideoDecoder base class and derived subclasses should cooperate as +follows: + +## Configuration + + * Initially, GstVideoDecoder calls `start` when the decoder element + is activated, which allows the subclass to perform any global setup. + + * GstVideoDecoder calls `set_format` to inform the subclass of caps + describing input video data that it is about to receive, including + possibly configuration data. + While unlikely, it might be called more than once, if changing input + parameters require reconfiguration. + + * Incoming data buffers are processed as needed, described in Data + Processing below. + + * GstVideoDecoder calls `stop` at end of all processing. + +## Data processing + + * The base class gathers input data, and optionally allows subclass + to parse this into subsequently manageable chunks, typically + corresponding to and referred to as 'frames'. + + * Each input frame is provided in turn to the subclass' `handle_frame` + callback. + The ownership of the frame is given to the `handle_frame` callback. + + * If codec processing results in decoded data, the subclass should call + `VideoDecoder::finish_frame` to have decoded data pushed. + downstream. Otherwise, the subclass must call + `VideoDecoder::drop_frame`, to allow the base class to do timestamp + and offset tracking, and possibly to requeue the frame for a later + attempt in the case of reverse playback. + +## Shutdown phase + + * The GstVideoDecoder class calls `stop` to inform the subclass that data + parsing will be stopped. + +## Additional Notes + + * Seeking/Flushing + + * When the pipeline is seeked or otherwise flushed, the subclass is + informed via a call to its `reset` callback, with the hard parameter + set to true. This indicates the subclass should drop any internal data + queues and timestamps and prepare for a fresh set of buffers to arrive + for parsing and decoding. + + * End Of Stream + + * At end-of-stream, the subclass `parse` function may be called some final + times with the at_eos parameter set to true, indicating that the element + should not expect any more data to be arriving, and it should parse and + remaining frames and call `VideoDecoder::have_frame` if possible. + +The subclass is responsible for providing pad template caps for +source and sink pads. The pads need to be named "sink" and "src". It also +needs to provide information about the ouptput caps, when they are known. +This may be when the base class calls the subclass' `set_format` function, +though it might be during decoding, before calling +`VideoDecoder::finish_frame`. This is done via +`VideoDecoder::set_output_state` + +The subclass is also responsible for providing (presentation) timestamps +(likely based on corresponding input ones). If that is not applicable +or possible, the base class provides limited framerate based interpolation. + +Similarly, the base class provides some limited (legacy) seeking support +if specifically requested by the subclass, as full-fledged support +should rather be left to upstream demuxer, parser or alike. This simple +approach caters for seeking and duration reporting using estimated input +bitrates. To enable it, a subclass should call +`VideoDecoderExt::set_estimate_rate` to enable handling of incoming +byte-streams. + +The base class provides some support for reverse playback, in particular +in case incoming data is not packetized or upstream does not provide +fragments on keyframe boundaries. However, the subclass should then be +prepared for the parsing and frame processing stage to occur separately +(in normal forward processing, the latter immediately follows the former), +The subclass also needs to ensure the parsing stage properly marks +keyframes, unless it knows the upstream elements will do so properly for +incoming data. + +The bare minimum that a functional subclass needs to implement is: + + * Provide pad templates + * Inform the base class of output caps via + `VideoDecoder::set_output_state` + + * Parse input data, if it is not considered packetized from upstream + Data will be provided to `parse` which should invoke + `VideoDecoderExt::add_to_frame` and `VideoDecoder::have_frame` to + separate the data belonging to each video frame. + + * Accept data in `handle_frame` and provide decoded results to + `VideoDecoder::finish_frame`, or call `VideoDecoder::drop_frame`. + +# Implements + +[`VideoDecoderExt`](trait.VideoDecoderExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) + +Trait containing all `VideoDecoder` methods. + +# Implementors + +[`VideoDecoder`](struct.VideoDecoder.html) + +Removes next `n_bytes` of input data and adds it to currently parsed frame. +## `n_bytes` +the number of bytes to add + +Helper function that allocates a buffer to hold a video frame for `self`'s +current `VideoCodecState`. + +You should use `VideoDecoder::allocate_output_frame` instead of this +function, if possible at all. + +# Returns + +allocated buffer, or NULL if no buffer could be + allocated (e.g. when downstream is flushing or shutting down) + +Helper function that allocates a buffer to hold a video frame for `self`'s +current `VideoCodecState`. Subclass should already have configured video +state and set src pad caps. + +The buffer allocated here is owned by the frame and you should only +keep references to the frame, not the buffer. +## `frame` +a `VideoCodecFrame` + +# Returns + +`gst::FlowReturn::Ok` if an output buffer could be allocated + +Same as `VideoDecoder::allocate_output_frame` except it allows passing +`gst::BufferPoolAcquireParams` to the sub call gst_buffer_pool_acquire_buffer. + +Feature: `v1_12` + +## `frame` +a `VideoCodecFrame` +## `params` +a `gst::BufferPoolAcquireParams` + +# Returns + +`gst::FlowReturn::Ok` if an output buffer could be allocated + +Similar to `VideoDecoder::finish_frame`, but drops `frame` in any +case and posts a QoS message with the frame's details on the bus. +In any case, the frame is considered finished and released. +## `frame` +the `VideoCodecFrame` to drop + +# Returns + +a `gst::FlowReturn`, usually GST_FLOW_OK. + +`frame` should have a valid decoded data buffer, whose metadata fields +are then appropriately set according to frame data and pushed downstream. +If no output data is provided, `frame` is considered skipped. +In any case, the frame is considered finished and released. + +After calling this function the output buffer of the frame is to be +considered read-only. This function will also change the metadata +of the buffer. +## `frame` +a decoded `VideoCodecFrame` + +# Returns + +a `gst::FlowReturn` resulting from sending data downstream + +Lets `VideoDecoder` 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 the decoder; free it after use it + + +# Returns + +currently configured byte to time conversion setting + +Get a pending unfinished `VideoCodecFrame` +## `frame_number` +system_frame_number of a frame + +# Returns + +pending unfinished `VideoCodecFrame` identified by `frame_number`. + +Get all pending unfinished `VideoCodecFrame` + +# Returns + +pending unfinished `VideoCodecFrame`. + +Query the configured decoder latency. Results will be returned via +`min_latency` and `max_latency`. +## `min_latency` +address of variable in which to store the + configured minimum latency, or `None` +## `max_latency` +address of variable in which to store the + configured mximum latency, or `None` + +Determines maximum possible decoding time for `frame` that will +allow it to decode and arrive in time (as determined by QoS events). +In particular, a negative result means decoding in time is no longer possible +and should therefore occur as soon/skippy as possible. +## `frame` +a `VideoCodecFrame` + +# Returns + +max decoding time. + + +# Returns + +currently configured decoder tolerated error count. + +Queries decoder required format handling. + +# Returns + +`true` if required format handling is enabled. + +Get the oldest pending unfinished `VideoCodecFrame` + +# Returns + +oldest pending unfinished `VideoCodecFrame`. + +Get the `VideoCodecState` currently describing the output stream. + +# Returns + +`VideoCodecState` describing format of video data. + +Queries whether input data is considered packetized or not by the +base class. + +# Returns + +TRUE if input data is considered packetized. + +Returns the number of bytes previously added to the current frame +by calling `VideoDecoderExt::add_to_frame`. + +# Returns + +The number of bytes pending for the current frame + + +# Returns + +The current QoS proportion. + +Gathers all data collected for currently parsed frame, gathers corresponding +metadata and passes it along for further processing, i.e. `handle_frame`. + +# Returns + +a `gst::FlowReturn` + +Sets the audio decoder tags and how they should be merged with any +upstream stream tags. This will override any tags previously-set +with `gst_audio_decoder_merge_tags`. + +Note that this is provided for convenience, and the subclass is +not required to use this and can still do tag handling on its own. + +MT safe. +## `tags` +a `gst::TagList` to merge, or NULL to unset + previously-set tags +## `mode` +the `gst::TagMergeMode` to use, usually `gst::TagMergeMode::Replace` + +Negotiate with downstream elements to currently configured `VideoCodecState`. +Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if +negotiate fails. + +# Returns + +`true` if the negotiation succeeded, else `false`. + +Returns caps that express `caps` (or sink template caps if `caps` == NULL) +restricted to resolution/format/... combinations supported by downstream +elements. +## `caps` +initial caps +## `filter` +filter caps + +# Returns + +a `gst::Caps` owned by caller + +Similar to `VideoDecoder::drop_frame`, but simply releases `frame` +without any processing other than removing it from list of pending frames, +after which it is considered finished and released. +## `frame` +the `VideoCodecFrame` to release + +Allows baseclass to perform byte to time estimated conversion. +## `enabled` +whether to enable byte to time conversion + +Same as `VideoDecoder::set_output_state`() but also allows you to also set +the interlacing mode. + +Feature: `v1_16` + +## `fmt` +a `VideoFormat` +## `mode` +A `VideoInterlaceMode` +## `width` +The width in pixels +## `height` +The height in pixels +## `reference` +An optional reference `VideoCodecState` + +# Returns + +the newly configured output state. + +Lets `VideoDecoder` sub-classes tell the baseclass what the decoder +latency is. Will also post a LATENCY message on the bus so the pipeline +can reconfigure its global latency. +## `min_latency` +minimum latency +## `max_latency` +maximum latency + +Sets numbers of tolerated decoder errors, where a tolerated one is then only +warned about, but more than tolerated will lead to fatal error. You can set +-1 for never returning fatal errors. Default is set to +GST_VIDEO_DECODER_MAX_ERRORS. + +The '-1' option was added in 1.4 +## `num` +max tolerated errors + +Configures decoder format needs. If enabled, subclass needs to be +negotiated with format caps before it can process any data. It will then +never be handed any data before it has been configured. +Otherwise, it might be handed data without having been configured and +is then expected being able to do so either by default +or based on the input data. +## `enabled` +new state + +Creates a new `VideoCodecState` with the specified `fmt`, `width` and `height` +as the output state for the decoder. +Any previously set output state on `self` will be replaced by the newly +created one. + +If the subclass wishes to copy over existing fields (like pixel aspec ratio, +or framerate) from an existing `VideoCodecState`, it can be provided as a +`reference`. + +If the subclass wishes to override some fields from the output state (like +pixel-aspect-ratio or framerate) it can do so on the returned `VideoCodecState`. + +The new output state will only take effect (set on pads and buffers) starting +from the next call to `VideoDecoder::finish_frame`(). +## `fmt` +a `VideoFormat` +## `width` +The width in pixels +## `height` +The height in pixels +## `reference` +An optional reference `VideoCodecState` + +# Returns + +the newly configured output state. + +Allows baseclass to consider input data as packetized or not. If the +input is packetized, then the `parse` method will not be called. +## `packetized` +whether the input data should be considered as packetized. + +Lets `VideoDecoder` sub-classes decide if they want the sink pad +to use the default pad query handler to reply to accept-caps queries. + +By setting this to true it is possible to further customize the default +handler with `GST_PAD_SET_ACCEPT_INTERSECT` and +`GST_PAD_SET_ACCEPT_TEMPLATE` +## `use_` +if the default pad accept-caps query handling should be used + +This base class is for video encoders turning raw video into +encoded video data. + +GstVideoEncoder and subclass should cooperate as follows. + +## Configuration + + * Initially, GstVideoEncoder calls `start` when the encoder element + is activated, which allows subclass to perform any global setup. + * GstVideoEncoder calls `set_format` to inform subclass of the format + of input video data that it is about to receive. Subclass should + setup for encoding and configure base class as appropriate + (e.g. latency). While unlikely, it might be called more than once, + if changing input parameters require reconfiguration. Baseclass + will ensure that processing of current configuration is finished. + * GstVideoEncoder calls `stop` at end of all processing. + +## Data processing + + * Base class collects input data and metadata into a frame and hands + this to subclass' `handle_frame`. + + * If codec processing results in encoded data, subclass should call + `VideoEncoder::finish_frame` to have encoded data pushed + downstream. + + * If implemented, baseclass calls subclass `pre_push` just prior to + pushing to allow subclasses to modify some metadata on the buffer. + If it returns GST_FLOW_OK, the buffer is pushed downstream. + + * GstVideoEncoderClass will handle both srcpad and sinkpad events. + Sink events will be passed to subclass if `event` callback has been + provided. + +## Shutdown phase + + * GstVideoEncoder class calls `stop` to inform the subclass that data + parsing will be stopped. + +Subclass is responsible for providing pad template caps for +source and sink pads. The pads need to be named "sink" and "src". It should +also be able to provide fixed src pad caps in `getcaps` by the time it calls +`VideoEncoder::finish_frame`. + +Things that subclass need to take care of: + + * Provide pad templates + * Provide source pad caps before pushing the first buffer + * Accept data in `handle_frame` and provide encoded results to + `VideoEncoder::finish_frame`. + + +The `VideoEncoder:qos` property will enable the Quality-of-Service +features of the encoder which gather statistics about the real-time +performance of the downstream elements. If enabled, subclasses can +use `VideoEncoderExt::get_max_encode_time` to check if input frames +are already late and drop them right away to give a chance to the +pipeline to catch up. + +# Implements + +[`VideoEncoderExt`](trait.VideoEncoderExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) + +Trait containing all `VideoEncoder` methods. + +# Implementors + +[`VideoEncoder`](struct.VideoEncoder.html) + +Helper function that allocates a buffer to hold an encoded video frame +for `self`'s current `VideoCodecState`. +## `size` +size of the buffer + +# Returns + +allocated buffer + +Helper function that allocates a buffer to hold an encoded video frame for `self`'s +current `VideoCodecState`. Subclass should already have configured video +state and set src pad caps. + +The buffer allocated here is owned by the frame and you should only +keep references to the frame, not the buffer. +## `frame` +a `VideoCodecFrame` +## `size` +size of the buffer + +# Returns + +`gst::FlowReturn::Ok` if an output buffer could be allocated + +`frame` must have a valid encoded data buffer, whose metadata fields +are then appropriately set according to frame data or no buffer at +all if the frame should be dropped. +It is subsequently pushed downstream or provided to `pre_push`. +In any case, the frame is considered finished and released. + +After calling this function the output buffer of the frame is to be +considered read-only. This function will also change the metadata +of the buffer. +## `frame` +an encoded `VideoCodecFrame` + +# Returns + +a `gst::FlowReturn` resulting from sending data downstream + +Lets `VideoEncoder` 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` + +Get a pending unfinished `VideoCodecFrame` +## `frame_number` +system_frame_number of a frame + +# Returns + +pending unfinished `VideoCodecFrame` identified by `frame_number`. + +Get all pending unfinished `VideoCodecFrame` + +# Returns + +pending unfinished `VideoCodecFrame`. + +Query the configured encoding latency. Results will be returned via +`min_latency` and `max_latency`. +## `min_latency` +address of variable in which to store the + configured minimum latency, or `None` +## `max_latency` +address of variable in which to store the + configured maximum latency, or `None` + +Determines maximum possible encoding time for `frame` that will +allow it to encode and arrive in time (as determined by QoS events). +In particular, a negative result means encoding in time is no longer possible +and should therefore occur as soon/skippy as possible. + +If no QoS events have been received from downstream, or if +`VideoEncoder:qos` is disabled this function returns `G_MAXINT64`. + +Feature: `v1_14` + +## `frame` +a `VideoCodecFrame` + +# Returns + +max decoding time. + +Get the oldest unfinished pending `VideoCodecFrame` + +# Returns + +oldest unfinished pending `VideoCodecFrame` + +Get the current `VideoCodecState` + +# Returns + +`VideoCodecState` describing format of video data. + +Checks if `self` is currently configured to handle Quality-of-Service +events from downstream. + +Feature: `v1_14` + + +# Returns + +`true` if the encoder is configured to perform Quality-of-Service. + +Sets the video encoder tags and how they should be merged with any +upstream stream tags. This will override any tags previously-set +with `VideoEncoderExt::merge_tags`. + +Note that this is provided for convenience, and the subclass is +not required to use this and can still do tag handling on its own. + +MT safe. +## `tags` +a `gst::TagList` to merge, or NULL to unset + previously-set tags +## `mode` +the `gst::TagMergeMode` to use, usually `gst::TagMergeMode::Replace` + +Negotiate with downstream elements to currently configured `VideoCodecState`. +Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if +negotiate fails. + +# Returns + +`true` if the negotiation succeeded, else `false`. + +Returns caps that express `caps` (or sink template caps if `caps` == NULL) +restricted to resolution/format/... combinations supported by downstream +elements (e.g. muxers). +## `caps` +initial caps +## `filter` +filter caps + +# Returns + +a `gst::Caps` owned by caller + +Set the codec headers to be sent downstream whenever requested. +## `headers` +a list of `gst::Buffer` containing the codec header + +Informs baseclass of encoding latency. +## `min_latency` +minimum latency +## `max_latency` +maximum latency + +Request minimal value for PTS passed to handle_frame. + +For streams with reordered frames this can be used to ensure that there +is enough time to accomodate first DTS, which may be less than first PTS +## `min_pts` +minimal PTS that will be passed to handle_frame + +Creates a new `VideoCodecState` with the specified caps as the output state +for the encoder. +Any previously set output state on `self` will be replaced by the newly +created one. + +The specified `caps` should not contain any resolution, pixel-aspect-ratio, +framerate, codec-data, .... Those should be specified instead in the returned +`VideoCodecState`. + +If the subclass wishes to copy over existing fields (like pixel aspect ratio, +or framerate) from an existing `VideoCodecState`, it can be provided as a +`reference`. + +If the subclass wishes to override some fields from the output state (like +pixel-aspect-ratio or framerate) it can do so on the returned `VideoCodecState`. + +The new output state will only take effect (set on pads and buffers) starting +from the next call to `VideoEncoder::finish_frame`(). +## `caps` +the `gst::Caps` to use for the output +## `reference` +An optional reference `VideoCodecState` + +# Returns + +the newly configured output state. + +Configures `self` to handle Quality-of-Service events from downstream. + +Feature: `v1_14` + +## `enabled` +the new qos value. Field order of interlaced content. This is only valid for interlace-mode=interleaved and not interlace-mode=mixed. In the case of @@ -108,6 +893,9 @@ to implement frame dropping. [`gst_base::BaseTransformExt`](../gst_base/trait.BaseTransformExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Enum value describing the most common video formats. + +See the [GStreamer raw video format design document](https://gstreamer.freedesktop.org/documentation/design/mediatype-video-raw.html`formats`) +for details about the layout and packing of these formats in memory. Unknown or unset video format id @@ -142,9 +930,9 @@ rgb with alpha channel first reverse rgb with alpha channel first -rgb +RGB packed into 24 bits without padding (`R-G-B-R-G-B`) -reverse rgb +reverse RGB packed into 24 bits without padding (`B-G-R-B-G-R`) planar 4:1:1 YUV @@ -238,7 +1026,7 @@ planar 4:2:0 YUV with interleaved UV plane, 10 bits per channel (Since: 1.10) planar 4:2:0 YUV with interleaved UV plane, 10 bits per channel (Since: 1.10) -packed 4:4:4 YUV (U-Y-V ...) (Since 1.10) +packed 4:4:4 YUV (U-Y-V ...) (Since: 1.10) packed 4:2:2 YUV (V0-Y0-U0-Y1 V2-Y2-U2-Y3 V4 ...) @@ -273,6 +1061,16 @@ planar 4:4:4 YUV, 12 bits per channel (Since: 1.12) 10-bit variant of `VideoFormat::Nv12`, packed into 32bit words (MSB 2 bits padding) (Since: 1.14) 10-bit variant of `VideoFormat::Nv16`, packed into 32bit words (MSB 2 bits padding) (Since: 1.14) + +Fully packed variant of NV12_10LE32 (Since: 1.16) + +packed 4:2:2 YUV, 10 bits per channel (Since: 1.16) + +packed 4:4:4 YUV, 10 bits per channel(A-V-Y-U...) (Since: 1.16) + +packed 4:4:4 YUV with alpha channel (V0-U0-Y0-A0...) (Since: 1.16) + +packed 4:4:4 RGB with alpha channel(B-G-R-A), 10 bits for R/G/B channel and MSB 2 bits for alpha channel (Since: 1.16) Information for a video format. @@ -461,6 +1259,25 @@ a height `false` if the returned video info is invalid, e.g. because the size of a frame can't be represented as a 32 bit integer (Since: 1.12) + +Same as `VideoInfo::set_format` but also allowing to set the interlaced +mode. + +Feature: `v1_16` + +## `format` +the format +## `mode` +a `VideoInterlaceMode` +## `width` +a width +## `height` +a height + +# Returns + +`false` if the returned video info is invalid, e.g. because the + size of a frame can't be represented as a 32 bit integer. Convert the values of `self` into a `gst::Caps`. @@ -486,6 +1303,12 @@ frames contains both interlaced and Each field has only half the amount of lines as noted in the height property. This mode requires multiple GstVideoMeta metadata to describe the fields. + +1 field is stored in one buffer, + `GST_VIDEO_BUFFER_FLAG_TF` or `GST_VIDEO_BUFFER_FLAG_BF` indicates if + the buffer is carrying the top or bottom field, respectively. The top and + bottom buffers are expected to alternate in the pipeline, with this mode + (Since: 1.16). `VideoMultiviewFramePacking` represents the subset of `VideoMultiviewMode` values that can be applied to any video frame without needing extra metadata. @@ -854,7 +1677,8 @@ interface that want the render rectangle to be controllable using properties. This helper will install "render-rectangle" property into the class. -Since 1.14 +Feature: `v1_14` + ## `oclass` The class on which the properties will be installed ## `last_prop_id` @@ -864,6 +1688,9 @@ This helper shall be used by classes implementing the `VideoOverlay` interface that want the render rectangle to be controllable using properties. This helper will parse and set the render rectangle calling `VideoOverlay::set_render_rectangle`. + +Feature: `v1_14` + ## `object` The instance on which the property is set ## `last_prop_id` @@ -876,8 +1703,6 @@ The `gobject::Value` to be set # Returns `true` if the `property_id` matches the GstVideoOverlay property - -Since 1.14 Tell an overlay that it has been exposed. This will redraw the current frame in the drawable even if the pipeline is PAUSED. @@ -989,11 +1814,15 @@ Feature: `v1_10` # Returns -a new empty `VideoTimeCode` +a new empty, invalid `VideoTimeCode` The resulting config->latest_daily_jam is set to midnight, and timecode is set to the given time. +This might return a completely invalid timecode, use +`VideoTimeCode::new_from_date_time_full` to ensure +that you would get `None` instead in that case. + Feature: `v1_12` ## `fps_n` @@ -1009,7 +1838,28 @@ Interlaced video field count # Returns -the `GVideoTimeCode` representation of `dt`. +the `VideoTimeCode` representation of `dt`. + +The resulting config->latest_daily_jam is set to +midnight, and timecode is set to the given time. + +Feature: `v1_16` + +## `fps_n` +Numerator of the frame rate +## `fps_d` +Denominator of the frame rate +## `dt` +`glib::DateTime` to convert +## `flags` +`VideoTimeCodeFlags` +## `field_count` +Interlaced video field count + +# Returns + +the `VideoTimeCode` representation of `dt`, or `None` if + no valid timecode could be created. Feature: `v1_12` @@ -1019,7 +1869,8 @@ The string that represents the `VideoTimeCode` # Returns -a new `VideoTimeCode` from the given string +a new `VideoTimeCode` from the given string or `None` + if the string could not be passed. Adds or subtracts `frames` amount of frames to `self`. tc needs to contain valid data, as verified by `VideoTimeCode::is_valid`. @@ -1047,21 +1898,23 @@ be dropped. These are then corrected to the next reasonable timecode. # Returns -A new `VideoTimeCode` with `tc_inter` added. +A new `VideoTimeCode` with `tc_inter` added or `None` + if the interval can't be added. -Initializes `self` with empty/zero/NULL values. +Initializes `self` with empty/zero/NULL values and frees any memory +it might currently use. Feature: `v1_10` -Compares `self` and `tc2` . If both have latest daily jam information, it is +Compares `self` and `tc2`. If both have latest daily jam information, it is taken into account. Otherwise, it is assumed that the daily jam of both `self` and `tc2` was at the same time. Both time codes must be valid. Feature: `v1_10` ## `tc2` -another `VideoTimeCode` +another valid `VideoTimeCode` # Returns @@ -1073,7 +1926,7 @@ Feature: `v1_10` # Returns -a new `VideoTimeCode` with the same values as `self` . +a new `VideoTimeCode` with the same values as `self`. Feature: `v1_10` @@ -1081,14 +1934,14 @@ Feature: `v1_10` # Returns -how many frames have passed since the daily jam of `self` . +how many frames have passed since the daily jam of `self`. -Frees `self` . +Frees `self`. Feature: `v1_10` -Adds one frame to `self` . +Adds one frame to `self`. Feature: `v1_10` @@ -1121,8 +1974,11 @@ the frames field of `VideoTimeCode` ## `field_count` Interlaced video field count -The resulting config->latest_daily_jam is set to -midnight, and timecode is set to the given time. +The resulting config->latest_daily_jam is set to midnight, and timecode is +set to the given time. + +Will assert on invalid parameters, use `VideoTimeCode::init_from_date_time_full` +for being able to handle invalid parameters. Feature: `v1_12` @@ -1136,6 +1992,26 @@ Denominator of the frame rate `VideoTimeCodeFlags` ## `field_count` Interlaced video field count + +The resulting config->latest_daily_jam is set to +midnight, and timecode is set to the given time. + +Feature: `v1_16` + +## `fps_n` +Numerator of the frame rate +## `fps_d` +Denominator of the frame rate +## `dt` +`glib::DateTime` to convert +## `flags` +`VideoTimeCodeFlags` +## `field_count` +Interlaced video field count + +# Returns + +`true` if `self` could be correctly initialized to a valid timecode Feature: `v1_10` @@ -1152,7 +2028,7 @@ Feature: `v1_10` # Returns -how many nsec have passed since the daily jam of `self` . +how many nsec have passed since the daily jam of `self`. The `self.config`->latest_daily_jam is required to be non-NULL. @@ -1161,7 +2037,8 @@ Feature: `v1_10` # Returns -the `glib::DateTime` representation of `self`. +the `glib::DateTime` representation of `self` or `None` if `self` + has no daily jam. Feature: `v1_10` @@ -1170,7 +2047,7 @@ Feature: `v1_10` # Returns the SMPTE ST 2059-1:2015 string representation of `self`. That will -take the form hh:mm:ss:ff . The last separator (between seconds and frames) +take the form hh:mm:ss:ff. The last separator (between seconds and frames) may vary: ';' for drop-frame, non-interlaced content and for drop-frame interlaced @@ -1211,6 +2088,7 @@ The string that represents the `VideoTimeCodeInterval` # Returns a new `VideoTimeCodeInterval` from the given string + or `None` if the string could not be passed. Initializes `self` with empty/zero/NULL values. @@ -1223,9 +2101,9 @@ Feature: `v1_12` # Returns -a new `VideoTimeCodeInterval` with the same values as `self` . +a new `VideoTimeCodeInterval` with the same values as `self`. -Frees `self` . +Frees `self`. Feature: `v1_12` diff --git a/docs/gstreamer/docs.md b/docs/gstreamer/docs.md index 294385d59..8a9b7c17f 100644 --- a/docs/gstreamer/docs.md +++ b/docs/gstreamer/docs.md @@ -1,4 +1,74 @@ + +Memory is usually created by allocators with a `AllocatorExt::alloc` +method call. When `None` is used as the allocator, the default allocator will +be used. + +New allocators can be registered with `Allocator::register`. +Allocators are identified by name and can be retrieved with +`Allocator::find`. `AllocatorExt::set_default` can be used to change the +default allocator. + +New memory can be created with `Memory::new_wrapped` that wraps the memory +allocated elsewhere. + +# Implements + +[`AllocatorExt`](trait.AllocatorExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) + +Trait containing all `Allocator` methods. + +# Implementors + +[`Allocator`](struct.Allocator.html) + +Find a previously registered allocator with `name`. When `name` is `None`, the +default allocator will be returned. +## `name` +the name of the allocator + +# Returns + +a `Allocator` or `None` when +the allocator with `name` was not registered. Use `GstObjectExt::unref` +to release the allocator after usage. + +Registers the memory `allocator` with `name`. This function takes ownership of +`allocator`. +## `name` +the name of the allocator +## `allocator` +`Allocator` + +Use `self` to allocate a new memory block with memory that is at least +`size` big. + +The optional `params` can specify the prefix and padding for the memory. If +`None` is passed, no flags, no extra prefix/padding and a default alignment is +used. + +The prefix/padding will be filled with 0 if flags contains +`MemoryFlags::ZeroPrefixed` and `MemoryFlags::ZeroPadded` respectively. + +When `self` is `None`, the default allocator will be used. + +The alignment in `params` is given as a bitmask so that `align` + 1 equals +the amount of bytes to align to. For example, to align to 8 bytes, +use an alignment of 7. +## `size` +size of the visible memory area +## `params` +optional parameters + +# Returns + +a new `Memory`. + +Free `memory` that was previously allocated with `AllocatorExt::alloc`. +## `memory` +the memory to free + +Set the default allocator. This function takes ownership of `self`. `Bin` is an element that can contain other `Element`, allowing them to be managed as a group. @@ -487,7 +557,7 @@ to hold a reference to another buffer that is only released when the child Typically, `ParentBufferMeta` is used when the child buffer is directly using the `Memory` of the parent buffer, and wants to prevent the parent buffer from being returned to a buffer pool until the `Memory` is available -for re-use. (Since 1.6) +for re-use. (Since: 1.6) Creates a newly allocated buffer without any data. @@ -531,6 +601,20 @@ allocated size of `data` # Returns a new `Buffer` + +Creates a new `Buffer` that wraps the given `bytes`. The data inside +`bytes` cannot be `None` and the resulting buffer will be marked as read only. + +MT safe. + +Feature: `v1_16` + +## `bytes` +a `glib::Bytes` to wrap + +# Returns + +a new `Buffer` wrapping `bytes` Allocate a new buffer that wraps the given memory. `data` must point to `maxsize` of memory, the wrapped buffer will have the region from `offset` and @@ -2111,9 +2195,25 @@ a `Caps` to intersect # Returns `true` if intersection would be not empty + +Creates a new `Caps` as a copy of the old `self`. The new caps will have a +refcount of 1, owned by the caller. The structures are copied as well. + +Note that this function is the semantic equivalent of a `gst_caps_ref` +followed by a `gst_caps_make_writable`. If you only want to hold on to a +reference to the data, you should use `gst_caps_ref`. + +When you are finished with the caps, call `gst_caps_unref` on it. + +# Returns + +the new `Caps` Creates a new `Caps` and appends a copy of the nth structure contained in `self`. + +Feature: `v1_16` + ## `nth` the nth structure to copy @@ -2373,6 +2473,13 @@ Index of the structure to remove Sets the `CapsFeatures` `features` for the structure at `index`. ## `index` the index of the structure +## `features` +the `CapsFeatures` to set + +Sets the `CapsFeatures` `features` for all the structures of `self`. + +Feature: `v1_16` + ## `features` the `CapsFeatures` to set @@ -2722,6 +2829,20 @@ A `ClockID` to compare with negative value if a < b; zero if a = b; positive value if a > b +MT safe. + +This function returns the underlying clock. + +Feature: `v1_16` + +## `id` +a `ClockID` + +# Returns + +a `Clock` or `None` when the + underlying clock has been freed. Unref after usage. + MT safe. Get the time of the clock ID @@ -2759,6 +2880,24 @@ async notifications, you need to create a new `ClockID`. MT safe. ## `id` The id to unschedule + +This function returns whether `id` uses `clock` as the underlying clock. +`clock` can be NULL, in which case the return value indicates whether +the underlying clock has been freed. If this is the case, the `id` is +no longer usable and should be freed. + +Feature: `v1_16` + +## `id` +a `ClockID` to check +## `clock` +a `Clock` to compare against + +# Returns + +whether the clock `id` uses the same underlying `Clock` `clock`. + +MT safe. Perform a blocking wait on `id`. `id` should have been created with `ClockExt::new_single_shot_id` @@ -3186,7 +3325,7 @@ time since Epoch monotonic time since some unspecified starting point -some other time source is used (Since 1.0.5) +some other time source is used (Since: 1.0.5) `Context` is a container object used to store contexts like a device context, a display server connection and similar concepts that should @@ -3501,7 +3640,7 @@ the day of the gregorian month the newly created `DateTime` Returns the day of the month of this `DateTime`. -Call gst_date_time_has_day before, to avoid warnings. +Call `DateTime::has_day` before, to avoid warnings. # Returns @@ -3509,7 +3648,7 @@ The day of this `DateTime` Retrieves the hour of the day represented by `self` in the gregorian calendar. The return is in the range of 0 to 23. -Call gst_date_time_has_haur before, to avoid warnings. +Call `DateTime::has_time` before, to avoid warnings. # Returns @@ -3524,14 +3663,14 @@ the microsecond of the second Retrieves the minute of the hour represented by `self` in the gregorian calendar. -Call gst_date_time_has_minute before, to avoid warnings. +Call `DateTime::has_time` before, to avoid warnings. # Returns the minute of the hour Returns the month of this `DateTime`. January is 1, February is 2, etc.. -Call gst_date_time_has_month before, to avoid warnings. +Call `DateTime::has_month` before, to avoid warnings. # Returns @@ -3539,7 +3678,7 @@ The month of this `DateTime` Retrieves the second of the minute represented by `self` in the gregorian calendar. -Call gst_date_time_has_second before, to avoid warnings. +Call `DateTime::has_time` before, to avoid warnings. # Returns @@ -3555,7 +3694,7 @@ If `self` represents UTC time, then the offset is zero. the offset from UTC in hours Returns the year of this `DateTime` -Call gst_date_time_has_year before, to avoid warnings. +Call `DateTime::has_year` before, to avoid warnings. # Returns @@ -3911,7 +4050,7 @@ will be emitted on the bus when the list of devices changes. Stops monitoring the devices. A `DeviceProvider` subclass is provided by a plugin that handles devices -if there is a way to programatically list connected devices. It can also +if there is a way to programmatically list connected devices. It can also optionally provide updates to the list of connected devices. Each `DeviceProvider` subclass is a singleton, a plugin should @@ -3955,6 +4094,19 @@ This is for use by subclasses. will be removed (see `Object::ref_sink`). ## `device` a `Device` that has been added + +This function is used when `changed_device` was modified into its new form +`device`. This will post a `DEVICE_CHANGED` message on the bus to let +the application know that the device was modified. `Device` is immutable +for MT. safety purposes so this is an "atomic" way of letting the application +know when a device was modified. + +Feature: `v1_16` + +## `device` +the new version of `changed_device` +## `changed_device` +the old version of the device that has been udpated Posts a message on the provider's `Bus` to inform applications that a device has been removed. @@ -4250,9 +4402,8 @@ MT safe. Adds a pad (link point) to `self`. `pad`'s parent will be set to `self`; see `GstObjectExt::set_parent` for refcounting information. -Pads are not automatically activated so elements should perform the needed -steps to activate the pad in case this pad is added in the PAUSED or PLAYING -state. See `PadExt::set_active` for more information about activating pads. +Pads are automatically activated when added in the PAUSED or PLAYING +state. The pad and the element should be unlocked when calling this function. @@ -4503,7 +4654,7 @@ Retrieves the factory that was used to create this element. # Returns the `ElementFactory` used for creating this - element. no refcounting is needed. + element or `None` if element has not been registered (static element). no refcounting is needed. Get metadata with `key` in `klass`. @@ -5113,6 +5264,10 @@ the `Context` to set. Locks the state of an element, so state changes of the parent don't affect this element anymore. +Note that this is racy if the state lock of the parent bin is not taken. +The parent bin might've just checked the flag in another thread and as the +next step proceed to change the child element's state. + MT safe. ## `locked_state` `true` to lock the element's state @@ -6106,6 +6261,12 @@ result location for the start position expressed in `format` result location for the `SeekType` of the stop position ## `stop` result location for the stop position expressed in `format` + +Retrieve the trickmode interval that may have been set on a +seek event with `Event::set_seek_trickmode_interval`. + +Feature: `v1_16` + Parses a segment `self` and stores the result in the given `segment` location. `segment` remains valid only until the `self` is freed. Don't modify the segment @@ -6148,7 +6309,7 @@ Parse a stream-start `self` and extract the `Stream` from it. Feature: `v1_10` ## `stream` -adress of variable to store the stream +address of variable to store the stream Retrieve new `StreamCollection` from STREAM_COLLECTION event `self`. @@ -6208,6 +6369,13 @@ Set the running time offset of a event. See MT safe. ## `offset` A the new running time offset + +Sets a trickmode interval on a (writable) seek event. Elements +that support TRICKMODE_KEY_UNITS seeks SHOULD use this as the minimal +interval between each frame they may output. + +Feature: `v1_16` + Set the sequence number of a event. @@ -6268,7 +6436,7 @@ A new media segment follows in the dataflow. The converting buffer timestamps to running-time and stream-time. -A new `StreamCollection` is available (Since 1.10) +A new `StreamCollection` is available (Since: 1.10) A new set of metadata tags has been found in the stream. @@ -6281,7 +6449,7 @@ An event that sinks turn into a message. Used to Indicates that there is no more data for the stream group ID in the message. Sent before EOS - in some instances and should be handled mostly the same. (Since 1.10) + in some instances and should be handled mostly the same. (Since: 1.10) End-Of-Stream. No more data is to be expected to follow without either a STREAM_START event, or a FLUSH_STOP and a SEGMENT @@ -6318,7 +6486,7 @@ A request for upstream renegotiating caps and reconfiguring. A request for a new playback position based on TOC entry's UID. -A request to select one or more streams (Since 1.10) +A request to select one or more streams (Since: 1.10) Upstream custom event @@ -6693,6 +6861,22 @@ The new `Device` # Returns +a newly allocated `Message` + +Creates a new device-changed message. The device-changed message is produced +by `DeviceProvider` or a `DeviceMonitor`. They announce that a device +properties has changed and `device` represent the new modified version of `changed_device`. + +Feature: `v1_16` + +## `src` +The `Object` that created the message +## `device` +The newly created device representing `replaced_device` + with its new configuration. + +# Returns + a newly allocated `Message` Creates a new device-removed message. The device-removed message is produced @@ -6779,7 +6963,7 @@ The GError for this message. ## `debug` A debugging string. ## `details` -(allow-none): A GstStructure with details +A GstStructure with details # Returns @@ -6824,7 +7008,7 @@ The GError for this message. ## `debug` A debugging string. ## `details` -(allow-none): A GstStructure with details +A GstStructure with details # Returns @@ -7258,7 +7442,7 @@ The GError for this message. ## `debug` A debugging string. ## `details` -(allow-none): A GstStructure with details +A GstStructure with details # Returns @@ -7388,6 +7572,20 @@ of monitored devices. ## `device` A location where to store a pointer to the new `Device`, or `None` + +Parses a device-changed message. The device-changed message is produced by +`DeviceProvider` or a `DeviceMonitor`. It announces the +disappearance of monitored devices. * It announce that a device properties has +changed and `device` represents the new modified version of `changed_device`. + +Feature: `v1_16` + +## `device` +A location where to store a + pointer to the updated version of the `Device`, or `None` +## `changed_device` +A location where to store a + pointer to the old version of the `Device`, or `None` Parses a device-removed message. The device-removed message is produced by `DeviceProvider` or a `DeviceMonitor`. It announces the @@ -7931,7 +8129,7 @@ Trait containing all `Object` methods. # Implementors -[`BufferPool`](struct.BufferPool.html), [`Bus`](struct.Bus.html), [`Clock`](struct.Clock.html), [`DeviceMonitor`](struct.DeviceMonitor.html), [`DeviceProvider`](struct.DeviceProvider.html), [`Device`](struct.Device.html), [`Element`](struct.Element.html), [`Object`](struct.Object.html), [`PadTemplate`](struct.PadTemplate.html), [`Pad`](struct.Pad.html), [`PluginFeature`](struct.PluginFeature.html), [`Plugin`](struct.Plugin.html), [`Registry`](struct.Registry.html), [`StreamCollection`](struct.StreamCollection.html), [`Stream`](struct.Stream.html) +[`Allocator`](struct.Allocator.html), [`BufferPool`](struct.BufferPool.html), [`Bus`](struct.Bus.html), [`Clock`](struct.Clock.html), [`DeviceMonitor`](struct.DeviceMonitor.html), [`DeviceProvider`](struct.DeviceProvider.html), [`Device`](struct.Device.html), [`Element`](struct.Element.html), [`Object`](struct.Object.html), [`PadTemplate`](struct.PadTemplate.html), [`Pad`](struct.Pad.html), [`PluginFeature`](struct.PluginFeature.html), [`Plugin`](struct.Plugin.html), [`Registry`](struct.Registry.html), [`StreamCollection`](struct.StreamCollection.html), [`Stream`](struct.Stream.html) Checks to see if there is any object named `name` in `list`. This function does not do any locking of any kind. You might want to protect the @@ -8012,7 +8210,7 @@ the `ControlBinding` that should be used has been setup for a non suitable property, `true` otherwise. A default error function that uses `g_printerr` to display the error message -and the optional debug sting.. +and the optional debug string.. The default handler will simply print the error string using g_print. ## `error` @@ -8032,7 +8230,7 @@ the `ControlBinding` for Obtain the control-rate for this `self`. Audio processing `Element` objects will use this rate to sub-divide their processing loop and call -`GstObjectExt::sync_values` inbetween. The length of the processing segment +`GstObjectExt::sync_values` in between. The length of the processing segment should be up to `control`-rate nanoseconds. If the `self` is not under property control, this will return @@ -8221,7 +8419,7 @@ or not. Change the control-rate for this `self`. Audio processing `Element` objects will use this rate to sub-divide their processing loop and call -`GstObjectExt::sync_values` inbetween. The length of the processing segment +`GstObjectExt::sync_values` in between. The length of the processing segment should be up to `control`-rate nanoseconds. The control-rate should not change if the element is in `State::Paused` or @@ -9430,6 +9628,10 @@ notify called when `query` will not be used anymore. Sets the given unlink function for the pad. It will be called when the pad is unlinked. + +Note that the pad's lock is already held when the unlink +function is called, so most pad functions cannot be called +from within the callback. ## `unlink` the `GstPadUnlinkFunction` to set. ## `user_data` @@ -10417,7 +10619,7 @@ a list of presets individual presets are read and overlaid in 1) system, 2) application and 3) user order. Whenever an earlier entry is newer, the later entries will be updated. Since 1.8 you can also provide extra paths where to find presets through the GST_PRESET_PATH environment variable. -Presets found in those paths will be concidered as "app presets". +Presets found in those paths will be considered as "app presets". # Implements @@ -10822,6 +11024,17 @@ the negotiated caps ## `need_pool` return a pool +# Returns + +a new `Query` + +Constructs a new query object for querying the bitrate. + +Free-function: `gst_query_unref` + +Feature: `v1_16` + + # Returns a new `Query` @@ -11138,6 +11351,13 @@ Pool details can be retrieved using `Query::get_n_allocation_pools` and The `Caps` ## `need_pool` Whether a `BufferPool` is needed + +Get the results of a bitrate query. See also `Query::set_bitrate`. + +Feature: `v1_16` + +## `nominal_bitrate` +The resulting bitrate in bits per second Get the percentage of buffered data. This is a value between 0 and 100. The `busy` indicator is `true` when the buffering is in progress. @@ -11374,6 +11594,15 @@ position in the allocation pool array to remove Set `result` as the result for the `self`. ## `result` the result to set + +Set the results of a bitrate query. The nominal bitrate is the average +bitrate expected over the length of the stream as advertised in file +headers (or similar). + +Feature: `v1_16` + +## `nominal_bitrate` +the nominal bitrate in bits per second Set the percentage of buffered data. This is a value between 0 and 100. The `busy` indicator is `true` when the buffering is in progress. @@ -11875,7 +12104,7 @@ used when the resource has no space left. used when the resource can't be opened due to missing authorization. - (Since 1.2.4) + (Since: 1.2.4) the number of resource error types. @@ -11939,10 +12168,39 @@ Get the segment associated with `self` the segment of `self`. The segment remains valid as long as `self` is valid. + +Set the buffer associated with `self`. `self` must be writable. + +Feature: `v1_16` + +## `buffer` +A `Buffer` -Set the buffer list associated with `self` +Set the buffer list associated with `self`. `self` must be writable. ## `buffer_list` a `BufferList` + +Set the caps associated with `self`. `self` must be writable. + +Feature: `v1_16` + +## `caps` +A `Caps` + +Set the info structure associated with `self`. `self` must be writable, +and `info` must not have a parent set already. + +Feature: `v1_16` + +## `info` +A `Structure` + +Set the segment associated with `self`. `self` must be writable. + +Feature: `v1_16` + +## `segment` +A `Segment` The different types of seek events. When constructing a seek event with `Event::new_seek` or when doing gst_segment_do_seek (). @@ -12259,7 +12517,7 @@ segment. Compared to `Segment::to_running_time` this function can return negative running-time. This function is typically used by elements that need to synchronize buffers -against the clock or eachother. +against the clock or each other. `position` can be any value and the result of this function for values outside of the segment is extrapolated. @@ -12305,7 +12563,7 @@ segment. Compared to `Segment::to_stream_time` this function can return negative stream-time. This function is typically used by elements that need to synchronize buffers -against the clock or eachother. +against the clock or each other. `position` can be any value and the result of this function for values outside of the segment is extrapolated. @@ -12406,17 +12664,17 @@ state change from READY to NULL. * Elements close devices * Elements reset any internal state. -state change from NULL to NULL. (Since 1.14) +state change from NULL to NULL. (Since: 1.14) state change from READY to READY, This might happen when going to PAUSED asynchronously failed, in that case -elements should make sure they are in a proper, coherent READY state. (Since 1.14) +elements should make sure they are in a proper, coherent READY state. (Since: 1.14) state change from PAUSED to PAUSED. This might happen when elements were in PLAYING state and 'lost state', -they should make sure to go back to real 'PAUSED' state (prerolling for example). (Since 1.14) +they should make sure to go back to real 'PAUSED' state (prerolling for example). (Since: 1.14) -state change from PLAYING to PLAYING. (Since 1.14) +state change from PLAYING to PLAYING. (Since: 1.14) The possible return values from a state change function such as `Element::set_state`. Only `StateChangeReturn::Failure` is a real failure. @@ -12982,9 +13240,9 @@ the name of the first field to read than the type specified), otherwise `true`. This is useful in language bindings where unknown `gobject::Value` types are not -supported. This function will convert the `GST_TYPE_ARRAY` and -`GST_TYPE_LIST` into a newly allocated `gobject::ValueArray` and return it through -`array`. Be aware that this is slower then getting the `gobject::Value` directly. +supported. This function will convert the `GST_TYPE_ARRAY` into a newly +allocated `gobject::ValueArray` and return it through `array`. Be aware that this is +slower then getting the `gobject::Value` directly. ## `fieldname` the name of a field ## `array` @@ -12993,8 +13251,8 @@ a pointer to a `gobject::ValueArray` # Returns `true` if the value could be set correctly. If there was no field -with `fieldname` or the existing field did not contain an int, this function -returns `false`. +with `fieldname` or the existing field did not contain a `GST_TYPE_ARRAY`, +this function returns `false`. Sets the boolean pointed to by `value` corresponding to the value of the given field. Caller is responsible for making sure the field exists @@ -13162,9 +13420,12 @@ with `fieldname` or the existing field did not contain a `gint64`, this function returns `false`. This is useful in language bindings where unknown `gobject::Value` types are not -supported. This function will convert the `GST_TYPE_ARRAY` and -`GST_TYPE_LIST` into a newly allocated GValueArray and return it through -`array`. Be aware that this is slower then getting the `gobject::Value` directly. +supported. This function will convert the `GST_TYPE_LIST` into a newly +allocated GValueArray and return it through `array`. Be aware that this is +slower then getting the `gobject::Value` directly. + +Feature: `v1_12` + ## `fieldname` the name of a field ## `array` @@ -13173,10 +13434,8 @@ a pointer to a `gobject::ValueArray` # Returns `true` if the value could be set correctly. If there was no field -with `fieldname` or the existing field did not contain an int, this function -returns `false`. - -Since 1.12 +with `fieldname` or the existing field did not contain a `GST_TYPE_LIST`, this +function returns `false`. Get the name of `self` as a string. @@ -13455,18 +13714,20 @@ supported. This function will convert a `array` to `GST_TYPE_ARRAY` and set the field specified by `fieldname`. Be aware that this is slower then using `GST_TYPE_ARRAY` in a `gobject::Value` directly. -Since 1.12 +Feature: `v1_12` + ## `fieldname` the name of a field ## `array` a pointer to a `gobject::ValueArray` This is useful in language bindings where unknown GValue types are not -supported. This function will convert a `array` to `GST_TYPE_ARRAY` and set +supported. This function will convert a `array` to `GST_TYPE_LIST` and set the field specified by `fieldname`. Be aware that this is slower then using -`GST_TYPE_ARRAY` in a `gobject::Value` directly. +`GST_TYPE_LIST` in a `gobject::Value` directly. + +Feature: `v1_12` -Since 1.12 ## `fieldname` the name of a field ## `array` @@ -14263,6 +14524,13 @@ keep existing tags keep all existing tags the number of merge modes + +GstTagScope specifies if a taglist applies to the complete +medium or only to one single stream. + +tags specific to this single stream + +global tags for the complete medium Element interface that allows setting of media metadata. @@ -14685,7 +14953,7 @@ unreffed before setting a new one. ## `toc` a `Toc` to set. -These functions allow querying informations about registered typefind +These functions allow querying information about registered typefind functions. How to create and register these functions is described in the section "Writing typefind functions"``.