`Bin` is an element that can contain other `Element`, allowing them to be managed as a group. Pads from the child elements can be ghosted to the bin, see `GhostPad`. This makes the bin look like any other elements and enables creation of higher-level abstraction elements. A new `Bin` is created with `Bin::new`. Use a `Pipeline` instead if you want to create a toplevel bin because a normal bin doesn't have a bus or handle clock distribution of its own. After the bin has been created you will typically add elements to it with `BinExt::add`. You can remove elements with `BinExt::remove`. An element can be retrieved from a bin with `BinExt::get_by_name`, using the elements name. `BinExt::get_by_name_recurse_up` is mainly used for internal purposes and will query the parent bins when the element is not found in the current bin. An iterator of elements in a bin can be retrieved with `BinExt::iterate_elements`. Various other iterators exist to retrieve the elements in a bin. `GstObjectExt::unref` is used to drop your reference to the bin. The `Bin::element-added` signal is fired whenever a new element is added to the bin. Likewise the `Bin::element-removed` signal is fired whenever an element is removed from the bin. ## Notes A `Bin` internally intercepts every `Message` posted by its children and implements the following default behaviour for each of them: * GST_MESSAGE_EOS: This message is only posted by sinks in the PLAYING state. If all sinks posted the EOS message, this bin will post and EOS message upwards. * GST_MESSAGE_SEGMENT_START: Just collected and never forwarded upwards. The messages are used to decide when all elements have completed playback of their segment. * GST_MESSAGE_SEGMENT_DONE: Is posted by `Bin` when all elements that posted a SEGMENT_START have posted a SEGMENT_DONE. * GST_MESSAGE_DURATION_CHANGED: Is posted by an element that detected a change in the stream duration. The default bin behaviour is to clear any cached duration values so that the next duration query will perform a full duration recalculation. The duration change is posted to the application so that it can refetch the new duration with a duration query. Note that these messages can be posted before the bin is prerolled, in which case the duration query might fail. * GST_MESSAGE_CLOCK_LOST: This message is posted by an element when it can no longer provide a clock. The default bin behaviour is to check if the lost clock was the one provided by the bin. If so and the bin is currently in the PLAYING state, the message is forwarded to the bin parent. This message is also generated when a clock provider is removed from the bin. If this message is received by the application, it should PAUSE the pipeline and set it back to PLAYING to force a new clock distribution. * GST_MESSAGE_CLOCK_PROVIDE: This message is generated when an element can provide a clock. This mostly happens when a new clock provider is added to the bin. The default behaviour of the bin is to mark the currently selected clock as dirty, which will perform a clock recalculation the next time the bin is asked to provide a clock. This message is never sent tot the application but is forwarded to the parent of the bin. * OTHERS: posted upwards. A `Bin` implements the following default behaviour for answering to a `Query`: * GST_QUERY_DURATION:If the query has been asked before with the same format and the bin is a toplevel bin (ie. has no parent), use the cached previous value. If no previous value was cached, the query is sent to all sink elements in the bin and the MAXIMUM of all values is returned. If the bin is a toplevel bin the value is cached. If no sinks are available in the bin, the query fails. * GST_QUERY_POSITION:The query is sent to all sink elements in the bin and the MAXIMUM of all values is returned. If no sinks are available in the bin, the query fails. * OTHERS:the query is forwarded to all sink elements, the result of the first sink that answers the query successfully is returned. If no sink is in the bin, the query fails. A `Bin` will by default forward any event sent to it to all sink (`EventTypeFlags::Downstream`) or source (`EventTypeFlags::Upstream`) elements depending on the event type. If all the elements return `true`, the bin will also return `true`, else `false` is returned. If no elements of the required type are in the bin, the event handler will return `true`. # Implements [`BinExt`](trait.BinExt.html), [`ElementExt`](trait.ElementExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ChildProxyExt`](trait.ChildProxyExt.html) Trait containing all `Bin` methods. # Implementors [`Bin`](struct.Bin.html), [`Pipeline`](struct.Pipeline.html) Creates a new bin with the given name. ## `name` the name of the new bin # Returns a new `Bin` Adds the given element to the bin. Sets the element's parent, and thus takes ownership of the element. An element can only be added to one bin. If the element's pads are linked to other pads, the pads will be unlinked before the element is added to the bin. > When you add an element to an already-running pipeline, you will have to > take care to set the state of the newly-added element to the desired > state (usually PLAYING or PAUSED, same you set the pipeline to originally) > with `ElementExt::set_state`, or use `ElementExt::sync_state_with_parent`. > The bin or pipeline will not take care of this for you. MT safe. ## `element` the `Element` to add # Returns `true` if the element could be added, `false` if the bin does not want to accept the element. Adds a `None`-terminated list of elements to a bin. This function is equivalent to calling `BinExt::add` for each member of the list. The return value of each `BinExt::add` is ignored. ## `element_1` the `Element` element to add to the bin Recursively looks for elements with an unlinked pad of the given direction within the specified bin and returns an unlinked pad if one is found, or `None` otherwise. If a pad is found, the caller owns a reference to it and should use `GstObjectExt::unref` on the pad when it is not needed any longer. ## `direction` whether to look for an unlinked source or sink pad # Returns unlinked pad of the given direction, `None`. Looks for an element inside the bin that implements the given interface. If such an element is found, it returns the element. You can cast this element to the given interface afterwards. If you want all elements that implement the interface, use `BinExt::iterate_all_by_interface`. This function recurses into child bins. MT safe. Caller owns returned reference. ## `iface` the `glib::Type` of an interface # Returns A `Element` inside the bin implementing the interface Gets the element with the given name from a bin. This function recurses into child bins. Returns `None` if no element with the given name is found in the bin. MT safe. Caller owns returned reference. ## `name` the element name to search for # Returns the `Element` with the given name, or `None` Gets the element with the given name from this bin. If the element is not found, a recursion is performed on the parent bin. Returns `None` if: - no element with the given name is found in the bin MT safe. Caller owns returned reference. ## `name` the element name to search for # Returns the `Element` with the given name, or `None` Return the suppressed flags of the bin. MT safe. Feature: `v1_10` # Returns the bin's suppressed `ElementFlags`. Looks for all elements inside the bin that implements the given interface. You can safely cast all returned elements to the given interface. The function recurses inside child bins. The iterator will yield a series of `Element` that should be unreffed after use. MT safe. Caller owns returned value. ## `iface` the `glib::Type` of an interface # Returns a `Iterator` of `Element` for all elements in the bin implementing the given interface, or `None` Gets an iterator for the elements in this bin. MT safe. Caller owns returned value. # Returns a `Iterator` of `Element`, or `None` Gets an iterator for the elements in this bin. This iterator recurses into GstBin children. MT safe. Caller owns returned value. # Returns a `Iterator` of `Element`, or `None` Gets an iterator for all elements in the bin that have the `ElementFlags::Sink` flag set. MT safe. Caller owns returned value. # Returns a `Iterator` of `Element`, or `None` Gets an iterator for the elements in this bin in topologically sorted order. This means that the elements are returned from the most downstream elements (sinks) to the sources. This function is used internally to perform the state changes of the bin elements and for clock selection. MT safe. Caller owns returned value. # Returns a `Iterator` of `Element`, or `None` Gets an iterator for all elements in the bin that have the `ElementFlags::Source` flag set. MT safe. Caller owns returned value. # Returns a `Iterator` of `Element`, or `None` Query `self` for the current latency using and reconfigures this latency to all the elements with a LATENCY event. This method is typically called on the pipeline when a `MessageType::Latency` is posted on the bus. This function simply emits the 'do-latency' signal so any custom latency calculations will be performed. # Returns `true` if the latency could be queried and reconfigured. Removes the element from the bin, unparenting it as well. Unparenting the element means that the element will be dereferenced, so if the bin holds the only reference to the element, the element will be freed in the process of removing it from the bin. If you want the element to still exist after removing, you need to call `GstObjectExt::ref` before removing it from the bin. If the element's pads are linked to other pads, the pads will be unlinked before the element is removed from the bin. MT safe. ## `element` the `Element` to remove # Returns `true` if the element could be removed, `false` if the bin does not want to remove the element. Remove a list of elements from a bin. This function is equivalent to calling `BinExt::remove` with each member of the list. ## `element_1` the first `Element` to remove from the bin Suppress the given flags on the bin. `ElementFlags` of a child element are propagated when it is added to the bin. When suppressed flags are set, those specified flags will not be propagated to the bin. MT safe. Feature: `v1_10` ## `flags` the `ElementFlags` to suppress Synchronizes the state of every child of `self` with the state of `self`. See also `ElementExt::sync_state_with_parent`. # Returns `true` if syncing the state was successful for all children, otherwise `false`. Will be emitted after the element was added to sub_bin. Feature: `v1_10` ## `sub_bin` the `Bin` the element was added to ## `element` the `Element` that was added to `sub_bin` Will be emitted after the element was removed from sub_bin. Feature: `v1_10` ## `sub_bin` the `Bin` the element was removed from ## `element` the `Element` that was removed from `sub_bin` Will be emitted when the bin needs to perform latency calculations. This signal is only emitted for toplevel bins or when async-handling is enabled. Only one signal handler is invoked. If no signals are connected, the default handler is invoked, which will query and distribute the lowest possible latency to all sinks. Connect to this signal if the default latency calculations are not sufficient, like when you need different latencies for different sinks in the same pipeline. Will be emitted after the element was added to the bin. ## `element` the `Element` that was added to the bin Will be emitted after the element was removed from the bin. ## `element` the `Element` that was removed from the bin If set to `true`, the bin will handle asynchronous state changes. This should be used only if the bin subclass is modifying the state of its children on its own. If set to `true`, the bin will handle asynchronous state changes. This should be used only if the bin subclass is modifying the state of its children on its own. Forward all children messages, even those that would normally be filtered by the bin. This can be interesting when one wants to be notified of the EOS state of individual elements, for example. The messages are converted to an ELEMENT message with the bin as the source. The structure of the message is named 'GstBinForwarded' and contains a field named 'message' of type GST_TYPE_MESSAGE that contains the original forwarded message. Forward all children messages, even those that would normally be filtered by the bin. This can be interesting when one wants to be notified of the EOS state of individual elements, for example. The messages are converted to an ELEMENT message with the bin as the source. The structure of the message is named 'GstBinForwarded' and contains a field named 'message' of type GST_TYPE_MESSAGE that contains the original forwarded message. Buffers are the basic unit of data transfer in GStreamer. They contain the timing and offset along with other arbitrary metadata that is associated with the `Memory` blocks that the buffer contains. Buffers are usually created with `Buffer::new`. After a buffer has been created one will typically allocate memory for it and add it to the buffer. The following example creates a buffer that can hold a given video frame with a given width, height and bits per plane. ```C GstBuffer *buffer; GstMemory *memory; gint size, width, height, bpp; ... size = width * height * bpp; buffer = gst_buffer_new (); memory = gst_allocator_alloc (NULL, size, NULL); gst_buffer_insert_memory (buffer, -1, memory); ... ``` Alternatively, use `Buffer::new_allocate` to create a buffer with preallocated data of a given size. Buffers can contain a list of `Memory` objects. You can retrieve how many memory objects with `Buffer::n_memory` and you can get a pointer to memory with `Buffer::peek_memory` A buffer will usually have timestamps, and a duration, but neither of these are guaranteed (they may be set to `GST_CLOCK_TIME_NONE`). Whenever a meaningful value can be given for these, they should be set. The timestamps and duration are measured in nanoseconds (they are `ClockTime` values). The buffer DTS refers to the timestamp when the buffer should be decoded and is usually monotonically increasing. The buffer PTS refers to the timestamp when the buffer content should be presented to the user and is not always monotonically increasing. A buffer can also have one or both of a start and an end offset. These are media-type specific. For video buffers, the start offset will generally be the frame number. For audio buffers, it will be the number of samples produced so far. For compressed data, it could be the byte offset in a source or destination file. Likewise, the end offset will be the offset of the end of the buffer. These can only be meaningfully interpreted if you know the media type of the buffer (the preceding CAPS event). Either or both can be set to `GST_BUFFER_OFFSET_NONE`. `gst_buffer_ref` is used to increase the refcount of a buffer. This must be done when you want to keep a handle to the buffer after pushing it to the next element. The buffer refcount determines the writability of the buffer, a buffer is only writable when the refcount is exactly 1, i.e. when the caller has the only reference to the buffer. To efficiently create a smaller buffer out of an existing one, you can use `Buffer::copy_region`. This method tries to share the memory objects between the two buffers. If a plug-in wants to modify the buffer data or metadata in-place, it should first obtain a buffer that is safe to modify by using `gst_buffer_make_writable`. This function is optimized so that a copy will only be made when it is necessary. Several flags of the buffer can be set and unset with the GST_BUFFER_FLAG_SET() and GST_BUFFER_FLAG_UNSET() macros. Use GST_BUFFER_FLAG_IS_SET() to test if a certain `BufferFlags` flag is set. Buffers can be efficiently merged into a larger buffer with `Buffer::append`. Copying of memory will only be done when absolutely needed. Arbitrary extra metadata can be set on a buffer with `Buffer::add_meta`. Metadata can be retrieved with `Buffer::get_meta`. See also `Meta` An element should either unref the buffer or push it out on a src pad using `Pad::push` (see `Pad`). Buffers are usually freed by unreffing them with `gst_buffer_unref`. When the refcount drops to 0, any memory and metadata pointed to by the buffer is unreffed as well. Buffers allocated from a `BufferPool` will be returned to the pool when the refcount drops to 0. The `ParentBufferMeta` is a meta which can be attached to a `Buffer` to hold a reference to another buffer that is only released when the child `Buffer` is released. 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) Creates a newly allocated buffer without any data. MT safe. # Returns the new `Buffer`. Tries to create a newly allocated buffer with data of the given size and extra parameters from `allocator`. If the requested amount of memory can't be allocated, `None` will be returned. The allocated buffer memory is not cleared. When `allocator` is `None`, the default memory allocator will be used. Note that when `size` == 0, the buffer will not have memory associated with it. MT safe. ## `allocator` the `Allocator` to use, or `None` to use the default allocator ## `size` the size in bytes of the new buffer's data. ## `params` optional parameters # Returns a new `Buffer`, or `None` if the memory couldn't be allocated. Creates a new buffer that wraps the given `data`. The memory will be freed with g_free and will be marked writable. MT safe. ## `data` data to wrap ## `size` allocated size of `data` # Returns a new `Buffer` 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 `size` visible. When the buffer is destroyed, `notify` will be called with `user_data`. The prefix/padding must be filled with 0 if `flags` contains `MemoryFlags::ZeroPrefixed` and `MemoryFlags::ZeroPadded` respectively. ## `flags` `MemoryFlags` ## `data` data to wrap ## `maxsize` allocated size of `data` ## `offset` offset in `data` ## `size` size of valid data ## `user_data` user_data ## `notify` called with `user_data` when the memory is freed # Returns a new `Buffer` Add metadata for `info` to `self` using the parameters in `params`. ## `info` a `MetaInfo` ## `params` params for `info` # Returns the metadata for the api in `info` on `self`. Add a `ParentBufferMeta` to `self` that holds a reference on `ref_` until the buffer is freed. ## `ref_` a `Buffer` to ref # Returns The `ParentBufferMeta` that was added to the buffer Attaches protection metadata to a `Buffer`. ## `info` a `Structure` holding cryptographic information relating to the sample contained in `self`. This function takes ownership of `info`. # Returns a pointer to the added `ProtectionMeta` if successful; `None` if unsuccessful. Add a `ReferenceTimestampMeta` to `self` that holds a `timestamp` and optionally `duration` based on a specific timestamp `reference`. See the documentation of `ReferenceTimestampMeta` for details. Feature: `v1_14` ## `reference` identifier for the timestamp reference. ## `timestamp` timestamp ## `duration` duration, or `GST_CLOCK_TIME_NONE` # Returns The `ReferenceTimestampMeta` that was added to the buffer Append all the memory from `buf2` to `self`. The result buffer will contain a concatenation of the memory of `self` and `buf2`. ## `buf2` the second source `Buffer` to append. # Returns the new `Buffer` that contains the memory of the two source buffers. Append the memory block `mem` to `self`. This function takes ownership of `mem` and thus doesn't increase its refcount. This function is identical to `Buffer::insert_memory` with an index of -1. See `Buffer::insert_memory` for more details. ## `mem` a `Memory`. Append `size` bytes at `offset` from `buf2` to `self`. The result buffer will contain a concatenation of the memory of `self` and the requested region of `buf2`. ## `buf2` the second source `Buffer` to append. ## `offset` the offset in `buf2` ## `size` the size or -1 of `buf2` # Returns the new `Buffer` that contains the memory of the two source buffers. Create a copy of the given buffer. This will make a newly allocated copy of the data the source buffer contains. # Returns a new copy of `self`. Copies the information from `src` into `self`. If `self` already contains memory and `flags` contains GST_BUFFER_COPY_MEMORY, the memory from `src` will be appended to `self`. `flags` indicate which fields will be copied. ## `src` a source `Buffer` ## `flags` flags indicating what metadata fields should be copied. ## `offset` offset to copy from ## `size` total size to copy. If -1, all data is copied. # Returns `true` if the copying succeeded, `false` otherwise. Creates a sub-buffer from `self` at `offset` and `size`. This sub-buffer uses the actual memory space of the parent buffer. This function will copy the offset and timestamp fields when the offset is 0. If not, they will be set to `GST_CLOCK_TIME_NONE` and `GST_BUFFER_OFFSET_NONE`. If `offset` equals 0 and `size` equals the total size of `buffer`, the duration and offset end fields are also copied. If not they will be set to `GST_CLOCK_TIME_NONE` and `GST_BUFFER_OFFSET_NONE`. MT safe. ## `flags` the `BufferCopyFlags` ## `offset` the offset into parent `Buffer` at which the new sub-buffer begins. ## `size` the size of the new `Buffer` sub-buffer, in bytes. If -1, all data is copied. # Returns the new `Buffer` or `None` if the arguments were invalid. Copy `size` bytes starting from `offset` in `self` to `dest`. ## `offset` the offset to extract ## `dest` the destination address ## `size` the size to extract # Returns The amount of bytes extracted. This value can be lower than `size` when `self` did not contain enough data. Extracts a copy of at most `size` bytes the data at `offset` into newly-allocated memory. `dest` must be freed using `g_free` when done. ## `offset` the offset to extract ## `size` the size to extract ## `dest` A pointer where the destination array will be written. Might be `None` if the size is 0. ## `dest_size` A location where the size of `dest` can be written Copy `size` bytes from `src` to `self` at `offset`. ## `offset` the offset to fill ## `src` the source address ## `size` the size to fill # Returns The amount of bytes copied. This value can be lower than `size` when `self` did not contain enough data. Find the memory blocks that span `size` bytes starting from `offset` in `self`. When this function returns `true`, `idx` will contain the index of the first memory block where the byte for `offset` can be found and `length` contains the number of memory blocks containing the `size` remaining bytes. `skip` contains the number of bytes to skip in the memory block at `idx` to get to the byte for `offset`. `size` can be -1 to get all the memory blocks after `idx`. ## `offset` an offset ## `size` a size ## `idx` pointer to index ## `length` pointer to length ## `skip` pointer to skip # Returns `true` when `size` bytes starting from `offset` could be found in `self` and `idx`, `length` and `skip` will be filled. Call `func` with `user_data` for each meta in `self`. `func` can modify the passed meta pointer or its contents. The return value of `func` define if this function returns or if the remaining metadata items in the buffer should be skipped. ## `func` a `GstBufferForeachMetaFunc` to call ## `user_data` user data passed to `func` # Returns `false` when `func` returned `false` for one of the metadata. Get all the memory block in `self`. The memory blocks will be merged into one large `Memory`. # Returns a `Memory` that contains the merged memory. Use gst_memory_unref () after usage. Get the `BufferFlags` flags set on this buffer. Feature: `v1_10` # Returns the flags set on this buffer. Get the memory block at index `idx` in `self`. ## `idx` an index # Returns a `Memory` that contains the data of the memory block at `idx`. Use gst_memory_unref () after usage. Get `length` memory blocks in `self` starting at `idx`. The memory blocks will be merged into one large `Memory`. If `length` is -1, all memory starting from `idx` is merged. ## `idx` an index ## `length` a length # Returns a `Memory` that contains the merged data of `length` blocks starting at `idx`. Use gst_memory_unref () after usage. Get the metadata for `api` on buffer. When there is no such metadata, `None` is returned. If multiple metadata with the given `api` are attached to this buffer only the first one is returned. To handle multiple metadata with a given API use `Buffer::iterate_meta` or `Buffer::foreach_meta` instead and check the meta->info.api member for the API type. ## `api` the `glib::Type` of an API # Returns the metadata for `api` on `self`. Feature: `v1_14` ## `api_type` the `glib::Type` of an API # Returns number of metas of type `api_type` on `self`. Find the first `ReferenceTimestampMeta` on `self` that conforms to `reference`. Conformance is tested by checking if the meta's reference is a subset of `reference`. Buffers can contain multiple `ReferenceTimestampMeta` metadata items. Feature: `v1_14` ## `reference` a reference `Caps` # Returns the `ReferenceTimestampMeta` or `None` when there is no such metadata on `self`. Get the total size of the memory blocks in `self`. # Returns total size of the memory blocks in `self`. Get the total size of the memory blocks in `b`. When not `None`, `offset` will contain the offset of the data in the first memory block in `self` and `maxsize` will contain the sum of the size and `offset` and the amount of extra padding on the last memory block. `offset` and `maxsize` can be used to resize the buffer memory blocks with `Buffer::resize`. ## `offset` a pointer to the offset ## `maxsize` a pointer to the maxsize # Returns total size of the memory blocks in `self`. Get the total size of `length` memory blocks stating from `idx` in `self`. When not `None`, `offset` will contain the offset of the data in the memory block in `self` at `idx` and `maxsize` will contain the sum of the size and `offset` and the amount of extra padding on the memory block at `idx` + `length` -1. `offset` and `maxsize` can be used to resize the buffer memory blocks with `Buffer::resize_range`. ## `idx` an index ## `length` a length ## `offset` a pointer to the offset ## `maxsize` a pointer to the maxsize # Returns total size of `length` memory blocks starting at `idx` in `self`. Insert the memory block `mem` to `self` at `idx`. This function takes ownership of `mem` and thus doesn't increase its refcount. Only `Buffer::get_max_memory` can be added to a buffer. If more memory is added, existing memory blocks will automatically be merged to make room for the new memory. ## `idx` the index to add the memory at, or -1 to append it to the end ## `mem` a `Memory`. Check if all memory blocks in `self` are writable. Note that this function does not check if `self` is writable, use `gst_buffer_is_writable` to check that if needed. # Returns `true` if all memory blocks in `self` are writable Check if `length` memory blocks in `self` starting from `idx` are writable. `length` can be -1 to check all the memory blocks after `idx`. Note that this function does not check if `self` is writable, use `gst_buffer_is_writable` to check that if needed. ## `idx` an index ## `length` a length should not be 0 # Returns `true` if the memory range is writable Retrieve the next `Meta` after `current`. If `state` points to `None`, the first metadata is returned. `state` will be updated with an opaque state pointer ## `state` an opaque state pointer # Returns The next `Meta` or `None` when there are no more items. Retrieve the next `Meta` of type `meta_api_type` after the current one according to `state`. If `state` points to `None`, the first metadata of type `meta_api_type` is returned. `state` will be updated with an opaque state pointer Feature: `v1_12` ## `state` an opaque state pointer ## `meta_api_type` only return `Meta` of this type # Returns The next `Meta` of type `meta_api_type` or `None` when there are no more items. This function fills `info` with the `MapInfo` of all merged memory blocks in `self`. `flags` describe the desired access of the memory. When `flags` is `MapFlags::Write`, `self` should be writable (as returned from `gst_buffer_is_writable`). When `self` is writable but the memory isn't, a writable copy will automatically be created and returned. The readonly copy of the buffer memory will then also be replaced with this writable copy. The memory in `info` should be unmapped with `Buffer::unmap` after usage. ## `info` info about the mapping ## `flags` flags for the mapping # Returns `true` if the map succeeded and `info` contains valid data. This function fills `info` with the `MapInfo` of `length` merged memory blocks starting at `idx` in `self`. When `length` is -1, all memory blocks starting from `idx` are merged and mapped. `flags` describe the desired access of the memory. When `flags` is `MapFlags::Write`, `self` should be writable (as returned from `gst_buffer_is_writable`). When `self` is writable but the memory isn't, a writable copy will automatically be created and returned. The readonly copy of the buffer memory will then also be replaced with this writable copy. The memory in `info` should be unmapped with `Buffer::unmap` after usage. ## `idx` an index ## `length` a length ## `info` info about the mapping ## `flags` flags for the mapping # Returns `true` if the map succeeded and `info` contains valid data. Compare `size` bytes starting from `offset` in `self` with the memory in `mem`. ## `offset` the offset in `self` ## `mem` the memory to compare ## `size` the size to compare # Returns 0 if the memory is equal. Fill `buf` with `size` bytes with `val` starting from `offset`. ## `offset` the offset in `self` ## `val` the value to set ## `size` the size to set # Returns The amount of bytes filled. This value can be lower than `size` when `self` did not contain enough data. Get the amount of memory blocks that this buffer has. This amount is never larger than what `Buffer::get_max_memory` returns. # Returns the number of memory blocks this buffer is made of. Get the memory block at `idx` in `self`. The memory block stays valid until the memory block in `self` is removed, replaced or merged, typically with any call that modifies the memory in `self`. ## `idx` an index # Returns the `Memory` at `idx`. Prepend the memory block `mem` to `self`. This function takes ownership of `mem` and thus doesn't increase its refcount. This function is identical to `Buffer::insert_memory` with an index of 0. See `Buffer::insert_memory` for more details. ## `mem` a `Memory`. Remove all the memory blocks in `self`. Remove the memory block in `b` at index `i`. ## `idx` an index Remove `length` memory blocks in `self` starting from `idx`. `length` can be -1, in which case all memory starting from `idx` is removed. ## `idx` an index ## `length` a length Remove the metadata for `meta` on `self`. ## `meta` a `Meta` # Returns `true` if the metadata existed and was removed, `false` if no such metadata was on `self`. Replaces all memory in `self` with `mem`. ## `mem` a `Memory` Replaces the memory block at index `idx` in `self` with `mem`. ## `idx` an index ## `mem` a `Memory` Replaces `length` memory blocks in `self` starting at `idx` with `mem`. If `length` is -1, all memory starting from `idx` will be removed and replaced with `mem`. `self` should be writable. ## `idx` an index ## `length` a length should not be 0 ## `mem` a `Memory` Set the offset and total size of the memory blocks in `self`. ## `offset` the offset adjustment ## `size` the new size or -1 to just adjust the offset Set the total size of the `length` memory blocks starting at `idx` in `self` ## `idx` an index ## `length` a length ## `offset` the offset adjustment ## `size` the new size or -1 to just adjust the offset # Returns `true` if resizing succeeded, `false` otherwise. Sets one or more buffer flags on a buffer. Feature: `v1_10` ## `flags` the `BufferFlags` to set. # Returns `true` if `flags` were successfully set on buffer. Set the total size of the memory blocks in `self`. ## `size` the new size Release the memory previously mapped with `Buffer::map`. ## `info` a `MapInfo` Clears one or more buffer flags. Feature: `v1_10` ## `flags` the `BufferFlags` to clear # Returns true if `flags` is successfully cleared from buffer. Get the maximum amount of memory blocks that a buffer can hold. This is a compile time constant that can be queried with the function. When more memory blocks are added, existing memory blocks will be merged together to make room for the new block. # Returns the maximum amount of memory blocks that a buffer can hold. Buffer lists are an object containing a list of buffers. Buffer lists are created with `BufferList::new` and filled with data using a `BufferList::insert`. Buffer lists can be pushed on a srcpad with `Pad::push_list`. This is interesting when multiple buffers need to be pushed in one go because it can reduce the amount of overhead for pushing each buffer individually. Creates a new, empty `BufferList`. The caller is responsible for unreffing the returned `BufferList`. Free-function: gst_buffer_list_unref # Returns the new `BufferList`. `gst_buffer_list_unref` after usage. Creates a new, empty `BufferList`. The caller is responsible for unreffing the returned `BufferList`. The list will have `size` space preallocated so that memory reallocations can be avoided. Free-function: gst_buffer_list_unref ## `size` an initial reserved size # Returns the new `BufferList`. `gst_buffer_list_unref` after usage. Calculates the size of the data contained in buffer list by adding the size of all buffers. Feature: `v1_14` # Returns the size of the data contained in buffer list in bytes. Create a copy of the given buffer list. This will make a newly allocated copy of the buffer that the source buffer list contains. # Returns a new copy of `self`. Call `func` with `data` for each buffer in `self`. `func` can modify the passed buffer pointer or its contents. The return value of `func` define if this function returns or if the remaining buffers in the list should be skipped. ## `func` a `GstBufferListFunc` to call ## `user_data` user data passed to `func` # Returns `true` when `func` returned `true` for each buffer in `self` or when `self` is empty. Get the buffer at `idx`. You must make sure that `idx` does not exceed the number of buffers available. ## `idx` the index # Returns the buffer at `idx` in `group` or `None` when there is no buffer. The buffer remains valid as long as `self` is valid and buffer is not removed from the list. Gets the buffer at `idx`, ensuring it is a writable buffer. You must make sure that `idx` does not exceed the number of buffers available. Feature: `v1_14` ## `idx` the index # Returns the buffer at `idx` in `group`. The returned buffer remains valid as long as `self` is valid and the buffer is not removed from the list. Insert `buffer` at `idx` in `self`. Other buffers are moved to make room for this new buffer. A -1 value for `idx` will append the buffer at the end. ## `idx` the index ## `buffer` a `Buffer` Returns the number of buffers in `self`. # Returns the number of buffers in the buffer list Remove `length` buffers starting from `idx` in `self`. The following buffers are moved to close the gap. ## `idx` the index ## `length` the amount to remove A `BufferPool` is an object that can be used to pre-allocate and recycle buffers of the same size and with the same properties. A `BufferPool` is created with `BufferPool::new`. Once a pool is created, it needs to be configured. A call to `BufferPool::get_config` returns the current configuration structure from the pool. With `BufferPool::config_set_params` and `BufferPool::config_set_allocator` the bufferpool parameters and allocator can be configured. Other properties can be configured in the pool depending on the pool implementation. A bufferpool can have extra options that can be enabled with `BufferPool::config_add_option`. The available options can be retrieved with `BufferPoolExt::get_options`. Some options allow for additional configuration properties to be set. After the configuration structure has been configured, `BufferPool::set_config` updates the configuration in the pool. This can fail when the configuration structure is not accepted. After the a pool has been configured, it can be activated with `BufferPoolExt::set_active`. This will preallocate the configured resources in the pool. When the pool is active, `BufferPool::acquire_buffer` can be used to retrieve a buffer from the pool. Buffers allocated from a bufferpool will automatically be returned to the pool with `BufferPool::release_buffer` when their refcount drops to 0. The bufferpool can be deactivated again with `BufferPoolExt::set_active`. All further `BufferPool::acquire_buffer` calls will return an error. When all buffers are returned to the pool they will be freed. Use `GstObjectExt::unref` to release the reference to a bufferpool. If the refcount of the pool reaches 0, the pool will be freed. # Implements [`BufferPoolExt`](trait.BufferPoolExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `BufferPool` methods. # Implementors [`BufferPool`](struct.BufferPool.html) Creates a new `BufferPool` instance. # Returns a new `BufferPool` instance Enabled the option in `config`. This will instruct the `bufferpool` to enable the specified option on the buffers that it allocates. The supported options by `pool` can be retrieved with `BufferPoolExt::get_options`. ## `config` a `BufferPool` configuration ## `option` an option to add Get the `allocator` and `params` from `config`. ## `config` a `BufferPool` configuration ## `allocator` a `Allocator`, or `None` ## `params` `AllocationParams`, or `None` # Returns `true`, if the values are set. Parse an available `config` and get the option at `index` of the options API array. ## `config` a `BufferPool` configuration ## `index` position in the option array to read # Returns a `gchar` of the option at `index`. Get the configuration values from `config`. ## `config` a `BufferPool` configuration ## `caps` the caps of buffers ## `size` the size of each buffer, not including prefix and padding ## `min_buffers` the minimum amount of buffers to allocate. ## `max_buffers` the maximum amount of buffers to allocate or 0 for unlimited. # Returns `true` if all parameters could be fetched. Check if `config` contains `option`. ## `config` a `BufferPool` configuration ## `option` an option # Returns `true` if the options array contains `option`. Retrieve the number of values currently stored in the options array of the `config` structure. ## `config` a `BufferPool` configuration # Returns the options array size as a `guint`. Set the `allocator` and `params` on `config`. One of `allocator` and `params` can be `None`, but not both. When `allocator` is `None`, the default allocator of the pool will use the values in `param` to perform its allocation. When `param` is `None`, the pool will use the provided `allocator` with its default `AllocationParams`. A call to `BufferPool::set_config` can update the allocator and params with the values that it is able to do. Some pools are, for example, not able to operate with different allocators or cannot allocate with the values specified in `params`. Use `BufferPool::get_config` to get the currently used values. ## `config` a `BufferPool` configuration ## `allocator` a `Allocator` ## `params` `AllocationParams` Configure `config` with the given parameters. ## `config` a `BufferPool` configuration ## `caps` caps for the buffers ## `size` the size of each buffer, not including prefix and padding ## `min_buffers` the minimum amount of buffers to allocate. ## `max_buffers` the maximum amount of buffers to allocate or 0 for unlimited. Validate that changes made to `config` are still valid in the context of the expected parameters. This function is a helper that can be used to validate changes made by a pool to a config when `BufferPool::set_config` returns `false`. This expects that `caps` haven't changed and that `min_buffers` aren't lower then what we initially expected. This does not check if options or allocator parameters are still valid, won't check if size have changed, since changing the size is valid to adapt padding. ## `config` a `BufferPool` configuration ## `caps` the excepted caps of buffers ## `size` the expected size of each buffer, not including prefix and padding ## `min_buffers` the expected minimum amount of buffers to allocate. ## `max_buffers` the expect maximum amount of buffers to allocate or 0 for unlimited. # Returns `true`, if the parameters are valid in this context. Acquire a buffer from `self`. `buffer` should point to a memory location that can hold a pointer to the new buffer. `params` can be `None` or contain optional parameters to influence the allocation. ## `buffer` a location for a `Buffer` ## `params` parameters. # Returns a `FlowReturn` such as `FlowReturn::Flushing` when the pool is inactive. Get a copy of the current configuration of the pool. This configuration can either be modified and used for the `BufferPool::set_config` call or it must be freed after usage. # Returns a copy of the current configuration of `self`. use `Structure::free` after usage or `BufferPool::set_config`. Get a `None` terminated array of string with supported bufferpool options for `self`. An option would typically be enabled with `BufferPool::config_add_option`. # Returns a `None` terminated array of strings. Check if the bufferpool supports `option`. ## `option` an option # Returns `true` if the buffer pool contains `option`. Check if `self` is active. A pool can be activated with the `BufferPoolExt::set_active` call. # Returns `true` when the pool is active. Release `buffer` to `self`. `buffer` should have previously been allocated from `self` with `BufferPool::acquire_buffer`. This function is usually called automatically when the last ref on `buffer` disappears. ## `buffer` a `Buffer` Control the active state of `self`. When the pool is inactive, new calls to `BufferPool::acquire_buffer` will return with `FlowReturn::Flushing`. Activating the bufferpool will preallocate all resources in the pool based on the configuration of the pool. Deactivating will free the resources again when there are no outstanding buffers. When there are outstanding buffers, they will be freed as soon as they are all returned to the pool. ## `active` the new active state # Returns `false` when the pool was not configured or when preallocation of the buffers failed. Set the configuration of the pool. If the pool is already configured, and the configuration haven't change, this function will return `true`. If the pool is active, this method will return `false` and active configuration will remain. Buffers allocated form this pool must be returned or else this function will do nothing and return `false`. `config` is a `Structure` that contains the configuration parameters for the pool. A default and mandatory set of parameters can be configured with `BufferPool::config_set_params`, `BufferPool::config_set_allocator` and `BufferPool::config_add_option`. If the parameters in `config` can not be set exactly, this function returns `false` and will try to update as much state as possible. The new state can then be retrieved and refined with `BufferPool::get_config`. This function takes ownership of `config`. ## `config` a `Structure` # Returns `true` when the configuration could be set. Enable or disable the flushing state of a `self` without freeing or allocating buffers. ## `flushing` whether to start or stop flushing The different types of buffering methods. a small amount of data is buffered the stream is being downloaded the stream is being downloaded in a ringbuffer the stream is a live stream The `Bus` is an object responsible for delivering `Message` packets in a first-in first-out way from the streaming threads (see `Task`) to the application. Since the application typically only wants to deal with delivery of these messages from one thread, the GstBus will marshall the messages between different threads. This is important since the actual streaming of media is done in another thread than the application. The GstBus provides support for `glib::Source` based notifications. This makes it possible to handle the delivery in the glib mainloop. The `glib::Source` callback function `Bus::async_signal_func` can be used to convert all bus messages into signal emissions. A message is posted on the bus with the `Bus::post` method. With the `Bus::peek` and `Bus::pop` methods one can look at or retrieve a previously posted message. The bus can be polled with the `Bus::poll` method. This methods blocks up to the specified timeout value until one of the specified messages types is posted on the bus. The application can then `Bus::pop` the messages from the bus to handle them. Alternatively the application can register an asynchronous bus function using `Bus::add_watch_full` or `Bus::add_watch`. This function will install a `glib::Source` in the default glib main loop and will deliver messages a short while after they have been posted. Note that the main loop should be running for the asynchronous callbacks. It is also possible to get messages from the bus without any thread marshalling with the `Bus::set_sync_handler` method. This makes it possible to react to a message in the same thread that posted the message on the bus. This should only be used if the application is able to deal with messages from different threads. Every `Pipeline` has one bus. Note that a `Pipeline` will set its bus into flushing state when changing from READY to NULL state. # Implements [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates a new `Bus` instance. # Returns a new `Bus` instance Adds a bus signal watch to the default main context with the default priority (`G_PRIORITY_DEFAULT`). It is also possible to use a non-default main context set up using `glib::MainContext::push_thread_default` (before one had to create a bus watch source and attach it to the desired main context 'manually'). After calling this statement, the bus will emit the "message" signal for each message posted on the bus. This function may be called multiple times. To clean up, the caller is responsible for calling `Bus::remove_signal_watch` as many times as this function is called. MT safe. Adds a bus signal watch to the default main context with the given `priority` (e.g. `G_PRIORITY_DEFAULT`). It is also possible to use a non-default main context set up using `glib::MainContext::push_thread_default` (before one had to create a bus watch source and attach it to the desired main context 'manually'). After calling this statement, the bus will emit the "message" signal for each message posted on the bus when the main loop is running. This function may be called multiple times. To clean up, the caller is responsible for calling `Bus::remove_signal_watch` as many times as this function is called. There can only be a single bus watch per bus, you must remove any signal watch before you can set another type of watch. MT safe. ## `priority` The priority of the watch. Adds a bus watch to the default main context with the default priority (`G_PRIORITY_DEFAULT`). It is also possible to use a non-default main context set up using `glib::MainContext::push_thread_default` (before one had to create a bus watch source and attach it to the desired main context 'manually'). This function is used to receive asynchronous messages in the main loop. There can only be a single bus watch per bus, you must remove it before you can set a new one. The bus watch will only work if a GLib main loop is being run. The watch can be removed using `Bus::remove_watch` or by returning `false` from `func`. If the watch was added to the default main context it is also possible to remove the watch using `glib::Source::remove`. The bus watch will take its own reference to the `self`, so it is safe to unref `self` using `GstObjectExt::unref` after setting the bus watch. MT safe. ## `func` A function to call when a message is received. ## `user_data` user data passed to `func`. # Returns The event source id or 0 if `self` already got an event source. Adds a bus watch to the default main context with the given `priority` (e.g. `G_PRIORITY_DEFAULT`). It is also possible to use a non-default main context set up using `glib::MainContext::push_thread_default` (before one had to create a bus watch source and attach it to the desired main context 'manually'). This function is used to receive asynchronous messages in the main loop. There can only be a single bus watch per bus, you must remove it before you can set a new one. The bus watch will only work if a GLib main loop is being run. When `func` is called, the message belongs to the caller; if you want to keep a copy of it, call `gst_message_ref` before leaving `func`. The watch can be removed using `Bus::remove_watch` or by returning `false` from `func`. If the watch was added to the default main context it is also possible to remove the watch using `glib::Source::remove`. The bus watch will take its own reference to the `self`, so it is safe to unref `self` using `GstObjectExt::unref` after setting the bus watch. MT safe. ## `priority` The priority of the watch. ## `func` A function to call when a message is received. ## `user_data` user data passed to `func`. ## `notify` the function to call when the source is removed. # Returns The event source id or 0 if `self` already got an event source. A helper `GstBusFunc` that can be used to convert all asynchronous messages into signals. ## `message` the `Message` received ## `data` user data # Returns `true` Create watch for this bus. The GSource will be dispatched whenever a message is on the bus. After the GSource is dispatched, the message is popped off the bus and unreffed. # Returns a `glib::Source` that can be added to a mainloop. Instructs GStreamer to stop emitting the "sync-message" signal for this bus. See `Bus::enable_sync_message_emission` for more information. In the event that multiple pieces of code have called `Bus::enable_sync_message_emission`, the sync-message emissions will only be stopped after all calls to `Bus::enable_sync_message_emission` were "cancelled" by calling this function. In this way the semantics are exactly the same as `GstObjectExt::ref` that which calls enable should also call disable. MT safe. Instructs GStreamer to emit the "sync-message" signal after running the bus's sync handler. This function is here so that code can ensure that they can synchronously receive messages without having to affect what the bin's sync handler is. This function may be called multiple times. To clean up, the caller is responsible for calling `Bus::disable_sync_message_emission` as many times as this function is called. While this function looks similar to `Bus::add_signal_watch`, it is not exactly the same -- this function enables ``synchronous`` emission of signals when messages arrive; `Bus::add_signal_watch` adds an idle callback to pop messages off the bus ``asynchronously``. The sync-message signal comes from the thread of whatever object posted the message; the "message" signal is marshalled to the main thread via the main loop. MT safe. Gets the file descriptor from the bus which can be used to get notified about messages being available with functions like `g_poll`, and allows integration into other event loops based on file descriptors. Whenever a message is available, the POLLIN / `glib::IOCondition::In` event is set. Warning: NEVER read or write anything to the returned fd but only use it for getting notifications via `g_poll` or similar and then use the normal GstBus API, e.g. `Bus::pop`. Feature: `v1_14` ## `fd` A GPollFD to fill Check if there are pending messages on the bus that should be handled. # Returns `true` if there are messages on the bus to be handled, `false` otherwise. MT safe. Peek the message on the top of the bus' queue. The message will remain on the bus' message queue. A reference is returned, and needs to be unreffed by the caller. # Returns the `Message` that is on the bus, or `None` if the bus is empty. MT safe. Poll the bus for messages. Will block while waiting for messages to come. You can specify a maximum time to poll with the `timeout` parameter. If `timeout` is negative, this function will block indefinitely. All messages not in `events` will be popped off the bus and will be ignored. It is not possible to use message enums beyond `MessageType::Extended` in the `events` mask Because poll is implemented using the "message" signal enabled by `Bus::add_signal_watch`, calling `Bus::poll` will cause the "message" signal to be emitted for every message that poll sees. Thus a "message" signal handler will see the same messages that this function sees -- neither will steal messages from the other. This function will run a main loop from the default main context when polling. You should never use this function, since it is pure evil. This is especially true for GUI applications based on Gtk+ or Qt, but also for any other non-trivial application that uses the GLib main loop. As this function runs a GLib main loop, any callback attached to the default GLib main context may be invoked. This could be timeouts, GUI events, I/O events etc.; even if `Bus::poll` is called with a 0 timeout. Any of these callbacks may do things you do not expect, e.g. destroy the main application window or some other resource; change other application state; display a dialog and run another main loop until the user clicks it away. In short, using this function may add a lot of complexity to your code through unexpected re-entrancy and unexpected changes to your application's state. For 0 timeouts use `Bus::pop_filtered` instead of this function; for other short timeouts use `Bus::timed_pop_filtered`; everything else is better handled by setting up an asynchronous bus watch and doing things from there. ## `events` a mask of `MessageType`, representing the set of message types to poll for (note special handling of extended message types below) ## `timeout` the poll timeout, as a `ClockTime`, or `GST_CLOCK_TIME_NONE` to poll indefinitely. # Returns the message that was received, or `None` if the poll timed out. The message is taken from the bus and needs to be unreffed with `gst_message_unref` after usage. Get a message from the bus. # Returns the `Message` that is on the bus, or `None` if the bus is empty. The message is taken from the bus and needs to be unreffed with `gst_message_unref` after usage. MT safe. Get a message matching `type_` from the bus. Will discard all messages on the bus that do not match `type_` and that have been posted before the first message that does match `type_`. If there is no message matching `type_` on the bus, all messages will be discarded. It is not possible to use message enums beyond `MessageType::Extended` in the `events` mask. ## `types` message types to take into account # Returns the next `Message` matching `type_` that is on the bus, or `None` if the bus is empty or there is no message matching `type_`. The message is taken from the bus and needs to be unreffed with `gst_message_unref` after usage. MT safe. Post a message on the given bus. Ownership of the message is taken by the bus. ## `message` the `Message` to post # Returns `true` if the message could be posted, `false` if the bus is flushing. MT safe. Removes a signal watch previously added with `Bus::add_signal_watch`. MT safe. Removes an installed bus watch from `self`. # Returns `true` on success or `false` if `self` has no event source. If `flushing`, flush out and unref any messages queued in the bus. Releases references to the message origin objects. Will flush future messages until `Bus::set_flushing` sets `flushing` to `false`. MT safe. ## `flushing` whether or not to flush the bus Sets the synchronous handler on the bus. The function will be called every time a new message is posted on the bus. Note that the function will be called in the same thread context as the posting object. This function is usually only called by the creator of the bus. Applications should handle messages asynchronously using the gst_bus watch and poll functions. You cannot replace an existing sync_handler. You can pass `None` to this function, which will clear the existing handler. ## `func` The handler function to install ## `user_data` User data that will be sent to the handler function. ## `notify` called when `user_data` becomes unused A helper GstBusSyncHandler that can be used to convert all synchronous messages into signals. ## `message` the `Message` received ## `data` user data # Returns GST_BUS_PASS Get a message from the bus, waiting up to the specified timeout. If `timeout` is 0, this function behaves like `Bus::pop`. If `timeout` is `GST_CLOCK_TIME_NONE`, this function will block forever until a message was posted on the bus. ## `timeout` a timeout # Returns the `Message` that is on the bus after the specified timeout or `None` if the bus is empty after the timeout expired. The message is taken from the bus and needs to be unreffed with `gst_message_unref` after usage. MT safe. Get a message from the bus whose type matches the message type mask `types`, waiting up to the specified timeout (and discarding any messages that do not match the mask provided). If `timeout` is 0, this function behaves like `Bus::pop_filtered`. If `timeout` is `GST_CLOCK_TIME_NONE`, this function will block forever until a matching message was posted on the bus. ## `timeout` a timeout in nanoseconds, or GST_CLOCK_TIME_NONE to wait forever ## `types` message types to take into account, GST_MESSAGE_ANY for any type # Returns a `Message` matching the filter in `types`, or `None` if no matching message was found on the bus until the timeout expired. The message is taken from the bus and needs to be unreffed with `gst_message_unref` after usage. MT safe. A message has been posted on the bus. This signal is emitted from a GSource added to the mainloop. this signal will only be emitted when there is a mainloop running. ## `message` the message that has been posted asynchronously A message has been posted on the bus. This signal is emitted from the thread that posted the message so one has to be careful with locking. This signal will not be emitted by default, you have to call `Bus::enable_sync_message_emission` before. ## `message` the message that has been posted synchronously The result values for a GstBusSyncHandler. drop the message pass the message to the async queue pass message to async queue, continue if message is handled Caps (capabilities) are lightweight refcounted objects describing media types. They are composed of an array of `Structure`. Caps are exposed on `PadTemplate` to describe all possible types a given pad can handle. They are also stored in the `Registry` along with a description of the `Element`. Caps are exposed on the element pads using the `PadExt::query_caps` pad function. This function describes the possible types that the pad can handle or produce at runtime. A `Caps` can be constructed with the following code fragment: ```C GstCaps *caps = gst_caps_new_simple ("video/x-raw", "format", G_TYPE_STRING, "I420", "framerate", GST_TYPE_FRACTION, 25, 1, "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1, "width", G_TYPE_INT, 320, "height", G_TYPE_INT, 240, NULL); ``` A `Caps` is fixed when it has no properties with ranges or lists. Use `Caps::is_fixed` to test for fixed caps. Fixed caps can be used in a caps event to notify downstream elements of the current media type. Various methods exist to work with the media types such as subtracting or intersecting. Be aware that the current `Caps` / `Structure` serialization into string has limited support for nested `Caps` / `Structure` fields. It can only support one level of nesting. Using more levels will lead to unexpected behavior when using serialization features, such as `Caps::to_string` or `gst_value_serialize` and their counterparts. Creates a new `Caps` that indicates that it is compatible with any media format. # Returns the new `Caps` Creates a new `Caps` that is empty. That is, the returned `Caps` contains no media formats. The `Caps` is guaranteed to be writable. Caller is responsible for unreffing the returned caps. # Returns the new `Caps` Creates a new `Caps` that contains one `Structure` with name `media_type`. Caller is responsible for unreffing the returned caps. ## `media_type` the media type of the structure # Returns the new `Caps` Creates a new `Caps` and adds all the structures listed as arguments. The list must be `None`-terminated. The structures are not copied; the returned `Caps` owns the structures. ## `struct1` the first structure to add # Returns the new `Caps` Creates a new `Caps` and adds all the structures listed as arguments. The list must be `None`-terminated. The structures are not copied; the returned `Caps` owns the structures. ## `structure` the first structure to add ## `var_args` additional structures to add # Returns the new `Caps` Creates a new `Caps` that contains one `Structure`. The structure is defined by the arguments, which have the same format as `Structure::new`. Caller is responsible for unreffing the returned caps. ## `media_type` the media type of the structure ## `fieldname` first field to set # Returns the new `Caps` Appends the structures contained in `caps2` to `self`. The structures in `caps2` are not copied -- they are transferred to `self`, and then `caps2` is freed. If either caps is ANY, the resulting caps will be ANY. ## `caps2` the `Caps` to append Appends `structure` to `self`. The structure is not copied; `self` becomes the owner of `structure`. ## `structure` the `Structure` to append Appends `structure` with `features` to `self`. The structure is not copied; `self` becomes the owner of `structure`. ## `structure` the `Structure` to append ## `features` the `CapsFeatures` to append Tries intersecting `self` and `caps2` and reports whether the result would not be empty ## `caps2` a `Caps` to intersect # Returns `true` if intersection would be not empty Creates a new `Caps` and appends a copy of the nth structure contained in `self`. ## `nth` the nth structure to copy # Returns the new `Caps` Calls the provided function once for each structure and caps feature in the `Caps`. In contrast to `Caps::foreach`, the function may modify the structure and features. In contrast to `Caps::filter_and_map_in_place`, the structure and features are removed from the caps if `false` is returned from the function. The caps must be mutable. ## `func` a function to call for each field ## `user_data` private data Modifies the given `self` into a representation with only fixed values. First the caps will be truncated and then the first structure will be fixated with `Structure::fixate`. This function takes ownership of `self` and will call `gst_caps_make_writable` on it so you must not use `self` afterwards unless you keep an additional reference to it with `gst_caps_ref`. # Returns the fixated caps Calls the provided function once for each structure and caps feature in the `Caps`. The function must not modify the fields. Also see `Caps::map_in_place` and `Caps::filter_and_map_in_place`. ## `func` a function to call for each field ## `user_data` private data # Returns `true` if the supplied function returns `true` for each call, `false` otherwise. Finds the features in `self` that has the index `index`, and returns it. WARNING: This function takes a const GstCaps *, but returns a non-const GstCapsFeatures *. This is for programming convenience -- the caller should be aware that structures inside a constant `Caps` should not be modified. However, if you know the caps are writable, either because you have just copied them or made them writable with `gst_caps_make_writable`, you may modify the features returned in the usual way, e.g. with functions like `CapsFeatures::add`. You do not need to free or unref the structure returned, it belongs to the `Caps`. ## `index` the index of the structure # Returns a pointer to the `CapsFeatures` corresponding to `index` Gets the number of structures contained in `self`. # Returns the number of structures that `self` contains Finds the structure in `self` that has the index `index`, and returns it. WARNING: This function takes a const GstCaps *, but returns a non-const GstStructure *. This is for programming convenience -- the caller should be aware that structures inside a constant `Caps` should not be modified. However, if you know the caps are writable, either because you have just copied them or made them writable with `gst_caps_make_writable`, you may modify the structure returned in the usual way, e.g. with functions like `Structure::set`. You do not need to free or unref the structure returned, it belongs to the `Caps`. ## `index` the index of the structure # Returns a pointer to the `Structure` corresponding to `index` Creates a new `Caps` that contains all the formats that are common to both `self` and `caps2`. Defaults to `CapsIntersectMode::ZigZag` mode. ## `caps2` a `Caps` to intersect # Returns the new `Caps` Creates a new `Caps` that contains all the formats that are common to both `self` and `caps2`, the order is defined by the `CapsIntersectMode` used. ## `caps2` a `Caps` to intersect ## `mode` The intersection algorithm/mode to use # Returns the new `Caps` A given `Caps` structure is always compatible with another if every media format that is in the first is also contained in the second. That is, `self` is a subset of `caps2`. ## `caps2` the `Caps` to test # Returns `true` if `self` is a subset of `caps2`. Determines if `self` represents any media format. # Returns `true` if `self` represents any format. Determines if `self` represents no media formats. # Returns `true` if `self` represents no formats. Checks if the given caps represent the same set of caps. ## `caps2` another `Caps` # Returns `true` if both caps are equal. Tests if two `Caps` are equal. This function only works on fixed `Caps`. ## `caps2` the `Caps` to test # Returns `true` if the arguments represent the same format Fixed `Caps` describe exactly one format, that is, they have exactly one structure, and each field in the structure describes a fixed type. Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST. # Returns `true` if `self` is fixed Checks if the given caps are exactly the same set of caps. ## `caps2` another `Caps` # Returns `true` if both caps are strictly equal. Checks if all caps represented by `self` are also represented by `superset`. ## `superset` a potentially greater `Caps` # Returns `true` if `self` is a subset of `superset` Checks if `structure` is a subset of `self`. See `Caps::is_subset` for more information. ## `structure` a potential `Structure` subset of `self` # Returns `true` if `structure` is a subset of `self` Checks if `structure` is a subset of `self`. See `Caps::is_subset` for more information. ## `structure` a potential `Structure` subset of `self` ## `features` a `CapsFeatures` for `structure` # Returns `true` if `structure` is a subset of `self` Calls the provided function once for each structure and caps feature in the `Caps`. In contrast to `Caps::foreach`, the function may modify but not delete the structures and features. The caps must be mutable. ## `func` a function to call for each field ## `user_data` private data # Returns `true` if the supplied function returns `true` for each call, `false` otherwise. Appends the structures contained in `caps2` to `self` if they are not yet expressed by `self`. The structures in `caps2` are not copied -- they are transferred to a writable copy of `self`, and then `caps2` is freed. If either caps is ANY, the resulting caps will be ANY. ## `caps2` the `Caps` to merge in # Returns the merged caps. Appends `structure` to `self` if its not already expressed by `self`. ## `structure` the `Structure` to merge # Returns the merged caps. Appends `structure` with `features` to `self` if its not already expressed by `self`. ## `structure` the `Structure` to merge ## `features` the `CapsFeatures` to merge # Returns the merged caps. Returns a `Caps` that represents the same set of formats as `self`, but contains no lists. Each list is expanded into separate `GstStructures`. This function takes ownership of `self` and will call `gst_caps_make_writable` on it so you must not use `self` afterwards unless you keep an additional reference to it with `gst_caps_ref`. # Returns the normalized `Caps` removes the structure with the given index from the list of structures contained in `self`. ## `idx` 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 fields in a `Caps`. The arguments must be passed in the same manner as `Structure::set`, and be `None`-terminated. ## `field` first field to set Sets fields in a `Caps`. The arguments must be passed in the same manner as `Structure::set`, and be `None`-terminated. ## `field` first field to set ## `varargs` additional parameters Sets the given `field` on all structures of `self` to the given `value`. This is a convenience function for calling `Structure::set_value` on all structures of `self`. ## `field` name of the field to set ## `value` value to set the field to Converts the given `self` into a representation that represents the same set of formats, but in a simpler form. Component structures that are identical are merged. Component structures that have values that can be merged are also merged. This function takes ownership of `self` and will call `gst_caps_make_writable` on it if necessary, so you must not use `self` afterwards unless you keep an additional reference to it with `gst_caps_ref`. This method does not preserve the original order of `self`. # Returns The simplified caps. Retrieves the structure with the given index from the list of structures contained in `self`. The caller becomes the owner of the returned structure. ## `index` Index of the structure to retrieve # Returns a pointer to the `Structure` corresponding to `index`. Subtracts the `subtrahend` from the `self`. > This function does not work reliably if optional properties for caps > are included on one caps and omitted on the other. ## `subtrahend` `Caps` to subtract # Returns the resulting caps Converts `self` to a string representation. This string representation can be converted back to a `Caps` by `Caps::from_string`. For debugging purposes its easier to do something like this: ```C GST_LOG ("caps are %" GST_PTR_FORMAT, caps); ``` This prints the caps in human readable form. The current implementation of serialization will lead to unexpected results when there are nested `Caps` / `Structure` deeper than one level. # Returns a newly allocated string representing `self`. Discard all but the first structure from `self`. Useful when fixating. This function takes ownership of `self` and will call `gst_caps_make_writable` on it if necessary, so you must not use `self` afterwards unless you keep an additional reference to it with `gst_caps_ref`. # Returns truncated caps Converts `caps` from a string representation. The current implementation of serialization will lead to unexpected results when there are nested `Caps` / `Structure` deeper than one level. ## `string` a string to convert to `Caps` # Returns a newly allocated `Caps` Modes of caps intersection `CapsIntersectMode::ZigZag` tries to preserve overall order of both caps by iterating on the caps' structures as the following matrix shows: ```text caps1 +------------- | 1 2 4 7 caps2 | 3 5 8 10 | 6 9 11 12 ``` Used when there is no explicit precedence of one caps over the other. e.g. tee's sink pad getcaps function, it will probe its src pad peers' for their caps and intersect them with this mode. `CapsIntersectMode::First` is useful when an element wants to preserve another element's caps priority order when intersecting with its own caps. Example: If caps1 is [A, B, C] and caps2 is [E, B, D, A], the result would be [A, B], maintaining the first caps priority on the intersection. Zig-zags over both caps. Keeps the first caps order. This interface abstracts handling of property sets for elements with children. Imagine elements such as mixers or polyphonic generators. They all have multiple `Pad` or some kind of voice objects. Another use case are container elements like `Bin`. The element implementing the interface acts as a parent for those child objects. By implementing this interface the child properties can be accessed from the parent element by using `ChildProxy::get` and `ChildProxy::set`. Property names are written as "child-name::property-name". The whole naming scheme is recursive. Thus "child1::child2::property" is valid too, if "child1" and "child2" implement the `ChildProxy` interface. # Implements [`ChildProxyExt`](trait.ChildProxyExt.html) Trait containing all `ChildProxy` methods. # Implementors [`Bin`](struct.Bin.html), [`ChildProxy`](struct.ChildProxy.html), [`Pipeline`](struct.Pipeline.html) Emits the "child-added" signal. ## `child` the newly added child ## `name` the name of the new child Emits the "child-removed" signal. ## `child` the removed child ## `name` the name of the old child Gets properties of the parent object and its children. ## `first_property_name` name of the first property to get Fetches a child by its number. ## `index` the child's position in the child list # Returns the child object or `None` if not found (index too high). Unref after usage. MT safe. Looks up a child element by the given name. This virtual method has a default implementation that uses `Object` together with `GstObjectExt::get_name`. If the interface is to be used with `GObjects`, this methods needs to be overridden. ## `name` the child's name # Returns the child object or `None` if not found. Unref after usage. MT safe. Gets the number of child objects this parent contains. # Returns the number of child objects MT safe. Gets a single property using the GstChildProxy mechanism. You are responsible for freeing it by calling `gobject::Value::unset` ## `name` name of the property ## `value` a `gobject::Value` that should take the result. Gets properties of the parent object and its children. ## `first_property_name` name of the first property to get ## `var_args` return location for the first property, followed optionally by more name/return location pairs, followed by `None` Looks up which object and `gobject::ParamSpec` would be effected by the given `name`. MT safe. ## `name` name of the property to look up ## `target` pointer to a `gobject::Object` that takes the real object to set property on ## `pspec` pointer to take the `gobject::ParamSpec` describing the property # Returns `true` if `target` and `pspec` could be found. `false` otherwise. In that case the values for `pspec` and `target` are not modified. Unref `target` after usage. For plain GObjects `target` is the same as `self`. Sets properties of the parent object and its children. ## `first_property_name` name of the first property to set Sets a single property using the GstChildProxy mechanism. ## `name` name of the property to set ## `value` new `gobject::Value` for the property Sets properties of the parent object and its children. ## `first_property_name` name of the first property to set ## `var_args` value for the first property, followed optionally by more name/value pairs, followed by `None` Will be emitted after the `object` was added to the `child_proxy`. ## `object` the `gobject::Object` that was added ## `name` the name of the new child Will be emitted after the `object` was removed from the `child_proxy`. ## `object` the `gobject::Object` that was removed ## `name` the name of the old child GStreamer uses a global clock to synchronize the plugins in a pipeline. Different clock implementations are possible by implementing this abstract base class or, more conveniently, by subclassing `SystemClock`. The `Clock` returns a monotonically increasing time with the method `ClockExt::get_time`. Its accuracy and base time depend on the specific clock implementation but time is always expressed in nanoseconds. Since the baseline of the clock is undefined, the clock time returned is not meaningful in itself, what matters are the deltas between two clock times. The time returned by a clock is called the absolute time. The pipeline uses the clock to calculate the running time. Usually all renderers synchronize to the global clock using the buffer timestamps, the newsegment events and the element's base time, see `Pipeline`. A clock implementation can support periodic and single shot clock notifications both synchronous and asynchronous. One first needs to create a `ClockID` for the periodic or single shot notification using `ClockExt::new_single_shot_id` or `ClockExt::new_periodic_id`. To perform a blocking wait for the specific time of the `ClockID` use the `Clock::id_wait`. To receive a callback when the specific time is reached in the clock use `Clock::id_wait_async`. Both these calls can be interrupted with the `Clock::id_unschedule` call. If the blocking wait is unscheduled a return value of `ClockReturn::Unscheduled` is returned. Periodic callbacks scheduled async will be repeatedly called automatically until it is unscheduled. To schedule a sync periodic callback, `Clock::id_wait` should be called repeatedly. The async callbacks can happen from any thread, either provided by the core or from a streaming thread. The application should be prepared for this. A `ClockID` that has been unscheduled cannot be used again for any wait operation, a new `ClockID` should be created and the old unscheduled one should be destroyed with `Clock::id_unref`. It is possible to perform a blocking wait on the same `ClockID` from multiple threads. However, registering the same `ClockID` for multiple async notifications is not possible, the callback will only be called for the thread registering the entry last. None of the wait operations unref the `ClockID`, the owner is responsible for unreffing the ids itself. This holds for both periodic and single shot notifications. The reason being that the owner of the `ClockID` has to keep a handle to the `ClockID` to unblock the wait on FLUSHING events or state changes and if the entry would be unreffed automatically, the handle might become invalid without any notification. These clock operations do not operate on the running time, so the callbacks will also occur when not in PLAYING state as if the clock just keeps on running. Some clocks however do not progress when the element that provided the clock is not PLAYING. When a clock has the `ClockFlags::CanSetMaster` flag set, it can be slaved to another `Clock` with the `ClockExt::set_master`. The clock will then automatically be synchronized to this master clock by repeatedly sampling the master clock and the slave clock and recalibrating the slave clock with `ClockExt::set_calibration`. This feature is mostly useful for plugins that have an internal clock but must operate with another clock selected by the `Pipeline`. They can track the offset and rate difference of their internal clock relative to the master clock by using the `ClockExt::get_calibration` function. The master/slave synchronisation can be tuned with the `Clock:timeout`, `Clock:window-size` and `Clock:window-threshold` properties. The `Clock:timeout` property defines the interval to sample the master clock and run the calibration functions. `Clock:window-size` defines the number of samples to use when calibrating and `Clock:window-threshold` defines the minimum number of samples before the calibration is performed. # Implements [`ClockExt`](trait.ClockExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `Clock` methods. # Implementors [`Clock`](struct.Clock.html), [`SystemClock`](struct.SystemClock.html) Compares the two `ClockID` instances. This function can be used as a GCompareFunc when sorting ids. ## `id1` A `ClockID` ## `id2` A `ClockID` to compare with # Returns negative value if a < b; zero if a = b; positive value if a > b MT safe. Get the time of the clock ID ## `id` The `ClockID` to query # Returns the time of the given clock id. MT safe. Increase the refcount of given `id`. ## `id` The `ClockID` to ref # Returns The same `ClockID` with increased refcount. MT safe. Unref given `id`. When the refcount reaches 0 the `ClockID` will be freed. MT safe. ## `id` The `ClockID` to unref Cancel an outstanding request with `id`. This can either be an outstanding async notification or a pending sync notification. After this call, `id` cannot be used anymore to receive sync or async notifications, you need to create a new `ClockID`. MT safe. ## `id` The id to unschedule Perform a blocking wait on `id`. `id` should have been created with `ClockExt::new_single_shot_id` or `ClockExt::new_periodic_id` and should not have been unscheduled with a call to `Clock::id_unschedule`. If the `jitter` argument is not `None` and this function returns `ClockReturn::Ok` or `ClockReturn::Early`, it will contain the difference against the clock and the time of `id` when this method was called. Positive values indicate how late `id` was relative to the clock (in which case this function will return `ClockReturn::Early`). Negative values indicate how much time was spent waiting on the clock before this function returned. ## `id` The `ClockID` to wait on ## `jitter` a pointer that will contain the jitter, can be `None`. # Returns the result of the blocking wait. `ClockReturn::Early` will be returned if the current clock time is past the time of `id`, `ClockReturn::Ok` if `id` was scheduled in time. `ClockReturn::Unscheduled` if `id` was unscheduled with `Clock::id_unschedule`. MT safe. Register a callback on the given `ClockID` `id` with the given function and user_data. When passing a `ClockID` with an invalid time to this function, the callback will be called immediately with a time set to GST_CLOCK_TIME_NONE. The callback will be called when the time of `id` has been reached. The callback `func` can be invoked from any thread, either provided by the core or from a streaming thread. The application should be prepared for this. ## `id` a `ClockID` to wait on ## `func` The callback function ## `user_data` User data passed in the callback ## `destroy_data` `GDestroyNotify` for user_data # Returns the result of the non blocking wait. MT safe. The time `master` of the master clock and the time `slave` of the slave clock are added to the list of observations. If enough observations are available, a linear regression algorithm is run on the observations and `self` is recalibrated. If this functions returns `true`, `r_squared` will contain the correlation coefficient of the interpolation. A value of 1.0 means a perfect regression was performed. This value can be used to control the sampling frequency of the master and slave clocks. ## `slave` a time on the slave ## `master` a time on the master ## `r_squared` a pointer to hold the result # Returns `true` if enough observations were added to run the regression algorithm. MT safe. Add a clock observation to the internal slaving algorithm the same as `ClockExt::add_observation`, and return the result of the master clock estimation, without updating the internal calibration. The caller can then take the results and call `ClockExt::set_calibration` with the values, or some modified version of them. ## `slave` a time on the slave ## `master` a time on the master ## `r_squared` a pointer to hold the result ## `internal` a location to store the internal time ## `external` a location to store the external time ## `rate_num` a location to store the rate numerator ## `rate_denom` a location to store the rate denominator Converts the given `internal` clock time to the external time, adjusting for the rate and reference time set with `ClockExt::set_calibration` and making sure that the returned time is increasing. This function should be called with the clock's OBJECT_LOCK held and is mainly used by clock subclasses. This function is the reverse of `ClockExt::unadjust_unlocked`. ## `internal` a clock time # Returns the converted time of the clock. Converts the given `internal_target` clock time to the external time, using the passed calibration parameters. This function performs the same calculation as `ClockExt::adjust_unlocked` when called using the current calibration parameters, but doesn't ensure a monotonically increasing result as `ClockExt::adjust_unlocked` does. Note: The `self` parameter is unused and can be NULL ## `internal_target` a clock time ## `cinternal` a reference internal time ## `cexternal` a reference external time ## `cnum` the numerator of the rate of the clock relative to its internal time ## `cdenom` the denominator of the rate of the clock # Returns the converted time of the clock. Gets the internal rate and reference time of `self`. See `ClockExt::set_calibration` for more information. `internal`, `external`, `rate_num`, and `rate_denom` can be left `None` if the caller is not interested in the values. MT safe. ## `internal` a location to store the internal time ## `external` a location to store the external time ## `rate_num` a location to store the rate numerator ## `rate_denom` a location to store the rate denominator Gets the current internal time of the given clock. The time is returned unadjusted for the offset and the rate. # Returns the internal time of the clock. Or GST_CLOCK_TIME_NONE when given invalid input. MT safe. Get the master clock that `self` is slaved to or `None` when the clock is not slaved to any master clock. # Returns a master `Clock` or `None` when this clock is not slaved to a master clock. Unref after usage. MT safe. Get the accuracy of the clock. The accuracy of the clock is the granularity of the values returned by `ClockExt::get_time`. # Returns the resolution of the clock in units of `ClockTime`. MT safe. Gets the current time of the given clock. The time is always monotonically increasing and adjusted according to the current offset and rate. # Returns the time of the clock. Or GST_CLOCK_TIME_NONE when given invalid input. MT safe. Get the amount of time that master and slave clocks are sampled. # Returns the interval between samples. Checks if the clock is currently synced. This returns if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is not set on the clock. # Returns `true` if the clock is currently synced Get an ID from `self` to trigger a periodic notification. The periodic notifications will start at time `start_time` and will then be fired with the given `interval`. `id` should be unreffed after usage. Free-function: gst_clock_id_unref ## `start_time` the requested start time ## `interval` the requested interval # Returns a `ClockID` that can be used to request the time notification. MT safe. Get a `ClockID` from `self` to trigger a single shot notification at the requested time. The single shot id should be unreffed after usage. Free-function: gst_clock_id_unref ## `time` the requested time # Returns a `ClockID` that can be used to request the time notification. MT safe. Reinitializes the provided periodic `id` to the provided start time and interval. Does not modify the reference count. ## `id` a `ClockID` ## `start_time` the requested start time ## `interval` the requested interval # Returns `true` if the GstClockID could be reinitialized to the provided `time`, else `false`. Adjusts the rate and time of `self`. A rate of 1/1 is the normal speed of the clock. Values bigger than 1/1 make the clock go faster. `internal` and `external` are calibration parameters that arrange that `ClockExt::get_time` should have been `external` at internal time `internal`. This internal time should not be in the future; that is, it should be less than the value of `ClockExt::get_internal_time` when this function is called. Subsequent calls to `ClockExt::get_time` will return clock times computed as follows: ```text time = (internal_time - internal) * rate_num / rate_denom + external ``` This formula is implemented in `ClockExt::adjust_unlocked`. Of course, it tries to do the integer arithmetic as precisely as possible. Note that `ClockExt::get_time` always returns increasing values so when you move the clock backwards, `ClockExt::get_time` will report the previous value until the clock catches up. MT safe. ## `internal` a reference internal time ## `external` a reference external time ## `rate_num` the numerator of the rate of the clock relative to its internal time ## `rate_denom` the denominator of the rate of the clock Set `master` as the master clock for `self`. `self` will be automatically calibrated so that `ClockExt::get_time` reports the same time as the master clock. A clock provider that slaves its clock to a master can get the current calibration values with `ClockExt::get_calibration`. `master` can be `None` in which case `self` will not be slaved anymore. It will however keep reporting its time adjusted with the last configured rate and time offsets. ## `master` a master `Clock` # Returns `true` if the clock is capable of being slaved to a master clock. Trying to set a master on a clock without the `ClockFlags::CanSetMaster` flag will make this function return `false`. MT safe. Set the accuracy of the clock. Some clocks have the possibility to operate with different accuracy at the expense of more resource usage. There is normally no need to change the default resolution of a clock. The resolution of a clock can only be changed if the clock has the `ClockFlags::CanSetResolution` flag set. ## `resolution` The resolution to set # Returns the new resolution of the clock. Sets `self` to synced and emits the GstClock::synced signal, and wakes up any thread waiting in `ClockExt::wait_for_sync`. This function must only be called if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is set on the clock, and is intended to be called by subclasses only. ## `synced` if the clock is synced Set the amount of time, in nanoseconds, to sample master and slave clocks ## `timeout` a timeout Reinitializes the provided single shot `id` to the provided time. Does not modify the reference count. ## `id` a `ClockID` ## `time` The requested time. # Returns `true` if the GstClockID could be reinitialized to the provided `time`, else `false`. Converts the given `external` clock time to the internal time of `self`, using the rate and reference time set with `ClockExt::set_calibration`. This function should be called with the clock's OBJECT_LOCK held and is mainly used by clock subclasses. This function is the reverse of `ClockExt::adjust_unlocked`. ## `external` an external clock time # Returns the internal time of the clock corresponding to `external`. Converts the given `external_target` clock time to the internal time, using the passed calibration parameters. This function performs the same calculation as `ClockExt::unadjust_unlocked` when called using the current calibration parameters. Note: The `self` parameter is unused and can be NULL ## `external_target` a clock time ## `cinternal` a reference internal time ## `cexternal` a reference external time ## `cnum` the numerator of the rate of the clock relative to its internal time ## `cdenom` the denominator of the rate of the clock # Returns the converted time of the clock. Waits until `self` is synced for reporting the current time. If `timeout` is `GST_CLOCK_TIME_NONE` it will wait forever, otherwise it will time out after `timeout` nanoseconds. For asynchronous waiting, the GstClock::synced signal can be used. This returns immediately with TRUE if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is not set on the clock, or if the clock is already synced. ## `timeout` timeout for waiting or `GST_CLOCK_TIME_NONE` # Returns `true` if waiting was successful, or `false` on timeout Signaled on clocks with GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC set once the clock is synchronized, or when it completely lost synchronization. This signal will not be emitted on clocks without the flag. This signal will be emitted from an arbitrary thread, most likely not the application's main thread. ## `synced` if the clock is synced now The return value of a clock operation. The operation succeeded. The operation was scheduled too late. The clockID was unscheduled The ClockID is busy A bad time was provided to a function. An error occurred Operation is not supported The ClockID is done waiting The different kind of clocks. time since Epoch monotonic time since some unspecified starting point 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 be shared between multiple elements. Applications can set a context on a complete pipeline by using `ElementExt::set_context`, which will then be propagated to all child elements. Elements can handle these in `ElementClass.set_context`() and merge them with the context information they already have. When an element needs a context it will do the following actions in this order until one step succeeds: 1. Check if the element already has a context 2. Query downstream with GST_QUERY_CONTEXT for the context 3. Query upstream with GST_QUERY_CONTEXT for the context 4. Post a GST_MESSAGE_NEED_CONTEXT message on the bus with the required context types and afterwards check if a usable context was set now 5. Create a context by itself and post a GST_MESSAGE_HAVE_CONTEXT message on the bus. Bins will catch GST_MESSAGE_NEED_CONTEXT messages and will set any previously known context on the element that asks for it if possible. Otherwise the application should provide one if it can. `Context`s can be persistent. A persistent `Context` is kept in elements when they reach `State::Null`, non-persistent ones will be removed. Also, a non-persistent context won't override a previous persistent context set to an element. Create a new context. ## `context_type` Context type ## `persistent` Persistent context # Returns The new context. Get the type of `self`. # Returns The type of the context. Access the structure of the context. # Returns The structure of the context. The structure is still owned by the context, which means that you should not modify it, free it and that the pointer becomes invalid when you free the context. Checks if `self` has `context_type`. ## `context_type` Context type to check. # Returns `true` if `self` has `context_type`. Check if `self` is persistent. # Returns `true` if the context is persistent. Get a writable version of the structure. # Returns The structure of the context. The structure is still owned by the context, which means that you should not free it and that the pointer becomes invalid when you free the context. This function checks if `self` is writable. Core errors are errors inside the core GStreamer library. a general error which doesn't fit in any other category. Make sure you add a custom message to the error call. do not use this except as a placeholder for deciding where to go while developing code. use this when you do not want to implement this functionality yet. used for state change errors. used for pad-related errors. used for thread-related errors. used for negotiation-related errors. used for event-related errors. used for seek-related errors. used for caps-related errors. used for negotiation-related errors. used if a plugin is missing. used for clock related errors. used if functionality has been disabled at compile time. the number of core error types. Struct to store date, time and timezone information altogether. `DateTime` is refcounted and immutable. Date information is handled using the proleptic Gregorian calendar. Provides basic creation functions and accessor functions to its fields. Creates a new `DateTime` using the date and times in the gregorian calendar in the supplied timezone. `year` should be from 1 to 9999, `month` should be from 1 to 12, `day` from 1 to 31, `hour` from 0 to 23, `minutes` and `seconds` from 0 to 59. Note that `tzoffset` is a float and was chosen so for being able to handle some fractional timezones, while it still keeps the readability of representing it in hours for most timezones. If value is -1 then all over value will be ignored. For example if `month` == -1, then `DateTime` will created only for `year`. If `day` == -1, then `DateTime` will created for `year` and `month` and so on. Free-function: gst_date_time_unref ## `tzoffset` Offset from UTC in hours. ## `year` the gregorian year ## `month` the gregorian month ## `day` the day of the gregorian month ## `hour` the hour of the day ## `minute` the minute of the hour ## `seconds` the second of the minute # Returns the newly created `DateTime` Creates a new `DateTime` from a `glib::DateTime` object. Free-function: gst_date_time_unref ## `dt` the `glib::DateTime`. The new `DateTime` takes ownership. # Returns a newly created `DateTime`, or `None` on error Tries to parse common variants of ISO-8601 datetime strings into a `DateTime`. Possible input formats are (for example): 2012-06-30T22:46:43Z, 2012, 2012-06, 2012-06-30, 2012-06-30T22:46:43-0430, 2012-06-30T22:46Z, 2012-06-30T22:46-0430, 2012-06-30 22:46, 2012-06-30 22:46:43, 2012-06-00, 2012-00-00, 2012-00-30, 22:46:43Z, 22:46Z, 22:46:43-0430, 22:46-0430, 22:46:30, 22:46 If no date is provided, it is assumed to be "today" in the timezone provided (if any), otherwise UTC. Free-function: gst_date_time_unref ## `string` ISO 8601-formatted datetime string. # Returns a newly created `DateTime`, or `None` on error Creates a new `DateTime` using the time since Jan 1, 1970 specified by `secs`. The `DateTime` is in the local timezone. Free-function: gst_date_time_unref ## `secs` seconds from the Unix epoch # Returns the newly created `DateTime` Creates a new `DateTime` using the time since Jan 1, 1970 specified by `secs`. The `DateTime` is in the UTC timezone. Free-function: gst_date_time_unref ## `secs` seconds from the Unix epoch # Returns the newly created `DateTime` Creates a new `DateTime` using the date and times in the gregorian calendar in the local timezone. `year` should be from 1 to 9999, `month` should be from 1 to 12, `day` from 1 to 31, `hour` from 0 to 23, `minutes` and `seconds` from 0 to 59. If `month` is -1, then the `DateTime` created will only contain `year`, and all other fields will be considered not set. If `day` is -1, then the `DateTime` created will only contain `year` and `month` and all other fields will be considered not set. If `hour` is -1, then the `DateTime` created will only contain `year` and `month` and `day`, and the time fields will be considered not set. In this case `minute` and `seconds` should also be -1. Free-function: gst_date_time_unref ## `year` the gregorian year ## `month` the gregorian month, or -1 ## `day` the day of the gregorian month, or -1 ## `hour` the hour of the day, or -1 ## `minute` the minute of the hour, or -1 ## `seconds` the second of the minute, or -1 # Returns the newly created `DateTime` Creates a new `DateTime` representing the current date and time. Free-function: gst_date_time_unref # Returns the newly created `DateTime` which should be freed with `DateTime::unref`. Creates a new `DateTime` that represents the current instant at Universal coordinated time. Free-function: gst_date_time_unref # Returns the newly created `DateTime` which should be freed with `DateTime::unref`. Creates a new `DateTime` using the date and times in the gregorian calendar in the local timezone. `year` should be from 1 to 9999. Free-function: gst_date_time_unref ## `year` the gregorian year # Returns the newly created `DateTime` Creates a new `DateTime` using the date and times in the gregorian calendar in the local timezone. `year` should be from 1 to 9999, `month` should be from 1 to 12. If value is -1 then all over value will be ignored. For example if `month` == -1, then `DateTime` will created only for `year`. Free-function: gst_date_time_unref ## `year` the gregorian year ## `month` the gregorian month # Returns the newly created `DateTime` Creates a new `DateTime` using the date and times in the gregorian calendar in the local timezone. `year` should be from 1 to 9999, `month` should be from 1 to 12, `day` from 1 to 31. If value is -1 then all over value will be ignored. For example if `month` == -1, then `DateTime` will created only for `year`. If `day` == -1, then `DateTime` will created for `year` and `month` and so on. Free-function: gst_date_time_unref ## `year` the gregorian year ## `month` the gregorian month ## `day` the day of the gregorian month # Returns the newly created `DateTime` Returns the day of the month of this `DateTime`. Call gst_date_time_has_day before, to avoid warnings. # Returns 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. # Returns the hour of the day Retrieves the fractional part of the seconds in microseconds represented by `self` in the gregorian calendar. # Returns 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. # 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. # Returns 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. # Returns the second represented by `self` Retrieves the offset from UTC in hours that the timezone specified by `self` represents. Timezones ahead (to the east) of UTC have positive values, timezones before (to the west) of UTC have negative values. If `self` represents UTC time, then the offset is zero. # Returns the offset from UTC in hours Returns the year of this `DateTime` Call gst_date_time_has_year before, to avoid warnings. # Returns The year of this `DateTime` # Returns `true` if `self`'s day field is set, otherwise `false` # Returns `true` if `self`'s month field is set, otherwise `false` # Returns `true` if `self`'s second field is set, otherwise `false` # Returns `true` if `self`'s hour and minute fields are set, otherwise `false` # Returns `true` if `self`'s year field is set (which should always be the case), otherwise `false` Atomically increments the reference count of `self` by one. # Returns the reference `self` Creates a new `glib::DateTime` from a fully defined `DateTime` object. Free-function: g_date_time_unref # Returns a newly created `glib::DateTime`, or `None` on error Create a minimal string compatible with ISO-8601. Possible output formats are (for example): 2012, 2012-06, 2012-06-23, 2012-06-23T23:30Z, 2012-06-23T23:30+0100, 2012-06-23T23:30:59Z, 2012-06-23T23:30:59+0100 # Returns a newly allocated string formatted according to ISO 8601 and only including the datetime fields that are valid, or `None` in case there was an error. The string should be freed with `g_free`. Atomically decrements the reference count of `self` by one. When the reference count reaches zero, the structure is freed. The level defines the importance of a debugging message. The more important a message is, the greater the probability that the debugging system outputs it. No debugging level specified or desired. Used to deactivate debugging output. Error messages are to be used only when an error occurred that stops the application from keeping working correctly. An examples is gst_element_error, which outputs a message with this priority. It does not mean that the application is terminating as with g_error. Warning messages are to inform about abnormal behaviour that could lead to problems or weird behaviour later on. An example of this would be clocking issues ("your computer is pretty slow") or broken input data ("Can't synchronize to stream.") Fixme messages are messages that indicate that something in the executed code path is not fully implemented or handled yet. Note that this does not replace proper error handling in any way, the purpose of this message is to make it easier to spot incomplete/unfinished pieces of code when reading the debug log. Informational messages should be used to keep the developer updated about what is happening. Examples where this should be used are when a typefind function has successfully determined the type of the stream or when an mp3 plugin detects the format to be used. ("This file has mono sound.") Debugging messages should be used when something common happens that is not the expected default behavior, or something that's useful to know but doesn't happen all the time (ie. per loop iteration or buffer processed or event handled). An example would be notifications about state changes or receiving/sending of events. Log messages are messages that are very common but might be useful to know. As a rule of thumb a pipeline that is running as expected should never output anything else but LOG messages whilst processing data. Use this log level to log recurring information in chain functions and loop functions, for example. Tracing-related messages. Examples for this are referencing/dereferencing of objects. memory dump messages are used to log (small) chunks of data as memory dumps in the log. They will be displayed as hexdump with ASCII characters. The number of defined debugging levels. `Device` are objects representing a device, they contain relevant metadata about the device, such as its class and the `Caps` representing the media types it can produce or handle. `Device` are created by `DeviceProvider` objects which can be aggregated by `DeviceMonitor` objects. # Implements [`DeviceExt`](trait.DeviceExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `Device` methods. # Implementors [`Device`](struct.Device.html) Creates the element with all of the required parameters set to use this device. ## `name` name of new element, or `None` to automatically create a unique name. # Returns a new `Element` configured to use this device Getter for the `Caps` that this device supports. # Returns The `Caps` supported by this device. Unref with `gst_caps_unref` when done. Gets the "class" of a device. This is a "/" separated list of classes that represent this device. They are a subset of the classes of the `DeviceProvider` that produced this device. # Returns The device class. Free with `g_free` after use. Gets the user-friendly name of the device. # Returns The device name. Free with `g_free` after use. Gets the extra properties of a device. # Returns The extra properties or `None` when there are none. Free with `Structure::free` after use. Check if `self` matches all of the given classes ## `classes` a "/"-separated list of device classes to match, only match if all classes are matched # Returns `true` if `self` matches. Check if `factory` matches all of the given classes ## `classes` a `None` terminated array of classes to match, only match if all classes are matched # Returns `true` if `self` matches. Tries to reconfigure an existing element to use the device. If this function fails, then one must destroy the element and create a new one using `DeviceExt::create_element`. Note: This should only be implemented for elements can change their device in the PLAYING state. ## `element` a `Element` # Returns `true` if the element could be reconfigured to use this device, `false` otherwise. Applications should create a `DeviceMonitor` when they want to probe, list and monitor devices of a specific type. The `DeviceMonitor` will create the appropriate `DeviceProvider` objects and manage them. It will then post messages on its `Bus` for devices that have been added and removed. The device monitor will monitor all devices matching the filters that the application has set. The basic use pattern of a device monitor is as follows: ```text static gboolean my_bus_func (GstBus * bus, GstMessage * message, gpointer user_data) { GstDevice *device; gchar *name; switch (GST_MESSAGE_TYPE (message)) { case GST_MESSAGE_DEVICE_ADDED: gst_message_parse_device_added (message, &device); name = gst_device_get_display_name (device); g_print("Device added: %s\n", name); g_free (name); gst_object_unref (device); break; case GST_MESSAGE_DEVICE_REMOVED: gst_message_parse_device_removed (message, &device); name = gst_device_get_display_name (device); g_print("Device removed: %s\n", name); g_free (name); gst_object_unref (device); break; default: break; } return G_SOURCE_CONTINUE; } GstDeviceMonitor * setup_raw_video_source_device_monitor (void) { GstDeviceMonitor *monitor; GstBus *bus; GstCaps *caps; monitor = gst_device_monitor_new (); bus = gst_device_monitor_get_bus (monitor); gst_bus_add_watch (bus, my_bus_func, NULL); gst_object_unref (bus); caps = gst_caps_new_empty_simple ("video/x-raw"); gst_device_monitor_add_filter (monitor, "Video/Source", caps); gst_caps_unref (caps); gst_device_monitor_start (monitor); return monitor; } ``` # Implements [`DeviceMonitorExt`](trait.DeviceMonitorExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `DeviceMonitor` methods. # Implementors [`DeviceMonitor`](struct.DeviceMonitor.html) Create a new `DeviceMonitor` # Returns a new device monitor. Adds a filter for which `Device` will be monitored, any device that matches all these classes and the `Caps` will be returned. If this function is called multiple times to add more filters, each will be matched independently. That is, adding more filters will not further restrict what devices are matched. The `Caps` supported by the device as returned by `DeviceExt::get_caps` are not intersected with caps filters added using this function. Filters must be added before the `DeviceMonitor` is started. ## `classes` device classes to use as filter or `None` for any class ## `caps` the `Caps` to filter or `None` for ANY # Returns The id of the new filter or 0 if no provider matched the filter's classes. Gets the `Bus` of this `DeviceMonitor` # Returns a `Bus` Gets a list of devices from all of the relevant monitors. This may actually probe the hardware if the monitor is not currently started. # Returns a `glib::List` of `Device` Get a list of the currently selected device provider factories. This # Returns A list of device provider factory names that are currently being monitored by `self` or `None` when nothing is being monitored. Get if `self` is curretly showing all devices, even those from hidden providers. # Returns `true` when all devices will be shown. Removes a filter from the `DeviceMonitor` using the id that was returned by `DeviceMonitorExt::add_filter`. ## `filter_id` the id of the filter # Returns `true` of the filter id was valid, `false` otherwise Set if all devices should be visible, even those devices from hidden providers. Setting `show_all` to true might show some devices multiple times. ## `show_all` show all devices Starts monitoring the devices, one this has succeeded, the `MessageType::DeviceAdded` and `MessageType::DeviceRemoved` messages will be emitted on the bus when the list of devices changes. # Returns `true` if the device monitoring could be started 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 optionally provide updates to the list of connected devices. Each `DeviceProvider` subclass is a singleton, a plugin should normally provide a single subclass for all devices. Applications would normally use a `DeviceMonitor` to monitor devices from all relevant providers. # Implements [`DeviceProviderExt`](trait.DeviceProviderExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `DeviceProvider` methods. # Implementors [`DeviceProvider`](struct.DeviceProvider.html) Create a new device providerfactory capable of instantiating objects of the `type_` and add the factory to `plugin`. ## `plugin` `Plugin` to register the device provider with, or `None` for a static device provider. ## `name` name of device providers of this type ## `rank` rank of device provider (higher rank means more importance when autoplugging) ## `type_` GType of device provider to register # Returns `true`, if the registering succeeded, `false` on error Posts a message on the provider's `Bus` to inform applications that a new device has been added. This is for use by subclasses. `device`'s reference count will be incremented, and any floating reference will be removed (see `Object::ref_sink`). ## `device` a `Device` that has been added Posts a message on the provider's `Bus` to inform applications that a device has been removed. This is for use by subclasses. ## `device` a `Device` that has been removed Gets the `Bus` of this `DeviceProvider` # Returns a `Bus` Gets a list of devices that this provider understands. This may actually probe the hardware if the provider is not currently started. # Returns a `glib::List` of `Device` Retrieves the factory that was used to create this device provider. # Returns the `DeviceProviderFactory` used for creating this device provider. no refcounting is needed. Get the provider factory names of the `DeviceProvider` instances that are hidden by `self`. # Returns a list of hidden providers factory names or `None` when nothing is hidden by `self`. Free with g_strfreev. Get metadata with `key` in `self`. Feature: `v1_14` ## `key` the key to get # Returns the metadata for `key`. Make `self` hide the devices from the factory with `name`. This function is used when `self` will also provide the devices reported by provider factory `name`. A monitor should stop monitoring the device provider with `name` to avoid duplicate devices. ## `name` a provider factory name Starts providering the devices. This will cause `MessageType::DeviceAdded` and `MessageType::DeviceRemoved` messages to be posted on the provider's bus when devices are added or removed from the system. Since the `DeviceProvider` is a singleton, `DeviceProviderExt::start` may already have been called by another user of the object, `DeviceProviderExt::stop` needs to be called the same number of times. # Returns `true` if the device providering could be started Decreases the use-count by one. If the use count reaches zero, this `DeviceProvider` will stop providering the devices. This needs to be called the same number of times that `DeviceProviderExt::start` was called. Make `self` unhide the devices from factory `name`. This function is used when `self` will no longer provide the devices reported by provider factory `name`. A monitor should start monitoring the devices from provider factory `name` in order to see all devices again. ## `name` a provider factory name `DeviceProviderFactory` is used to create instances of device providers. A GstDeviceProviderfactory can be added to a `Plugin` as it is also a `PluginFeature`. Use the `DeviceProviderFactory::find` and `DeviceProviderFactory::get` functions to create device provider instances or use `DeviceProviderFactory::get_by_name` as a convenient shortcut. # Implements [`PluginFeatureExt`](trait.PluginFeatureExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Search for an device provider factory of the given name. Refs the returned device provider factory; caller is responsible for unreffing. ## `name` name of factory to find # Returns `DeviceProviderFactory` if found, `None` otherwise Returns the device provider of the type defined by the given device provider factory. ## `factoryname` a named factory to instantiate # Returns a `DeviceProvider` or `None` if unable to create device provider Get a list of factories with a rank greater or equal to `minrank`. The list of factories is returned by decreasing rank. ## `minrank` Minimum rank # Returns a `glib::List` of `DeviceProviderFactory` device providers. Use `PluginFeature::list_free` after usage. Returns the device provider of the type defined by the given device providerfactory. # Returns the `DeviceProvider` or `None` if the device provider couldn't be created Get the `glib::Type` for device providers managed by this factory. The type can only be retrieved if the device provider factory is loaded, which can be assured with `PluginFeatureExt::load`. # Returns the `glib::Type` for device providers managed by this factory. Get the metadata on `self` with `key`. ## `key` a key # Returns the metadata with `key` on `self` or `None` when there was no metadata with the given `key`. Get the available keys for the metadata on `self`. # Returns a `None`-terminated array of key strings, or `None` when there is no metadata. Free with `g_strfreev` when no longer needed. Check if `self` matches all of the given `classes` ## `classes` a "/" separate list of classes to match, only match if all classes are matched # Returns `true` if `self` matches or if `classes` is `None`. Check if `self` matches all of the given classes ## `classes` a `None` terminated array of classes to match, only match if all classes are matched # Returns `true` if `self` matches. GstElement is the abstract base class needed to construct an element that can be used in a GStreamer pipeline. Please refer to the plugin writers guide for more information on creating `Element` subclasses. The name of a `Element` can be get with `gst_element_get_name` and set with `gst_element_set_name`. For speed, GST_ELEMENT_NAME() can be used in the core when using the appropriate locking. Do not use this in plug-ins or applications in order to retain ABI compatibility. Elements can have pads (of the type `Pad`). These pads link to pads on other elements. `Buffer` flow between these linked pads. A `Element` has a `glib::List` of `Pad` structures for all their input (or sink) and output (or source) pads. Core and plug-in writers can add and remove pads with `ElementExt::add_pad` and `ElementExt::remove_pad`. An existing pad of an element can be retrieved by name with `ElementExt::get_static_pad`. A new dynamic pad can be created using `ElementExt::request_pad` with a `PadTemplate`. An iterator of all pads can be retrieved with `ElementExt::iterate_pads`. Elements can be linked through their pads. If the link is straightforward, use the `ElementExt::link` convenience function to link two elements, or `ElementExt::link_many` for more elements in a row. Use `ElementExt::link_filtered` to link two elements constrained by a specified set of `Caps`. For finer control, use `ElementExt::link_pads` and `ElementExt::link_pads_filtered` to specify the pads to link on each element by name. Each element has a state (see `State`). You can get and set the state of an element with `ElementExt::get_state` and `ElementExt::set_state`. Setting a state triggers a `StateChange`. To get a string representation of a `State`, use `Element::state_get_name`. You can get and set a `Clock` on an element using `ElementExt::get_clock` and `ElementExt::set_clock`. Some elements can provide a clock for the pipeline if the `ElementFlags::ProvideClock` flag is set. With the `ElementExt::provide_clock` method one can retrieve the clock provided by such an element. Not all elements require a clock to operate correctly. If the `ElementFlags::RequireClock`() flag is set, a clock should be set on the element with `ElementExt::set_clock`. Note that clock selection and distribution is normally handled by the toplevel `Pipeline` so the clock functions are only to be used in very specific situations. # Implements [`ElementExt`](trait.ElementExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `Element` methods. # Implementors [`Bin`](struct.Bin.html), [`Element`](struct.Element.html), [`TagSetter`](struct.TagSetter.html), [`TocSetter`](struct.TocSetter.html) Creates an element for handling the given URI. ## `type_` Whether to create a source or a sink ## `uri` URI to create an element for ## `elementname` Name of created element, can be `None`. # Returns a new element or `None` if none could be created Create a new elementfactory capable of instantiating objects of the `type_` and add the factory to `plugin`. ## `plugin` `Plugin` to register the element with, or `None` for a static element. ## `name` name of elements of this type ## `rank` rank of element (higher rank means more importance when autoplugging) ## `type_` GType of element to register # Returns `true`, if the registering succeeded, `false` on error Gets a string representing the given state change result. ## `state_ret` a `StateChangeReturn` to get the name of. # Returns a string with the name of the state result. Gets a string representing the given state. ## `state` a `State` to get the name of. # Returns a string with the name of the state. Abort the state change of the element. This function is used by elements that do asynchronous state changes and find out something is wrong. This function should be called with the STATE_LOCK held. 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. The pad and the element should be unlocked when calling this function. This function will emit the `Element::pad-added` signal on the element. ## `pad` the `Pad` to add to the element. # Returns `true` if the pad could be added. This function can fail when a pad with the same name already existed or the pad already had another parent. MT safe. Feature: `v1_10` ## `property_name` name of property to watch for changes, or NULL to watch all properties ## `include_value` whether to include the new property value in the message # Returns a watch id, which can be used in connection with `Element::remove_property_notify_watch` to remove the watch again. Feature: `v1_10` ## `property_name` name of property to watch for changes, or NULL to watch all properties ## `include_value` whether to include the new property value in the message # Returns a watch id, which can be used in connection with `Element::remove_property_notify_watch` to remove the watch again. Calls `func` from another thread and passes `user_data` to it. This is to be used for cases when a state change has to be performed from a streaming thread, directly via `ElementExt::set_state` or indirectly e.g. via SEEK events. Calling those functions directly from the streaming thread will cause deadlocks in many situations, as they might involve waiting for the streaming thread to shut down from this very streaming thread. MT safe. Feature: `v1_10` ## `func` Function to call asynchronously from another thread ## `user_data` Data to pass to `func` ## `destroy_notify` GDestroyNotify for `user_data` Perform `transition` on `self`. This function must be called with STATE_LOCK held and is mainly used internally. ## `transition` the requested transition # Returns the `StateChangeReturn` of the state transition. Commit the state change of the element and proceed to the next pending state if any. This function is used by elements that do asynchronous state changes. The core will normally call this method automatically when an element returned `StateChangeReturn::Success` from the state change function. If after calling this method the element still has not reached the pending state, the next state change is performed. This method is used internally and should normally not be called by plugins or applications. This function must be called with STATE_LOCK held. ## `ret` The previous state return value # Returns The result of the commit state change. MT safe. Creates a pad for each pad template that is always available. This function is only useful during object initialization of subclasses of `Element`. Call `func` with `user_data` for each of `self`'s pads. `func` will be called exactly once for each pad that exists at the time of this call, unless one of the calls to `func` returns `false` in which case we will stop iterating pads and return early. If new pads are added or pads are removed while pads are being iterated, this will not be taken into account until next time this function is used. Feature: `v1_14` ## `func` function to call for each pad ## `user_data` user data passed to `func` # Returns `false` if `self` had no pads or if one of the calls to `func` returned `false`. Call `func` with `user_data` for each of `self`'s sink pads. `func` will be called exactly once for each sink pad that exists at the time of this call, unless one of the calls to `func` returns `false` in which case we will stop iterating pads and return early. If new sink pads are added or sink pads are removed while the sink pads are being iterated, this will not be taken into account until next time this function is used. Feature: `v1_14` ## `func` function to call for each sink pad ## `user_data` user data passed to `func` # Returns `false` if `self` had no sink pads or if one of the calls to `func` returned `false`. Call `func` with `user_data` for each of `self`'s source pads. `func` will be called exactly once for each source pad that exists at the time of this call, unless one of the calls to `func` returns `false` in which case we will stop iterating pads and return early. If new source pads are added or source pads are removed while the source pads are being iterated, this will not be taken into account until next time this function is used. Feature: `v1_14` ## `func` function to call for each source pad ## `user_data` user data passed to `func` # Returns `false` if `self` had no source pads or if one of the calls to `func` returned `false`. Returns the base time of the element. The base time is the absolute time of the clock when this element was last put to PLAYING. Subtracting the base time from the clock time gives the running time of the element. # Returns the base time of the element. MT safe. Returns the bus of the element. Note that only a `Pipeline` will provide a bus for the application. # Returns the element's `Bus`. unref after usage. MT safe. Gets the currently configured clock of the element. This is the clock as was last set with `ElementExt::set_clock`. Elements in a pipeline will only have their clock set when the pipeline is in the PLAYING state. # Returns the `Clock` of the element. unref after usage. MT safe. Looks for an unlinked pad to which the given pad can link. It is not guaranteed that linking the pads will work, though it should work in most cases. This function will first attempt to find a compatible unlinked ALWAYS pad, and if none can be found, it will request a compatible REQUEST pad by looking at the templates of `self`. ## `pad` the `Pad` to find a compatible one for. ## `caps` the `Caps` to use as a filter. # Returns the `Pad` to which a link can be made, or `None` if one cannot be found. `GstObjectExt::unref` after usage. Retrieves a pad template from `self` that is compatible with `compattempl`. Pads from compatible templates can be linked together. ## `compattempl` the `PadTemplate` to find a compatible template for # Returns a compatible `PadTemplate`, or `None` if none was found. No unreferencing is necessary. Gets the context with `context_type` set on the element or NULL. MT safe. ## `context_type` a name of a context to retrieve # Returns A `Context` or NULL Gets the context with `context_type` set on the element or NULL. ## `context_type` a name of a context to retrieve # Returns A `Context` or NULL Gets the contexts set on the element. MT safe. # Returns List of `Context` Retrieves the factory that was used to create this element. # Returns the `ElementFactory` used for creating this element. no refcounting is needed. Get metadata with `key` in `klass`. Feature: `v1_14` ## `key` the key to get # Returns the metadata for `key`. Retrieves a padtemplate from `self` with the given name. Feature: `v1_14` ## `name` the name of the `PadTemplate` to get. # Returns the `PadTemplate` with the given name, or `None` if none was found. No unreferencing is necessary. Retrieves a list of the pad templates associated with `self`. The list must not be modified by the calling code. Feature: `v1_14` # Returns the `glib::List` of pad templates. Retrieves a pad from the element by name (e.g. "src_\%d"). This version only retrieves request pads. The pad should be released with `ElementExt::release_request_pad`. This method is slower than manually getting the pad template and calling `ElementExt::request_pad` if the pads should have a specific name (e.g. `name` is "src_1" instead of "src_\%u"). ## `name` the name of the request `Pad` to retrieve. # Returns requested `Pad` if found, otherwise `None`. Release after usage. Returns the start time of the element. The start time is the running time of the clock when this element was last put to PAUSED. Usually the start_time is managed by a toplevel element such as `Pipeline`. MT safe. # Returns the start time of the element. Gets the state of the element. For elements that performed an ASYNC state change, as reported by `ElementExt::set_state`, this function will block up to the specified timeout value for the state change to complete. If the element completes the state change or goes into an error, this function returns immediately with a return value of `StateChangeReturn::Success` or `StateChangeReturn::Failure` respectively. For elements that did not return `StateChangeReturn::Async`, this function returns the current and pending state immediately. This function returns `StateChangeReturn::NoPreroll` if the element successfully changed its state but is not able to provide data yet. This mostly happens for live sources that only produce data in `State::Playing`. While the state change return is equivalent to `StateChangeReturn::Success`, it is returned to the application to signal that some sink elements might not be able to complete their state change because an element is not producing data to complete the preroll. When setting the element to playing, the preroll will complete and playback will start. ## `state` a pointer to `State` to hold the state. Can be `None`. ## `pending` a pointer to `State` to hold the pending state. Can be `None`. ## `timeout` a `ClockTime` to specify the timeout for an async state change or `GST_CLOCK_TIME_NONE` for infinite timeout. # Returns `StateChangeReturn::Success` if the element has no more pending state and the last state change succeeded, `StateChangeReturn::Async` if the element is still performing a state change or `StateChangeReturn::Failure` if the last state change failed. MT safe. Retrieves a pad from `self` by name. This version only retrieves already-existing (i.e. 'static') pads. ## `name` the name of the static `Pad` to retrieve. # Returns the requested `Pad` if found, otherwise `None`. unref after usage. MT safe. Checks if the state of an element is locked. If the state of an element is locked, state changes of the parent don't affect the element. This way you can leave currently unused elements inside bins. Just lock their state before changing the state from `State::Null`. MT safe. # Returns `true`, if the element's state is locked. Retrieves an iterator of `self`'s pads. The iterator should be freed after usage. Also more specialized iterators exists such as `ElementExt::iterate_src_pads` or `ElementExt::iterate_sink_pads`. The order of pads returned by the iterator will be the order in which the pads were added to the element. # Returns the `Iterator` of `Pad`. MT safe. Retrieves an iterator of `self`'s sink pads. The order of pads returned by the iterator will be the order in which the pads were added to the element. # Returns the `Iterator` of `Pad`. MT safe. Retrieves an iterator of `self`'s source pads. The order of pads returned by the iterator will be the order in which the pads were added to the element. # Returns the `Iterator` of `Pad`. MT safe. Links `self` to `dest`. The link must be from source to destination; the other direction will not be tried. The function looks for existing pads that aren't linked yet. It will request new pads if necessary. Such pads need to be released manually when unlinking. If multiple links are possible, only one is established. Make sure you have added your elements to a bin or pipeline with `BinExt::add` before trying to link them. ## `dest` the `Element` containing the destination pad. # Returns `true` if the elements could be linked, `false` otherwise. Links `self` to `dest` using the given caps as filtercaps. The link must be from source to destination; the other direction will not be tried. The function looks for existing pads that aren't linked yet. It will request new pads if necessary. If multiple links are possible, only one is established. Make sure you have added your elements to a bin or pipeline with `BinExt::add` before trying to link them. ## `dest` the `Element` containing the destination pad. ## `filter` the `Caps` to filter the link, or `None` for no filter. # Returns `true` if the pads could be linked, `false` otherwise. Chain together a series of elements. Uses `ElementExt::link`. Make sure you have added your elements to a bin or pipeline with `BinExt::add` before trying to link them. ## `element_2` the second `Element` in the link chain. # Returns `true` on success, `false` otherwise. Links the two named pads of the source and destination elements. Side effect is that if one of the pads has no parent, it becomes a child of the parent of the other element. If they have different parents, the link fails. ## `srcpadname` the name of the `Pad` in source element or `None` for any pad. ## `dest` the `Element` containing the destination pad. ## `destpadname` the name of the `Pad` in destination element, or `None` for any pad. # Returns `true` if the pads could be linked, `false` otherwise. Links the two named pads of the source and destination elements. Side effect is that if one of the pads has no parent, it becomes a child of the parent of the other element. If they have different parents, the link fails. If `caps` is not `None`, makes sure that the caps of the link is a subset of `caps`. ## `srcpadname` the name of the `Pad` in source element or `None` for any pad. ## `dest` the `Element` containing the destination pad. ## `destpadname` the name of the `Pad` in destination element or `None` for any pad. ## `filter` the `Caps` to filter the link, or `None` for no filter. # Returns `true` if the pads could be linked, `false` otherwise. Links the two named pads of the source and destination elements. Side effect is that if one of the pads has no parent, it becomes a child of the parent of the other element. If they have different parents, the link fails. Calling `ElementExt::link_pads_full` with `flags` == `PadLinkCheck::Default` is the same as calling `ElementExt::link_pads` and the recommended way of linking pads with safety checks applied. This is a convenience function for `PadExt::link_full`. ## `srcpadname` the name of the `Pad` in source element or `None` for any pad. ## `dest` the `Element` containing the destination pad. ## `destpadname` the name of the `Pad` in destination element, or `None` for any pad. ## `flags` the `PadLinkCheck` to be performed when linking pads. # Returns `true` if the pads could be linked, `false` otherwise. Brings the element to the lost state. The current state of the element is copied to the pending state so that any call to `ElementExt::get_state` will return `StateChangeReturn::Async`. An ASYNC_START message is posted. If the element was PLAYING, it will go to PAUSED. The element will be restored to its PLAYING state by the parent pipeline when it prerolls again. This is mostly used for elements that lost their preroll buffer in the `State::Paused` or `State::Playing` state after a flush, they will go to their pending state again when a new preroll buffer is queued. This function can only be called when the element is currently not in error or an async state change. This function is used internally and should normally not be called from plugins or applications. Post an error, warning or info message on the bus from inside an element. `type_` must be of `MessageType::Error`, `MessageType::Warning` or `MessageType::Info`. MT safe. ## `type_` the `MessageType` ## `domain` the GStreamer GError domain this message belongs to ## `code` the GError code belonging to the domain ## `text` an allocated text string to be used as a replacement for the default message connected to code, or `None` ## `debug` an allocated debug message to be used as a replacement for the default debugging information, or `None` ## `file` the source code file where the error was generated ## `function` the source code function where the error was generated ## `line` the source code line where the error was generated Post an error, warning or info message on the bus from inside an element. `type_` must be of `MessageType::Error`, `MessageType::Warning` or `MessageType::Info`. Feature: `v1_10` ## `type_` the `MessageType` ## `domain` the GStreamer GError domain this message belongs to ## `code` the GError code belonging to the domain ## `text` an allocated text string to be used as a replacement for the default message connected to code, or `None` ## `debug` an allocated debug message to be used as a replacement for the default debugging information, or `None` ## `file` the source code file where the error was generated ## `function` the source code function where the error was generated ## `line` the source code line where the error was generated ## `structure` optional details structure Use this function to signal that the element does not expect any more pads to show up in the current pipeline. This function should be called whenever pads have been added by the element itself. Elements with `PadPresence::Sometimes` pad templates use this in combination with autopluggers to figure out that the element is done initializing its pads. This function emits the `Element::no-more-pads` signal. MT safe. Post a message on the element's `Bus`. This function takes ownership of the message; if you want to access the message after this call, you should add an additional reference before calling. ## `message` a `Message` to post # Returns `true` if the message was successfully posted. The function returns `false` if the element did not have a bus. MT safe. Get the clock provided by the given element. > An element is only required to provide a clock in the PAUSED > state. Some elements can provide a clock in other states. # Returns the GstClock provided by the element or `None` if no clock could be provided. Unref after usage. MT safe. Performs a query on the given element. For elements that don't implement a query handler, this function forwards the query to a random srcpad or to the peer of a random linked sinkpad of this element. Please note that some queries might need a running pipeline to work. ## `query` the `Query`. # Returns `true` if the query could be performed. MT safe. Queries an element to convert `src_val` in `src_format` to `dest_format`. ## `src_format` a `Format` to convert from. ## `src_val` a value to convert. ## `dest_format` the `Format` to convert to. ## `dest_val` a pointer to the result. # Returns `true` if the query could be performed. Queries an element (usually top-level pipeline or playbin element) for the total stream duration in nanoseconds. This query will only work once the pipeline is prerolled (i.e. reached PAUSED or PLAYING state). The application will receive an ASYNC_DONE message on the pipeline bus when that is the case. If the duration changes for some reason, you will get a DURATION_CHANGED message on the pipeline bus, in which case you should re-query the duration using this function. ## `format` the `Format` requested ## `duration` A location in which to store the total duration, or `None`. # Returns `true` if the query could be performed. Queries an element (usually top-level pipeline or playbin element) for the stream position in nanoseconds. This will be a value between 0 and the stream duration (if the stream duration is known). This query will usually only work once the pipeline is prerolled (i.e. reached PAUSED or PLAYING state). The application will receive an ASYNC_DONE message on the pipeline bus when that is the case. If one repeatedly calls this function one can also create a query and reuse it in `Element::query`. ## `format` the `Format` requested ## `cur` a location in which to store the current position, or `None`. # Returns `true` if the query could be performed. Makes the element free the previously requested pad as obtained with `ElementExt::request_pad`. This does not unref the pad. If the pad was created by using `ElementExt::request_pad`, `ElementExt::release_request_pad` needs to be followed by `GstObjectExt::unref` to free the `pad`. MT safe. ## `pad` the `Pad` to release. Removes `pad` from `self`. `pad` will be destroyed if it has not been referenced elsewhere using `GstObjectExt::unparent`. This function is used by plugin developers and should not be used by applications. Pads that were dynamically requested from elements with `ElementExt::request_pad` should be released with the `ElementExt::release_request_pad` function instead. Pads are not automatically deactivated so elements should perform the needed steps to deactivate the pad in case this pad is removed in the PAUSED or PLAYING state. See `PadExt::set_active` for more information about deactivating pads. The pad and the element should be unlocked when calling this function. This function will emit the `Element::pad-removed` signal on the element. ## `pad` the `Pad` to remove from the element. # Returns `true` if the pad could be removed. Can return `false` if the pad does not belong to the provided element. MT safe. Feature: `v1_10` ## `watch_id` watch id to remove Retrieves a request pad from the element according to the provided template. Pad templates can be looked up using `ElementFactory::get_static_pad_templates`. The pad should be released with `ElementExt::release_request_pad`. ## `templ` a `PadTemplate` of which we want a pad of. ## `name` the name of the request `Pad` to retrieve. Can be `None`. ## `caps` the caps of the pad we want to request. Can be `None`. # Returns requested `Pad` if found, otherwise `None`. Release after usage. Sends a seek event to an element. See `Event::new_seek` for the details of the parameters. The seek event is sent to the element using `Element::send_event`. MT safe. ## `rate` The new playback rate ## `format` The format of the seek values ## `flags` The optional seek flags. ## `start_type` The type and flags for the new start position ## `start` The value of the new start position ## `stop_type` The type and flags for the new stop position ## `stop` The value of the new stop position # Returns `true` if the event was handled. Flushing seeks will trigger a preroll, which will emit `MessageType::AsyncDone`. Simple API to perform a seek on the given element, meaning it just seeks to the given position relative to the start of the stream. For more complex operations like segment seeks (e.g. for looping) or changing the playback rate or seeking relative to the last configured playback segment you should use `Element::seek`. In a completely prerolled PAUSED or PLAYING pipeline, seeking is always guaranteed to return `true` on a seekable media type or `false` when the media type is certainly not seekable (such as a live stream). Some elements allow for seeking in the READY state, in this case they will store the seek event and execute it when they are put to PAUSED. If the element supports seek in READY, it will always return `true` when it receives the event in the READY state. ## `format` a `Format` to execute the seek in, such as `Format::Time` ## `seek_flags` seek options; playback applications will usually want to use GST_SEEK_FLAG_FLUSH | GST_SEEK_FLAG_KEY_UNIT here ## `seek_pos` position to seek to (relative to the start); if you are doing a seek in `Format::Time` this value is in nanoseconds - multiply with `GST_SECOND` to convert seconds to nanoseconds or with `GST_MSECOND` to convert milliseconds to nanoseconds. # Returns `true` if the seek operation succeeded. Flushing seeks will trigger a preroll, which will emit `MessageType::AsyncDone`. Sends an event to an element. If the element doesn't implement an event handler, the event will be pushed on a random linked sink pad for downstream events or a random linked source pad for upstream events. This function takes ownership of the provided event so you should `gst_event_ref` it if you want to reuse the event after this call. MT safe. ## `event` the `Event` to send to the element. # Returns `true` if the event was handled. Events that trigger a preroll (such as flushing seeks and steps) will emit `MessageType::AsyncDone`. Set the base time of an element. See `ElementExt::get_base_time`. MT safe. ## `time` the base time to set. Sets the bus of the element. Increases the refcount on the bus. For internal use only, unless you're testing elements. MT safe. ## `bus` the `Bus` to set. Sets the clock for the element. This function increases the refcount on the clock. Any previously set clock on the object is unreffed. ## `clock` the `Clock` to set for the element. # Returns `true` if the element accepted the clock. An element can refuse a clock when it, for example, is not able to slave its internal clock to the `clock` or when it requires a specific clock to operate. MT safe. Sets the context of the element. Increases the refcount of the context. MT safe. ## `context` the `Context` to set. Locks the state of an element, so state changes of the parent don't affect this element anymore. MT safe. ## `locked_state` `true` to lock the element's state # Returns `true` if the state was changed, `false` if bad parameters were given or the elements state-locking needed no change. Set the start time of an element. The start time of the element is the running time of the element when it last went to the PAUSED state. In READY or after a flushing seek, it is set to 0. Toplevel elements like `Pipeline` will manage the start_time and base_time on its children. Setting the start_time to `GST_CLOCK_TIME_NONE` on such a toplevel element will disable the distribution of the base_time to the children and can be useful if the application manages the base_time itself, for example if you want to synchronize capture from multiple pipelines, and you can also ensure that the pipelines have the same clock. MT safe. ## `time` the base time to set. Sets the state of the element. This function will try to set the requested state by going through all the intermediary states and calling the class's state change function for each. This function can return `StateChangeReturn::Async`, in which case the element will perform the remainder of the state change asynchronously in another thread. An application can use `ElementExt::get_state` to wait for the completion of the state change or it can wait for a `MessageType::AsyncDone` or `MessageType::StateChanged` on the bus. State changes to `State::Ready` or `State::Null` never return `StateChangeReturn::Async`. ## `state` the element's new `State`. # Returns Result of the state change using `StateChangeReturn`. MT safe. Tries to change the state of the element to the same as its parent. If this function returns `false`, the state of element is undefined. # Returns `true`, if the element's state could be synced to the parent's state. MT safe. Unlinks all source pads of the source element with all sink pads of the sink element to which they are linked. If the link has been made using `ElementExt::link`, it could have created an requestpad, which has to be released using `ElementExt::release_request_pad`. ## `dest` the sink `Element` to unlink. Unlinks a series of elements. Uses `ElementExt::unlink`. ## `element_2` the second `Element` in the link chain. Unlinks the two named pads of the source and destination elements. This is a convenience function for `PadExt::unlink`. ## `srcpadname` the name of the `Pad` in source element. ## `dest` a `Element` containing the destination pad. ## `destpadname` the name of the `Pad` in destination element. This signals that the element will not generate more dynamic pads. Note that this signal will usually be emitted from the context of the streaming thread. a new `Pad` has been added to the element. Note that this signal will usually be emitted from the context of the streaming thread. Also keep in mind that if you add new elements to the pipeline in the signal handler you will need to set them to the desired target state with `ElementExt::set_state` or `ElementExt::sync_state_with_parent`. ## `new_pad` the pad that has been added a `Pad` has been removed from the element ## `old_pad` the pad that has been removed `ElementFactory` is used to create instances of elements. A GstElementFactory can be added to a `Plugin` as it is also a `PluginFeature`. Use the `ElementFactory::find` and `ElementFactory::create` functions to create element instances or use `ElementFactory::make` as a convenient shortcut. The following code example shows you how to create a GstFileSrc element. ## Using an element factory ```C #include <gst/gst.h> GstElement *src; GstElementFactory *srcfactory; gst_init (&argc, &argv); srcfactory = gst_element_factory_find ("filesrc"); g_return_if_fail (srcfactory != NULL); src = gst_element_factory_create (srcfactory, "src"); g_return_if_fail (src != NULL); ... ``` # Implements [`PluginFeatureExt`](trait.PluginFeatureExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Search for an element factory of the given name. Refs the returned element factory; caller is responsible for unreffing. ## `name` name of factory to find # Returns `ElementFactory` if found, `None` otherwise Filter out all the elementfactories in `list` that can handle `caps` in the given direction. If `subsetonly` is `true`, then only the elements whose pads templates are a complete superset of `caps` will be returned. Else any element whose pad templates caps can intersect with `caps` will be returned. ## `list` a `glib::List` of `ElementFactory` to filter ## `caps` a `Caps` ## `direction` a `PadDirection` to filter on ## `subsetonly` whether to filter on caps subsets or not. # Returns a `glib::List` of `ElementFactory` elements that match the given requisites. Use `PluginFeature::list_free` after usage. Get a list of factories that match the given `type_`. Only elements with a rank greater or equal to `minrank` will be returned. The list of factories is returned by decreasing rank. ## `type_` a `ElementFactoryListType` ## `minrank` Minimum rank # Returns a `glib::List` of `ElementFactory` elements. Use `PluginFeature::list_free` after usage. Create a new element of the type defined by the given element factory. If name is `None`, then the element will receive a guaranteed unique name, consisting of the element factory name and a number. If name is given, it will be given the name supplied. ## `factoryname` a named factory to instantiate ## `name` name of new element, or `None` to automatically create a unique name # Returns new `Element` or `None` if unable to create element Checks if the factory can sink all possible capabilities. ## `caps` the caps to check # Returns `true` if the caps are fully compatible. Checks if the factory can sink any possible capability. ## `caps` the caps to check # Returns `true` if the caps have a common subset. Checks if the factory can src all possible capabilities. ## `caps` the caps to check # Returns `true` if the caps are fully compatible. Checks if the factory can src any possible capability. ## `caps` the caps to check # Returns `true` if the caps have a common subset. Create a new element of the type defined by the given elementfactory. It will be given the name supplied, since all elements require a name as their first argument. ## `name` name of new element, or `None` to automatically create a unique name # Returns new `Element` or `None` if the element couldn't be created Get the `glib::Type` for elements managed by this factory. The type can only be retrieved if the element factory is loaded, which can be assured with `PluginFeatureExt::load`. # Returns the `glib::Type` for elements managed by this factory or 0 if the factory is not loaded. Get the metadata on `self` with `key`. ## `key` a key # Returns the metadata with `key` on `self` or `None` when there was no metadata with the given `key`. Get the available keys for the metadata on `self`. # Returns a `None`-terminated array of key strings, or `None` when there is no metadata. Free with `g_strfreev` when no longer needed. Gets the number of pad_templates in this factory. # Returns the number of pad_templates Gets the `glib::List` of `StaticPadTemplate` for this factory. # Returns the static pad templates Gets a `None`-terminated array of protocols this element supports or `None` if no protocols are supported. You may not change the contents of the returned array, as it is still owned by the element factory. Use `g_strdupv` to make a copy of the protocol string array if you need to. # Returns the supported protocols or `None` Gets the type of URIs the element supports or `URIType::Unknown` if none. # Returns type of URIs this element supports Check if `self` implements the interface with name `interfacename`. ## `interfacename` an interface name # Returns `true` when `self` implement the interface. Check if `self` is of the given types. ## `type_` a `ElementFactoryListType` # Returns `true` if `self` is of `type_`. The event class provides factory methods to construct events for sending and functions to query (parse) received events. Events are usually created with gst_event_new_*() which takes event-type specific parameters as arguments. To send an event application will usually use `Element::send_event` and elements will use `Pad::send_event` or `Pad::push_event`. The event should be unreffed with `gst_event_unref` if it has not been sent. Events that have been received can be parsed with their respective gst_event_parse_*() functions. It is valid to pass `None` for unwanted details. Events are passed between elements in parallel to the data stream. Some events are serialized with buffers, others are not. Some events only travel downstream, others only upstream. Some events can travel both upstream and downstream. The events are used to signal special conditions in the datastream such as EOS (end of stream) or the start of a new stream-segment. Events are also used to flush the pipeline of any pending data. Most of the event API is used inside plugins. Applications usually only construct and use seek events. To do that `Event::new_seek` is used to create a seek event. It takes the needed parameters to specify seeking time and mode. ```C GstEvent *event; gboolean result; ... // construct a seek event to play the media from second 2 to 5, flush // the pipeline to decrease latency. event = gst_event_new_seek (1.0, GST_FORMAT_TIME, GST_SEEK_FLAG_FLUSH, GST_SEEK_TYPE_SET, 2 * GST_SECOND, GST_SEEK_TYPE_SET, 5 * GST_SECOND); ... result = gst_element_send_event (pipeline, event); if (!result) g_warning ("seek failed"); ... ``` Create a new buffersize event. The event is sent downstream and notifies elements that they should provide a buffer of the specified dimensions. When the `async` flag is set, a thread boundary is preferred. ## `format` buffer format ## `minsize` minimum buffer size ## `maxsize` maximum buffer size ## `async` thread behavior # Returns a new `Event` Create a new CAPS event for `caps`. The caps event can only travel downstream synchronized with the buffer flow and contains the format of the buffers that will follow after the event. ## `caps` a `Caps` # Returns the new CAPS event. Create a new custom-typed event. This can be used for anything not handled by other event-specific functions to pass an event to another element. Make sure to allocate an event type with the `GST_EVENT_MAKE_TYPE` macro, assigning a free number and filling in the correct direction and serialization flags. New custom events can also be created by subclassing the event type if needed. ## `type_` The type of the new event ## `structure` the structure for the event. The event will take ownership of the structure. # Returns the new custom event. Create a new EOS event. The eos event can only travel downstream synchronized with the buffer flow. Elements that receive the EOS event on a pad can return `FlowReturn::Eos` as a `FlowReturn` when data after the EOS event arrives. The EOS event will travel down to the sink elements in the pipeline which will then post the `MessageType::Eos` on the bus after they have finished playing any buffered data. When all sinks have posted an EOS message, an EOS message is forwarded to the application. The EOS event itself will not cause any state transitions of the pipeline. # Returns the new EOS event. Allocate a new flush start event. The flush start event can be sent upstream and downstream and travels out-of-bounds with the dataflow. It marks pads as being flushing and will make them return `FlowReturn::Flushing` when used for data flow with `Pad::push`, `Pad::chain`, `Pad::get_range` and `Pad::pull_range`. Any event (except a `EventType::FlushStop`) received on a flushing pad will return `false` immediately. Elements should unlock any blocking functions and exit their streaming functions as fast as possible when this event is received. This event is typically generated after a seek to flush out all queued data in the pipeline so that the new media is played as soon as possible. # Returns a new flush start event. Allocate a new flush stop event. The flush stop event can be sent upstream and downstream and travels serialized with the dataflow. It is typically sent after sending a FLUSH_START event to make the pads accept data again. Elements can process this event synchronized with the dataflow since the preceding FLUSH_START event stopped the dataflow. This event is typically generated to complete a seek and to resume dataflow. ## `reset_time` if time should be reset # Returns a new flush stop event. Create a new GAP event. A gap event can be thought of as conceptually equivalent to a buffer to signal that there is no data for a certain amount of time. This is useful to signal a gap to downstream elements which may wait for data, such as muxers or mixers or overlays, especially for sparse streams such as subtitle streams. ## `timestamp` the start time (pts) of the gap ## `duration` the duration of the gap # Returns the new GAP event. Create a new latency event. The event is sent upstream from the sinks and notifies elements that they should add an additional `latency` to the running time before synchronising against the clock. The latency is mostly used in live sinks and is always expressed in the time format. ## `latency` the new latency value # Returns a new `Event` Create a new navigation event from the given description. ## `structure` description of the event. The event will take ownership of the structure. # Returns a new `Event` Creates a new event containing information specific to a particular protection system (uniquely identified by `system_id`), by which that protection system can acquire key(s) to decrypt a protected stream. In order for a decryption element to decrypt media protected using a specific system, it first needs all the protection system specific information necessary to acquire the decryption key(s) for that stream. The functions defined here enable this information to be passed in events from elements that extract it (e.g., ISOBMFF demuxers, MPEG DASH demuxers) to protection decrypter elements that use it. Events containing protection system specific information are created using `Event::new_protection`, and they can be parsed by downstream elements using `Event::parse_protection`. In Common Encryption, protection system specific information may be located within ISOBMFF files, both in movie (moov) boxes and movie fragment (moof) boxes; it may also be contained in ContentProtection elements within MPEG DASH MPDs. The events created by `Event::new_protection` contain data identifying from which of these locations the encapsulated protection system specific information originated. This origin information is required as some protection systems use different encodings depending upon where the information originates. The events returned by `Event::new_protection` are implemented in such a way as to ensure that the most recently-pushed protection info event of a particular `origin` and `system_id` will be stuck to the output pad of the sending element. ## `system_id` a string holding a UUID that uniquely identifies a protection system. ## `data` a `Buffer` holding protection system specific information. The reference count of the buffer will be incremented by one. ## `origin` a string indicating where the protection information carried in the event was extracted from. The allowed values of this string will depend upon the protection scheme. # Returns a `EventType::Protection` event, if successful; `None` if unsuccessful. Allocate a new qos event with the given values. The QOS event is generated in an element that wants an upstream element to either reduce or increase its rate because of high/low CPU load or other resource usage such as network performance or throttling. Typically sinks generate these events for each buffer they receive. `type_` indicates the reason for the QoS event. `QOSType::Overflow` is used when a buffer arrived in time or when the sink cannot keep up with the upstream datarate. `QOSType::Underflow` is when the sink is not receiving buffers fast enough and thus has to drop late buffers. `QOSType::Throttle` is used when the datarate is artificially limited by the application, for example to reduce power consumption. `proportion` indicates the real-time performance of the streaming in the element that generated the QoS event (usually the sink). The value is generally computed based on more long term statistics about the streams timestamps compared to the clock. A value < 1.0 indicates that the upstream element is producing data faster than real-time. A value > 1.0 indicates that the upstream element is not producing data fast enough. 1.0 is the ideal `proportion` value. The proportion value can safely be used to lower or increase the quality of the element. `diff` is the difference against the clock in running time of the last buffer that caused the element to generate the QOS event. A negative value means that the buffer with `timestamp` arrived in time. A positive value indicates how late the buffer with `timestamp` was. When throttling is enabled, `diff` will be set to the requested throttling interval. `timestamp` is the timestamp of the last buffer that cause the element to generate the QOS event. It is expressed in running time and thus an ever increasing value. The upstream element can use the `diff` and `timestamp` values to decide whether to process more buffers. For positive `diff`, all buffers with timestamp <= `timestamp` + `diff` will certainly arrive late in the sink as well. A (negative) `diff` value so that `timestamp` + `diff` would yield a result smaller than 0 is not allowed. The application can use general event probes to intercept the QoS event and implement custom application specific QoS handling. ## `type_` the QoS type ## `proportion` the proportion of the qos message ## `diff` The time difference of the last Clock sync ## `timestamp` The timestamp of the buffer # Returns a new QOS event. Create a new reconfigure event. The purpose of the reconfigure event is to travel upstream and make elements renegotiate their caps or reconfigure their buffer pools. This is useful when changing properties on elements or changing the topology of the pipeline. # Returns a new `Event` Allocate a new seek event with the given parameters. The seek event configures playback of the pipeline between `start` to `stop` at the speed given in `rate`, also called a playback segment. The `start` and `stop` values are expressed in `format`. A `rate` of 1.0 means normal playback rate, 2.0 means double speed. Negatives values means backwards playback. A value of 0.0 for the rate is not allowed and should be accomplished instead by PAUSING the pipeline. A pipeline has a default playback segment configured with a start position of 0, a stop position of -1 and a rate of 1.0. The currently configured playback segment can be queried with `QueryType::Segment`. `start_type` and `stop_type` specify how to adjust the currently configured start and stop fields in playback segment. Adjustments can be made relative or absolute to the last configured values. A type of `SeekType::None` means that the position should not be updated. When the rate is positive and `start` has been updated, playback will start from the newly configured start position. For negative rates, playback will start from the newly configured stop position (if any). If the stop position is updated, it must be different from -1 (`GST_CLOCK_TIME_NONE`) for negative rates. It is not possible to seek relative to the current playback position, to do this, PAUSE the pipeline, query the current playback position with `QueryType::Position` and update the playback segment current position with a `SeekType::Set` to the desired position. ## `rate` The new playback rate ## `format` The format of the seek values ## `flags` The optional seek flags ## `start_type` The type and flags for the new start position ## `start` The value of the new start position ## `stop_type` The type and flags for the new stop position ## `stop` The value of the new stop position # Returns a new seek event. Create a new SEGMENT event for `segment`. The segment event can only travel downstream synchronized with the buffer flow and contains timing information and playback properties for the buffers that will follow. The segment event marks the range of buffers to be processed. All data not within the segment range is not to be processed. This can be used intelligently by plugins to apply more efficient methods of skipping unneeded data. The valid range is expressed with the `start` and `stop` values. The time value of the segment is used in conjunction with the start value to convert the buffer timestamps into the stream time. This is usually done in sinks to report the current stream_time. `time` represents the stream_time of a buffer carrying a timestamp of `start`. `time` cannot be -1. `start` cannot be -1, `stop` can be -1. If there is a valid `stop` given, it must be greater or equal the `start`, including when the indicated playback `rate` is < 0. The `applied_rate` value provides information about any rate adjustment that has already been made to the timestamps and content on the buffers of the stream. (`rate` * `applied_rate`) should always equal the rate that has been requested for playback. For example, if an element has an input segment with intended playback `rate` of 2.0 and applied_rate of 1.0, it can adjust incoming timestamps and buffer content by half and output a segment event with `rate` of 1.0 and `applied_rate` of 2.0 After a segment event, the buffer stream time is calculated with: time + (TIMESTAMP(buf) - start) * ABS (rate * applied_rate) ## `segment` a `Segment` # Returns the new SEGMENT event. Create a new segment-done event. This event is sent by elements that finish playback of a segment as a result of a segment seek. ## `format` The format of the position being done ## `position` The position of the segment being done # Returns a new `Event` Allocate a new select-streams event. The select-streams event requests the specified `streams` to be activated. The list of `streams` corresponds to the "Stream ID" of each stream to be activated. Those ID can be obtained via the `Stream` objects present in `EventType::StreamStart`, `EventType::StreamCollection` or `MessageType::StreamCollection`. Note: The list of `streams` can not be empty. Feature: `v1_10` ## `streams` the list of streams to activate # Returns a new select-streams event or `None` in case of an error (like an empty streams list). Create a new sink-message event. The purpose of the sink-message event is to instruct a sink to post the message contained in the event synchronized with the stream. `name` is used to store multiple sticky events on one pad. ## `name` a name for the event ## `msg` the `Message` to be posted # Returns a new `Event` Create a new step event. The purpose of the step event is to instruct a sink to skip `amount` (expressed in `format`) of media. It can be used to implement stepping through the video frame by frame or for doing fast trick modes. A rate of <= 0.0 is not allowed. Pause the pipeline, for the effect of rate = 0.0 or first reverse the direction of playback using a seek event to get the same effect as rate < 0.0. The `flush` flag will clear any pending data in the pipeline before starting the step operation. The `intermediate` flag instructs the pipeline that this step operation is part of a larger step operation. ## `format` the format of `amount` ## `amount` the amount of data to step ## `rate` the step rate ## `flush` flushing steps ## `intermediate` intermediate steps # Returns a new `Event` Create a new STREAM_COLLECTION event. The stream collection event can only travel downstream synchronized with the buffer flow. Source elements, demuxers and other elements that manage collections of streams and post `StreamCollection` messages on the bus also send this event downstream on each pad involved in the collection, so that activation of a new collection can be tracked through the downstream data flow. Feature: `v1_10` ## `collection` Active collection for this data flow # Returns the new STREAM_COLLECTION event. Create a new Stream Group Done event. The stream-group-done event can only travel downstream synchronized with the buffer flow. Elements that receive the event on a pad should handle it mostly like EOS, and emit any data or pending buffers that would depend on more data arriving and unblock, since there won't be any more data. This event is followed by EOS at some point in the future, and is generally used when switching pads - to unblock downstream so that new pads can be exposed before sending EOS on the existing pads. Feature: `v1_10` ## `group_id` the group id of the stream group which is ending # Returns the new stream-group-done event. Create a new STREAM_START event. The stream start event can only travel downstream synchronized with the buffer flow. It is expected to be the first event that is sent for a new stream. Source elements, demuxers and other elements that create new streams are supposed to send this event as the first event of a new stream. It should not be sent after a flushing seek or in similar situations and is used to mark the beginning of a new logical stream. Elements combining multiple streams must ensure that this event is only forwarded downstream once and not for every single input stream. The `stream_id` should be a unique string that consists of the upstream stream-id, / as separator and a unique stream-id for this specific stream. A new stream-id should only be created for a stream if the upstream stream is split into (potentially) multiple new streams, e.g. in a demuxer, but not for every single element in the pipeline. `PadExt::create_stream_id` or `PadExt::create_stream_id_printf` can be used to create a stream-id. There are no particular semantics for the stream-id, though it should be deterministic (to support stream matching) and it might be used to order streams (besides any information conveyed by stream flags). ## `stream_id` Identifier for this stream # Returns the new STREAM_START event. Generates a metadata tag event from the given `taglist`. The scope of the taglist specifies if the taglist applies to the complete medium or only to this specific stream. As the tag event is a sticky event, elements should merge tags received from upstream with a given scope with their own tags with the same scope and create a new tag event from it. ## `taglist` metadata list. The event will take ownership of the taglist. # Returns a new `Event` Generate a TOC event from the given `toc`. The purpose of the TOC event is to inform elements that some kind of the TOC was found. ## `toc` `Toc` structure. ## `updated` whether `toc` was updated or not. # Returns a new `Event`. Generate a TOC select event with the given `uid`. The purpose of the TOC select event is to start playback based on the TOC's entry with the given `uid`. ## `uid` UID in the TOC to start playback from. # Returns a new `Event`. Parses a segment `self` and copies the `Segment` into the location given by `segment`. ## `segment` a pointer to a `Segment` Retrieve the accumulated running time offset of the event. Events passing through `GstPads` that have a running time offset set via `PadExt::set_offset` will get their offset adjusted according to the pad's offset. If the event contains any information that related to the running time, this information will need to be updated before usage with this offset. # Returns The event's running time offset MT safe. Retrieve the sequence number of a event. Events have ever-incrementing sequence numbers, which may also be set explicitly via `Event::set_seqnum`. Sequence numbers are typically used to indicate that a event corresponds to some other set of events or messages, for example an EOS event corresponding to a SEEK event. It is considered good practice to make this correspondence when possible, though it is not required. Note that events and messages share the same sequence number incrementor; two events or messages will never have the same sequence number unless that correspondence was made explicitly. # Returns The event's sequence number. MT safe. Access the structure of the event. # Returns The structure of the event. The structure is still owned by the event, which means that you should not free it and that the pointer becomes invalid when you free the event. MT safe. Checks if `self` has the given `name`. This function is usually used to check the name of a custom event. ## `name` name to check # Returns `true` if `name` matches the name of the event structure. Get the format, minsize, maxsize and async-flag in the buffersize event. ## `format` A pointer to store the format in ## `minsize` A pointer to store the minsize in ## `maxsize` A pointer to store the maxsize in ## `async` A pointer to store the async-flag in Get the caps from `self`. The caps remains valid as long as `self` remains valid. ## `caps` A pointer to the caps Parse the FLUSH_STOP event and retrieve the `reset_time` member. ## `reset_time` if time should be reset Extract timestamp and duration from a new GAP event. ## `timestamp` location where to store the start time (pts) of the gap, or `None` ## `duration` location where to store the duration of the gap, or `None` ## `group_id` address of variable where to store the group id # Returns `true` if a group id was set on the event and could be parsed, `false` otherwise. Get the latency in the latency event. ## `latency` A pointer to store the latency in. Parses an event containing protection system specific information and stores the results in `system_id`, `data` and `origin`. The data stored in `system_id`, `origin` and `data` are valid until `self` is released. ## `system_id` pointer to store the UUID string uniquely identifying a content protection system. ## `data` pointer to store a `Buffer` holding protection system specific information. ## `origin` pointer to store a value that indicates where the protection information carried by `self` was extracted from. Get the type, proportion, diff and timestamp in the qos event. See `Event::new_qos` for more information about the different QoS values. `timestamp` will be adjusted for any pad offsets of pads it was passing through. ## `type_` A pointer to store the QoS type in ## `proportion` A pointer to store the proportion in ## `diff` A pointer to store the diff in ## `timestamp` A pointer to store the timestamp in Parses a seek `self` and stores the results in the given result locations. ## `rate` result location for the rate ## `format` result location for the stream format ## `flags` result location for the `SeekFlags` ## `start_type` result location for the `SeekType` of the start position ## `start` result location for the start position expressed in `format` ## `stop_type` result location for the `SeekType` of the stop position ## `stop` result location for the stop position expressed in `format` 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 and make a copy if you want to modify it or store it for later use. ## `segment` a pointer to a `Segment` Extracts the position and format from the segment done message. ## `format` Result location for the format, or `None` ## `position` Result location for the position, or `None` Parse the SELECT_STREAMS event and retrieve the contained streams. Feature: `v1_10` ## `streams` the streams Parse the sink-message event. Unref `msg` after usage. ## `msg` a pointer to store the `Message` in. Parse the step event. ## `format` a pointer to store the format in ## `amount` a pointer to store the amount in ## `rate` a pointer to store the rate in ## `flush` a pointer to store the flush boolean in ## `intermediate` a pointer to store the intermediate boolean in Parse a stream-start `self` and extract the `Stream` from it. Feature: `v1_10` ## `stream` adress of variable to store the stream Retrieve new `StreamCollection` from STREAM_COLLECTION event `self`. Feature: `v1_10` ## `collection` pointer to store the collection ## `flags` address of variable where to store the stream flags Parse a stream-group-done `self` and store the result in the given `group_id` location. Feature: `v1_10` ## `group_id` address of variable to store the group id into Parse a stream-id `self` and store the result in the given `stream_id` location. The string stored in `stream_id` must not be modified and will remain valid only until `self` gets freed. Make a copy if you want to modify it or store it for later use. ## `stream_id` pointer to store the stream-id Parses a tag `self` and stores the results in the given `taglist` location. No reference to the taglist will be returned, it remains valid only until the `self` is freed. Don't modify or free the taglist, make a copy if you want to modify it or store it for later use. ## `taglist` pointer to metadata list Parse a TOC `self` and store the results in the given `toc` and `updated` locations. ## `toc` pointer to `Toc` structure. ## `updated` pointer to store TOC updated flag. Parse a TOC select `self` and store the results in the given `uid` location. ## `uid` storage for the selection UID. All streams that have the same group id are supposed to be played together, i.e. all streams inside a container file should have the same group id but different stream ids. The group id should change each time the stream is started, resulting in different group ids each time a file is played for example. Use `gst_util_group_id_next` to get a new group id. ## `group_id` the group id to set Set the running time offset of a event. See `Event::get_running_time_offset` for more information. MT safe. ## `offset` A the new running time offset Set the sequence number of a event. This function might be called by the creator of a event to indicate that the event relates to other events or messages. See `Event::get_seqnum` for more information. MT safe. ## `seqnum` A sequence number. Set the `stream` on the stream-start `self` Feature: `v1_10` ## `stream` the stream object to set ## `flags` the stream flags to set Get a writable version of the structure. # Returns The structure of the event. The structure is still owned by the event, which means that you should not free it and that the pointer becomes invalid when you free the event. This function checks if `self` is writable and will never return `None`. MT safe. `EventType` lists the standard event types that can be sent in a pipeline. The custom event types can be used for private messages between elements that can't be expressed using normal GStreamer buffer passing semantics. Custom events carry an arbitrary `Structure`. Specific custom events are distinguished by the name of the structure. unknown event. Start a flush operation. This event clears all data from the pipeline and unblock all streaming threads. Stop a flush operation. This event resets the running-time of the pipeline. Event to mark the start of a new stream. Sent before any other serialized event and only sent at the start of a new stream, not after flushing seeks. `Caps` event. Notify the pad of a new media type. A new media segment follows in the dataflow. The segment events contains information for clipping buffers and converting buffer timestamps to running-time and stream-time. A new `StreamCollection` is available (Since 1.10) A new set of metadata tags has been found in the stream. Notification of buffering requirements. Currently not used yet. An event that sinks turn into a message. Used to send messages that should be emitted in sync with rendering. 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) 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 event. An event which indicates that a new table of contents (TOC) was found or updated. An event which indicates that new or updated encryption information has been found in the stream. Marks the end of a segment playback. Marks a gap in the datastream. A quality message. Used to indicate to upstream elements that the downstream elements should adjust their processing rate. A request for a new playback position and rate. Navigation events are usually used for communicating user requests, such as mouse or keyboard movements, to upstream elements. Notification of new latency adjustment. Sinks will use the latency information to adjust their synchronisation. A request for stepping through the media. Sinks will usually execute the step operation. 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) Upstream custom event Downstream custom event that travels in the data flow. Custom out-of-band downstream event. Custom sticky downstream event. Custom upstream or downstream event. In-band when travelling downstream. Custom upstream or downstream out-of-band event. The result of passing data to a pad. Note that the custom return values should not be exposed outside of the element scope. Pre-defined custom success code. Pre-defined custom success code (define your custom success code to this to avoid compiler warnings). Elements can use values starting from this (and higher) to define custom success codes. Data passing was ok. Pad is not linked. Pad is flushing. Pad is EOS. Pad is not negotiated. Some (fatal) error occurred. Element generating this error should post an error message with more details. This operation is not supported. Elements can use values starting from this (and lower) to define custom error codes. Pre-defined custom error code (define your custom error code to this to avoid compiler warnings). Pre-defined custom error code. Standard predefined formats undefined format the default format of the pad/element. This can be samples for raw audio, frames/fields for raw video (some, but not all, elements support this; use `Format::Time` if you don't have a good reason to query for samples/frames) bytes time in nanoseconds buffers (few, if any, elements implement this as of May 2009) percentage of stream (few, if any, elements implement this as of May 2009) GhostPads are useful when organizing pipelines with `Bin` like elements. The idea here is to create hierarchical element graphs. The bin element contains a sub-graph. Now one would like to treat the bin-element like any other `Element`. This is where GhostPads come into play. A GhostPad acts as a proxy for another pad. Thus the bin can have sink and source ghost-pads that are associated with sink and source pads of the child elements. If the target pad is known at creation time, `GhostPad::new` is the function to use to get a ghost-pad. Otherwise one can use `GhostPad::new_no_target` to create the ghost-pad and use `GhostPadExt::set_target` to establish the association later on. Note that GhostPads add overhead to the data processing of a pipeline. # Implements [`GhostPadExt`](trait.GhostPadExt.html), [`ProxyPadExt`](trait.ProxyPadExt.html), [`PadExt`](trait.PadExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `GhostPad` methods. # Implementors [`GhostPad`](struct.GhostPad.html) Create a new ghostpad with `target` as the target. The direction will be taken from the target pad. `target` must be unlinked. Will ref the target. ## `name` the name of the new pad, or `None` to assign a default name ## `target` the pad to ghost. # Returns a new `Pad`, or `None` in case of an error. Create a new ghostpad with `target` as the target. The direction will be taken from the target pad. The template used on the ghostpad will be `template`. Will ref the target. ## `name` the name of the new pad, or `None` to assign a default name. ## `target` the pad to ghost. ## `templ` the `PadTemplate` to use on the ghostpad. # Returns a new `Pad`, or `None` in case of an error. Create a new ghostpad without a target with the given direction. A target can be set on the ghostpad later with the `GhostPadExt::set_target` function. The created ghostpad will not have a padtemplate. ## `name` the name of the new pad, or `None` to assign a default name. ## `dir` the direction of the ghostpad # Returns a new `Pad`, or `None` in case of an error. Create a new ghostpad based on `templ`, without setting a target. The direction will be taken from the `templ`. ## `name` the name of the new pad, or `None` to assign a default name ## `templ` the `PadTemplate` to create the ghostpad from. # Returns a new `Pad`, or `None` in case of an error. Invoke the default activate mode function of a ghost pad. ## `pad` the `Pad` to activate or deactivate. ## `parent` the parent of `pad` or `None` ## `mode` the requested activation mode ## `active` whether the pad should be active or not. # Returns `true` if the operation was successful. Invoke the default activate mode function of a proxy pad that is owned by a ghost pad. ## `pad` the `Pad` to activate or deactivate. ## `parent` the parent of `pad` or `None` ## `mode` the requested activation mode ## `active` whether the pad should be active or not. # Returns `true` if the operation was successful. Finish initialization of a newly allocated ghost pad. This function is most useful in language bindings and when subclassing `GhostPad`; plugin and application developers normally will not call this function. Call this function directly after a call to g_object_new (GST_TYPE_GHOST_PAD, "direction", `dir`, ..., NULL). # Returns `true` if the construction succeeds, `false` otherwise. Get the target pad of `self`. Unref target pad after usage. # Returns the target `Pad`, can be `None` if the ghostpad has no target set. Unref target pad after usage. Set the new target of the ghostpad `self`. Any existing target is unlinked and links to the new target are established. if `newtarget` is `None` the target will be cleared. ## `newtarget` the new pad target # Returns `true` if the new target could be set. This function can return `false` when the internal pads could not be linked. Library errors are for errors from the library being used by elements (initializing, finalizing, settings, ...) a general error which doesn't fit in any other category. Make sure you add a custom message to the error call. do not use this except as a placeholder for deciding where to go while developing code. used when the library could not be opened. used when the library could not be closed. used when the library doesn't accept settings. used when the library generated an encoding error. the number of library error types. Messages are implemented as a subclass of `MiniObject` with a generic `Structure` as the content. This allows for writing custom messages without requiring an API change while allowing a wide range of different types of messages. Messages are posted by objects in the pipeline and are passed to the application using the `Bus`. The basic use pattern of posting a message on a `Bus` is as follows: ```C gst_bus_post (bus, gst_message_new_eos()); ``` A `Element` usually posts messages on the bus provided by the parent container using `ElementExt::post_message`. Create a new application-typed message. GStreamer will never create these messages; they are a gift from us to you. Enjoy. ## `src` The object originating the message. ## `structure` the structure for the message. The message will take ownership of the structure. # Returns The new application message. MT safe. The message is posted when elements completed an ASYNC state change. `running_time` contains the time of the desired running_time when this elements goes to PLAYING. A value of `GST_CLOCK_TIME_NONE` for `running_time` means that the element has no clock interaction and thus doesn't care about the running_time of the pipeline. ## `src` The object originating the message. ## `running_time` the desired running_time # Returns The new async_done message. MT safe. This message is posted by elements when they start an ASYNC state change. ## `src` The object originating the message. # Returns The new async_start message. MT safe. Create a new buffering message. This message can be posted by an element that needs to buffer data before it can continue processing. `percent` should be a value between 0 and 100. A value of 100 means that the buffering completed. When `percent` is < 100 the application should PAUSE a PLAYING pipeline. When `percent` is 100, the application can set the pipeline (back) to PLAYING. The application must be prepared to receive BUFFERING messages in the PREROLLING state and may only set the pipeline to PLAYING after receiving a message with `percent` set to 100, which can happen after the pipeline completed prerolling. MT safe. ## `src` The object originating the message. ## `percent` The buffering percent # Returns The new buffering message. Create a clock lost message. This message is posted whenever the clock is not valid anymore. If this message is posted by the pipeline, the pipeline will select a new clock again when it goes to PLAYING. It might therefore be needed to set the pipeline to PAUSED and PLAYING again. ## `src` The object originating the message. ## `clock` the clock that was lost # Returns The new clock lost message. MT safe. Create a clock provide message. This message is posted whenever an element is ready to provide a clock or lost its ability to provide a clock (maybe because it paused or became EOS). This message is mainly used internally to manage the clock selection. ## `src` The object originating the message. ## `clock` the clock it provides ## `ready` `true` if the sender can provide a clock # Returns the new provide clock message. MT safe. Create a new custom-typed message. This can be used for anything not handled by other message-specific functions to pass a message to the app. The structure field can be `None`. ## `type_` The `MessageType` to distinguish messages ## `src` The object originating the message. ## `structure` the structure for the message. The message will take ownership of the structure. # Returns The new message. MT safe. Creates a new device-added message. The device-added message is produced by `DeviceProvider` or a `DeviceMonitor`. They announce the appearance of monitored devices. ## `src` The `Object` that created the message ## `device` The new `Device` # Returns a newly allocated `Message` Creates a new device-removed message. The device-removed message is produced by `DeviceProvider` or a `DeviceMonitor`. They announce the disappearance of monitored devices. ## `src` The `Object` that created the message ## `device` The removed `Device` # Returns a newly allocated `Message` Create a new duration changed message. This message is posted by elements that know the duration of a stream when the duration changes. This message is received by bins and is used to calculate the total duration of a pipeline. ## `src` The object originating the message. # Returns The new duration-changed message. MT safe. Create a new element-specific message. This is meant as a generic way of allowing one-way communication from an element to an application, for example "the firewire cable was unplugged". The format of the message should be documented in the element's documentation. The structure field can be `None`. ## `src` The object originating the message. ## `structure` The structure for the message. The message will take ownership of the structure. # Returns The new element message. MT safe. Create a new eos message. This message is generated and posted in the sink elements of a GstBin. The bin will only forward the EOS message to the application if all sinks have posted an EOS message. ## `src` The object originating the message. # Returns The new eos message. MT safe. Create a new error message. The message will copy `error` and `debug`. This message is posted by element when a fatal event occurred. The pipeline will probably (partially) stop. The application receiving this message should stop the pipeline. ## `src` The object originating the message. ## `error` The GError for this message. ## `debug` A debugging string. # Returns the new error message. MT safe. Create a new error message. The message will copy `error` and `debug`. This message is posted by element when a fatal event occurred. The pipeline will probably (partially) stop. The application receiving this message should stop the pipeline. Feature: `v1_10` ## `src` The object originating the message. ## `error` The GError for this message. ## `debug` A debugging string. ## `details` (allow-none): A GstStructure with details # Returns the new error message. This message is posted when an element has a new local `Context`. ## `src` The object originating the message. ## `context` the context # Returns The new have-context message. MT safe. Create a new info message. The message will make copies of `error` and `debug`. ## `src` The object originating the message. ## `error` The GError for this message. ## `debug` A debugging string. # Returns the new info message. MT safe. Create a new info message. The message will make copies of `error` and `debug`. Feature: `v1_10` ## `src` The object originating the message. ## `error` The GError for this message. ## `debug` A debugging string. ## `details` (allow-none): A GstStructure with details # Returns the new warning message. This message can be posted by elements when their latency requirements have changed. ## `src` The object originating the message. # Returns The new latency message. MT safe. This message is posted when an element needs a specific `Context`. ## `src` The object originating the message. ## `context_type` The context type that is needed # Returns The new need-context message. MT safe. Create a new clock message. This message is posted whenever the pipeline selects a new clock for the pipeline. ## `src` The object originating the message. ## `clock` the new selected clock # Returns The new new clock message. MT safe. Progress messages are posted by elements when they use an asynchronous task to perform actions triggered by a state change. `code` contains a well defined string describing the action. `text` should contain a user visible string detailing the current action. ## `src` The object originating the message. ## `type_` a `ProgressType` ## `code` a progress code ## `text` free, user visible text describing the progress # Returns The new qos message. Feature: `v1_10` ## `src` The `Object` whose property changed (may or may not be a `Element`) ## `property_name` name of the property that changed ## `val` new property value, or `None` # Returns a newly allocated `Message` A QOS message is posted on the bus whenever an element decides to drop a buffer because of QoS reasons or whenever it changes its processing strategy because of QoS reasons (quality adjustments such as processing at lower accuracy). This message can be posted by an element that performs synchronisation against the clock (live) or it could be dropped by an element that performs QoS because of QOS events received from a downstream element (!live). `running_time`, `stream_time`, `timestamp`, `duration` should be set to the respective running-time, stream-time, timestamp and duration of the (dropped) buffer that generated the QoS event. Values can be left to GST_CLOCK_TIME_NONE when unknown. ## `src` The object originating the message. ## `live` if the message was generated by a live element ## `running_time` the running time of the buffer that generated the message ## `stream_time` the stream time of the buffer that generated the message ## `timestamp` the timestamps of the buffer that generated the message ## `duration` the duration of the buffer that generated the message # Returns The new qos message. MT safe. Creates a new redirect message and adds a new entry to it. Redirect messages are posted when an element detects that the actual data has to be retrieved from a different location. This is useful if such a redirection cannot be handled inside a source element, for example when HTTP 302/303 redirects return a non-HTTP URL. The redirect message can hold multiple entries. The first one is added when the redirect message is created, with the given location, tag_list, entry_struct arguments. Use `Message::add_redirect_entry` to add more entries. Each entry has a location, a tag list, and a structure. All of these are optional. The tag list and structure are useful for additional metadata, such as bitrate statistics for the given location. By default, message recipients should treat entries in the order they are stored. The recipient should therefore try entry `0` first, and if this entry is not acceptable or working, try entry `1` etc. Senders must make sure that they add entries in this order. However, recipients are free to ignore the order and pick an entry that is "best" for them. One example would be a recipient that scans the entries for the one with the highest bitrate tag. The specified location string is copied. However, ownership over the tag list and structure are transferred to the message. Feature: `v1_10` ## `src` The `Object` whose property changed (may or may not be a `Element`) ## `location` location string for the new entry ## `tag_list` tag list for the new entry ## `entry_struct` structure for the new entry # Returns a newly allocated `Message` This message can be posted by elements when they want to have their state changed. A typical use case would be an audio server that wants to pause the pipeline because a higher priority stream is being played. ## `src` The object originating the message. ## `state` The new requested state # Returns the new request state message. MT safe. This message is posted when the pipeline running-time should be reset to `running_time`, like after a flushing seek. ## `src` The object originating the message. ## `running_time` the requested running-time # Returns The new reset_time message. MT safe. Create a new segment done message. This message is posted by elements that finish playback of a segment as a result of a segment seek. This message is received by the application after all elements that posted a segment_start have posted the segment_done. ## `src` The object originating the message. ## `format` The format of the position being done ## `position` The position of the segment being done # Returns the new segment done message. MT safe. Create a new segment message. This message is posted by elements that start playback of a segment as a result of a segment seek. This message is not received by the application but is used for maintenance reasons in container elements. ## `src` The object originating the message. ## `format` The format of the position being played ## `position` The position of the segment being played # Returns the new segment start message. MT safe. Create a state change message. This message is posted whenever an element changed its state. ## `src` The object originating the message. ## `oldstate` the previous state ## `newstate` the new (current) state ## `pending` the pending (target) state # Returns the new state change message. MT safe. Create a state dirty message. This message is posted whenever an element changed its state asynchronously and is used internally to update the states of container objects. ## `src` The object originating the message # Returns the new state dirty message. MT safe. This message is posted by elements when they complete a part, when `intermediate` set to `true`, or a complete step operation. `duration` will contain the amount of time (in GST_FORMAT_TIME) of the stepped `amount` of media in format `format`. ## `src` The object originating the message. ## `format` the format of `amount` ## `amount` the amount of stepped data ## `rate` the rate of the stepped amount ## `flush` is this an flushing step ## `intermediate` is this an intermediate step ## `duration` the duration of the data ## `eos` the step caused EOS # Returns the new step_done message. MT safe. This message is posted by elements when they accept or activate a new step event for `amount` in `format`. `active` is set to `false` when the element accepted the new step event and has queued it for execution in the streaming threads. `active` is set to `true` when the element has activated the step operation and is now ready to start executing the step in the streaming thread. After this message is emitted, the application can queue a new step operation in the element. ## `src` The object originating the message. ## `active` if the step is active or queued ## `format` the format of `amount` ## `amount` the amount of stepped data ## `rate` the rate of the stepped amount ## `flush` is this an flushing step ## `intermediate` is this an intermediate step # Returns The new step_start message. MT safe. Creates a new stream-collection message. The message is used to announce new `StreamCollection` Feature: `v1_10` ## `src` The `Object` that created the message ## `collection` The `StreamCollection` # Returns a newly allocated `Message` Create a new stream_start message. This message is generated and posted in the sink elements of a GstBin. The bin will only forward the STREAM_START message to the application if all sinks have posted an STREAM_START message. ## `src` The object originating the message. # Returns The new stream_start message. MT safe. Create a new stream status message. This message is posted when a streaming thread is created/destroyed or when the state changed. ## `src` The object originating the message. ## `type_` The stream status type. ## `owner` the owner element of `src`. # Returns the new stream status message. MT safe. Creates a new steams-selected message. The message is used to announce that an array of streams has been selected. This is generally in response to a `EventType::SelectStreams` event, or when an element (such as decodebin3) makes an initial selection of streams. The message also contains the `StreamCollection` to which the various streams belong to. Users of `Message::new_streams_selected` can add the selected streams with `Message::streams_selected_add`. Feature: `v1_10` ## `src` The `Object` that created the message ## `collection` The `StreamCollection` # Returns a newly allocated `Message` Create a new structure change message. This message is posted when the structure of a pipeline is in the process of being changed, for example when pads are linked or unlinked. `src` should be the sinkpad that unlinked or linked. ## `src` The object originating the message. ## `type_` The change type. ## `owner` The owner element of `src`. ## `busy` Whether the structure change is busy. # Returns the new structure change message. MT safe. Create a new tag message. The message will take ownership of the tag list. The message is posted by elements that discovered a new taglist. ## `src` The object originating the message. ## `tag_list` the tag list for the message. # Returns the new tag message. MT safe. Create a new TOC message. The message is posted by elements that discovered or updated a TOC. ## `src` the object originating the message. ## `toc` `Toc` structure for the message. ## `updated` whether TOC was updated or not. # Returns a new TOC message. MT safe. Create a new warning message. The message will make copies of `error` and `debug`. ## `src` The object originating the message. ## `error` The GError for this message. ## `debug` A debugging string. # Returns the new warning message. MT safe. Create a new warning message. The message will make copies of `error` and `debug`. Feature: `v1_10` ## `src` The object originating the message. ## `error` The GError for this message. ## `debug` A debugging string. ## `details` (allow-none): A GstStructure with details # Returns the new warning message. Creates and appends a new entry. The specified location string is copied. However, ownership over the tag list and structure are transferred to the message. Feature: `v1_10` ## `location` location string for the new entry ## `tag_list` tag list for the new entry ## `entry_struct` structure for the new entry Feature: `v1_10` # Returns the number of entries stored in the message Retrieve the sequence number of a message. Messages have ever-incrementing sequence numbers, which may also be set explicitly via `Message::set_seqnum`. Sequence numbers are typically used to indicate that a message corresponds to some other set of messages or events, for example a SEGMENT_DONE message corresponding to a SEEK event. It is considered good practice to make this correspondence when possible, though it is not required. Note that events and messages share the same sequence number incrementor; two events or messages will never have the same sequence number unless that correspondence was made explicitly. # Returns The message's sequence number. MT safe. Extracts the object managing the streaming thread from `self`. # Returns a GValue containing the object that manages the streaming thread. This object is usually of type GstTask but other types can be added in the future. The object remains valid as long as `self` is valid. Access the structure of the message. # Returns The structure of the message. The structure is still owned by the message, which means that you should not free it and that the pointer becomes invalid when you free the message. MT safe. Checks if `self` has the given `name`. This function is usually used to check the name of a custom message. ## `name` name to check # Returns `true` if `name` matches the name of the message structure. Extract the running_time from the async_done message. MT safe. ## `running_time` Result location for the running_time or `None` Extracts the buffering percent from the GstMessage. see also `Message::new_buffering`. MT safe. ## `percent` Return location for the percent. Extracts the buffering stats values from `self`. ## `mode` a buffering mode, or `None` ## `avg_in` the average input rate, or `None` ## `avg_out` the average output rate, or `None` ## `buffering_left` amount of buffering time left in milliseconds, or `None` Extracts the lost clock from the GstMessage. The clock object returned remains valid until the message is freed. MT safe. ## `clock` a pointer to hold the lost clock Extracts the clock and ready flag from the GstMessage. The clock object returned remains valid until the message is freed. MT safe. ## `clock` a pointer to hold a clock object, or `None` ## `ready` a pointer to hold the ready flag, or `None` Parse a context type from an existing GST_MESSAGE_NEED_CONTEXT message. ## `context_type` the context type, or `None` # Returns a `gboolean` indicating if the parsing succeeded. Parses a device-added message. The device-added message is produced by `DeviceProvider` or a `DeviceMonitor`. It announces the appearance of monitored devices. ## `device` A location where to store a pointer to the new `Device`, or `None` Parses a device-removed message. The device-removed message is produced by `DeviceProvider` or a `DeviceMonitor`. It announces the disappearance of monitored devices. ## `device` A location where to store a pointer to the removed `Device`, or `None` Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done. Typical usage of this function might be: ```C ... switch (GST_MESSAGE_TYPE (msg)) { case GST_MESSAGE_ERROR: { GError *err = NULL; gchar *dbg_info = NULL; gst_message_parse_error (msg, &err, &dbg_info); g_printerr ("ERROR from element %s: %s\n", GST_OBJECT_NAME (msg->src), err->message); g_printerr ("Debugging info: %s\n", (dbg_info) ? dbg_info : "none"); g_error_free (err); g_free (dbg_info); break; } ... } ... ``` MT safe. ## `gerror` location for the GError ## `debug` location for the debug message, or `None` Returns the optional details structure, may be NULL if none. The returned structure must not be freed. Feature: `v1_10` ## `structure` A pointer to the returned details Extract the group from the STREAM_START message. ## `group_id` Result location for the group id or `None` # Returns `true` if the message had a group id set, `false` otherwise MT safe. Extract the context from the HAVE_CONTEXT message. MT safe. ## `context` Result location for the context or `None` Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done. MT safe. ## `gerror` location for the GError ## `debug` location for the debug message, or `None` Returns the optional details structure, may be NULL if none The returned structure must not be freed. Feature: `v1_10` ## `structure` A pointer to the returned details structure Extracts the new clock from the GstMessage. The clock object returned remains valid until the message is freed. MT safe. ## `clock` a pointer to hold the selected new clock Parses the progress `type_`, `code` and `text`. ## `type_` location for the type ## `code` location for the code ## `text` location for the text Parses a property-notify message. These will be posted on the bus only when set up with `Element::add_property_notify_watch` or `Element::add_property_deep_notify_watch`. Feature: `v1_10` ## `object` location where to store a pointer to the object whose property got changed, or `None` ## `property_name` return location for the name of the property that got changed, or `None` ## `property_value` return location for the new value of the property that got changed, or `None`. This will only be set if the property notify watch was told to include the value when it was set up Extract the timestamps and live status from the QoS message. The returned values give the running_time, stream_time, timestamp and duration of the dropped buffer. Values of GST_CLOCK_TIME_NONE mean unknown values. MT safe. ## `live` if the message was generated by a live element ## `running_time` the running time of the buffer that generated the message ## `stream_time` the stream time of the buffer that generated the message ## `timestamp` the timestamps of the buffer that generated the message ## `duration` the duration of the buffer that generated the message Extract the QoS stats representing the history of the current continuous pipeline playback period. When `format` is `Format::Undefined` both `dropped` and `processed` are invalid. Values of -1 for either `processed` or `dropped` mean unknown values. MT safe. ## `format` Units of the 'processed' and 'dropped' fields. Video sinks and video filters will use GST_FORMAT_BUFFERS (frames). Audio sinks and audio filters will likely use GST_FORMAT_DEFAULT (samples). ## `processed` Total number of units correctly processed since the last state change to READY or a flushing operation. ## `dropped` Total number of units dropped since the last state change to READY or a flushing operation. Extract the QoS values that have been calculated/analysed from the QoS data MT safe. ## `jitter` The difference of the running-time against the deadline. ## `proportion` Long term prediction of the ideal rate relative to normal rate to get optimal quality. ## `quality` An element dependent integer value that specifies the current quality level of the element. The default maximum quality is 1000000. Parses the location and/or structure from the entry with the given index. The index must be between 0 and `Message::get_num_redirect_entries` - 1. Returned pointers are valid for as long as this message exists. Feature: `v1_10` ## `entry_index` index of the entry to parse ## `location` return location for the pointer to the entry's location string, or `None` ## `tag_list` return location for the pointer to the entry's tag list, or `None` ## `entry_struct` return location for the pointer to the entry's structure, or `None` Extract the requested state from the request_state message. MT safe. ## `state` Result location for the requested state or `None` Extract the running-time from the RESET_TIME message. MT safe. ## `running_time` Result location for the running_time or `None` Extracts the position and format from the segment done message. MT safe. ## `format` Result location for the format, or `None` ## `position` Result location for the position, or `None` Extracts the position and format from the segment start message. MT safe. ## `format` Result location for the format, or `None` ## `position` Result location for the position, or `None` Extracts the old and new states from the GstMessage. Typical usage of this function might be: ```C ... switch (GST_MESSAGE_TYPE (msg)) { case GST_MESSAGE_STATE_CHANGED: { GstState old_state, new_state; gst_message_parse_state_changed (msg, &old_state, &new_state, NULL); g_print ("Element %s changed state from %s to %s.\n", GST_OBJECT_NAME (msg->src), gst_element_state_get_name (old_state), gst_element_state_get_name (new_state)); break; } ... } ... ``` MT safe. ## `oldstate` the previous state, or `None` ## `newstate` the new (current) state, or `None` ## `pending` the pending (target) state, or `None` Extract the values the step_done message. MT safe. ## `format` result location for the format ## `amount` result location for the amount ## `rate` result location for the rate ## `flush` result location for the flush flag ## `intermediate` result location for the intermediate flag ## `duration` result location for the duration ## `eos` result location for the EOS flag Extract the values from step_start message. MT safe. ## `active` result location for the active flag ## `format` result location for the format ## `amount` result location for the amount ## `rate` result location for the rate ## `flush` result location for the flush flag ## `intermediate` result location for the intermediate flag Parses a stream-collection message. Feature: `v1_10` ## `collection` A location where to store a pointer to the `StreamCollection`, or `None` Extracts the stream status type and owner the GstMessage. The returned owner remains valid for as long as the reference to `self` is valid and should thus not be unreffed. MT safe. ## `type_` A pointer to hold the status type ## `owner` The owner element of the message source Parses a streams-selected message. Feature: `v1_10` ## `collection` A location where to store a pointer to the `StreamCollection`, or `None` Extracts the change type and completion status from the GstMessage. MT safe. ## `type_` A pointer to hold the change type ## `owner` The owner element of the message source ## `busy` a pointer to hold whether the change is in progress or has been completed Extracts the tag list from the GstMessage. The tag list returned in the output argument is a copy; the caller must free it when done. Typical usage of this function might be: ```C ... switch (GST_MESSAGE_TYPE (msg)) { case GST_MESSAGE_TAG: { GstTagList *tags = NULL; gst_message_parse_tag (msg, &tags); g_print ("Got tags from element %s\n", GST_OBJECT_NAME (msg->src)); handle_tags (tags); gst_tag_list_unref (tags); break; } ... } ... ``` MT safe. ## `tag_list` return location for the tag-list. Extract the TOC from the `Message`. The TOC returned in the output argument is a copy; the caller must free it with `gst_toc_unref` when done. MT safe. ## `toc` return location for the TOC. ## `updated` return location for the updated flag. Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done. MT safe. ## `gerror` location for the GError ## `debug` location for the debug message, or `None` Returns the optional details structure, may be NULL if none The returned structure must not be freed. Feature: `v1_10` ## `structure` A pointer to the returned details structure Configures the buffering stats values in `self`. ## `mode` a buffering mode ## `avg_in` the average input rate ## `avg_out` the average output rate ## `buffering_left` amount of buffering time left in milliseconds Sets the group id on the stream-start message. All streams that have the same group id are supposed to be played together, i.e. all streams inside a container file should have the same group id but different stream ids. The group id should change each time the stream is started, resulting in different group ids each time a file is played for example. MT safe. ## `group_id` the group id Set the QoS stats representing the history of the current continuous pipeline playback period. When `format` is `Format::Undefined` both `dropped` and `processed` are invalid. Values of -1 for either `processed` or `dropped` mean unknown values. MT safe. ## `format` Units of the 'processed' and 'dropped' fields. Video sinks and video filters will use GST_FORMAT_BUFFERS (frames). Audio sinks and audio filters will likely use GST_FORMAT_DEFAULT (samples). ## `processed` Total number of units correctly processed since the last state change to READY or a flushing operation. ## `dropped` Total number of units dropped since the last state change to READY or a flushing operation. Set the QoS values that have been calculated/analysed from the QoS data MT safe. ## `jitter` The difference of the running-time against the deadline. ## `proportion` Long term prediction of the ideal rate relative to normal rate to get optimal quality. ## `quality` An element dependent integer value that specifies the current quality level of the element. The default maximum quality is 1000000. Set the sequence number of a message. This function might be called by the creator of a message to indicate that the message relates to other messages or events. See `Message::get_seqnum` for more information. MT safe. ## `seqnum` A sequence number. Configures the object handling the streaming thread. This is usually a GstTask object but other objects might be added in the future. ## `object` the object controlling the streaming Adds the `stream` to the `self`. Feature: `v1_10` ## `stream` a `Stream` to add to `self` Returns the number of streams contained in the `self`. Feature: `v1_10` # Returns The number of streams contained within. Retrieves the `Stream` with index `index` from the `self`. Feature: `v1_10` ## `idx` Index of the stream to retrieve # Returns A `Stream` Get a writable version of the structure. Feature: `v1_14` # Returns The structure of the message. The structure is still owned by the message, which means that you should not free it and that the pointer becomes invalid when you free the message. This function checks if `self` is writable and will never return `None`. MT safe. `Object` provides a root for the object hierarchy tree filed in by the GStreamer library. It is currently a thin wrapper on top of `gobject::InitiallyUnowned`. It is an abstract class that is not very usable on its own. `Object` gives us basic refcounting, parenting functionality and locking. Most of the functions are just extended for special GStreamer needs and can be found under the same name in the base class of `Object` which is `gobject::Object` (e.g. `gobject::ObjectExt::ref` becomes `GstObjectExt::ref`). Since `Object` derives from `gobject::InitiallyUnowned`, it also inherits the floating reference. Be aware that functions such as `BinExt::add` and `ElementExt::add_pad` take ownership of the floating reference. In contrast to `gobject::Object` instances, `Object` adds a name property. The functions `GstObjectExt::set_name` and `GstObjectExt::get_name` are used to set/get the name of the object. ## controlled properties Controlled properties offers a lightweight way to adjust gobject properties over stream-time. It works by using time-stamped value pairs that are queued for element-properties. At run-time the elements continuously pull value changes for the current stream-time. What needs to be changed in a `Element`? Very little - it is just two steps to make a plugin controllable! * mark gobject-properties paramspecs that make sense to be controlled, by GST_PARAM_CONTROLLABLE. * when processing data (get, chain, loop function) at the beginning call gst_object_sync_values(element,timestamp). This will make the controller update all GObject properties that are under its control with the current values based on the timestamp. What needs to be done in applications? Again it's not a lot to change. * create a `ControlSource`. csource = gst_interpolation_control_source_new (); g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL); * Attach the `ControlSource` on the controller to a property. gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource)); * Set the control values gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,0 * GST_SECOND, value1); gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,1 * GST_SECOND, value2); * start your pipeline # Implements [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) 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) 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 provided list with the lock of the owner of the list. This function will lock each `Object` in the list to compare the name, so be careful when passing a list with a locked object. ## `list` a list of `Object` to check through ## `name` the name to search for # Returns `true` if a `Object` named `name` does not appear in `list`, `false` if it does. MT safe. Grabs and releases the LOCK of each object in the list. A default deep_notify signal callback for an object. The user data should contain a pointer to an array of strings that should be excluded from the notify. The default handler will print the new value of the property using g_print. MT safe. This function grabs and releases `object`'s LOCK for getting its path string. ## `object` the `gobject::Object` that signalled the notify. ## `orig` a `Object` that initiated the notify. ## `pspec` a `gobject::ParamSpec` of the property. ## `excluded_props` a set of user-specified properties to exclude or `None` to show all changes. Increase the reference count of `object`, and possibly remove the floating reference, if `object` has a floating reference. In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one. For more background on "floating references" please see the `gobject::Object` documentation. ## `object` a `Object` to sink Atomically modifies a pointer to point to a new object. The reference count of `oldobj` is decreased and the reference count of `newobj` is increased. Either `newobj` and the value pointed to by `oldobj` may be `None`. ## `oldobj` pointer to a place of a `Object` to replace ## `newobj` a new `Object` # Returns `true` if `newobj` was different from `oldobj` Attach the `ControlBinding` to the object. If there already was a `ControlBinding` for this property it will be replaced. The object's reference count will be incremented, and any floating reference will be removed (see `Object::ref_sink`) ## `binding` the `ControlBinding` that should be used # Returns `false` if the given `binding` has not been setup for this object or 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.. The default handler will simply print the error string using g_print. ## `error` the GError. ## `debug` an additional debug information string, or `None` Gets the corresponding `ControlBinding` for the property. This should be unreferenced again after use. ## `property_name` name of the property # Returns the `ControlBinding` for `property_name` or `None` if the property is not controlled. 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 should be up to `control`-rate nanoseconds. If the `self` is not under property control, this will return `GST_CLOCK_TIME_NONE`. This allows the element to avoid the sub-dividing. The control-rate is not expected to change if the element is in `State::Paused` or `State::Playing`. # Returns the control rate in nanoseconds Gets a number of `GValues` for the given controlled property starting at the requested time. The array `values` need to hold enough space for `n_values` of `gobject::Value`. This function is useful if one wants to e.g. draw a graph of the control curve or apply a control curve sample by sample. ## `property_name` the name of the property to get ## `timestamp` the time that should be processed ## `interval` the time spacing between subsequent values ## `n_values` the number of values ## `values` array to put control-values in # Returns `true` if the given array could be filled, `false` otherwise Returns a copy of the name of `self`. Caller should `g_free` the return value after usage. For a nameless object, this returns `None`, which you can safely `g_free` as well. Free-function: g_free # Returns the name of `self`. `g_free` after usage. MT safe. This function grabs and releases `self`'s LOCK. Returns the parent of `self`. This function increases the refcount of the parent object so you should `GstObjectExt::unref` it after usage. # Returns parent of `self`, this can be `None` if `self` has no parent. unref after usage. MT safe. Grabs and releases `self`'s LOCK. Generates a string describing the path of `self` in the object hierarchy. Only useful (or used) for debugging. Free-function: g_free # Returns a string describing the path of `self`. You must `g_free` the string after usage. MT safe. Grabs and releases the `Object`'s LOCK for all objects in the hierarchy. Gets the value for the given controlled property at the requested time. ## `property_name` the name of the property to get ## `timestamp` the time the control-change should be read from # Returns the GValue of the property at the given time, or `None` if the property isn't controlled. Gets a number of values for the given controlled property starting at the requested time. The array `values` need to hold enough space for `n_values` of the same type as the objects property's type. This function is useful if one wants to e.g. draw a graph of the control curve or apply a control curve sample by sample. The values are unboxed and ready to be used. The similar function `GstObjectExt::get_g_value_array` returns the array as `GValues` and is better suites for bindings. ## `property_name` the name of the property to get ## `timestamp` the time that should be processed ## `interval` the time spacing between subsequent values ## `n_values` the number of values ## `values` array to put control-values in # Returns `true` if the given array could be filled, `false` otherwise Check if the `self` has active controlled properties. # Returns `true` if the object has active controlled properties Check if `self` has an ancestor `ancestor` somewhere up in the hierarchy. One can e.g. check if a `Element` is inside a `Pipeline`. # Deprecated Use `GstObjectExt::has_as_ancestor` instead. MT safe. Grabs and releases `self`'s locks. ## `ancestor` a `Object` to check as ancestor # Returns `true` if `ancestor` is an ancestor of `self`. Check if `self` has an ancestor `ancestor` somewhere up in the hierarchy. One can e.g. check if a `Element` is inside a `Pipeline`. ## `ancestor` a `Object` to check as ancestor # Returns `true` if `ancestor` is an ancestor of `self`. MT safe. Grabs and releases `self`'s locks. Check if `parent` is the parent of `self`. E.g. a `Element` can check if it owns a given `Pad`. ## `parent` a `Object` to check as parent # Returns `false` if either `self` or `parent` is `None`. `true` if `parent` is the parent of `self`. Otherwise `false`. MT safe. Grabs and releases `self`'s locks. Increments the reference count on `self`. This function does not take the lock on `self` because it relies on atomic refcounting. This object returns the input parameter to ease writing constructs like : result = gst_object_ref (object->parent); # Returns A pointer to `self` Removes the corresponding `ControlBinding`. If it was the last ref of the binding, it will be disposed. ## `binding` the binding # Returns `true` if the binding could be removed. This function is used to disable the control bindings on a property for some time, i.e. `GstObjectExt::sync_values` will do nothing for the property. ## `property_name` property to disable ## `disabled` boolean that specifies whether to disable the controller or not. This function is used to disable all controlled properties of the `self` for some time, i.e. `GstObjectExt::sync_values` will do nothing. ## `disabled` boolean that specifies whether to disable the controller 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 should be up to `control`-rate nanoseconds. The control-rate should not change if the element is in `State::Paused` or `State::Playing`. ## `control_rate` the new control-rate in nanoseconds. Sets the name of `self`, or gives `self` a guaranteed unique name (if `name` is `None`). This function makes a copy of the provided name, so the caller retains ownership of the name it sent. ## `name` new name of object # Returns `true` if the name could be set. Since Objects that have a parent cannot be renamed, this function returns `false` in those cases. MT safe. This function grabs and releases `self`'s LOCK. Sets the parent of `self` to `parent`. The object's reference count will be incremented, and any floating reference will be removed (see `Object::ref_sink`). ## `parent` new parent of object # Returns `true` if `parent` could be set or `false` when `self` already had a parent or `self` and `parent` are the same. MT safe. Grabs and releases `self`'s LOCK. Returns a suggestion for timestamps where buffers should be split to get best controller results. # Returns Returns the suggested timestamp or `GST_CLOCK_TIME_NONE` if no control-rate was set. Sets the properties of the object, according to the `GstControlSources` that (maybe) handle them and for the given timestamp. If this function fails, it is most likely the application developers fault. Most probably the control sources are not setup correctly. ## `timestamp` the time that should be processed # Returns `true` if the controller values could be applied to the object properties, `false` otherwise Clear the parent of `self`, removing the associated reference. This function decreases the refcount of `self`. MT safe. Grabs and releases `self`'s lock. Decrements the reference count on `self`. If reference count hits zero, destroy `self`. This function does not take the lock on `self` as it relies on atomic refcounting. The unref method should never be called with the LOCK held since this might deadlock the dispose function. The deep notify signal is used to be notified of property changes. It is typically attached to the toplevel bin to receive notifications from all the elements contained in that bin. ## `prop_object` the object that originated the signal ## `prop` the property that changed The parent of the object. Please note, that when changing the 'parent' property, we don't emit `gobject::Object::notify` and `Object::deep-notify` signals due to locking issues. In some cases one can use `Bin::element-added` or `Bin::element-removed` signals on the parent to achieve a similar effect. The parent of the object. Please note, that when changing the 'parent' property, we don't emit `gobject::Object::notify` and `Object::deep-notify` signals due to locking issues. In some cases one can use `Bin::element-added` or `Bin::element-removed` signals on the parent to achieve a similar effect. A `Element` is linked to other elements via "pads", which are extremely light-weight generic link points. Pads have a `PadDirection`, source pads produce data, sink pads consume data. Pads are typically created from a `PadTemplate` with `Pad::new_from_template` and are then added to a `Element`. This usually happens when the element is created but it can also happen dynamically based on the data that the element is processing or based on the pads that the application requests. Pads without pad templates can be created with `Pad::new`, which takes a direction and a name as an argument. If the name is `None`, then a guaranteed unique name will be assigned to it. A `Element` creating a pad will typically use the various gst_pad_set_*`_function` calls to register callbacks for events, queries or dataflow on the pads. `gst_pad_get_parent` will retrieve the `Element` that owns the pad. After two pads are retrieved from an element by `ElementExt::get_static_pad`, the pads can be linked with `PadExt::link`. (For quick links, you can also use `ElementExt::link`, which will make the obvious link for you if it's straightforward.). Pads can be unlinked again with `PadExt::unlink`. `PadExt::get_peer` can be used to check what the pad is linked to. Before dataflow is possible on the pads, they need to be activated with `PadExt::set_active`. `Pad::query` and `Pad::peer_query` can be used to query various properties of the pad and the stream. To send a `Event` on a pad, use `Pad::send_event` and `Pad::push_event`. Some events will be sticky on the pad, meaning that after they pass on the pad they can be queried later with `PadExt::get_sticky_event` and `PadExt::sticky_events_foreach`. `PadExt::get_current_caps` and `PadExt::has_current_caps` are convenience functions to query the current sticky CAPS event on a pad. GstElements will use `Pad::push` and `Pad::pull_range` to push out or pull in a buffer. The dataflow, events and queries that happen on a pad can be monitored with probes that can be installed with `PadExt::add_probe`. `PadExt::is_blocked` can be used to check if a block probe is installed on the pad. `PadExt::is_blocking` checks if the blocking probe is currently blocking the pad. `Pad::remove_probe` is used to remove a previously installed probe and unblock blocking probes if any. Pad have an offset that can be retrieved with `PadExt::get_offset`. This offset will be applied to the running_time of all data passing over the pad. `PadExt::set_offset` can be used to change the offset. Convenience functions exist to start, pause and stop the task on a pad with `PadExt::start_task`, `PadExt::pause_task` and `PadExt::stop_task` respectively. # Implements [`PadExt`](trait.PadExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `Pad` methods. # Implementors [`Pad`](struct.Pad.html), [`ProxyPad`](struct.ProxyPad.html) Creates a new pad with the given name in the given direction. If name is `None`, a guaranteed unique name (across all pads) will be assigned. This function makes a copy of the name so you can safely free the name. ## `name` the name of the new pad. ## `direction` the `PadDirection` of the pad. # Returns a new `Pad`, or `None` in case of an error. MT safe. Creates a new pad with the given name from the given static template. If name is `None`, a guaranteed unique name (across all pads) will be assigned. This function makes a copy of the name so you can safely free the name. ## `templ` the `StaticPadTemplate` to use ## `name` the name of the pad # Returns a new `Pad`, or `None` in case of an error. Creates a new pad with the given name from the given template. If name is `None`, a guaranteed unique name (across all pads) will be assigned. This function makes a copy of the name so you can safely free the name. ## `templ` the pad template to use ## `name` the name of the pad # Returns a new `Pad`, or `None` in case of an error. Gets a string representing the given pad-link return. ## `ret` a `PadLinkReturn` to get the name of. # Returns a static string with the name of the pad-link return. Activates or deactivates the given pad in `mode` via dispatching to the pad's activatemodefunc. For use from within pad activation functions only. If you don't know what this is, you probably don't want to call it. ## `mode` the requested activation mode ## `active` whether or not the pad should be active. # Returns `true` if the operation was successful. MT safe. Be notified of different states of pads. The provided callback is called for every state that matches `mask`. Probes are called in groups: First GST_PAD_PROBE_TYPE_BLOCK probes are called, then others, then finally GST_PAD_PROBE_TYPE_IDLE. The only exception here are GST_PAD_PROBE_TYPE_IDLE probes that are called immediately if the pad is already idle while calling `PadExt::add_probe`. In each of the groups, probes are called in the order in which they were added. ## `mask` the probe mask ## `callback` `GstPadProbeCallback` that will be called with notifications of the pad state ## `user_data` user data passed to the callback ## `destroy_data` `GDestroyNotify` for user_data # Returns an id or 0 if no probe is pending. The id can be used to remove the probe with `Pad::remove_probe`. When using GST_PAD_PROBE_TYPE_IDLE it can happen that the probe can be run immediately and if the probe returns GST_PAD_PROBE_REMOVE this functions returns 0. MT safe. Checks if the source pad and the sink pad are compatible so they can be linked. ## `sinkpad` the sink `Pad`. # Returns `true` if the pads can be linked. Chain a buffer to `self`. The function returns `FlowReturn::Flushing` if the pad was flushing. If the buffer type is not acceptable for `self` (as negotiated with a preceding GST_EVENT_CAPS event), this function returns `FlowReturn::NotNegotiated`. The function proceeds calling the chain function installed on `self` (see `gst_pad_set_chain_function`) and the return value of that function is returned to the caller. `FlowReturn::NotSupported` is returned if `self` has no chain function. In all cases, success or failure, the caller loses its reference to `buffer` after calling this function. ## `buffer` the `Buffer` to send, return GST_FLOW_ERROR if not. # Returns a `FlowReturn` from the pad. MT safe. Chain a bufferlist to `self`. The function returns `FlowReturn::Flushing` if the pad was flushing. If `self` was not negotiated properly with a CAPS event, this function returns `FlowReturn::NotNegotiated`. The function proceeds calling the chainlist function installed on `self` (see `gst_pad_set_chain_list_function`) and the return value of that function is returned to the caller. `FlowReturn::NotSupported` is returned if `self` has no chainlist function. In all cases, success or failure, the caller loses its reference to `list` after calling this function. MT safe. ## `list` the `BufferList` to send, return GST_FLOW_ERROR if not. # Returns a `FlowReturn` from the pad. Check and clear the `PadFlags::NeedReconfigure` flag on `self` and return `true` if the flag was set. # Returns `true` is the GST_PAD_FLAG_NEED_RECONFIGURE flag was set on `self`. Creates a stream-id for the source `Pad` `self` by combining the upstream information with the optional `stream_id` of the stream of `self`. `self` must have a parent `Element` and which must have zero or one sinkpad. `stream_id` can only be `None` if the parent element of `self` has only a single source pad. This function generates an unique stream-id by getting the upstream stream-start event stream ID and appending `stream_id` to it. If the element has no sinkpad it will generate an upstream stream-id by doing an URI query on the element and in the worst case just uses a random number. Source elements that don't implement the URI handler interface should ideally generate a unique, deterministic stream-id manually instead. Since stream IDs are sorted alphabetically, any numbers in the stream ID should be printed with a fixed number of characters, preceded by 0's, such as by using the format \%03u instead of \%u. ## `parent` Parent `Element` of `self` ## `stream_id` The stream-id # Returns A stream-id for `self`. `g_free` after usage. Creates a stream-id for the source `Pad` `self` by combining the upstream information with the optional `stream_id` of the stream of `self`. `self` must have a parent `Element` and which must have zero or one sinkpad. `stream_id` can only be `None` if the parent element of `self` has only a single source pad. This function generates an unique stream-id by getting the upstream stream-start event stream ID and appending `stream_id` to it. If the element has no sinkpad it will generate an upstream stream-id by doing an URI query on the element and in the worst case just uses a random number. Source elements that don't implement the URI handler interface should ideally generate a unique, deterministic stream-id manually instead. ## `parent` Parent `Element` of `self` ## `stream_id` The stream-id # Returns A stream-id for `self`. `g_free` after usage. Creates a stream-id for the source `Pad` `self` by combining the upstream information with the optional `stream_id` of the stream of `self`. `self` must have a parent `Element` and which must have zero or one sinkpad. `stream_id` can only be `None` if the parent element of `self` has only a single source pad. This function generates an unique stream-id by getting the upstream stream-start event stream ID and appending `stream_id` to it. If the element has no sinkpad it will generate an upstream stream-id by doing an URI query on the element and in the worst case just uses a random number. Source elements that don't implement the URI handler interface should ideally generate a unique, deterministic stream-id manually instead. ## `parent` Parent `Element` of `self` ## `stream_id` The stream-id ## `var_args` parameters for the `stream_id` format string # Returns A stream-id for `self`. `g_free` after usage. Invokes the default event handler for the given pad. The EOS event will pause the task associated with `self` before it is forwarded to all internally linked pads, The event is sent to all pads internally linked to `self`. This function takes ownership of `event`. ## `parent` the parent of `self` or `None` ## `event` the `Event` to handle. # Returns `true` if the event was sent successfully. Calls `forward` for all internally linked pads of `self`. This function deals with dynamically changing internal pads and will make sure that the `forward` function is only called once for each pad. When `forward` returns `true`, no further pads will be processed. ## `forward` a `GstPadForwardFunction` ## `user_data` user data passed to `forward` # Returns `true` if one of the dispatcher functions returned `true`. Gets the capabilities of the allowed media types that can flow through `self` and its peer. The allowed capabilities is calculated as the intersection of the results of calling `PadExt::query_caps` on `self` and its peer. The caller owns a reference on the resulting caps. # Returns the allowed `Caps` of the pad link. Unref the caps when you no longer need it. This function returns `None` when `self` has no peer. MT safe. Gets the capabilities currently configured on `self` with the last `EventType::Caps` event. # Returns the current caps of the pad with incremented ref-count or `None` when pad has no caps. Unref after usage. Gets the direction of the pad. The direction of the pad is decided at construction time so this function does not take the LOCK. # Returns the `PadDirection` of the pad. MT safe. Gets the private data of a pad. No locking is performed in this function. # Returns a `gpointer` to the private data. Gets the `FlowReturn` return from the last data passed by this pad. Get the offset applied to the running time of `self`. `self` has to be a source pad. # Returns the offset. Gets the template for `self`. # Returns the `PadTemplate` from which this pad was instantiated, or `None` if this pad has no template. Unref after usage. Gets the capabilities for `self`'s template. # Returns the `Caps` of this pad template. Unref after usage. Gets the parent of `self`, cast to a `Element`. If a `self` has no parent or its parent is not an element, return `None`. # Returns the parent of the pad. The caller has a reference on the parent, so unref when you're finished with it. MT safe. Gets the peer of `self`. This function refs the peer pad so you need to unref it after use. # Returns the peer `Pad`. Unref after usage. MT safe. When `self` is flushing this function returns `FlowReturn::Flushing` immediately and `buffer` is `None`. Calls the getrange function of `self`, see `GstPadGetRangeFunction` for a description of a getrange function. If `self` has no getrange function installed (see `gst_pad_set_getrange_function`) this function returns `FlowReturn::NotSupported`. If `buffer` points to a variable holding `None`, a valid new `Buffer` will be placed in `buffer` when this function returns `FlowReturn::Ok`. The new buffer must be freed with `gst_buffer_unref` after usage. When `buffer` points to a variable that points to a valid `Buffer`, the buffer will be filled with the result data when this function returns `FlowReturn::Ok`. If the provided buffer is larger than `size`, only `size` bytes will be filled in the result buffer and its size will be updated accordingly. Note that less than `size` bytes can be returned in `buffer` when, for example, an EOS condition is near or when `buffer` is not large enough to hold `size` bytes. The caller should check the result buffer size to get the result size. When this function returns any other result value than `FlowReturn::Ok`, `buffer` will be unchanged. This is a lowlevel function. Usually `Pad::pull_range` is used. ## `offset` The start offset of the buffer ## `size` The length of the buffer ## `buffer` a pointer to hold the `Buffer`, returns `FlowReturn::Error` if `None`. # Returns a `FlowReturn` from the pad. MT safe. Returns a new reference of the sticky event of type `event_type` from the event. ## `event_type` the `EventType` that should be retrieved. ## `idx` the index of the event # Returns a `Event` of type `event_type` or `None` when no event of `event_type` was on `self`. Unref after usage. Returns the current `Stream` for the `self`, or `None` if none has been set yet, i.e. the pad has not received a stream-start event yet. This is a convenience wrapper around `PadExt::get_sticky_event` and `Event::parse_stream`. Feature: `v1_10` # Returns the current `Stream` for `self`, or `None`. unref the returned stream when no longer needed. Returns the current stream-id for the `self`, or `None` if none has been set yet, i.e. the pad has not received a stream-start event yet. This is a convenience wrapper around `PadExt::get_sticky_event` and `Event::parse_stream_start`. The returned stream-id string should be treated as an opaque string, its contents should not be interpreted. # Returns a newly-allocated copy of the stream-id for `self`, or `None`. `g_free` the returned string when no longer needed. Get `self` task state. If no task is currently set, `TaskState::Stopped` is returned. Feature: `v1_12` # Returns The current state of `self`'s task. Check if `self` has caps set on it with a `EventType::Caps` event. # Returns `true` when `self` has caps associated with it. Query if a pad is active # Returns `true` if the pad is active. MT safe. Checks if the pad is blocked or not. This function returns the last requested state of the pad. It is not certain that the pad is actually blocking at this point (see `PadExt::is_blocking`). # Returns `true` if the pad is blocked. MT safe. Checks if the pad is blocking or not. This is a guaranteed state of whether the pad is actually blocking on a `Buffer` or a `Event`. # Returns `true` if the pad is blocking. MT safe. Checks if a `self` is linked to another pad or not. # Returns `true` if the pad is linked, `false` otherwise. MT safe. Gets an iterator for the pads to which the given pad is linked to inside of the parent element. Each `Pad` element yielded by the iterator will have its refcount increased, so unref after use. Free-function: gst_iterator_free # Returns a new `Iterator` of `Pad` or `None` when the pad does not have an iterator function configured. Use `Iterator::free` after usage. Iterate the list of pads to which the given pad is linked to inside of the parent element. This is the default handler, and thus returns an iterator of all of the pads inside the parent element with opposite direction. The caller must free this iterator after use with `Iterator::free`. ## `parent` the parent of `self` or `None` # Returns a `Iterator` of `Pad`, or `None` if `self` has no parent. Unref each returned pad with `GstObjectExt::unref`. Links the source pad and the sink pad. ## `sinkpad` the sink `Pad` to link. # Returns A result code indicating if the connection worked or what went wrong. MT Safe. Links the source pad and the sink pad. This variant of `PadExt::link` provides a more granular control on the checks being done when linking. While providing some considerable speedups the caller of this method must be aware that wrong usage of those flags can cause severe issues. Refer to the documentation of `PadLinkCheck` for more information. MT Safe. ## `sinkpad` the sink `Pad` to link. ## `flags` the checks to validate when linking # Returns A result code indicating if the connection worked or what went wrong. Links `self` to `sink`, creating any `GhostPad`'s in between as necessary. This is a convenience function to save having to create and add intermediate `GhostPad`'s as required for linking across `Bin` boundaries. If `self` or `sink` pads don't have parent elements or do not share a common ancestor, the link will fail. Feature: `v1_10` ## `sink` a `Pad` # Returns whether the link succeeded. Links `self` to `sink`, creating any `GhostPad`'s in between as necessary. This is a convenience function to save having to create and add intermediate `GhostPad`'s as required for linking across `Bin` boundaries. If `self` or `sink` pads don't have parent elements or do not share a common ancestor, the link will fail. Calling `PadExt::link_maybe_ghosting_full` with `flags` == `PadLinkCheck::Default` is the recommended way of linking pads with safety checks applied. Feature: `v1_10` ## `sink` a `Pad` ## `flags` some `PadLinkCheck` flags # Returns whether the link succeeded. Mark a pad for needing reconfiguration. The next call to `PadExt::check_reconfigure` will return `true` after this call. Check the `PadFlags::NeedReconfigure` flag on `self` and return `true` if the flag was set. # Returns `true` is the GST_PAD_FLAG_NEED_RECONFIGURE flag is set on `self`. Pause the task of `self`. This function will also wait until the function executed by the task is finished if this function is not called from the task function. # Returns a `true` if the task could be paused or `false` when the pad has no task. Performs `Pad::query` on the peer of `self`. The caller is responsible for both the allocation and deallocation of the query structure. ## `query` the `Query` to perform. # Returns `true` if the query could be performed. This function returns `false` if `self` has no peer. Check if the peer of `self` accepts `caps`. If `self` has no peer, this function returns `true`. ## `caps` a `Caps` to check on the pad # Returns `true` if the peer of `self` can accept the caps or `self` has no peer. Gets the capabilities of the peer connected to this pad. Similar to `PadExt::query_caps`. When called on srcpads `filter` contains the caps that upstream could produce in the order preferred by upstream. When called on sinkpads `filter` contains the caps accepted by downstream in the preferred order. `filter` might be `None` but if it is not `None` the returned caps will be a subset of `filter`. ## `filter` a `Caps` filter, or `None`. # Returns the caps of the peer pad with incremented ref-count. When there is no peer pad, this function returns `filter` or, when `filter` is `None`, ANY caps. Queries the peer pad of a given sink pad to convert `src_val` in `src_format` to `dest_format`. ## `src_format` a `Format` to convert from. ## `src_val` a value to convert. ## `dest_format` the `Format` to convert to. ## `dest_val` a pointer to the result. # Returns `true` if the query could be performed. Queries the peer pad of a given sink pad for the total stream duration. ## `format` the `Format` requested ## `duration` a location in which to store the total duration, or `None`. # Returns `true` if the query could be performed. Queries the peer of a given sink pad for the stream position. ## `format` the `Format` requested ## `cur` a location in which to store the current position, or `None`. # Returns `true` if the query could be performed. Checks if all internally linked pads of `self` accepts the caps in `query` and returns the intersection of the results. This function is useful as a default accept caps query function for an element that can handle any stream format, but requires caps that are acceptable for all opposite pads. ## `query` an ACCEPT_CAPS `Query`. # Returns `true` if `query` could be executed Calls `PadExt::query_caps` for all internally linked pads of `self` and returns the intersection of the results. This function is useful as a default caps query function for an element that can handle any stream format, but requires all its pads to have the same caps. Two such elements are tee and adder. ## `query` a CAPS `Query`. # Returns `true` if `query` could be executed Pulls a `buffer` from the peer pad or fills up a provided buffer. This function will first trigger the pad block signal if it was installed. When `self` is not linked `FlowReturn::NotLinked` is returned else this function returns the result of `Pad::get_range` on the peer pad. See `Pad::get_range` for a list of return values and for the semantics of the arguments of this function. If `buffer` points to a variable holding `None`, a valid new `Buffer` will be placed in `buffer` when this function returns `FlowReturn::Ok`. The new buffer must be freed with `gst_buffer_unref` after usage. When this function returns any other result value, `buffer` will still point to `None`. When `buffer` points to a variable that points to a valid `Buffer`, the buffer will be filled with the result data when this function returns `FlowReturn::Ok`. When this function returns any other result value, `buffer` will be unchanged. If the provided buffer is larger than `size`, only `size` bytes will be filled in the result buffer and its size will be updated accordingly. Note that less than `size` bytes can be returned in `buffer` when, for example, an EOS condition is near or when `buffer` is not large enough to hold `size` bytes. The caller should check the result buffer size to get the result size. ## `offset` The start offset of the buffer ## `size` The length of the buffer ## `buffer` a pointer to hold the `Buffer`, returns GST_FLOW_ERROR if `None`. # Returns a `FlowReturn` from the peer pad. MT safe. Pushes a buffer to the peer of `self`. This function will call installed block probes before triggering any installed data probes. The function proceeds calling `Pad::chain` on the peer pad and returns the value from that function. If `self` has no peer, `FlowReturn::NotLinked` will be returned. In all cases, success or failure, the caller loses its reference to `buffer` after calling this function. ## `buffer` the `Buffer` to push returns GST_FLOW_ERROR if not. # Returns a `FlowReturn` from the peer pad. MT safe. Sends the event to the peer of the given pad. This function is mainly used by elements to send events to their peer elements. This function takes ownership of the provided event so you should `gst_event_ref` it if you want to reuse the event after this call. ## `event` the `Event` to send to the pad. # Returns `true` if the event was handled. MT safe. Pushes a buffer list to the peer of `self`. This function will call installed block probes before triggering any installed data probes. The function proceeds calling the chain function on the peer pad and returns the value from that function. If `self` has no peer, `FlowReturn::NotLinked` will be returned. If the peer pad does not have any installed chainlist function every group buffer of the list will be merged into a normal `Buffer` and chained via `Pad::chain`. In all cases, success or failure, the caller loses its reference to `list` after calling this function. ## `list` the `BufferList` to push returns GST_FLOW_ERROR if not. # Returns a `FlowReturn` from the peer pad. MT safe. Dispatches a query to a pad. The query should have been allocated by the caller via one of the type-specific allocation functions. The element that the pad belongs to is responsible for filling the query with an appropriate response, which should then be parsed with a type-specific query parsing function. Again, the caller is responsible for both the allocation and deallocation of the query structure. Please also note that some queries might need a running pipeline to work. ## `query` the `Query` to perform. # Returns `true` if the query could be performed. Check if the given pad accepts the caps. ## `caps` a `Caps` to check on the pad # Returns `true` if the pad can accept the caps. Gets the capabilities this pad can produce or consume. Note that this method doesn't necessarily return the caps set by sending a `Event::new_caps` - use `PadExt::get_current_caps` for that instead. gst_pad_query_caps returns all possible caps a pad can operate with, using the pad's CAPS query function, If the query fails, this function will return `filter`, if not `None`, otherwise ANY. When called on sinkpads `filter` contains the caps that upstream could produce in the order preferred by upstream. When called on srcpads `filter` contains the caps accepted by downstream in the preferred order. `filter` might be `None` but if it is not `None` the returned caps will be a subset of `filter`. Note that this function does not return writable `Caps`, use `gst_caps_make_writable` before modifying the caps. ## `filter` suggested `Caps`, or `None` # Returns the caps of the pad with incremented ref-count. Queries a pad to convert `src_val` in `src_format` to `dest_format`. ## `src_format` a `Format` to convert from. ## `src_val` a value to convert. ## `dest_format` the `Format` to convert to. ## `dest_val` a pointer to the result. # Returns `true` if the query could be performed. Invokes the default query handler for the given pad. The query is sent to all pads internally linked to `self`. Note that if there are many possible sink pads that are internally linked to `self`, only one will be sent the query. Multi-sinkpad elements should implement custom query handlers. ## `parent` the parent of `self` or `None` ## `query` the `Query` to handle. # Returns `true` if the query was performed successfully. Queries a pad for the total stream duration. ## `format` the `Format` requested ## `duration` a location in which to store the total duration, or `None`. # Returns `true` if the query could be performed. Queries a pad for the stream position. ## `format` the `Format` requested ## `cur` A location in which to store the current position, or `None`. # Returns `true` if the query could be performed. Remove the probe with `id` from `self`. MT safe. ## `id` the probe id to remove Sends the event to the pad. This function can be used by applications to send events in the pipeline. If `self` is a source pad, `event` should be an upstream event. If `self` is a sink pad, `event` should be a downstream event. For example, you would not send a `EventType::Eos` on a src pad; EOS events only propagate downstream. Furthermore, some downstream events have to be serialized with data flow, like EOS, while some can travel out-of-band, like `EventType::FlushStart`. If the event needs to be serialized with data flow, this function will take the pad's stream lock while calling its event function. To find out whether an event type is upstream, downstream, or downstream and serialized, see `EventTypeFlags`, `EventType::get_flags`, `GST_EVENT_IS_UPSTREAM`, `GST_EVENT_IS_DOWNSTREAM`, and `GST_EVENT_IS_SERIALIZED`. Note that in practice that an application or plugin doesn't need to bother itself with this information; the core handles all necessary locks and checks. This function takes ownership of the provided event so you should `gst_event_ref` it if you want to reuse the event after this call. ## `event` the `Event` to send to the pad. # Returns `true` if the event was handled. Sets the given activate function for `self`. The activate function will dispatch to `PadExt::activate_mode` to perform the actual activation. Only makes sense to set on sink pads. Call this function if your sink pad can start a pull-based task. ## `activate` the `GstPadActivateFunction` to set. ## `user_data` user_data passed to `notify` ## `notify` notify called when `activate` will not be used anymore. Sets the given activate_mode function for the pad. An activate_mode function prepares the element for data passing. ## `activatemode` the `GstPadActivateModeFunction` to set. ## `user_data` user_data passed to `notify` ## `notify` notify called when `activatemode` will not be used anymore. Activates or deactivates the given pad. Normally called from within core state change functions. If `active`, makes sure the pad is active. If it is already active, either in push or pull mode, just return. Otherwise dispatches to the pad's activate function to perform the actual activation. If not `active`, calls `PadExt::activate_mode` with the pad's current mode and a `false` argument. ## `active` whether or not the pad should be active. # Returns `true` if the operation was successful. MT safe. Sets the given chain function for the pad. The chain function is called to process a `Buffer` input buffer. see `GstPadChainFunction` for more details. ## `chain` the `GstPadChainFunction` to set. ## `user_data` user_data passed to `notify` ## `notify` notify called when `chain` will not be used anymore. Sets the given chain list function for the pad. The chainlist function is called to process a `BufferList` input buffer list. See `GstPadChainListFunction` for more details. ## `chainlist` the `GstPadChainListFunction` to set. ## `user_data` user_data passed to `notify` ## `notify` notify called when `chainlist` will not be used anymore. Set the given private data gpointer on the pad. This function can only be used by the element that owns the pad. No locking is performed in this function. ## `priv_` The private data to attach to the pad. Sets the given event handler for the pad. ## `event` the `GstPadEventFullFunction` to set. ## `user_data` user_data passed to `notify` ## `notify` notify called when `event` will not be used anymore. Sets the given event handler for the pad. ## `event` the `GstPadEventFunction` to set. ## `user_data` user_data passed to `notify` ## `notify` notify called when `event` will not be used anymore. Sets the given getrange function for the pad. The getrange function is called to produce a new `Buffer` to start the processing pipeline. see `GstPadGetRangeFunction` for a description of the getrange function. ## `get` the `GstPadGetRangeFunction` to set. ## `user_data` user_data passed to `notify` ## `notify` notify called when `get` will not be used anymore. Sets the given internal link iterator function for the pad. ## `iterintlink` the `GstPadIterIntLinkFunction` to set. ## `user_data` user_data passed to `notify` ## `notify` notify called when `iterintlink` will not be used anymore. Sets the given link function for the pad. It will be called when the pad is linked with another pad. The return value `PadLinkReturn::Ok` should be used when the connection can be made. The return value `PadLinkReturn::Refused` should be used when the connection cannot be made for some reason. If `link` is installed on a source pad, it should call the `GstPadLinkFunction` of the peer sink pad, if present. ## `link` the `GstPadLinkFunction` to set. ## `user_data` user_data passed to `notify` ## `notify` notify called when `link` will not be used anymore. Set the offset that will be applied to the running time of `self`. ## `offset` the offset Set the given query function for the pad. ## `query` the `GstPadQueryFunction` to set. ## `user_data` user_data passed to `notify` ## `notify` 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. ## `unlink` the `GstPadUnlinkFunction` to set. ## `user_data` user_data passed to `notify` ## `notify` notify called when `unlink` will not be used anymore. Starts a task that repeatedly calls `func` with `user_data`. This function is mostly used in pad activation functions to start the dataflow. The `GST_PAD_STREAM_LOCK` of `self` will automatically be acquired before `func` is called. ## `func` the task function to call ## `user_data` user data passed to the task function ## `notify` called when `user_data` is no longer referenced # Returns a `true` if the task could be started. Iterates all sticky events on `self` and calls `foreach_func` for every event. If `foreach_func` returns `false` the iteration is immediately stopped. ## `foreach_func` the `GstPadStickyEventsForeachFunction` that should be called for every event. ## `user_data` the optional user data. Stop the task of `self`. This function will also make sure that the function executed by the task will effectively stop if not called from the GstTaskFunction. This function will deadlock if called from the GstTaskFunction of the task. Use `Task::pause` instead. Regardless of whether the pad has a task, the stream lock is acquired and released so as to ensure that streaming through this pad has finished. # Returns a `true` if the task could be stopped or `false` on error. Store the sticky `event` on `self` ## `event` a `Event` # Returns `FlowReturn::Ok` on success, `FlowReturn::Flushing` when the pad was flushing or `FlowReturn::Eos` when the pad was EOS. Unlinks the source pad from the sink pad. Will emit the `Pad::unlinked` signal on both pads. ## `sinkpad` the sink `Pad` to unlink. # Returns `true` if the pads were unlinked. This function returns `false` if the pads were not linked together. MT safe. A helper function you can use that sets the FIXED_CAPS flag This way the default CAPS query will always return the negotiated caps or in case the pad is not negotiated, the padtemplate caps. The negotiated caps are the caps of the last CAPS event that passed on the pad. Use this function on a pad that, once it negotiated to a CAPS, cannot be renegotiated to something else. Signals that a pad has been linked to the peer pad. ## `peer` the peer pad that has been connected Signals that a pad has been unlinked from the peer pad. ## `peer` the peer pad that has been disconnected The offset that will be applied to the running time of the pad. The offset that will be applied to the running time of the pad. The direction of a pad. direction is unknown. the pad is a source pad. the pad is a sink pad. Result values from gst_pad_link and friends. link succeeded pads have no common grandparent pad was already linked pads have wrong direction pads do not have common format pads cannot cooperate in scheduling refused for some reason The status of a GstPad. After activating a pad, which usually happens when the parent element goes from READY to PAUSED, the GstPadMode defines if the pad operates in push or pull mode. Pad will not handle dataflow Pad handles dataflow in downstream push mode Pad handles dataflow in upstream pull mode Indicates when this pad will become available. the pad is always available the pad will become available depending on the media stream the pad is only available on request with `ElementExt::request_pad`. Different return values for the `GstPadProbeCallback`. drop data in data probes. For push mode this means that the data item is not sent downstream. For pull mode, it means that the data item is not passed upstream. In both cases, no other probes are called for this item and `FlowReturn::Ok` or `true` is returned to the caller. normal probe return value. This leaves the probe in place, and defers decisions about dropping or passing data to other probes, if any. If there are no other probes, the default behaviour for the probe type applies ('block' for blocking probes, and 'pass' for non-blocking probes). remove this probe. pass the data item in the block probe and block on the next item. Data has been handled in the probe and will not be forwarded further. For events and buffers this is the same behaviour as `PadProbeReturn::Drop` (except that in this case you need to unref the buffer or event yourself). For queries it will also return `true` to the caller. The probe can also modify the `FlowReturn` value by using the `GST_PAD_PROBE_INFO_FLOW_RETURN`() accessor. Note that the resulting query must contain valid entries. Since: 1.6 Padtemplates describe the possible media types a pad or an elementfactory can handle. This allows for both inspection of handled types before loading the element plugin as well as identifying pads on elements that are not yet created (request or sometimes pads). Pad and PadTemplates have `Caps` attached to it to describe the media type they are capable of dealing with. `PadTemplate::get_caps` or GST_PAD_TEMPLATE_CAPS() are used to get the caps of a padtemplate. It's not possible to modify the caps of a padtemplate after creation. PadTemplates have a `PadPresence` property which identifies the lifetime of the pad and that can be retrieved with GST_PAD_TEMPLATE_PRESENCE(). Also the direction of the pad can be retrieved from the `PadTemplate` with GST_PAD_TEMPLATE_DIRECTION(). The GST_PAD_TEMPLATE_NAME_TEMPLATE () is important for GST_PAD_REQUEST pads because it has to be used as the name in the `ElementExt::get_request_pad` call to instantiate a pad from this template. Padtemplates can be created with `PadTemplate::new` or with gst_static_pad_template_get (), which creates a `PadTemplate` from a `StaticPadTemplate` that can be filled with the convenient GST_STATIC_PAD_TEMPLATE() macro. A padtemplate can be used to create a pad (see `Pad::new_from_template` or gst_pad_new_from_static_template ()) or to add to an element class (see gst_element_class_add_static_pad_template ()). The following code example shows the code to create a pad from a padtemplate. ```C GstStaticPadTemplate my_template = GST_STATIC_PAD_TEMPLATE ( "sink", // the name of the pad GST_PAD_SINK, // the direction of the pad GST_PAD_ALWAYS, // when this pad will be present GST_STATIC_CAPS ( // the capabilities of the padtemplate "audio/x-raw, " "channels = (int) [ 1, 6 ]" ) ); void my_method (void) { GstPad *pad; pad = gst_pad_new_from_static_template (&my_template, "sink"); ... } ``` The following example shows you how to add the padtemplate to an element class, this is usually done in the class_init of the class: ```C static void my_element_class_init (GstMyElementClass *klass) { GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass); gst_element_class_add_static_pad_template (gstelement_class, &my_template); } ``` # Implements [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates a new pad template with a name according to the given template and with the given arguments. ## `name_template` the name template. ## `direction` the `PadDirection` of the template. ## `presence` the `PadPresence` of the pad. ## `caps` a `Caps` set for the template. # Returns a new `PadTemplate`. Converts a `StaticPadTemplate` into a `PadTemplate` with a type. Feature: `v1_14` ## `pad_template` the static pad template ## `pad_type` The `glib::Type` of the pad to create # Returns a new `PadTemplate`. Creates a new pad template with a name according to the given template and with the given arguments. Feature: `v1_14` ## `name_template` the name template. ## `direction` the `PadDirection` of the template. ## `presence` the `PadPresence` of the pad. ## `caps` a `Caps` set for the template. ## `pad_type` The `glib::Type` of the pad to create # Returns a new `PadTemplate`. Gets the capabilities of the pad template. # Returns the `Caps` of the pad template. Unref after usage. Emit the pad-created signal for this template when created by this pad. ## `pad` the `Pad` that created it This signal is fired when an element creates a pad from this template. ## `pad` the pad that was created. The capabilities of the pad described by the pad template. The capabilities of the pad described by the pad template. The direction of the pad described by the pad template. The direction of the pad described by the pad template. The type of the pad described by the pad template. Feature: `v1_14` The type of the pad described by the pad template. Feature: `v1_14` The name template of the pad template. The name template of the pad template. When the pad described by the pad template will become available. When the pad described by the pad template will become available. Opaque structure. Allocates a parse context for use with `gst_parse_launch_full` or `gst_parse_launchv_full`. Free-function: gst_parse_context_free # Returns a newly-allocated parse context. Free with `ParseContext::free` when no longer needed. Copies the `self`. # Returns A copied `ParseContext` Frees a parse context previously allocated with `ParseContext::new`. Retrieve missing elements from a previous run of `gst_parse_launch_full` or `gst_parse_launchv_full`. Will only return results if an error code of `ParseError::NoSuchElement` was returned. # Returns a `None`-terminated array of element factory name strings of missing elements. Free with `g_strfreev` when no longer needed. The different parsing errors that can occur. A syntax error occurred. The description contained an unknown element An element did not have a specified property There was an error linking two pads. There was an error setting a property An empty bin was specified. An empty description was specified A delayed link did not get resolved. A `Pipeline` is a special `Bin` used as the toplevel container for the filter graph. The `Pipeline` will manage the selection and distribution of a global `Clock` as well as provide a `Bus` to the application. `Pipeline::new` is used to create a pipeline. when you are done with the pipeline, use `GstObjectExt::unref` to free its resources including all added `Element` objects (if not otherwise referenced). Elements are added and removed from the pipeline using the `Bin` methods like `BinExt::add` and `BinExt::remove` (see `Bin`). Before changing the state of the `Pipeline` (see `Element`) a `Bus` can be retrieved with `Pipeline::get_bus`. This bus can then be used to receive `Message` from the elements in the pipeline. By default, a `Pipeline` will automatically flush the pending `Bus` messages when going to the NULL state to ensure that no circular references exist when no messages are read from the `Bus`. This behaviour can be changed with `PipelineExt::set_auto_flush_bus`. When the `Pipeline` performs the PAUSED to PLAYING state change it will select a clock for the elements. The clock selection algorithm will by default select a clock provided by an element that is most upstream (closest to the source). For live pipelines (ones that return `StateChangeReturn::NoPreroll` from the `ElementExt::set_state` call) this will select the clock provided by the live source. For normal pipelines this will select a clock provided by the sinks (most likely the audio sink). If no element provides a clock, a default `SystemClock` is used. The clock selection can be controlled with the `PipelineExt::use_clock` method, which will enforce a given clock on the pipeline. With `PipelineExt::auto_clock` the default clock selection algorithm can be restored. A `Pipeline` maintains a running time for the elements. The running time is defined as the difference between the current clock time and the base time. When the pipeline goes to READY or a flushing seek is performed on it, the running time is reset to 0. When the pipeline is set from PLAYING to PAUSED, the current clock time is sampled and used to configure the base time for the elements when the pipeline is set to PLAYING again. The effect is that the running time (as the difference between the clock time and the base time) will count how much time was spent in the PLAYING state. This default behaviour can be changed with the `ElementExt::set_start_time` method. # Implements [`PipelineExt`](trait.PipelineExt.html), [`BinExt`](trait.BinExt.html), [`ElementExt`](trait.ElementExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ChildProxyExt`](trait.ChildProxyExt.html) Trait containing all `Pipeline` methods. # Implementors [`Pipeline`](struct.Pipeline.html) Create a new pipeline with the given name. ## `name` name of new pipeline # Returns newly created GstPipeline MT safe. Let `self` select a clock automatically. This is the default behaviour. Use this function if you previous forced a fixed clock with `PipelineExt::use_clock` and want to restore the default pipeline clock selection algorithm. MT safe. Check if `self` will automatically flush messages when going to the NULL state. # Returns whether the pipeline will automatically flush its bus when going from READY to NULL state or not. MT safe. Gets the `Bus` of `self`. The bus allows applications to receive `Message` packets. # Returns a `Bus`, unref after usage. MT safe. Gets the current clock used by `self`. Users of object oriented languages should use `PipelineExt::get_pipeline_clock` to avoid confusion with `ElementExt::get_clock` which has a different behavior. Unlike `ElementExt::get_clock`, this function will always return a clock, even if the pipeline is not in the PLAYING state. # Returns a `Clock`, unref after usage. Get the configured delay (see `PipelineExt::set_delay`). # Returns The configured delay. MT safe. Gets the latency that should be configured on the pipeline. See `PipelineExt::set_latency`. # Returns Latency to configure on the pipeline or GST_CLOCK_TIME_NONE Gets the current clock used by `self`. Unlike `ElementExt::get_clock`, this function will always return a clock, even if the pipeline is not in the PLAYING state. # Returns a `Clock`, unref after usage. Usually, when a pipeline goes from READY to NULL state, it automatically flushes all pending messages on the bus, which is done for refcounting purposes, to break circular references. This means that applications that update state using (async) bus messages (e.g. do certain things when a pipeline goes from PAUSED to READY) might not get to see messages when the pipeline is shut down, because they might be flushed before they can be dispatched in the main thread. This behaviour can be disabled using this function. It is important that all messages on the bus are handled when the automatic flushing is disabled else memory leaks will be introduced. MT safe. ## `auto_flush` whether or not to automatically flush the bus when the pipeline goes from READY to NULL state Set the clock for `self`. The clock will be distributed to all the elements managed by the pipeline. ## `clock` the clock to set # Returns `true` if the clock could be set on the pipeline. `false` if some element did not accept the clock. MT safe. Set the expected delay needed for all elements to perform the PAUSED to PLAYING state change. `delay` will be added to the base time of the elements so that they wait an additional `delay` amount of time before starting to process buffers and cannot be `GST_CLOCK_TIME_NONE`. This option is used for tuning purposes and should normally not be used. MT safe. ## `delay` the delay Sets the latency that should be configured on the pipeline. Setting GST_CLOCK_TIME_NONE will restore the default behaviour of using the minimum latency from the LATENCY query. Setting this is usually not required and the pipeline will figure out an appropriate latency automatically. Setting a too low latency, especially lower than the minimum latency from the LATENCY query, will most likely cause the pipeline to fail. ## `latency` latency to configure Force `self` to use the given `clock`. The pipeline will always use the given clock even if new clock providers are added to this pipeline. If `clock` is `None` all clocking will be disabled which will make the pipeline run as fast as possible. MT safe. ## `clock` the clock to use Whether or not to automatically flush all messages on the pipeline's bus when going from READY to NULL state. Please see `PipelineExt::set_auto_flush_bus` for more information on this option. Whether or not to automatically flush all messages on the pipeline's bus when going from READY to NULL state. Please see `PipelineExt::set_auto_flush_bus` for more information on this option. The expected delay needed for elements to spin up to the PLAYING state expressed in nanoseconds. see `PipelineExt::set_delay` for more information on this option. The expected delay needed for elements to spin up to the PLAYING state expressed in nanoseconds. see `PipelineExt::set_delay` for more information on this option. Latency to configure on the pipeline. See `PipelineExt::set_latency`. Latency to configure on the pipeline. See `PipelineExt::set_latency`. GStreamer is extensible, so `Element` instances can be loaded at runtime. A plugin system can provide one or more of the basic ``GStreamer`` `PluginFeature` subclasses. A plugin should export a symbol ``gst_plugin_desc`` that is a struct of type `PluginDesc`. the plugin loader will check the version of the core library the plugin was linked against and will create a new `Plugin`. It will then call the `GstPluginInitFunc` function that was provided in the ``gst_plugin_desc``. Once you have a handle to a `Plugin` (e.g. from the `Registry`), you can add any object that subclasses `PluginFeature`. Usually plugins are always automatically loaded so you don't need to call `Plugin::load` explicitly to bring it into memory. There are options to statically link plugins to an app or even use GStreamer without a plugin repository in which case `Plugin::load` can be needed to bring the plugin into memory. # Implements [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Unrefs each member of `list`, then frees the list. ## `list` list of `Plugin` Load the named plugin. Refs the plugin. ## `name` name of plugin to load # Returns a reference to a loaded plugin, or `None` on error. Loads the given plugin and refs it. Caller needs to unref after use. ## `filename` the plugin filename to load # Returns a reference to the existing loaded GstPlugin, a reference to the newly-loaded GstPlugin, or `None` if an error occurred. Registers a static plugin, ie. a plugin which is private to an application or library and contained within the application or library (as opposed to being shipped as a separate module file). You must make sure that GStreamer has been initialised (with `gst_init` or via `gst_init_get_option_group`) before calling this function. ## `major_version` the major version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MAJOR here ## `minor_version` the minor version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MINOR here ## `name` a unique name of the plugin (ideally prefixed with an application- or library-specific namespace prefix in order to avoid name conflicts in case a similar plugin with the same name ever gets added to GStreamer) ## `description` description of the plugin ## `init_func` pointer to the init function of this plugin. ## `version` version string of the plugin ## `license` effective license of plugin. Must be one of the approved licenses (see `PluginDesc` above) or the plugin will not be registered. ## `source` source module plugin belongs to ## `package` shipped package plugin belongs to ## `origin` URL to provider of plugin # Returns `true` if the plugin was registered correctly, otherwise `false`. Registers a static plugin, ie. a plugin which is private to an application or library and contained within the application or library (as opposed to being shipped as a separate module file) with a `GstPluginInitFullFunc` which allows user data to be passed to the callback function (useful for bindings). You must make sure that GStreamer has been initialised (with `gst_init` or via `gst_init_get_option_group`) before calling this function. ## `major_version` the major version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MAJOR here ## `minor_version` the minor version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MINOR here ## `name` a unique name of the plugin (ideally prefixed with an application- or library-specific namespace prefix in order to avoid name conflicts in case a similar plugin with the same name ever gets added to GStreamer) ## `description` description of the plugin ## `init_full_func` pointer to the init function with user data of this plugin. ## `version` version string of the plugin ## `license` effective license of plugin. Must be one of the approved licenses (see `PluginDesc` above) or the plugin will not be registered. ## `source` source module plugin belongs to ## `package` shipped package plugin belongs to ## `origin` URL to provider of plugin ## `user_data` gpointer to user data # Returns `true` if the plugin was registered correctly, otherwise `false`. Make GStreamer aware of external dependencies which affect the feature set of this plugin (ie. the elements or typefinders associated with it). GStreamer will re-inspect plugins with external dependencies whenever any of the external dependencies change. This is useful for plugins which wrap other plugin systems, e.g. a plugin which wraps a plugin-based visualisation library and makes visualisations available as GStreamer elements, or a codec loader which exposes elements and/or caps dependent on what external codec libraries are currently installed. ## `env_vars` `None`-terminated array of environment variables affecting the feature set of the plugin (e.g. an environment variable containing paths where to look for additional modules/plugins of a library), or `None`. Environment variable names may be followed by a path component which will be added to the content of the environment variable, e.g. "HOME/.mystuff/plugins". ## `paths` `None`-terminated array of directories/paths where dependent files may be, or `None`. ## `names` `None`-terminated array of file names (or file name suffixes, depending on `flags`) to be used in combination with the paths from `paths` and/or the paths extracted from the environment variables in `env_vars`, or `None`. ## `flags` optional flags, or `PluginDependencyFlags::None` Make GStreamer aware of external dependencies which affect the feature set of this plugin (ie. the elements or typefinders associated with it). GStreamer will re-inspect plugins with external dependencies whenever any of the external dependencies change. This is useful for plugins which wrap other plugin systems, e.g. a plugin which wraps a plugin-based visualisation library and makes visualisations available as GStreamer elements, or a codec loader which exposes elements and/or caps dependent on what external codec libraries are currently installed. Convenience wrapper function for `Plugin::add_dependency` which takes simple strings as arguments instead of string arrays, with multiple arguments separated by predefined delimiters (see above). ## `env_vars` one or more environment variables (separated by ':', ';' or ','), or `None`. Environment variable names may be followed by a path component which will be added to the content of the environment variable, e.g. "HOME/.mystuff/plugins:MYSTUFF_PLUGINS_PATH" ## `paths` one ore more directory paths (separated by ':' or ';' or ','), or `None`. Example: "/usr/lib/mystuff/plugins" ## `names` one or more file names or file name suffixes (separated by commas), or `None` ## `flags` optional flags, or `PluginDependencyFlags::None` Gets the plugin specific data cache. If it is `None` there is no cached data stored. This is the case when the registry is getting rebuilt. # Returns The cached data as a `Structure` or `None`. Get the long descriptive name of the plugin # Returns the long name of the plugin get the filename of the plugin # Returns the filename of the plugin get the license of the plugin # Returns the license of the plugin Get the short name of the plugin # Returns the name of the plugin get the URL where the plugin comes from # Returns the origin of the plugin get the package the plugin belongs to. # Returns the package of the plugin Get the release date (and possibly time) in form of a string, if available. For normal GStreamer plugin releases this will usually just be a date in the form of "YYYY-MM-DD", while pre-releases and builds from git may contain a time component after the date as well, in which case the string will be formatted like "YYYY-MM-DDTHH:MMZ" (e.g. "2012-04-30T09:30Z"). There may be plugins that do not have a valid release date set on them. # Returns the date string of the plugin, or `None` if not available. get the source module the plugin belongs to. # Returns the source of the plugin get the version of the plugin # Returns the version of the plugin queries if the plugin is loaded into memory # Returns `true` is loaded, `false` otherwise Loads `self`. Note that the *return value* is the loaded plugin; `self` is untouched. The normal use pattern of this function goes like this: ```text GstPlugin *loaded_plugin; loaded_plugin = gst_plugin_load (plugin); // presumably, we're no longer interested in the potentially-unloaded plugin gst_object_unref (plugin); plugin = loaded_plugin; ``` # Returns a reference to a loaded plugin, or `None` on error. Adds plugin specific data to cache. Passes the ownership of the structure to the `self`. The cache is flushed every time the registry is rebuilt. ## `cache_data` a structure containing the data to cache The plugin loading errors The plugin could not be loaded The plugin has unresolved dependencies The plugin has already be loaded from a different file This is a base class for anything that can be added to a `Plugin`. # Implements [`PluginFeatureExt`](trait.PluginFeatureExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `PluginFeature` methods. # Implementors [`DeviceProviderFactory`](struct.DeviceProviderFactory.html), [`ElementFactory`](struct.ElementFactory.html), [`PluginFeature`](struct.PluginFeature.html), [`TypeFindFactory`](struct.TypeFindFactory.html) Copies the list of features. Caller should call `PluginFeature::list_free` when done with the list. ## `list` list of `PluginFeature` # Returns a copy of `list`, with each feature's reference count incremented. Debug the plugin feature names in `list`. ## `list` a `glib::List` of plugin features Unrefs each member of `list`, then frees the list. ## `list` list of `PluginFeature` Compares the two given `PluginFeature` instances. This function can be used as a `GCompareFunc` when sorting by rank and then by name. ## `p1` a `PluginFeature` ## `p2` a `PluginFeature` # Returns negative value if the rank of p1 > the rank of p2 or the ranks are equal but the name of p1 comes before the name of p2; zero if the rank and names are equal; positive value if the rank of p1 < the rank of p2 or the ranks are equal but the name of p2 comes before the name of p1 Checks whether the given plugin feature is at least the required version ## `min_major` minimum required major version ## `min_minor` minimum required minor version ## `min_micro` minimum required micro version # Returns `true` if the plugin feature has at least the required version, otherwise `false`. Get the plugin that provides this feature. # Returns the plugin that provides this feature, or `None`. Unref with `GstObjectExt::unref` when no longer needed. Get the name of the plugin that provides this feature. # Returns the name of the plugin that provides this feature, or `None` if the feature is not associated with a plugin. Gets the rank of a plugin feature. # Returns The rank of the feature Loads the plugin containing `self` if it's not already loaded. `self` is unaffected; use the return value instead. Normally this function is used like this: ```C GstPluginFeature *loaded_feature; loaded_feature = gst_plugin_feature_load (feature); // presumably, we're no longer interested in the potentially-unloaded feature gst_object_unref (feature); feature = loaded_feature; ``` # Returns a reference to the loaded feature, or `None` on error Specifies a rank for a plugin feature, so that autoplugging uses the most appropriate feature. ## `rank` rank value - higher number means more priority rank This interface offers methods to query and manipulate parameter preset sets. A preset is a bunch of property settings, together with meta data and a name. The name of a preset serves as key for subsequent method calls to manipulate single presets. All instances of one type will share the list of presets. The list is created on demand, if presets are not used, the list is not created. The interface comes with a default implementation that serves most plugins. Wrapper plugins will override most methods to implement support for the native preset format of those wrapped plugins. One method that is useful to be overridden is `Preset::get_property_names`. With that one can control which properties are saved and in which order. When implementing support for read-only presets, one should set the vmethods for `Preset::save_preset` and `Preset::delete_preset` to `None`. Applications can use `Preset::is_editable` to check for that. The default implementation supports presets located in a system directory, application specific directory and in the users home directory. When getting 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". # Implements [`PresetExt`](trait.PresetExt.html) Trait containing all `Preset` methods. # Implementors [`Preset`](struct.Preset.html) Gets the directory for application specific presets if set by the application. # Returns the directory or `None`, don't free or modify the string Sets an extra directory as an absolute path that should be considered when looking for presets. Any presets in the application dir will shadow the system presets. ## `app_dir` the application specific preset dir # Returns `true` for success, `false` if the dir already has been set Delete the given preset. ## `name` preset name to remove # Returns `true` for success, `false` if e.g. there is no preset with that `name` Gets the `value` for an existing meta data `tag`. Meta data `tag` names can be something like e.g. "comment". Returned values need to be released when done. ## `name` preset name ## `tag` meta data item name ## `value` value # Returns `true` for success, `false` if e.g. there is no preset with that `name` or no value for the given `tag` Get a copy of preset names as a `None` terminated string array. # Returns list with names, use `g_strfreev` after usage. Get a the names of the GObject properties that can be used for presets. # Returns an array of property names which should be freed with `g_strfreev` after use. Check if one can add new presets, change existing ones and remove presets. # Returns `true` if presets are editable or `false` if they are static Load the given preset. ## `name` preset name to load # Returns `true` for success, `false` if e.g. there is no preset with that `name` Renames a preset. If there is already a preset by the `new_name` it will be overwritten. ## `old_name` current preset name ## `new_name` new preset name # Returns `true` for success, `false` if e.g. there is no preset with `old_name` Save the current object settings as a preset under the given name. If there is already a preset by this `name` it will be overwritten. ## `name` preset name to save # Returns `true` for success, `false` Sets a new `value` for an existing meta data item or adds a new item. Meta data `tag` names can be something like e.g. "comment". Supplying `None` for the `value` will unset an existing value. ## `name` preset name ## `tag` meta data item name ## `value` new value # Returns `true` for success, `false` if e.g. there is no preset with that `name` The type of a `MessageType::Progress`. The progress messages inform the application of the status of asynchronous tasks. A new task started. A task completed and a new one continues. A task completed. A task was canceled. A task caused an error. An error message is also posted on the bus. The `Promise` object implements the container for values that may be available later. i.e. a Future or a Promise in https://en.wikipedia.org/wiki/Futures_and_promises`` As with all Future/Promise-like functionality, there is the concept of the producer of the value and the consumer of the value. A `Promise` is created with `Promise::new` by the consumer and passed to the producer to avoid thread safety issues with the change callback. A `Promise` can be replied to with a value (or an error) by the producer with `Promise::reply`. `Promise::interrupt` is for the consumer to indicate to the producer that the value is not needed anymore and producing that value can stop. The `PromiseResult::Expired` state set by a call to `Promise::expire` indicates to the consumer that a value will never be produced and is intended to be called by a third party that implements some notion of message handling such as `Bus`. A callback can also be installed at `Promise` creation for result changes with `Promise::new_with_change_func`. The change callback can be used to chain `GstPromises`'s together as in the following example. ```C const GstStructure *reply; GstPromise *p; if (gst_promise_wait (promise) != GST_PROMISE_RESULT_REPLIED) return; // interrupted or expired value reply = gst_promise_get_reply (promise); if (error in reply) return; // propagate error p = gst_promise_new_with_change_func (another_promise_change_func, user_data, notify); pass p to promise-using API ``` Each `Promise` starts out with a `PromiseResult` of `PromiseResult::Pending` and only ever transitions once into one of the other `PromiseResult`'s. In order to support multi-threaded code, `Promise::reply`, `Promise::interrupt` and `Promise::expire` may all be from different threads with some restrictions and the final result of the promise is whichever call is made first. There are two restrictions on ordering: 1. That `Promise::reply` and `Promise::interrupt` cannot be called after `Promise::expire` 2. That `Promise::reply` and `Promise::interrupt` cannot be called twice. The change function set with `Promise::new_with_change_func` is called directly from either the `Promise::reply`, `Promise::interrupt` or `Promise::expire` and can be called from an arbitrary thread. `Promise` using APIs can restrict this to a single thread or a subset of threads but that is entirely up to the API that uses `Promise`. Feature: `v1_14` Feature: `v1_14` # Returns a new `Promise` `func` will be called exactly once when transitioning out of `PromiseResult::Pending` into any of the other `PromiseResult` states. Feature: `v1_14` ## `func` a `GstPromiseChangeFunc` to call ## `user_data` argument to call `func` with ## `notify` notification function that `user_data` is no longer needed # Returns a new `Promise` Expire a `self`. This will wake up any waiters with `PromiseResult::Expired`. Called by a message loop when the parent message is handled and/or destroyed (possibly unanswered). Feature: `v1_14` Retrieve the reply set on `self`. `self` must be in `PromiseResult::Replied` and the returned structure is owned by `self` Feature: `v1_14` # Returns The reply set on `self` Interrupt waiting for a `self`. This will wake up any waiters with `PromiseResult::Interrupted`. Called when the consumer does not want the value produced anymore. Feature: `v1_14` Set a reply on `self`. This will wake up any waiters with `PromiseResult::Replied`. Called by the producer of the value to indicate success (or failure). If `self` has already been interrupted by the consumer, then this reply is not visible to the consumer. Feature: `v1_14` ## `s` a `Structure` with the the reply contents Wait for `self` to move out of the `PromiseResult::Pending` state. If `self` is not in `PromiseResult::Pending` then it will return immediately with the current result. Feature: `v1_14` # Returns the result of the promise The result of a `Promise` Initial state. Waiting for transition to any other state. Interrupted by the consumer as it doesn't want the value anymore. A producer marked a reply The promise expired (the carrying object lost all refs) and the promise will never be fulfilled. Feature: `v1_14` # Implements [`ProxyPadExt`](trait.ProxyPadExt.html), [`PadExt`](trait.PadExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `ProxyPad` methods. # Implementors [`GhostPad`](struct.GhostPad.html), [`ProxyPad`](struct.ProxyPad.html) Invoke the default chain function of the proxy pad. ## `pad` a sink `Pad`, returns GST_FLOW_ERROR if not. ## `parent` the parent of `pad` or `None` ## `buffer` the `Buffer` to send, return GST_FLOW_ERROR if not. # Returns a `FlowReturn` from the pad. Invoke the default chain list function of the proxy pad. ## `pad` a sink `Pad`, returns GST_FLOW_ERROR if not. ## `parent` the parent of `pad` or `None` ## `list` the `BufferList` to send, return GST_FLOW_ERROR if not. # Returns a `FlowReturn` from the pad. Invoke the default getrange function of the proxy pad. ## `pad` a src `Pad`, returns `FlowReturn::Error` if not. ## `parent` the parent of `pad` ## `offset` The start offset of the buffer ## `size` The length of the buffer ## `buffer` a pointer to hold the `Buffer`, returns `FlowReturn::Error` if `None`. # Returns a `FlowReturn` from the pad. Invoke the default iterate internal links function of the proxy pad. ## `pad` the `Pad` to get the internal links of. ## `parent` the parent of `pad` or `None` # Returns a `Iterator` of `Pad`, or `None` if `pad` has no parent. Unref each returned pad with `GstObjectExt::unref`. Get the internal pad of `self`. Unref target pad after usage. The internal pad of a `GhostPad` is the internally used pad of opposite direction, which is used to link to the target. # Returns the target `ProxyPad`, can be `None`. Unref target pad after usage. The different types of QoS events that can be given to the `Event::new_qos` method. The QoS event type that is produced when upstream elements are producing data too quickly and the element can't keep up processing the data. Upstream should reduce their production rate. This type is also used when buffers arrive early or in time. The QoS event type that is produced when upstream elements are producing data too slowly and need to speed up their production rate. The QoS event type that is produced when the application enabled throttling to limit the data rate. Queries can be performed on pads (`Pad::query`) and elements (`Element::query`). Please note that some queries might need a running pipeline to work. Queries can be created using the gst_query_new_*() functions. Query values can be set using gst_query_set_*(), and parsed using gst_query_parse_*() helpers. The following example shows how to query the duration of a pipeline: ```C GstQuery *query; gboolean res; query = gst_query_new_duration (GST_FORMAT_TIME); res = gst_element_query (pipeline, query); if (res) { gint64 duration; gst_query_parse_duration (query, NULL, &duration); g_print ("duration = %"GST_TIME_FORMAT, GST_TIME_ARGS (duration)); } else { g_print ("duration query failed..."); } gst_query_unref (query); ``` Constructs a new query object for querying if `caps` are accepted. Free-function: `gst_query_unref` ## `caps` a fixed `Caps` # Returns a new `Query` Constructs a new query object for querying the allocation properties. Free-function: `gst_query_unref` ## `caps` the negotiated caps ## `need_pool` return a pool # Returns a new `Query` Constructs a new query object for querying the buffering status of a stream. Free-function: `gst_query_unref` ## `format` the default `Format` for the new query # Returns a new `Query` Constructs a new query object for querying the caps. The CAPS query should return the allowable caps for a pad in the context of the element's state, its link to other elements, and the devices or files it has opened. These caps must be a subset of the pad template caps. In the NULL state with no links, the CAPS query should ideally return the same caps as the pad template. In rare circumstances, an object property can affect the caps returned by the CAPS query, but this is discouraged. For most filters, the caps returned by CAPS query is directly affected by the allowed caps on other pads. For demuxers and decoders, the caps returned by the srcpad's getcaps function is directly related to the stream data. Again, the CAPS query should return the most specific caps it reasonably can, since this helps with autoplugging. The `filter` is used to restrict the result caps, only the caps matching `filter` should be returned from the CAPS query. Specifying a filter might greatly reduce the amount of processing an element needs to do. Free-function: `gst_query_unref` ## `filter` a filter # Returns a new `Query` Constructs a new query object for querying the pipeline-local context. Free-function: `gst_query_unref` ## `context_type` Context type to query # Returns a new `Query` Constructs a new convert query object. Use `gst_query_unref` when done with it. A convert query is used to ask for a conversion between one format and another. Free-function: `gst_query_unref` ## `src_format` the source `Format` for the new query ## `value` the value to convert ## `dest_format` the target `Format` # Returns a `Query` Constructs a new custom query object. Use `gst_query_unref` when done with it. Free-function: `gst_query_unref` ## `type_` the query type ## `structure` a structure for the query # Returns a new `Query` Constructs a new query object for querying the drain state. Free-function: `gst_query_unref` # Returns a new `Query` Constructs a new stream duration query object to query in the given format. Use `gst_query_unref` when done with it. A duration query will give the total length of the stream. Free-function: `gst_query_unref` ## `format` the `Format` for this duration query # Returns a new `Query` Constructs a new query object for querying formats of the stream. Free-function: `gst_query_unref` # Returns a new `Query` Constructs a new latency query object. Use `gst_query_unref` when done with it. A latency query is usually performed by sinks to compensate for additional latency introduced by elements in the pipeline. Free-function: `gst_query_unref` # Returns a `Query` Constructs a new query stream position query object. Use `gst_query_unref` when done with it. A position query is used to query the current position of playback in the streams, in some format. Free-function: `gst_query_unref` ## `format` the default `Format` for the new query # Returns a new `Query` Constructs a new query object for querying the scheduling properties. Free-function: `gst_query_unref` # Returns a new `Query` Constructs a new query object for querying seeking properties of the stream. Free-function: `gst_query_unref` ## `format` the default `Format` for the new query # Returns a new `Query` Constructs a new segment query object. Use `gst_query_unref` when done with it. A segment query is used to discover information about the currently configured segment for playback. Free-function: `gst_query_unref` ## `format` the `Format` for the new query # Returns a new `Query` Constructs a new query URI query object. Use `gst_query_unref` when done with it. An URI query is used to query the current URI that is used by the source or sink. Free-function: `gst_query_unref` # Returns a new `Query` Add `api` with `params` as one of the supported metadata API to `self`. ## `api` the metadata API ## `params` API specific parameters Add `allocator` and its `params` as a supported memory allocator. ## `allocator` the memory allocator ## `params` a `AllocationParams` Set the pool parameters in `self`. ## `pool` the `BufferPool` ## `size` the buffer size ## `min_buffers` the min buffers ## `max_buffers` the max buffers Set the buffering-ranges array field in `self`. The current last start position of the array should be inferior to `start`. ## `start` start position of the range ## `stop` stop position of the range # Returns a `gboolean` indicating if the range was added or not. Add `mode` as one of the supported scheduling modes to `self`. ## `mode` a `PadMode` Check if `self` has metadata `api` set. When this function returns `true`, `index` will contain the index where the requested API and the parameters can be found. ## `api` the metadata API ## `index` the index # Returns `true` when `api` is in the list of metadata. Retrieve the number of values currently stored in the meta API array of the query's structure. # Returns the metadata API array size as a `guint`. Retrieve the number of values currently stored in the allocator params array of the query's structure. If no memory allocator is specified, the downstream element can handle the default memory allocator. The first memory allocator in the query should be generic and allow mapping to system memory, all following allocators should be ordered by preference with the preferred one first. # Returns the allocator array size as a `guint`. Retrieve the number of values currently stored in the pool array of the query's structure. # Returns the pool array size as a `guint`. Retrieve the number of values currently stored in the buffered-ranges array of the query's structure. # Returns the range array size as a `guint`. Retrieve the number of values currently stored in the scheduling mode array of the query's structure. # Returns the scheduling mode array size as a `guint`. Get the structure of a query. # Returns the `Structure` of the query. The structure is still owned by the query and will therefore be freed when the query is unreffed. Check if `self` has scheduling mode set. > When checking if upstream supports pull mode, it is usually not > enough to just check for GST_PAD_MODE_PULL with this function, you > also want to check whether the scheduling flags returned by > `Query::parse_scheduling` have the seeking flag set (meaning > random access is supported, not only sequential pulls). ## `mode` the scheduling mode # Returns `true` when `mode` is in the list of scheduling modes. Check if `self` has scheduling mode set and `flags` is set in query scheduling flags. ## `mode` the scheduling mode ## `flags` `SchedulingFlags` # Returns `true` when `mode` is in the list of scheduling modes and `flags` are compatible with query flags. Get the caps from `self`. The caps remains valid as long as `self` remains valid. ## `caps` A pointer to the caps Parse the result from `self` and store in `result`. ## `result` location for the result Parse an allocation query, writing the requested caps in `caps` and whether a pool is needed in `need_pool`, if the respective parameters are non-`None`. Pool details can be retrieved using `Query::get_n_allocation_pools` and `Query::parse_nth_allocation_pool`. ## `caps` The `Caps` ## `need_pool` Whether a `BufferPool` is needed 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. ## `busy` if buffering is busy, or `None` ## `percent` a buffering percent, or `None` Parse an available query, writing the format into `format`, and other results into the passed parameters, if the respective parameters are non-`None` ## `format` the format to set for the `segment_start` and `segment_end` values, or `None` ## `start` the start to set, or `None` ## `stop` the stop to set, or `None` ## `estimated_total` estimated total amount of download time remaining in milliseconds, or `None` Extracts the buffering stats values from `self`. ## `mode` a buffering mode, or `None` ## `avg_in` the average input rate, or `None` ## `avg_out` the average output rat, or `None` ## `buffering_left` amount of buffering time left in milliseconds, or `None` Get the filter from the caps `self`. The caps remains valid as long as `self` remains valid. ## `filter` A pointer to the caps filter Get the caps result from `self`. The caps remains valid as long as `self` remains valid. ## `caps` A pointer to the caps Get the context from the context `self`. The context remains valid as long as `self` remains valid. ## `context` A pointer to store the `Context` Parse a context type from an existing GST_QUERY_CONTEXT query. ## `context_type` the context type, or `None` # Returns a `gboolean` indicating if the parsing succeeded. Parse a convert query answer. Any of `src_format`, `src_value`, `dest_format`, and `dest_value` may be `None`, in which case that value is omitted. ## `src_format` the storage for the `Format` of the source value, or `None` ## `src_value` the storage for the source value, or `None` ## `dest_format` the storage for the `Format` of the destination value, or `None` ## `dest_value` the storage for the destination value, or `None` Parse a duration query answer. Write the format of the duration into `format`, and the value into `duration`, if the respective variables are non-`None`. ## `format` the storage for the `Format` of the duration value, or `None`. ## `duration` the storage for the total duration, or `None`. Parse a latency query answer. ## `live` storage for live or `None` ## `min_latency` the storage for the min latency or `None` ## `max_latency` the storage for the max latency or `None` Parse the number of formats in the formats `self`. ## `n_formats` the number of formats in this query. Parse an available query and get the metadata API at `index` of the metadata API array. ## `index` position in the metadata API array to read ## `params` API specific parameters # Returns a `glib::Type` of the metadata API at `index`. Parse an available query and get the allocator and its params at `index` of the allocator array. ## `index` position in the allocator array to read ## `allocator` variable to hold the result ## `params` parameters for the allocator Get the pool parameters in `self`. Unref `pool` with `GstObjectExt::unref` when it's not needed any more. ## `index` index to parse ## `pool` the `BufferPool` ## `size` the buffer size ## `min_buffers` the min buffers ## `max_buffers` the max buffers Parse an available query and get the start and stop values stored at the `index` of the buffered ranges array. ## `index` position in the buffered-ranges array to read ## `start` the start position to set, or `None` ## `stop` the stop position to set, or `None` # Returns a `gboolean` indicating if the parsing succeeded. Parse the format query and retrieve the `nth` format from it into `format`. If the list contains less elements than `nth`, `format` will be set to GST_FORMAT_UNDEFINED. ## `nth` the nth format to retrieve. ## `format` a pointer to store the nth format Parse an available query and get the scheduling mode at `index` of the scheduling modes array. ## `index` position in the scheduling modes array to read # Returns a `PadMode` of the scheduling mode at `index`. Parse a position query, writing the format into `format`, and the position into `cur`, if the respective parameters are non-`None`. ## `format` the storage for the `Format` of the position values (may be `None`) ## `cur` the storage for the current position (may be `None`) Set the scheduling properties. ## `flags` `SchedulingFlags` ## `minsize` the suggested minimum size of pull requests ## `maxsize` the suggested maximum size of pull requests: ## `align` the suggested alignment of pull requests Parse a seeking query, writing the format into `format`, and other results into the passed parameters, if the respective parameters are non-`None` ## `format` the format to set for the `segment_start` and `segment_end` values, or `None` ## `seekable` the seekable flag to set, or `None` ## `segment_start` the segment_start to set, or `None` ## `segment_end` the segment_end to set, or `None` Parse a segment query answer. Any of `rate`, `format`, `start_value`, and `stop_value` may be `None`, which will cause this value to be omitted. See `Query::set_segment` for an explanation of the function arguments. ## `rate` the storage for the rate of the segment, or `None` ## `format` the storage for the `Format` of the values, or `None` ## `start_value` the storage for the start value, or `None` ## `stop_value` the storage for the stop value, or `None` Parse an URI query, writing the URI into `uri` as a newly allocated string, if the respective parameters are non-`None`. Free the string with `g_free` after usage. ## `uri` the storage for the current URI (may be `None`) Parse an URI query, writing the URI into `uri` as a newly allocated string, if the respective parameters are non-`None`. Free the string with `g_free` after usage. ## `uri` the storage for the redirect URI (may be `None`) Parse an URI query, and set `permanent` to `true` if there is a redirection and it should be considered permanent. If a redirection is permanent, applications should update their internal storage of the URI, otherwise they should make all future requests to the original URI. ## `permanent` if the URI redirection is permanent (may be `None`) Remove the metadata API at `index` of the metadata API array. ## `index` position in the metadata API array to remove Remove the allocation param at `index` of the allocation param array. ## `index` position in the allocation param array to remove Remove the allocation pool at `index` of the allocation pool array. ## `index` position in the allocation pool array to remove Set `result` as the result for the `self`. ## `result` the result to set 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. ## `busy` if buffering is busy ## `percent` a buffering percent Set the available query result fields in `self`. ## `format` the format to set for the `start` and `stop` values ## `start` the start to set ## `stop` the stop to set ## `estimated_total` estimated total amount of download time remaining in milliseconds Configures the buffering stats values in `self`. ## `mode` a buffering mode ## `avg_in` the average input rate ## `avg_out` the average output rate ## `buffering_left` amount of buffering time left in milliseconds Set the `caps` result in `self`. ## `caps` A pointer to the caps Answer a context query by setting the requested context. ## `context` the requested `Context` Answer a convert query by setting the requested values. ## `src_format` the source `Format` ## `src_value` the source value ## `dest_format` the destination `Format` ## `dest_value` the destination value Answer a duration query by setting the requested value in the given format. ## `format` the `Format` for the duration ## `duration` the duration of the stream Set the formats query result fields in `self`. The number of formats passed must be equal to `n_formats`. ## `n_formats` the number of formats to set. Set the formats query result fields in `self`. The number of formats passed in the `formats` array must be equal to `n_formats`. ## `n_formats` the number of formats to set. ## `formats` an array containing `n_formats` `Format` values. Answer a latency query by setting the requested values in the given format. ## `live` if there is a live element upstream ## `min_latency` the minimal latency of the upstream elements ## `max_latency` the maximal latency of the upstream elements Parse an available query and get the allocator and its params at `index` of the allocator array. ## `index` position in the allocator array to set ## `allocator` new allocator to set ## `params` parameters for the allocator Set the pool parameters in `self`. ## `index` index to modify ## `pool` the `BufferPool` ## `size` the buffer size ## `min_buffers` the min buffers ## `max_buffers` the max buffers Answer a position query by setting the requested value in the given format. ## `format` the requested `Format` ## `cur` the position to set Set the scheduling properties. ## `flags` `SchedulingFlags` ## `minsize` the suggested minimum size of pull requests ## `maxsize` the suggested maximum size of pull requests ## `align` the suggested alignment of pull requests Set the seeking query result fields in `self`. ## `format` the format to set for the `segment_start` and `segment_end` values ## `seekable` the seekable flag to set ## `segment_start` the segment_start to set ## `segment_end` the segment_end to set Answer a segment query by setting the requested values. The normal playback segment of a pipeline is 0 to duration at the default rate of 1.0. If a seek was performed on the pipeline to play a different segment, this query will return the range specified in the last seek. `start_value` and `stop_value` will respectively contain the configured playback range start and stop values expressed in `format`. The values are always between 0 and the duration of the media and `start_value` <= `stop_value`. `rate` will contain the playback rate. For negative rates, playback will actually happen from `stop_value` to `start_value`. ## `rate` the rate of the segment ## `format` the `Format` of the segment values (`start_value` and `stop_value`) ## `start_value` the start value ## `stop_value` the stop value Answer a URI query by setting the requested URI. ## `uri` the URI to set Answer a URI query by setting the requested URI redirection. ## `uri` the URI to set Answer a URI query by setting the requested URI redirection to permanent or not. ## `permanent` whether the redirect is permanent or not Get the structure of a query. This method should be called with a writable `self` so that the returned structure is guaranteed to be writable. # Returns the `Structure` of the query. The structure is still owned by the query and will therefore be freed when the query is unreffed. Element priority ranks. Defines the order in which the autoplugger (or similar rank-picking mechanisms, such as e.g. `Element::make_from_uri`) will choose this element over an alternative one with the same function. These constants serve as a rough guidance for defining the rank of a `PluginFeature`. Any value is valid, including values bigger than `Rank::Primary`. will be chosen last or not at all unlikely to be chosen likely to be chosen will be chosen first One registry holds the metadata of a set of plugins. Design:`` The `Registry` object is a list of plugins and some functions for dealing with them. Each `Plugin` is matched 1-1 with a file on disk, and may or may not be loaded at a given time. The primary source, at all times, of plugin information is each plugin file itself. Thus, if an application wants information about a particular plugin, or wants to search for a feature that satisfies given criteria, the primary means of doing so is to load every plugin and look at the resulting information that is gathered in the default registry. Clearly, this is a time consuming process, so we cache information in the registry file. The format and location of the cache file is internal to gstreamer. On startup, plugins are searched for in the plugin search path. The following locations are checked in this order: * location from --gst-plugin-path commandline option. * the GST_PLUGIN_PATH environment variable. * the GST_PLUGIN_SYSTEM_PATH environment variable. * default locations (if GST_PLUGIN_SYSTEM_PATH is not set). Those default locations are: `$XDG_DATA_HOME/gstreamer-$GST_API_VERSION/plugins/` and `$prefix/libs/gstreamer-$GST_API_VERSION/`. [$XDG_DATA_HOME](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) defaults to `$HOME/.local/share`. The registry cache file is loaded from `$XDG_CACHE_HOME/gstreamer-$GST_API_VERSION/registry-$ARCH.bin` (where $XDG_CACHE_HOME defaults to `$HOME/.cache`) or the file listed in the `GST_REGISTRY` env var. One reason to change the registry location is for testing. For each plugin that is found in the plugin search path, there could be 3 possibilities for cached information: * the cache may not contain information about a given file. * the cache may have stale information. * the cache may have current information. In the first two cases, the plugin is loaded and the cache updated. In addition to these cases, the cache may have entries for plugins that are not relevant to the current process. These are marked as not available to the current process. If the cache is updated for whatever reason, it is marked dirty. A dirty cache is written out at the end of initialization. Each entry is checked to make sure the information is minimally valid. If not, the entry is simply dropped. ## Implementation notes: The "cache" and "registry" are different concepts and can represent different sets of plugins. For various reasons, at init time, the cache is stored in the default registry, and plugins not relevant to the current process are marked with the `PluginFlags::Cached` bit. These plugins are removed at the end of initialization. # Implements [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) By default GStreamer will perform scanning and rebuilding of the registry file using a helper child process. Applications might want to disable this behaviour with the `Registry::fork_set_enabled` function, in which case new plugins are scanned (and loaded) into the application process. # Returns `true` if GStreamer will use the child helper process when rebuilding the registry. Applications might want to disable/enable spawning of a child helper process when rebuilding the registry. See `Registry::fork_is_enabled` for more information. ## `enabled` whether rebuilding the registry can use a temporary child helper process. Retrieves the singleton plugin registry. The caller does not own a reference on the registry, as it is alive as long as GStreamer is initialized. # Returns the `Registry`. Add the feature to the registry. The feature-added signal will be emitted. `feature`'s reference count will be incremented, and any floating reference will be removed (see `Object::ref_sink`) ## `feature` the feature to add # Returns `true` on success. MT safe. Add the plugin to the registry. The plugin-added signal will be emitted. `plugin`'s reference count will be incremented, and any floating reference will be removed (see `Object::ref_sink`) ## `plugin` the plugin to add # Returns `true` on success. MT safe. Checks whether a plugin feature by the given name exists in `self` and whether its version is at least the version required. ## `feature_name` the name of the feature (e.g. "oggdemux") ## `min_major` the minimum major version number ## `min_minor` the minimum minor version number ## `min_micro` the minimum micro version number # Returns `true` if the feature could be found and the version is the same as the required version or newer, and `false` otherwise. Runs a filter against all features of the plugins in the registry and returns a GList with the results. If the first flag is set, only the first match is returned (as a list with a single object). ## `filter` the filter to use ## `first` only return first match ## `user_data` user data passed to the filter function # Returns a `glib::List` of `PluginFeature`. Use `PluginFeature::list_free` after usage. MT safe. Find the pluginfeature with the given name and type in the registry. ## `name` the pluginfeature name to find ## `type_` the pluginfeature type to find # Returns the pluginfeature with the given name and type or `None` if the plugin was not found. `GstObjectExt::unref` after usage. MT safe. Find the plugin with the given name in the registry. The plugin will be reffed; caller is responsible for unreffing. ## `name` the plugin name to find # Returns the plugin with the given name or `None` if the plugin was not found. `GstObjectExt::unref` after usage. MT safe. Retrieves a `glib::List` of `PluginFeature` of `type_`. ## `type_` a `glib::Type`. # Returns a `glib::List` of `PluginFeature` of `type_`. Use `PluginFeature::list_free` after use MT safe. Retrieves a `glib::List` of features of the plugin with name `name`. ## `name` a plugin name. # Returns a `glib::List` of `PluginFeature`. Use `PluginFeature::list_free` after usage. Returns the registry's feature list cookie. This changes every time a feature is added or removed from the registry. # Returns the feature list cookie. Get a copy of all plugins registered in the given registry. The refcount of each element in the list in incremented. # Returns a `glib::List` of `Plugin`. Use `Plugin::list_free` after usage. MT safe. Look up a plugin in the given registry with the given filename. If found, plugin is reffed. ## `filename` the name of the file to look up # Returns the `Plugin` if found, or `None` if not. `GstObjectExt::unref` after usage. Find a `PluginFeature` with `name` in `self`. ## `name` a `PluginFeature` name # Returns a `PluginFeature` with its refcount incremented, use `GstObjectExt::unref` after usage. MT safe. Runs a filter against all plugins in the registry and returns a `glib::List` with the results. If the first flag is set, only the first match is returned (as a list with a single object). Every plugin is reffed; use `Plugin::list_free` after use, which will unref again. ## `filter` the filter to use ## `first` only return first match ## `user_data` user data passed to the filter function # Returns a `glib::List` of `Plugin`. Use `Plugin::list_free` after usage. MT safe. Remove the feature from the registry. MT safe. ## `feature` the feature to remove Remove the plugin from the registry. MT safe. ## `plugin` the plugin to remove Scan the given path for plugins to add to the registry. The syntax of the path is specific to the registry. ## `path` the path to scan # Returns `true` if registry changed Signals that a feature has been added to the registry (possibly replacing a previously-added one by the same name) ## `feature` the feature that has been added Signals that a plugin has been added to the registry (possibly replacing a previously-added one by the same name) ## `plugin` the plugin that has been added Resource errors are for any resource used by an element: memory, files, network connections, process space, ... They're typically used by source and sink elements. a general error which doesn't fit in any other category. Make sure you add a custom message to the error call. do not use this except as a placeholder for deciding where to go while developing code. used when the resource could not be found. used when resource is busy. used when resource fails to open for reading. used when resource fails to open for writing. used when resource cannot be opened for both reading and writing, or either (but unspecified which). used when the resource can't be closed. used when the resource can't be read from. used when the resource can't be written to. used when a seek on the resource fails. used when a synchronize on the resource fails. used when settings can't be manipulated on. used when the resource has no space left. used when the resource can't be opened due to missing authorization. (Since 1.2.4) the number of resource error types. A `Sample` is a small object containing data, a type, timing and extra arbitrary information. Create a new `Sample` with the provided details. Free-function: gst_sample_unref ## `buffer` a `Buffer`, or `None` ## `caps` a `Caps`, or `None` ## `segment` a `Segment`, or `None` ## `info` a `Structure`, or `None` # Returns the new `Sample`. `gst_sample_unref` after usage. Get the buffer associated with `self` # Returns the buffer of `self` or `None` when there is no buffer. The buffer remains valid as long as `self` is valid. If you need to hold on to it for longer than that, take a ref to the buffer with `gst_buffer_ref`. Get the buffer list associated with `self` # Returns the buffer list of `self` or `None` when there is no buffer list. The buffer list remains valid as long as `self` is valid. If you need to hold on to it for longer than that, take a ref to the buffer list with gst_mini_object_ref (). Get the caps associated with `self` # Returns the caps of `self` or `None` when there is no caps. The caps remain valid as long as `self` is valid. If you need to hold on to the caps for longer than that, take a ref to the caps with `gst_caps_ref`. Get extra information associated with `self`. # Returns the extra info of `self`. The info remains valid as long as `self` is valid. Get the segment associated with `self` # Returns the segment of `self`. The segment remains valid as long as `self` is valid. Set the buffer list associated with `self` ## `buffer_list` a `BufferList` The different types of seek events. When constructing a seek event with `Event::new_seek` or when doing gst_segment_do_seek (). no change in position is required absolute position is requested relative position to duration is requested This helper structure holds the relevant values for tracking the region of interest in a media file, called a segment. The structure can be used for two purposes: * performing seeks (handling seek events) * tracking playback regions (handling newsegment events) The segment is usually configured by the application with a seek event which is propagated upstream and eventually handled by an element that performs the seek. The configured segment is then propagated back downstream with a newsegment event. This information is then used to clip media to the segment boundaries. A segment structure is initialized with `Segment::init`, which takes a `Format` that will be used as the format of the segment values. The segment will be configured with a start value of 0 and a stop/duration of -1, which is undefined. The default rate and applied_rate is 1.0. The public duration field contains the duration of the segment. When using the segment for seeking, the start and time members should normally be left to their default 0 value. The stop position is left to -1 unless explicitly configured to a different value after a seek event. The current position in the segment should be set by changing the position member in the structure. For elements that perform seeks, the current segment should be updated with the `Segment::do_seek` and the values from the seek event. This method will update all the segment fields. The position field will contain the new playback position. If the start_type was different from GST_SEEK_TYPE_NONE, playback continues from the position position, possibly with updated flags or rate. For elements that want to use `Segment` to track the playback region, update the segment fields with the information from the newsegment event. The `Segment::clip` method can be used to check and clip the media data to the segment boundaries. For elements that want to synchronize to the pipeline clock, `Segment::to_running_time` can be used to convert a timestamp to a value that can be used to synchronize to the clock. This function takes into account the base as well as any rate or applied_rate conversions. For elements that need to perform operations on media data in stream_time, `Segment::to_stream_time` can be used to convert a timestamp and the segment info to stream time (which is always between 0 and the duration of the stream). Allocate a new `Segment` structure and initialize it using `Segment::init`. Free-function: gst_segment_free # Returns a new `Segment`, free with `Segment::free`. Clip the given `start` and `stop` values to the segment boundaries given in `self`. `start` and `stop` are compared and clipped to `self` start and stop values. If the function returns `false`, `start` and `stop` are known to fall outside of `self` and `clip_start` and `clip_stop` are not updated. When the function returns `true`, `clip_start` and `clip_stop` will be updated. If `clip_start` or `clip_stop` are different from `start` or `stop` respectively, the region fell partially in the segment. Note that when `stop` is -1, `clip_stop` will be set to the end of the segment. Depending on the use case, this may or may not be what you want. ## `format` the format of the segment. ## `start` the start position in the segment ## `stop` the stop position in the segment ## `clip_start` the clipped start position in the segment ## `clip_stop` the clipped stop position in the segment # Returns `true` if the given `start` and `stop` times fall partially or completely in `self`, `false` if the values are completely outside of the segment. Create a copy of given `self`. Free-function: gst_segment_free # Returns a new `Segment`, free with `Segment::free`. Copy the contents of `self` into `dest`. ## `dest` a `Segment` Update the segment structure with the field values of a seek event (see `Event::new_seek`). After calling this method, the segment field position and time will contain the requested new position in the segment. The new requested position in the segment depends on `rate` and `start_type` and `stop_type`. For positive `rate`, the new position in the segment is the new `self` start field when it was updated with a `start_type` different from `SeekType::None`. If no update was performed on `self` start position (`SeekType::None`), `start` is ignored and `self` position is unmodified. For negative `rate`, the new position in the segment is the new `self` stop field when it was updated with a `stop_type` different from `SeekType::None`. If no stop was previously configured in the segment, the duration of the segment will be used to update the stop position. If no update was performed on `self` stop position (`SeekType::None`), `stop` is ignored and `self` position is unmodified. The applied rate of the segment will be set to 1.0 by default. If the caller can apply a rate change, it should update `self` rate and applied_rate after calling this function. `update` will be set to `true` if a seek should be performed to the segment position field. This field can be `false` if, for example, only the `rate` has been changed but not the playback position. ## `rate` the rate of the segment. ## `format` the format of the segment. ## `flags` the segment flags for the segment ## `start_type` the seek method ## `start` the seek start value ## `stop_type` the seek method ## `stop` the seek stop value ## `update` boolean holding whether position was updated. # Returns `true` if the seek could be performed. Free the allocated segment `self`. The start/position fields are set to 0 and the stop/duration fields are set to -1 (unknown). The default rate of 1.0 and no flags are set. Initialize `self` to its default values. ## `format` the format of the segment. Checks for two segments being equal. Equality here is defined as perfect equality, including floating point values. ## `s1` a `Segment` structure. # Returns `true` if the segments are equal, `false` otherwise. Adjust the values in `self` so that `offset` is applied to all future running-time calculations. ## `format` the format of the segment. ## `offset` the offset to apply in the segment # Returns `true` if the segment could be updated successfully. If `false` is returned, `offset` is not in `self`. Convert `running_time` into a position in the segment so that `Segment::to_running_time` with that position returns `running_time`. ## `format` the format of the segment. ## `running_time` the running_time in the segment # Returns the position in the segment for `running_time`. This function returns -1 when `running_time` is -1 or when it is not inside `self`. Translate `running_time` to the segment position using the currently configured segment. Compared to `Segment::position_from_running_time` this function can return negative segment position. This function is typically used by elements that need to synchronize buffers against the clock or each other. `running_time` can be any value and the result of this function for values outside of the segment is extrapolated. When 1 is returned, `running_time` resulted in a positive position returned in `position`. When this function returns -1, the returned `position` should be negated to get the real negative segment position. ## `format` the format of the segment. ## `running_time` the running-time ## `position` the resulting position in the segment # Returns a 1 or -1 on success, 0 on failure. Convert `stream_time` into a position in the segment so that `Segment::to_stream_time` with that position returns `stream_time`. ## `format` the format of the segment. ## `stream_time` the stream_time in the segment # Returns the position in the segment for `stream_time`. This function returns -1 when `stream_time` is -1 or when it is not inside `self`. Translate `stream_time` to the segment position using the currently configured segment. Compared to `Segment::position_from_stream_time` this function can return negative segment position. This function is typically used by elements that need to synchronize buffers against the clock or each other. `stream_time` can be any value and the result of this function for values outside of the segment is extrapolated. When 1 is returned, `stream_time` resulted in a positive position returned in `position`. When this function returns -1, the returned `position` should be negated to get the real negative segment position. ## `format` the format of the segment. ## `stream_time` the stream-time ## `position` the resulting position in the segment # Returns a 1 or -1 on success, 0 on failure. Adjust the start/stop and base values of `self` such that the next valid buffer will be one with `running_time`. ## `format` the format of the segment. ## `running_time` the running_time in the segment # Returns `true` if the segment could be updated successfully. If `false` is returned, `running_time` is -1 or not in `self`. Convert `running_time` into a position in the segment so that `Segment::to_running_time` with that position returns `running_time`. # Deprecated Use `Segment::position_from_running_time` instead. ## `format` the format of the segment. ## `running_time` the running_time in the segment # Returns the position in the segment for `running_time`. This function returns -1 when `running_time` is -1 or when it is not inside `self`. Translate `position` to the total running time using the currently configured segment. Position is a value between `self` start and stop time. This function is typically used by elements that need to synchronize to the global clock in a pipeline. The running time is a constantly increasing value starting from 0. When `Segment::init` is called, this value will reset to 0. This function returns -1 if the position is outside of `self` start and stop. ## `format` the format of the segment. ## `position` the position in the segment # Returns the position as the total running time or -1 when an invalid position was given. Translate `position` to the total running time using the currently configured 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. `position` can be any value and the result of this function for values outside of the segment is extrapolated. When 1 is returned, `position` resulted in a positive running-time returned in `running_time`. When this function returns -1, the returned `running_time` should be negated to get the real negative running time. ## `format` the format of the segment. ## `position` the position in the segment ## `running_time` result running-time # Returns a 1 or -1 on success, 0 on failure. Translate `position` to stream time using the currently configured segment. The `position` value must be between `self` start and stop value. This function is typically used by elements that need to operate on the stream time of the buffers it receives, such as effect plugins. In those use cases, `position` is typically the buffer timestamp or clock time that one wants to convert to the stream time. The stream time is always between 0 and the total duration of the media stream. ## `format` the format of the segment. ## `position` the position in the segment # Returns the position in stream_time or -1 when an invalid position was given. Translate `position` to the total stream time using the currently configured 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. `position` can be any value and the result of this function for values outside of the segment is extrapolated. When 1 is returned, `position` resulted in a positive stream-time returned in `stream_time`. When this function returns -1, the returned `stream_time` should be negated to get the real negative stream time. ## `format` the format of the segment. ## `position` the position in the segment ## `stream_time` result stream-time # Returns a 1 or -1 on success, 0 on failure. The possible states an element can be in. States can be changed using `ElementExt::set_state` and checked using `ElementExt::get_state`. no pending state. the NULL state or initial state of an element. the element is ready to go to PAUSED. the element is PAUSED, it is ready to accept and process data. Sink elements however only accept one buffer and then block. the element is PLAYING, the `Clock` is running and the data is flowing. These are the different state changes an element goes through. `State::Null` ⇒ `State::Playing` is called an upwards state change and `State::Playing` ⇒ `State::Null` a downwards state change. state change from NULL to READY. * The element must check if the resources it needs are available. Device sinks and -sources typically try to probe the device to constrain their caps. * The element opens the device (in case feature need to be probed). state change from READY to PAUSED. * The element pads are activated in order to receive data in PAUSED. Streaming threads are started. * Some elements might need to return `StateChangeReturn::Async` and complete the state change when they have enough information. It is a requirement for sinks to return `StateChangeReturn::Async` and complete the state change when they receive the first buffer or `EventType::Eos` (preroll). Sinks also block the dataflow when in PAUSED. * A pipeline resets the running_time to 0. * Live sources return `StateChangeReturn::NoPreroll` and don't generate data. state change from PAUSED to PLAYING. * Most elements ignore this state change. * The pipeline selects a `Clock` and distributes this to all the children before setting them to PLAYING. This means that it is only allowed to synchronize on the `Clock` in the PLAYING state. * The pipeline uses the `Clock` and the running_time to calculate the base_time. The base_time is distributed to all children when performing the state change. * Sink elements stop blocking on the preroll buffer or event and start rendering the data. * Sinks can post `MessageType::Eos` in the PLAYING state. It is not allowed to post `MessageType::Eos` when not in the PLAYING state. * While streaming in PAUSED or PLAYING elements can create and remove sometimes pads. * Live sources start generating data and return `StateChangeReturn::Success`. state change from PLAYING to PAUSED. * Most elements ignore this state change. * The pipeline calculates the running_time based on the last selected `Clock` and the base_time. It stores this information to continue playback when going back to the PLAYING state. * Sinks unblock any `Clock` wait calls. * When a sink does not have a pending buffer to play, it returns `StateChangeReturn::Async` from this state change and completes the state change when it receives a new buffer or an `EventType::Eos`. * Any queued `MessageType::Eos` items are removed since they will be reposted when going back to the PLAYING state. The EOS messages are queued in `Bin` containers. * Live sources stop generating data and return `StateChangeReturn::NoPreroll`. state change from PAUSED to READY. * Sinks unblock any waits in the preroll. * Elements unblock any waits on devices * Chain or get_range functions return `FlowReturn::Flushing`. * The element pads are deactivated so that streaming becomes impossible and all streaming threads are stopped. * The sink forgets all negotiated formats * Elements remove all sometimes pads 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 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) 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) state change from PLAYING to PLAYING. (Since 1.14) The possible return values from a state change function such as `ElementExt::set_state`. Only `StateChangeReturn::Failure` is a real failure. the state change failed the state change succeeded the state change will happen asynchronously the state change succeeded but the element cannot produce data in `State::Paused`. This typically happens with live sources. Datastructure to initialize `Caps` from a string description usually used in conjunction with GST_STATIC_CAPS() and `StaticCaps::get` to instantiate a `Caps`. Clean up the cached caps contained in `self`. Converts a `StaticCaps` to a `Caps`. # Returns a pointer to the `Caps`. Unref after usage. Since the core holds an additional ref to the returned caps, use `gst_caps_make_writable` on the returned caps to modify it. Structure describing the `StaticPadTemplate`. Converts a `StaticPadTemplate` into a `PadTemplate`. # Returns a new `PadTemplate`. Gets the capabilities of the static pad template. # Returns the `Caps` of the static pad template. Unref after usage. Since the core holds an additional ref to the returned caps, use `gst_caps_make_writable` on the returned caps to modify it. A high-level object representing a single stream. It might be backed, or not, by an actual flow of data in a pipeline (`Pad`). A `Stream` does not care about data changes (such as decoding, encoding, parsing,...) as long as the underlying data flow corresponds to the same high-level flow (ex: a certain audio track). A `Stream` contains all the information pertinent to a stream, such as stream-id, tags, caps, type, ... Elements can subclass a `Stream` for internal usage (to contain information pertinent to streams of data). Feature: `v1_10` # Implements [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Create a new `Stream` for the given `stream_id`, `caps`, `type_` and `flags` Feature: `v1_10` ## `stream_id` the id for the new stream. If `None`, a new one will be automatically generated ## `caps` the `Caps` of the stream ## `type_` the `StreamType` of the stream ## `flags` the `StreamFlags` of the stream # Returns The new `Stream` Retrieve the caps for `self`, if any Feature: `v1_10` # Returns The `Caps` for `self` Retrieve the current stream flags for `self` Feature: `v1_10` # Returns The `StreamFlags` for `self` Returns the stream ID of `self`. Feature: `v1_10` # Returns the stream ID of `self`. Only valid during the lifetime of `self`. Retrieve the stream type for `self` Feature: `v1_10` # Returns The `StreamType` for `self` Retrieve the tags for `self`, if any Feature: `v1_10` # Returns The `TagList` for `self` Set the caps for the `Stream` Feature: `v1_10` ## `caps` a `Caps` Set the `flags` for the `self`. Feature: `v1_10` ## `flags` the flags to set on `self` Set the stream type of `self` Feature: `v1_10` ## `stream_type` the type to set on `self` Set the tags for the `Stream` Feature: `v1_10` ## `tags` a `TagList` The `Caps` of the `Stream`. The `Caps` of the `Stream`. The unique identifier of the `Stream`. Can only be set at construction time. The unique identifier of the `Stream`. Can only be set at construction time. The `StreamType` of the `Stream`. Can only be set at construction time. The `StreamType` of the `Stream`. Can only be set at construction time. The `TagList` of the `Stream`. The `TagList` of the `Stream`. A collection of `Stream` that are available. A `StreamCollection` will be provided by elements that can make those streams available. Applications can use the collection to show the user what streams are available by using `StreamCollection::get_stream`() Once posted, a `StreamCollection` is immutable. Updates are made by sending a new `StreamCollection` message, which may or may not share some of the `Stream` objects from the collection it replaces. The receiver can check the sender of a stream collection message to know which collection is obsoleted. Several elements in a pipeline can provide `StreamCollection`. Applications can activate streams from a collection by using the `EventType::SelectStreams` event on a pipeline, bin or element. Feature: `v1_10` # Implements [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Create a new `StreamCollection`. Feature: `v1_10` ## `upstream_id` The stream id of the parent stream # Returns The new `StreamCollection`. Add the given `stream` to the `self`. Feature: `v1_10` ## `stream` the `Stream` to add # Returns `true` if the `stream` was properly added, else `false` Get the number of streams this collection contains Feature: `v1_10` # Returns The number of streams that `self` contains Retrieve the `Stream` with index `index` from the collection. The caller should not modify the returned `Stream` Feature: `v1_10` ## `index` Index of the stream to retrieve # Returns A `Stream` Returns the upstream id of the `self`. Feature: `v1_10` # Returns The upstream id Stream errors are for anything related to the stream being processed: format errors, media type errors, ... They're typically used by decoders, demuxers, converters, ... a general error which doesn't fit in any other category. Make sure you add a custom message to the error call. do not use this except as a placeholder for deciding where to go while developing code. use this when you do not want to implement this functionality yet. used when the element doesn't know the stream's type. used when the element doesn't handle this type of stream. used when there's no codec to handle the stream's type. used when decoding fails. used when encoding fails. used when demuxing fails. used when muxing fails. used when the stream is of the wrong format (for example, wrong caps). used when the stream is encrypted and can't be decrypted because this is not supported by the element. used when the stream is encrypted and can't be decrypted because no suitable key is available. the number of stream error types. The type of a `MessageType::StreamStatus`. The stream status messages inform the application of new streaming threads and their status. A new thread need to be created. a thread entered its loop function a thread left its loop function a thread is destroyed a thread is started a thread is paused a thread is stopped A `Structure` is a collection of key/value pairs. The keys are expressed as GQuarks and the values can be of any GType. In addition to the key/value pairs, a `Structure` also has a name. The name starts with a letter and can be filled by letters, numbers and any of "/-_.:". `Structure` is used by various GStreamer subsystems to store information in a flexible and extensible way. A `Structure` does not have a refcount because it usually is part of a higher level object such as `Caps`, `Message`, `Event`, `Query`. It provides a means to enforce mutability using the refcount of the parent with the `Structure::set_parent_refcount` method. A `Structure` can be created with `Structure::new_empty` or `Structure::new`, which both take a name and an optional set of key/value pairs along with the types of the values. Field values can be changed with `Structure::set_value` or `Structure::set`. Field values can be retrieved with `Structure::get_value` or the more convenient gst_structure_get_*() functions. Fields can be removed with `Structure::remove_field` or `Structure::remove_fields`. Strings in structures must be ASCII or UTF-8 encoded. Other encodings are not allowed. Strings may be `None` however. Be aware that the current `Caps` / `Structure` serialization into string has limited support for nested `Caps` / `Structure` fields. It can only support one level of nesting. Using more levels will lead to unexpected behavior when using serialization features, such as `Caps::to_string` or `gst_value_serialize` and their counterparts. Creates a new `Structure` with the given name. Parses the list of variable arguments and sets fields to the values listed. Variable arguments should be passed as field name, field type, and value. Last variable argument should be `None`. Free-function: gst_structure_free ## `name` name of new structure ## `firstfield` name of first field to set # Returns a new `Structure` Creates a new, empty `Structure` with the given `name`. See `Structure::set_name` for constraints on the `name` parameter. Free-function: gst_structure_free ## `name` name of new structure # Returns a new, empty `Structure` Creates a `Structure` from a string representation. If end is not `None`, a pointer to the place inside the given string where parsing ended will be returned. The current implementation of serialization will lead to unexpected results when there are nested `Caps` / `Structure` deeper than one level. Free-function: gst_structure_free ## `string` a string representation of a `Structure` # Returns a new `Structure` or `None` when the string could not be parsed. Free with `Structure::free` after use. Creates a new `Structure` with the given name as a GQuark, followed by fieldname quark, GType, argument(s) "triplets" in the same format as `Structure::id_set`. Basically a convenience wrapper around `Structure::new_id_empty` and `Structure::id_set`. The last variable argument must be `None` (or 0). Free-function: gst_structure_free ## `name_quark` name of new structure ## `field_quark` the GQuark for the name of the field to set # Returns a new `Structure` Creates a new, empty `Structure` with the given name as a GQuark. Free-function: gst_structure_free ## `quark` name of new structure # Returns a new, empty `Structure` Creates a new `Structure` with the given `name`. Structure fields are set according to the varargs in a manner similar to `Structure::new`. See `Structure::set_name` for constraints on the `name` parameter. Free-function: gst_structure_free ## `name` name of new structure ## `firstfield` name of first field to set ## `varargs` variable argument list # Returns a new `Structure` Tries intersecting `self` and `struct2` and reports whether the result would not be empty. ## `struct2` a `Structure` # Returns `true` if intersection would not be empty Duplicates a `Structure` and all its fields and values. Free-function: gst_structure_free # Returns a new `Structure`. Calls the provided function once for each field in the `Structure`. In contrast to `Structure::foreach`, the function may modify the fields. In contrast to `Structure::map_in_place`, the field is removed from the structure if `false` is returned from the function. The structure must be mutable. ## `func` a function to call for each field ## `user_data` private data Fixate all values in `self` using `gst_value_fixate`. `self` will be modified in-place and should be writable. Fixates a `Structure` by changing the given field with its fixated value. ## `field_name` a field in `self` # Returns `true` if the structure field could be fixated Fixates a `Structure` by changing the given `field_name` field to the given `target` boolean if that field is not fixed yet. ## `field_name` a field in `self` ## `target` the target value of the fixation # Returns `true` if the structure could be fixated Fixates a `Structure` by changing the given field to the nearest double to `target` that is a subset of the existing field. ## `field_name` a field in `self` ## `target` the target value of the fixation # Returns `true` if the structure could be fixated Fixates a `Structure` by changing the given field to the nearest fraction to `target_numerator`/`target_denominator` that is a subset of the existing field. ## `field_name` a field in `self` ## `target_numerator` The numerator of the target value of the fixation ## `target_denominator` The denominator of the target value of the fixation # Returns `true` if the structure could be fixated Fixates a `Structure` by changing the given field to the nearest integer to `target` that is a subset of the existing field. ## `field_name` a field in `self` ## `target` the target value of the fixation # Returns `true` if the structure could be fixated Fixates a `Structure` by changing the given `field_name` field to the given `target` string if that field is not fixed yet. ## `field_name` a field in `self` ## `target` the target value of the fixation # Returns `true` if the structure could be fixated Calls the provided function once for each field in the `Structure`. The function must not modify the fields. Also see `Structure::map_in_place` and `Structure::filter_and_map_in_place`. ## `func` a function to call for each field ## `user_data` private data # Returns `true` if the supplied function returns `true` For each of the fields, `false` otherwise. Frees a `Structure` and all its fields and values. The structure must not have a parent when this function is called. Parses the variable arguments and reads fields from `self` accordingly. Variable arguments should be in the form field name, field type (as a GType), pointer(s) to a variable(s) to hold the return value(s). The last variable argument should be `None`. For refcounted (mini)objects you will receive a new reference which you must release with a suitable `_unref` when no longer needed. For strings and boxed types you will receive a copy which you will need to release with either `g_free` or the suitable function for the boxed type. ## `first_fieldname` the name of the first field to read # Returns `false` if there was a problem reading any of the fields (e.g. because the field requested did not exist, or was of a type other 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. ## `fieldname` the name of a field ## `array` 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`. Sets the boolean pointed to by `value` corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type. ## `fieldname` the name of a field ## `value` a pointer to a `gboolean` to set # Returns `true` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain a boolean, this function returns `false`. Sets the clock time pointed to by `value` corresponding to the clock time of the given field. Caller is responsible for making sure the field exists and has the correct type. ## `fieldname` the name of a field ## `value` a pointer to a `ClockTime` to set # Returns `true` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain a `ClockTime`, this function returns `false`. Sets the date pointed to by `value` corresponding to the date of the given field. Caller is responsible for making sure the field exists and has the correct type. On success `value` will point to a newly-allocated copy of the date which should be freed with `glib::Date::free` when no longer needed (note: this is inconsistent with e.g. `Structure::get_string` which doesn't return a copy of the string). ## `fieldname` the name of a field ## `value` a pointer to a `glib::Date` to set # Returns `true` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain a data, this function returns `false`. Sets the datetime pointed to by `value` corresponding to the datetime of the given field. Caller is responsible for making sure the field exists and has the correct type. On success `value` will point to a reference of the datetime which should be unreffed with `DateTime::unref` when no longer needed (note: this is inconsistent with e.g. `Structure::get_string` which doesn't return a copy of the string). ## `fieldname` the name of a field ## `value` a pointer to a `DateTime` to set # Returns `true` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain a data, this function returns `false`. Sets the double pointed to by `value` corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type. ## `fieldname` the name of a field ## `value` a pointer to a gdouble to set # Returns `true` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain a double, this function returns `false`. Sets the int pointed to by `value` corresponding to the value of the given field. Caller is responsible for making sure the field exists, has the correct type and that the enumtype is correct. ## `fieldname` the name of a field ## `enumtype` the enum type of a field ## `value` a pointer to an int to set # Returns `true` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain an enum of the given type, this function returns `false`. Finds the field with the given name, and returns the type of the value it contains. If the field is not found, G_TYPE_INVALID is returned. ## `fieldname` the name of the field # Returns the `gobject::Value` of the field Read the GstFlagSet flags and mask out of the structure into the provided pointers. ## `fieldname` the name of a field ## `value_flags` a pointer to a guint for the flags field ## `value_mask` a pointer to a guint for the mask field # Returns `true` if the values could be set correctly. If there was no field with `fieldname` or the existing field did not contain a GstFlagSet, this function returns `false`. Sets the integers pointed to by `value_numerator` and `value_denominator` corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type. ## `fieldname` the name of a field ## `value_numerator` a pointer to an int to set ## `value_denominator` a pointer to an int to set # Returns `true` if the values could be set correctly. If there was no field with `fieldname` or the existing field did not contain a GstFraction, this function returns `false`. Sets the int pointed to by `value` corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type. ## `fieldname` the name of a field ## `value` a pointer to an int to set # 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`. Sets the `gint64` pointed to by `value` corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type. ## `fieldname` the name of a field ## `value` a pointer to a `gint64` to set # Returns `true` if the value could be set correctly. If there was no field 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. ## `fieldname` the name of a field ## `array` 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 Get the name of `self` as a string. # Returns the name of the structure. Get the name of `self` as a GQuark. # Returns the quark representing the name of the structure. Finds the field corresponding to `fieldname`, and returns the string contained in the field's value. Caller is responsible for making sure the field exists and has the correct type. The string should not be modified, and remains valid until the next call to a gst_structure_*() function with the given structure. ## `fieldname` the name of a field # Returns a pointer to the string or `None` when the field did not exist or did not contain a string. Sets the uint pointed to by `value` corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type. ## `fieldname` the name of a field ## `value` a pointer to a uint to set # Returns `true` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain a uint, this function returns `false`. Sets the `guint64` pointed to by `value` corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type. ## `fieldname` the name of a field ## `value` a pointer to a `guint64` to set # Returns `true` if the value could be set correctly. If there was no field with `fieldname` or the existing field did not contain a `guint64`, this function returns `false`. Parses the variable arguments and reads fields from `self` accordingly. valist-variant of `Structure::get`. Look at the documentation of `Structure::get` for more details. ## `first_fieldname` the name of the first field to read ## `args` variable arguments # Returns `true`, or `false` if there was a problem reading any of the fields Get the value of the field with name `fieldname`. ## `fieldname` the name of the field to get # Returns the `gobject::Value` corresponding to the field with the given name. Check if `self` contains a field named `fieldname`. ## `fieldname` the name of a field # Returns `true` if the structure contains a field with the given name Check if `self` contains a field named `fieldname` and with GType `type_`. ## `fieldname` the name of a field ## `type_` the type of a value # Returns `true` if the structure contains a field with the given name and type Checks if the structure has the given name ## `name` structure name to check for # Returns `true` if `name` matches the name of the structure. Parses the variable arguments and reads fields from `self` accordingly. Variable arguments should be in the form field id quark, field type (as a GType), pointer(s) to a variable(s) to hold the return value(s). The last variable argument should be `None` (technically it should be a 0 quark, but we require `None` so compilers that support it can check for the `None` terminator and warn if it's not there). This function is just like `Structure::get` only that it is slightly more efficient since it saves the string-to-quark lookup in the global quark hashtable. For refcounted (mini)objects you will receive a new reference which you must release with a suitable `_unref` when no longer needed. For strings and boxed types you will receive a copy which you will need to release with either `g_free` or the suitable function for the boxed type. ## `first_field_id` the quark of the first field to read # Returns `false` if there was a problem reading any of the fields (e.g. because the field requested did not exist, or was of a type other than the type specified), otherwise `true`. Parses the variable arguments and reads fields from `self` accordingly. valist-variant of `Structure::id_get`. Look at the documentation of `Structure::id_get` for more details. ## `first_field_id` the quark of the first field to read ## `args` variable arguments # Returns `true`, or `false` if there was a problem reading any of the fields Get the value of the field with GQuark `field`. ## `field` the `glib::Quark` of the field to get # Returns the `gobject::Value` corresponding to the field with the given name identifier. Check if `self` contains a field named `field`. ## `field` `glib::Quark` of the field name # Returns `true` if the structure contains a field with the given name Check if `self` contains a field named `field` and with GType `type_`. ## `field` `glib::Quark` of the field name ## `type_` the type of a value # Returns `true` if the structure contains a field with the given name and type Identical to gst_structure_set, except that field names are passed using the GQuark for the field name. This allows more efficient setting of the structure if the caller already knows the associated quark values. The last variable argument must be `None`. ## `fieldname` the GQuark for the name of the field to set va_list form of `Structure::id_set`. ## `fieldname` the name of the field to set ## `varargs` variable arguments Sets the field with the given GQuark `field` to `value`. If the field does not exist, it is created. If the field exists, the previous value is replaced and freed. ## `field` a `glib::Quark` representing a field ## `value` the new value of the field Sets the field with the given GQuark `field` to `value`. If the field does not exist, it is created. If the field exists, the previous value is replaced and freed. ## `field` a `glib::Quark` representing a field ## `value` the new value of the field Intersects `self` and `struct2` and returns the intersection. ## `struct2` a `Structure` # Returns Intersection of `self` and `struct2` Tests if the two `Structure` are equal. ## `structure2` a `Structure`. # Returns `true` if the two structures have the same name and field. Checks if `self` is a subset of `superset`, i.e. has the same structure name and for all fields that are existing in `superset`, `self` has a value that is a subset of the value in `superset`. ## `superset` a potentially greater `Structure` # Returns `true` if `self` is a subset of `superset` Calls the provided function once for each field in the `Structure`. In contrast to `Structure::foreach`, the function may modify but not delete the fields. The structure must be mutable. ## `func` a function to call for each field ## `user_data` private data # Returns `true` if the supplied function returns `true` For each of the fields, `false` otherwise. Get the number of fields in the structure. # Returns the number of fields in the structure Get the name of the given field number, counting from 0 onwards. ## `index` the index to get the name of # Returns the name of the given field number Removes all fields in a GstStructure. Removes the field with the given name. If the field with the given name does not exist, the structure is unchanged. ## `fieldname` the name of the field to remove Removes the fields with the given names. If a field does not exist, the argument is ignored. ## `fieldname` the name of the field to remove va_list form of `Structure::remove_fields`. ## `fieldname` the name of the field to remove ## `varargs` `None`-terminated list of more fieldnames to remove Parses the variable arguments and sets fields accordingly. Fields that weren't already part of the structure are added as needed. Variable arguments should be in the form field name, field type (as a GType), value(s). The last variable argument should be `None`. ## `fieldname` the name of the field to set 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 the field specified by `fieldname`. Be aware that this is slower then using `GST_TYPE_ARRAY` in a `gobject::Value` directly. Since 1.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 the field specified by `fieldname`. Be aware that this is slower then using `GST_TYPE_ARRAY` in a `gobject::Value` directly. Since 1.12 ## `fieldname` the name of a field ## `array` a pointer to a `gobject::ValueArray` Sets the name of the structure to the given `name`. The string provided is copied before being used. It must not be empty, start with a letter and can be followed by letters, numbers and any of "/-_.:". ## `name` the new name of the structure Sets the parent_refcount field of `Structure`. This field is used to determine whether a structure is mutable or not. This function should only be called by code implementing parent objects of `Structure`, as described in the MT Refcounting section of the design documents. ## `refcount` a pointer to the parent's refcount # Returns `true` if the parent refcount could be set. va_list form of `Structure::set`. ## `fieldname` the name of the field to set ## `varargs` variable arguments Sets the field with the given name `field` to `value`. If the field does not exist, it is created. If the field exists, the previous value is replaced and freed. ## `fieldname` the name of the field to set ## `value` the new value of the field Sets the field with the given name `field` to `value`. If the field does not exist, it is created. If the field exists, the previous value is replaced and freed. The function will take ownership of `value`. ## `fieldname` the name of the field to set ## `value` the new value of the field Converts `self` to a human-readable string representation. For debugging purposes its easier to do something like this: ```C GST_LOG ("structure is %" GST_PTR_FORMAT, structure); ``` This prints the structure in human readable form. The current implementation of serialization will lead to unexpected results when there are nested `Caps` / `Structure` deeper than one level. Free-function: g_free # Returns a pointer to string allocated by `g_malloc`. `g_free` after usage. Creates a `Structure` from a string representation. If end is not `None`, a pointer to the place inside the given string where parsing ended will be returned. Free-function: gst_structure_free ## `string` a string representation of a `Structure`. ## `end` pointer to store the end of the string in. # Returns a new `Structure` or `None` when the string could not be parsed. Free with `Structure::free` after use. The type of a `MessageType::StructureChange`. Pad linking is starting or done. Pad unlinking is starting or done. The GStreamer core provides a GstSystemClock based on the system time. Asynchronous callbacks are scheduled from an internal thread. Clock implementors are encouraged to subclass this systemclock as it implements the async notification. Subclasses can however override all of the important methods for sync and async notifications to implement their own callback methods or blocking wait operations. # Implements [`SystemClockExt`](trait.SystemClockExt.html), [`ClockExt`](trait.ClockExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `SystemClock` methods. # Implementors [`SystemClock`](struct.SystemClock.html) Get a handle to the default system clock. The refcount of the clock will be increased so you need to unref the clock after usage. # Returns the default clock. MT safe. Sets the default system clock that can be obtained with `SystemClock::obtain`. This is mostly used for testing and debugging purposes when you want to have control over the time reported by the default system clock. MT safe. ## `new_clock` a `Clock` List of tags and values used to describe media metadata. Strings in structures must be ASCII or UTF-8 encoded. Other encodings are not allowed. Strings must not be empty or `None`. Creates a new taglist and appends the values for the given tags. It expects tag-value pairs like `TagList::add`, and a `None` terminator after the last pair. The type of the values is implicit and is documented in the API reference, but can also be queried at runtime with `gst_tag_get_type`. It is an error to pass a value of a type not matching the tag type into this function. The tag list will make copies of any arguments passed (e.g. strings, buffers). After creation you might also want to set a `TagScope` on the returned taglist to signal if the contained tags are global or stream tags. By default stream scope is assumes. See `TagList::set_scope`. Free-function: gst_tag_list_unref ## `tag` tag # Returns a new `TagList`. Free with `gst_tag_list_unref` when no longer needed. Creates a new empty GstTagList. Free-function: gst_tag_list_unref # Returns An empty tag list Deserializes a tag list. ## `str` a string created with `TagList::to_string` # Returns a new `TagList`, or `None` in case of an error. Just like `TagList::new`, only that it takes a va_list argument. Useful mostly for language bindings. Free-function: gst_tag_list_unref ## `var_args` tag / value pairs to set # Returns a new `TagList`. Free with `gst_tag_list_unref` when no longer needed. Sets the values for the given tags using the specified mode. ## `mode` the mode to use ## `tag` tag Sets the values for the given tags using the specified mode. ## `mode` the mode to use ## `tag` tag ## `var_args` tag / value pairs to set Sets the GValues for the given tags using the specified mode. ## `mode` the mode to use ## `tag` tag ## `var_args` tag / GValue pairs to set Sets the GValue for a given tag using the specified mode. ## `mode` the mode to use ## `tag` tag ## `value` GValue for this tag Sets the GValues for the given tags using the specified mode. ## `mode` the mode to use ## `tag` tag Calls the given function for each tag inside the tag list. Note that if there is no tag, the function won't be called at all. ## `func` function to be called for each tag ## `user_data` user specified data Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. ## `tag` tag to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. Gets the value that is at the given index for the given tag in the given list. ## `tag` tag to read out ## `index` number of entry to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. Copies the first date for the given tag in the taglist into the variable pointed to by `value`. Free the date with `glib::Date::free` when it is no longer needed. Free-function: g_date_free ## `tag` tag to read out ## `value` address of a GDate pointer variable to store the result into # Returns `true`, if a date was copied, `false` if the tag didn't exist in the given list or if it was `None`. Gets the date that is at the given index for the given tag in the given list and copies it into the variable pointed to by `value`. Free the date with `glib::Date::free` when it is no longer needed. Free-function: g_date_free ## `tag` tag to read out ## `index` number of entry to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list or if it was `None`. Copies the first datetime for the given tag in the taglist into the variable pointed to by `value`. Unref the date with `DateTime::unref` when it is no longer needed. Free-function: gst_date_time_unref ## `tag` tag to read out ## `value` address of a `DateTime` pointer variable to store the result into # Returns `true`, if a datetime was copied, `false` if the tag didn't exist in the given list or if it was `None`. Gets the datetime that is at the given index for the given tag in the given list and copies it into the variable pointed to by `value`. Unref the datetime with `DateTime::unref` when it is no longer needed. Free-function: gst_date_time_unref ## `tag` tag to read out ## `index` number of entry to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list or if it was `None`. Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. ## `tag` tag to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. Gets the value that is at the given index for the given tag in the given list. ## `tag` tag to read out ## `index` number of entry to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. ## `tag` tag to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. Gets the value that is at the given index for the given tag in the given list. ## `tag` tag to read out ## `index` number of entry to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. ## `tag` tag to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. ## `tag` tag to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. Gets the value that is at the given index for the given tag in the given list. ## `tag` tag to read out ## `index` number of entry to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. Gets the value that is at the given index for the given tag in the given list. ## `tag` tag to read out ## `index` number of entry to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. ## `tag` tag to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. Gets the value that is at the given index for the given tag in the given list. ## `tag` tag to read out ## `index` number of entry to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. Copies the first sample for the given tag in the taglist into the variable pointed to by `sample`. Free the sample with `gst_sample_unref` when it is no longer needed. You can retrieve the buffer from the sample using `Sample::get_buffer` and the associated caps (if any) with `Sample::get_caps`. Free-function: gst_sample_unref ## `tag` tag to read out ## `sample` address of a GstSample pointer variable to store the result into # Returns `true`, if a sample was returned, `false` if the tag didn't exist in the given list or if it was `None`. Gets the sample that is at the given index for the given tag in the given list and copies it into the variable pointed to by `sample`. Free the sample with `gst_sample_unref` when it is no longer needed. You can retrieve the buffer from the sample using `Sample::get_buffer` and the associated caps (if any) with `Sample::get_caps`. Free-function: gst_sample_unref ## `tag` tag to read out ## `index` number of entry to read out ## `sample` address of a GstSample pointer variable to store the result into # Returns `true`, if a sample was copied, `false` if the tag didn't exist in the given list or if it was `None`. Gets the scope of `self`. # Returns The scope of `self` Copies the contents for the given tag into the value, possibly merging multiple values into one if multiple values are associated with the tag. Use gst_tag_list_get_string_index (list, tag, 0, value) if you want to retrieve the first string associated with this tag unmodified. The resulting string in `value` will be in UTF-8 encoding and should be freed by the caller using g_free when no longer needed. The returned string is also guaranteed to be non-`None` and non-empty. Free-function: g_free ## `tag` tag to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. Gets the value that is at the given index for the given tag in the given list. The resulting string in `value` will be in UTF-8 encoding and should be freed by the caller using g_free when no longer needed. The returned string is also guaranteed to be non-`None` and non-empty. Free-function: g_free ## `tag` tag to read out ## `index` number of entry to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. Checks how many value are stored in this tag list for the given tag. ## `tag` the tag to query # Returns The number of tags stored Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. ## `tag` tag to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. ## `tag` tag to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. Gets the value that is at the given index for the given tag in the given list. ## `tag` tag to read out ## `index` number of entry to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. Gets the value that is at the given index for the given tag in the given list. ## `tag` tag to read out ## `index` number of entry to read out ## `value` location for the result # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. Gets the value that is at the given index for the given tag in the given list. ## `tag` tag to read out ## `index` number of entry to read out # Returns The GValue for the specified entry or `None` if the tag wasn't available or the tag doesn't have as many entries Inserts the tags of the `from` list into the first list using the given mode. ## `from` list to merge from ## `mode` the mode to use Checks if the given taglist is empty. # Returns `true` if the taglist is empty, otherwise `false`. Checks if the two given taglists are equal. ## `list2` a `TagList`. # Returns `true` if the taglists are equal, otherwise `false` Merges the two given lists into a new list. If one of the lists is `None`, a copy of the other is returned. If both lists are `None`, `None` is returned. Free-function: gst_tag_list_unref ## `list2` second list to merge ## `mode` the mode to use # Returns the new list Get the number of tags in `self`. # Returns The number of tags in `self`. Get the name of the tag in `self` at `index`. ## `index` the index # Returns The name of the tag at `index`. Peeks at the value that is at the given index for the given tag in the given list. The resulting string in `value` will be in UTF-8 encoding and doesn't need to be freed by the caller. The returned string is also guaranteed to be non-`None` and non-empty. ## `tag` tag to read out ## `index` number of entry to read out ## `value` location for the result # Returns `true`, if a value was set, `false` if the tag didn't exist in the given list. Removes the given tag from the taglist. ## `tag` tag to remove Sets the scope of `self` to `scope`. By default the scope of a taglist is stream scope. ## `scope` new scope for `self` Serializes a tag list to a string. # Returns a newly-allocated string, or `None` in case of an error. The string must be freed with `g_free` when no longer needed. Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. You must `gobject::Value::unset` the value after use. ## `dest` uninitialized `gobject::Value` to copy into ## `list` list to get the tag from ## `tag` tag to read out # Returns `true`, if a value was copied, `false` if the tag didn't exist in the given list. The different tag merging modes are basically replace, overwrite and append, but they can be seen from two directions. Given two taglists: (A) the tags already in the element and (B) the ones that are supplied to the element ( e.g. via `TagSetter::merge_tags` / `TagSetter::add_tags` or a `EventType::Tag`), how are these tags merged? In the table below this is shown for the cases that a tag exists in the list (A) or does not exists (!A) and combinations thereof. `` `` `` ``merge mode`` ``A + B`` ``A + !B`` ``!A + B`` ``!A + !B`` `` `` `` `` ``REPLACE_ALL`` ``B`` ``-`` ``B`` ``-`` `` `` ``REPLACE`` ``B`` ``A`` ``B`` ``-`` `` `` ``APPEND`` ``A, B`` ``A`` ``B`` ``-`` `` `` ``PREPEND`` ``B, A`` ``A`` ``B`` ``-`` `` `` ``KEEP`` ``A`` ``A`` ``B`` ``-`` `` `` ``KEEP_ALL`` ``A`` ``A`` ``-`` ``-`` `` `` `` `` undefined merge mode replace all tags (clear list and append) replace tags append tags prepend tags keep existing tags keep all existing tags the number of merge modes Element interface that allows setting of media metadata. Elements that support changing a stream's metadata will implement this interface. Examples of such elements are 'vorbisenc', 'theoraenc' and 'id3v2mux'. If you just want to retrieve metadata in your application then all you need to do is watch for tag messages on your pipeline's bus. This interface is only for setting metadata, not for extracting it. To set tags from the application, find tagsetter elements and set tags using e.g. `TagSetter::merge_tags` or `TagSetter::add_tags`. Also consider setting the `TagMergeMode` that is used for tag events that arrive at the tagsetter element (default mode is to keep existing tags). The application should do that before the element goes to `State::Paused`. Elements implementing the `TagSetter` interface often have to merge any tags received from upstream and the tags set by the application via the interface. This can be done like this: ```C GstTagMergeMode merge_mode; const GstTagList *application_tags; const GstTagList *event_tags; GstTagSetter *tagsetter; GstTagList *result; tagsetter = GST_TAG_SETTER (element); merge_mode = gst_tag_setter_get_tag_merge_mode (tagsetter); application_tags = gst_tag_setter_get_tag_list (tagsetter); event_tags = (const GstTagList *) element->event_tags; GST_LOG_OBJECT (tagsetter, "merging tags, merge mode = %d", merge_mode); GST_LOG_OBJECT (tagsetter, "event tags: %" GST_PTR_FORMAT, event_tags); GST_LOG_OBJECT (tagsetter, "set tags: %" GST_PTR_FORMAT, application_tags); result = gst_tag_list_merge (application_tags, event_tags, merge_mode); GST_LOG_OBJECT (tagsetter, "final tags: %" GST_PTR_FORMAT, result); ``` # Implements [`TagSetterExt`](trait.TagSetterExt.html), [`ElementExt`](trait.ElementExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `TagSetter` methods. # Implementors [`TagSetter`](struct.TagSetter.html) Adds the given tag / value pairs on the setter using the given merge mode. The list must be terminated with `None`. ## `mode` the mode to use ## `tag` tag to set ## `var_args` tag / value pairs to set Adds the given tag / GValue pairs on the setter using the given merge mode. The list must be terminated with `None`. ## `mode` the mode to use ## `tag` tag to set ## `var_args` tag / GValue pairs to set Adds the given tag / GValue pair on the setter using the given merge mode. ## `mode` the mode to use ## `tag` tag to set ## `value` GValue to set for the tag Adds the given tag / GValue pairs on the setter using the given merge mode. The list must be terminated with `None`. ## `mode` the mode to use ## `tag` tag to set Adds the given tag / value pairs on the setter using the given merge mode. The list must be terminated with `None`. ## `mode` the mode to use ## `tag` tag to set Returns the current list of tags the setter uses. The list should not be modified or freed. This function is not thread-safe. # Returns a current snapshot of the taglist used in the setter or `None` if none is used. Queries the mode by which tags inside the setter are overwritten by tags from events # Returns the merge mode used inside the element. Merges the given list into the setter's list using the given mode. ## `list` a tag list to merge from ## `mode` the mode to merge with Reset the internal taglist. Elements should call this from within the state-change handler. Sets the given merge mode that is used for adding tags from events to tags specified by this interface. The default is `TagMergeMode::Keep`, which keeps the tags set with this interface and discards tags from events. ## `mode` The mode with which tags are added The different states a task can be in the task is started and running the task is stopped the task is paused `Toc` functions are used to create/free `Toc` and `TocEntry` structures. Also they are used to convert `Toc` into `Structure` and vice versa. `Toc` lets you to inform other elements in pipeline or application that playing source has some kind of table of contents (TOC). These may be chapters, editions, angles or other types. For example: DVD chapters, Matroska chapters or cue sheet TOC. Such TOC will be useful for applications to display instead of just a playlist. Using TOC is very easy. Firstly, create `Toc` structure which represents root contents of the source. You can also attach TOC-specific tags to it. Then fill it with `TocEntry` entries by appending them to the `Toc` using `Toc::append_entry`, and appending subentries to a `TocEntry` using `TocEntry::append_sub_entry`. Note that root level of the TOC can contain only either editions or chapters. You should not mix them together at the same level. Otherwise you will get serialization /deserialization errors. Make sure that no one of the entries has negative start and stop values. Use `Event::new_toc` to create a new TOC `Event`, and `Event::parse_toc` to parse received TOC event. Use `Event::new_toc_select` to create a new TOC select `Event`, and `Event::parse_toc_select` to parse received TOC select event. The same rule for the `Message`: `Message::new_toc` to create new TOC `Message`, and `Message::parse_toc` to parse received TOC message. TOCs can have global scope or current scope. Global scope TOCs contain all entries that can possibly be selected using a toc select event, and are what an application is usually interested in. TOCs with current scope only contain the parts of the TOC relevant to the currently selected/playing stream; the current scope TOC is used by downstream elements such as muxers to write correct TOC entries when transcoding files, for example. When playing a DVD, the global TOC would contain a hierarchy of all titles, chapters and angles, for example, while the current TOC would only contain the chapters for the currently playing title if playback of a specific title was requested. Applications and plugins should not rely on TOCs having a certain kind of structure, but should allow for different alternatives. For example, a simple CUE sheet embedded in a file may be presented as a flat list of track entries, or could have a top-level edition node (or some other alternative type entry) with track entries underneath that node; or even multiple top-level edition nodes (or some other alternative type entries) each with track entries underneath, in case the source file has extracted a track listing from different sources). Create a new `Toc` structure. ## `scope` scope of this TOC # Returns newly allocated `Toc` structure, free it with `gst_toc_unref`. Appends the `TocEntry` `entry` to `self`. ## `entry` A `TocEntry` Find `TocEntry` with given `uid` in the `self`. ## `uid` UID to find `TocEntry` with. # Returns `TocEntry` with specified `uid` from the `self`, or `None` if not found. Gets the list of `TocEntry` of `self`. # Returns A `glib::List` of `TocEntry` for `entry` # Returns scope of `self` Gets the tags for `self`. # Returns A `TagList` for `entry` Merge `tags` into the existing tags of `self` using `mode`. ## `tags` A `TagList` or `None` ## `mode` A `TagMergeMode` Set a `TagList` with tags for the complete `self`. ## `tags` A `TagList` or `None` Create new `TocEntry` structure. ## `type_` entry type. ## `uid` unique ID (UID) in the whole TOC. # Returns newly allocated `TocEntry` structure, free it with `gst_toc_entry_unref`. Appends the `TocEntry` `subentry` to `self`. ## `subentry` A `TocEntry` # Returns `self`'s entry type Get `loop_type` and `repeat_count` values from the `self` and write them into appropriate storages. Loops are e.g. used by sampled instruments. GStreamer is not automatically applying the loop. The application can process this meta data and use it e.g. to send a seek-event to loop a section. ## `loop_type` the storage for the loop_type value, leave `None` if not need. ## `repeat_count` the storage for the repeat_count value, leave `None` if not need. # Returns `true` if all non-`None` storage pointers were filled with appropriate values, `false` otherwise. Gets the parent `TocEntry` of `self`. # Returns The parent `TocEntry` of `self` Get `start` and `stop` values from the `self` and write them into appropriate storages. ## `start` the storage for the start value, leave `None` if not need. ## `stop` the storage for the stop value, leave `None` if not need. # Returns `true` if all non-`None` storage pointers were filled with appropriate values, `false` otherwise. Gets the sub-entries of `self`. # Returns A `glib::List` of `TocEntry` of `self` Gets the tags for `self`. # Returns A `TagList` for `self` Gets the parent `Toc` of `self`. # Returns The parent `Toc` of `self` Gets the UID of `self`. # Returns The UID of `self` # Returns `true` if `self`'s type is an alternative type, otherwise `false` # Returns `true` if `self`'s type is a sequence type, otherwise `false` Merge `tags` into the existing tags of `self` using `mode`. ## `tags` A `TagList` or `None` ## `mode` A `TagMergeMode` Set `loop_type` and `repeat_count` values for the `self`. ## `loop_type` loop_type value to set. ## `repeat_count` repeat_count value to set. Set `start` and `stop` values for the `self`. ## `start` start value to set. ## `stop` stop value to set. Set a `TagList` with tags for the complete `self`. ## `tags` A `TagList` or `None` The different types of TOC entries (see `TocEntry`). There are two types of TOC entries: alternatives or parts in a sequence. entry is an angle (i.e. an alternative) entry is a version (i.e. alternative) entry is an edition (i.e. alternative) invalid entry type value entry is a title (i.e. a part of a sequence) entry is a track (i.e. a part of a sequence) entry is a chapter (i.e. a part of a sequence) How a `TocEntry` should be repeated. By default, entries are played a single time. single forward playback repeat forward repeat backward repeat forward and backward The scope of a TOC. global TOC representing all selectable options (this is what applications are usually interested in) TOC for the currently active/selected stream (this is a TOC representing the current stream from start to EOS, and is what a TOC writer / muxer is usually interested in; it will usually be a subset of the global TOC, e.g. just the chapters of the current title, or the chapters selected for playback from the current title) Element interface that allows setting of the TOC. Elements that support some kind of chapters or editions (or tracks like in the FLAC cue sheet) will implement this interface. If you just want to retrieve the TOC in your application then all you need to do is watch for TOC messages on your pipeline's bus (or you can perform TOC query). This interface is only for setting TOC data, not for extracting it. To set TOC from the application, find proper tocsetter element and set TOC using `TocSetter::set_toc`. Elements implementing the `TocSetter` interface can extend existing TOC by getting extend UID for that (you can use `Toc::find_entry` to retrieve it) with any TOC entries received from downstream. # Implements [`TocSetterExt`](trait.TocSetterExt.html), [`ElementExt`](trait.ElementExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `TocSetter` methods. # Implementors [`TocSetter`](struct.TocSetter.html) Return current TOC the setter uses. The TOC should not be modified without making it writable first. # Returns TOC set, or `None`. Unref with `gst_toc_unref` when no longer needed Reset the internal TOC. Elements should call this from within the state-change handler. Set the given TOC on the setter. Previously set TOC will be unreffed before setting a new one. ## `toc` a `Toc` to set. These functions allow querying informations about registered typefind functions. How to create and register these functions is described in the section "Writing typefind functions"``. The following example shows how to write a very simple typefinder that identifies the given data. You can get quite a bit more complicated than that though. ```C typedef struct { guint8 *data; guint size; guint probability; GstCaps *data; } MyTypeFind; static void my_peek (gpointer data, gint64 offset, guint size) { MyTypeFind *find = (MyTypeFind *) data; if (offset >= 0 && offset + size <= find->size) { return find->data + offset; } return NULL; } static void my_suggest (gpointer data, guint probability, GstCaps *caps) { MyTypeFind *find = (MyTypeFind *) data; if (probability > find->probability) { find->probability = probability; gst_caps_replace (&find->caps, caps); } } static GstCaps * find_type (guint8 *data, guint size) { GList *walk, *type_list; MyTypeFind find = {data, size, 0, NULL}; GstTypeFind gst_find = {my_peek, my_suggest, &find, }; walk = type_list = gst_type_find_factory_get_list (); while (walk) { GstTypeFindFactory *factory = GST_TYPE_FIND_FACTORY (walk->data); walk = g_list_next (walk) gst_type_find_factory_call_function (factory, &gst_find); } g_list_free (type_list); return find.caps; }; ``` # Implements [`PluginFeatureExt`](trait.PluginFeatureExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Gets the list of all registered typefind factories. You must free the list using `PluginFeature::list_free`. The returned factories are sorted by highest rank first, and then by factory name. Free-function: gst_plugin_feature_list_free # Returns the list of all registered `TypeFindFactory`. Calls the `GstTypeFindFunction` associated with this factory. ## `find` a properly setup `TypeFind` entry. The get_data and suggest_type members must be set. Gets the `Caps` associated with a typefind factory. # Returns the `Caps` associated with this factory Gets the extensions associated with a `TypeFindFactory`. The returned array should not be changed. If you need to change stuff in it, you should copy it using `g_strdupv`. This function may return `None` to indicate a 0-length list. # Returns a `None`-terminated array of extensions associated with this factory Check whether the factory has a typefind function. Typefind factories without typefind functions are a last-effort fallback mechanism to e.g. assume a certain media type based on the file extension. # Returns `true` if the factory has a typefind functions set, otherwise `false` The probability of the typefind function. Higher values have more certainty in doing a reliable typefind. type undetected. unlikely typefind. possible type detected. likely a type was detected. nearly certain that a type was detected. very certain a type was detected. Different URI-related errors that can occur. The protocol is not supported There was a problem with the URI Could not set or change the URI because the URI handler was in a state where that is not possible or not permitted There was a problem with the entity that the URI references The `URIHandler` is an interface that is implemented by Source and Sink `Element` to unify handling of URI. An application can use the following functions to quickly get an element that handles the given URI for reading or writing (`Element::make_from_uri`). Source and Sink plugins should implement this interface when possible. # Implements [`URIHandlerExt`](trait.URIHandlerExt.html) Trait containing all `URIHandler` methods. # Implementors [`URIHandler`](struct.URIHandler.html) Gets the list of protocols supported by `self`. This list may not be modified. # Returns the supported protocols. Returns `None` if the `self` isn't implemented properly, or the `self` doesn't support any protocols. Gets the currently handled URI. # Returns the URI currently handled by the `self`. Returns `None` if there are no URI currently handled. The returned string must be freed with `g_free` when no longer needed. Gets the type of the given URI handler # Returns the `URIType` of the URI handler. Returns `URIType::Unknown` if the `self` isn't implemented correctly. Tries to set the URI of the given handler. ## `uri` URI to set # Returns `true` if the URI was set successfully, else `false`. The different types of URI direction. The URI direction is unknown The URI is a consumer. The URI is a producer.