This class is for elements that receive buffers in an undesired size. While for example raw video contains one image per buffer, the same is not true for a lot of other formats, especially those that come directly from a file. So if you have undefined buffer sizes and require a specific size, this object is for you. An adapter is created with gst_adapter_new(). It can be freed again with g_object_unref(). into the adapter using gst_adapter_push() and the data is then read back in chunks of the desired size using gst_adapter_peek(). After the data is processed, it is freed using gst_adapter_flush(). Other methods such as gst_adapter_take() and gst_adapter_take_buffer() combine gst_adapter_peek() and gst_adapter_flush() in one method and are potentially more convenient for some use cases. For example, a sink pad's chain function that needs to pass data to a library in 512-byte chunks could be implemented like this: |[ static GstFlowReturn sink_pad_chain (GstPad *pad, GstBuffer *buffer) { MyElement *this; GstAdapter *adapter; GstFlowReturn ret = GST_FLOW_OK; // will give the element an extra ref; remember to drop it this = MY_ELEMENT (gst_pad_get_parent (pad)); adapter = this->adapter; // put buffer into adapter gst_adapter_push (adapter, buffer); // while we can read out 512 bytes, process them while (gst_adapter_available (adapter) >= 512 && ret == GST_FLOW_OK) { // use flowreturn as an error value ret = my_library_foo (gst_adapter_peek (adapter, 512)); gst_adapter_flush (adapter, 512); } gst_object_unref (this); return ret; } ]| For another example, a simple element inside GStreamer that uses GstAdapter is the libvisual element. An element using GstAdapter in its sink pad chain function should ensure that when the FLUSH_STOP event is received, that any queued data is cleared using gst_adapter_clear(). Data should also be cleared or processed on EOS and when changing state from #GST_STATE_PAUSED to #GST_STATE_READY. Also check the GST_BUFFER_FLAG_DISCONT flag on the buffer. Some elements might need to clear the adapter after a discontinuity. Since 0.10.24, the adapter will keep track of the timestamps of the buffers that were pushed. The last seen timestamp before the current position can be queried with gst_adapter_prev_timestamp(). This function can optionally return the amount of bytes between the start of the buffer that carried the timestamp and the current adapter position. The distance is useful when dealing with, for example, raw audio samples because it allows you to calculate the timestamp of the current adapter position by using the last seen timestamp and the amount of bytes since. A last thing to note is that while GstAdapter is pretty optimized, merging buffers still might be an operation that requires a malloc() and memcpy() operation, and these operations are not the fastest. Because of this, some functions like gst_adapter_available_fast() are provided to help speed up such cases should you want to. To avoid repeated memory allocations, gst_adapter_copy() can be used to copy data into a (statically allocated) user provided buffer. GstAdapter is not MT safe. All operations on an adapter must be serialized by the caller. This is not normally a problem, however, as the normal use case of GstAdapter is inside one pad's chain function, in which case access is serialized via the pad's STREAM_LOCK. Note that gst_adapter_push() takes ownership of the buffer passed. Use gst_buffer_ref() before pushing it into the adapter if you still want to access the buffer later. The adapter will never modify the data in the buffer pushed in it. Last reviewed on 2009-05-13 (0.10.24). Creates a new #GstAdapter. Free with g_object_unref(). a new #GstAdapter Gets the maximum amount of bytes available, that is it returns the maximum value that can be supplied to gst_adapter_peek() without that function returning NULL. number of bytes available in @adapter Gets the maximum number of bytes that are immediately available without requiring any expensive operations (like copying the data into a temporary buffer). operations number of bytes that are available in @adapter without expensive Removes all buffers from @adapter. Copies @size bytes of data starting at @offset out of the buffers contained in @GstAdapter into an array @dest provided by the caller. The array @dest should be large enough to contain @size bytes. The user should check that the adapter has (@offset + @size) bytes available before calling this function. the memory to copy into the bytes offset in the adapter to start from the number of bytes to copy Flushes the first @flush bytes in the @adapter. The caller must ensure that at least this many bytes are available. the number of bytes to flush Scan for pattern @pattern with applied mask @mask in the adapter data, starting from offset @offset. The bytes in @pattern and @mask are interpreted left-to-right, regardless of endianness. All four bytes of the pattern must be present in the adapter for it to match, even if the first or last bytes are masked out. It is an error to call this function without making sure that there is enough data (offset+size bytes) in the adapter. This function calls gst_adapter_masked_scan_uint32_peek() passing NULL for value. Example: <programlisting> // Assume the adapter contains 0x00 0x01 0x02 ... 0xfe 0xff gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x00010203, 0, 256); // -> returns 0 gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x00010203, 1, 255); // -> returns -1 gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x01020304, 1, 255); // -> returns 1 gst_adapter_masked_scan_uint32 (adapter, 0xffff, 0x0001, 0, 256); // -> returns -1 gst_adapter_masked_scan_uint32 (adapter, 0xffff, 0x0203, 0, 256); // -> returns 0 gst_adapter_masked_scan_uint32 (adapter, 0xffff0000, 0x02030000, 0, 256); // -> returns 2 gst_adapter_masked_scan_uint32 (adapter, 0xffff0000, 0x02030000, 0, 4); // -> returns -1 </programlisting> offset of the first match, or -1 if no match was found. mask to apply to data before matching against @pattern pattern to match (after mask is applied) offset into the adapter data from which to start scanning, returns the last scanned position. number of bytes to scan from offset Scan for pattern @pattern with applied mask @mask in the adapter data, starting from offset @offset. If a match is found, the value that matched is returned through @value, otherwise @value is left untouched. The bytes in @pattern and @mask are interpreted left-to-right, regardless of endianness. All four bytes of the pattern must be present in the adapter for it to match, even if the first or last bytes are masked out. It is an error to call this function without making sure that there is enough data (offset+size bytes) in the adapter. offset of the first match, or -1 if no match was found. mask to apply to data before matching against @pattern pattern to match (after mask is applied) offset into the adapter data from which to start scanning, returns the last scanned position. number of bytes to scan from offset pointer to uint32 to return matching data Gets the first @size bytes stored in the @adapter. The returned pointer is valid until the next function is called on the adapter. Note that setting the returned pointer as the data of a #GstBuffer is incorrect for general-purpose plugins. The reason is that if a downstream element stores the buffer so that it has access to it outside of the bounds of its chain function, the buffer will have an invalid data pointer after your element flushes the bytes. In that case you should use gst_adapter_take(), which returns a freshly-allocated buffer that you can set as #GstBuffer malloc_data or the potentially more performant gst_adapter_take_buffer(). Returns #NULL if @size bytes are not available. a pointer to the first the number of bytes to peek Get the timestamp that was before the current byte in the adapter. When position is returned. The timestamp is reset to GST_CLOCK_TIME_NONE and the distance is set to 0 when the adapter is first created or when it is cleared. This also means that before the first byte with a timestamp is removed from the adapter, the timestamp and distance returned are GST_CLOCK_TIME_NONE and 0 respectively. The previously seen timestamp. pointer to location for distance, or NULL Adds the data from @buf to the data stored inside @adapter and takes ownership of the buffer. a #GstBuffer to add to queue in the adapter Returns a freshly allocated buffer containing the first @nbytes bytes of the Caller owns returned value. g_free after usage. #NULL if @nbytes bytes are not available oven-fresh hot data, or the number of bytes to take Returns a #GstBuffer containing the first @nbytes bytes of the This function is potentially more performant than gst_adapter_take() since it can reuse the memory in pushed buffers by subbuffering or merging. Caller owns returned value. gst_buffer_unref() after usage. the adapter, or #NULL if @nbytes bytes are not available a #GstBuffer containing the first @nbytes of the number of bytes to take Returns a #GList of buffers containing the first @nbytes bytes of the When the caller can deal with individual buffers, this function is more performant because no memory should be copied. Caller owns returned list and contained buffers. gst_buffer_unref() each buffer in the list before freeing the list after usage. containing the first @nbytes of the adapter, or #NULL if @nbytes bytes are not available a #GList of buffers the number of bytes to take This base class is for parser elements that process data and splits it into separate audio/video/whatever frames. It provides for: <itemizedlist> <listitem><para>provides one sink pad and one source pad</para></listitem> <listitem><para>handles state changes</para></listitem> <listitem><para>can operate in pull mode or push mode</para></listitem> <listitem><para>handles seeking in both modes</para></listitem> <listitem><para>handles events (NEWSEGMENT/EOS/FLUSH)</para></listitem> <listitem><para> handles queries (POSITION/DURATION/SEEKING/FORMAT/CONVERT) </para></listitem> <listitem><para>handles flushing</para></listitem> </itemizedlist> The purpose of this base class is to provide the basic functionality of a parser and share a lot of rather complex code. Description of the parsing mechanism: <orderedlist> <listitem> <itemizedlist><title>Set-up phase</title> <listitem><para> GstBaseParse class calls @set_sink_caps to inform the subclass about incoming sinkpad caps. Subclass should set the srcpad caps accordingly. </para></listitem> <listitem><para> GstBaseParse calls @start to inform subclass that data processing is about to start now. </para></listitem> <listitem><para> At least at this point subclass needs to tell the GstBaseParse class how big data chunks it wants to receive (min_frame_size). It can do this with gst_base_parse_set_min_frame_size(). </para></listitem> <listitem><para> GstBaseParse class sets up appropriate data passing mode (pull/push) and starts to process the data. </para></listitem> </itemizedlist> </listitem> <listitem> <itemizedlist> <title>Parsing phase</title> <listitem><para> GstBaseParse gathers at least min_frame_size bytes of data either by pulling it from upstream or collecting buffers in an internal #GstAdapter. </para></listitem> <listitem><para> A buffer of (at least) min_frame_size bytes is passed to subclass with if the buffer contains a valid frame. It also needs to set the contain a valid frame, this call must return FALSE and optionally set the @skipsize value to inform base class that how many bytes it needs to skip in order to find a valid frame. @framesize can always indicate a new minimum for current frame parsing. The passed buffer is read-only. Note that @check_valid_frame might receive any small amount of input data when leftover data is being drained (e.g. at EOS). </para></listitem> <listitem><para> After valid frame is found, it will be passed again to subclass with frame contents and setting the caps, and buffer metadata (e.g. buffer timestamp and duration, or keyframe if applicable). (although the latter can also be done by GstBaseParse if it is appropriately configured, see below). Frame is provided with timestamp derived from upstream (as much as generally possible), duration obtained from configuration (see below), and offset if meaningful (in pull mode). </para></listitem> <listitem><para> Finally the buffer can be pushed downstream and the parsing loop starts over again. Just prior to actually pushing the buffer in question, it is passed to @pre_push_buffer which gives subclass yet one last chance to examine buffer metadata, or to send some custom (tag) events, or to perform custom (segment) filtering. </para></listitem> <listitem><para> During the parsing process GstBaseParseClass will handle both srcpad and sinkpad events. They will be passed to subclass if @event or </para></listitem> </itemizedlist> </listitem> <listitem> <itemizedlist><title>Shutdown phase</title> <listitem><para> GstBaseParse class calls @stop to inform the subclass that data parsing will be stopped. </para></listitem> </itemizedlist> </listitem> </orderedlist> Subclass is responsible for providing pad template caps for source and sink pads. The pads need to be named "sink" and "src". It also needs to set the fixed caps on srcpad, when the format is ensured (e.g. when base class calls subclass' @set_sink_caps function). This base class uses #GST_FORMAT_DEFAULT as a meaning of frames. So, subclass conversion routine needs to know that conversion from #GST_FORMAT_TIME to #GST_FORMAT_DEFAULT must return the frame number that can be found from the given byte position. GstBaseParse uses subclasses conversion methods also for seeking (or otherwise uses its own default one, see also below). Subclass @start and @stop functions will be called to inform the beginning and end of data processing. Things that subclass need to take care of: <itemizedlist> <listitem><para>Provide pad templates</para></listitem> <listitem><para> Fixate the source pad caps when appropriate </para></listitem> <listitem><para> Inform base class how big data chunks should be retrieved. This is done with gst_base_parse_set_min_frame_size() function. </para></listitem> <listitem><para> Examine data chunks passed to subclass with @check_valid_frame and tell if they contain a valid frame </para></listitem> <listitem><para> Set the caps and timestamp to frame that is passed to subclass with </para></listitem> <listitem><para>Provide conversion functions</para></listitem> <listitem><para> Update the duration information with gst_base_parse_set_duration() </para></listitem> <listitem><para> Optionally passthrough using gst_base_parse_set_passthrough() </para></listitem> <listitem><para> Configure various baseparse parameters using gst_base_parse_set_average_bitrate(), gst_base_parse_set_syncable() and gst_base_parse_set_frame_rate(). </para></listitem> <listitem><para> In particular, if subclass is unable to determine a duration, but parsing (or specs) yields a frames per seconds rate, then this can be provided to GstBaseParse to enable it to cater for buffer time metadata (which will be taken from upstream as much as possible). Internally keeping track of frame durations and respective sizes that have been pushed provides GstBaseParse with an estimated bitrate. A default @convert (used if not overriden) will then use these rates to perform obvious conversions. These rates are also used to update (estimated) duration at regular frame intervals. </para></listitem> </itemizedlist> Adds an entry to the index associating @offset to @ts. It is recommended to only add keyframe entries. @force allows to bypass checks, such as whether the stream is (upstream) seekable, another entry is already "close" to the new entry, etc. #gboolean indicating whether entry was added offset of entry timestamp associated with offset whether entry refers to keyframe add entry disregarding sanity checks Default implementation of "convert" vmethod in #GstBaseParse class. TRUE if conversion was successful. #GstFormat describing the source format. Source value to be converted. #GstFormat defining the converted format. Pointer where the conversion result will be put. Pushes the frame downstream, sends any pending events and does some timestamp and segment handling. Takes ownership of @frame and will clear it (if it was initialised with gst_base_parse_frame_init()) or free it. This must be called with sinkpad STREAM_LOCK held. #GstFlowReturn a #GstBaseParseFrame Optionally sets the average bitrate detected in media (if non-zero), e.g. based on metadata, as it will be posted to the application. By default, announced average bitrate is estimated. The average bitrate is used to estimate the total duration of the stream and to estimate a seek position, if there's no index and the format is syncable (see gst_base_parse_set_syncable()). average bitrate in bits/second Sets the duration of the currently playing media. Subclass can use this when it is able to determine duration and/or notices a change in the media duration. Alternatively, if @interval is non-zero (default), then stream duration is determined based on estimated bitrate, and updated every @interval frames. #GstFormat. duration value. how often to update the duration estimate based on bitrate, or 0. If frames per second is configured, parser can take care of buffer duration and timestamping. When performing segment clipping, or seeking to a specific location, a corresponding decoder might need an initial @lead_in and a following @lead_out number of frames to ensure the desired segment is entirely filled upon decoding. frames per second (numerator). frames per second (denominator). frames needed before a segment for subsequent decode frames needed after a segment Set if frames carry timing information which the subclass can (generally) parse and provide. In particular, intrinsic (rather than estimated) time can be obtained following a seek. whether frames carry timing information Subclass can use this function to tell the base class that it needs to give at least #min_size buffers. Minimum size of the data that this base class should give to subclass. Set if the nature of the format or configuration does not allow (much) parsing, and the parser should operate in passthrough mode (which only applies when operating in push mode). That is, incoming buffers are pushed through unmodified, i.e. no @check_valid_frame or @parse_frame callbacks will be invoked, but @pre_push_buffer will still be invoked, so subclass can perform as much or as little is appropriate for passthrough semantics in @pre_push_buffer. %TRUE if parser should run in passthrough mode Set if frame starts can be identified. This is set by default and determines whether seeking based on bitrate averages is possible for a format/stream. set if frame starts can be identified Subclasses can override any of the available virtual methods or not, as needed. At minimum @check_valid_frame and @parse_frame needs to be overridden. Frame (context) data passed to each frame parsing virtual methods. In addition to providing the data to be checked for a valid frame or an already identified frame, it conveys additional metadata or control information from and to the subclass w.r.t. the particular frame in question (rather than global parameters). Some of these may apply to each parsing stage, others only to some a particular one. These parameters are effectively zeroed at start of each frame's processing, i.e. parsing virtual method invocation sequence. Allocates a new #GstBaseParseFrame. This function is mainly for bindings, elements written in C should usually allocate the frame on the stack and then use gst_base_parse_frame_init() to initialise it. gst_base_parse_frame_free() when no longer needed, unless you gave away ownership to gst_base_parse_push_frame(). a newly-allocated #GstBaseParseFrame. Free with a #GstBuffer the flags number of bytes in this frame which should be counted as metadata overhead, ie. not used to calculate the average bitrate. Set to -1 to mark the entire frame as metadata. If in doubt, set to 0. Sets a #GstBaseParseFrame to initial state. Currently this means all public fields are zero-ed and a private flag is set to make sure gst_base_parse_frame_free() only frees the contents but not the actual frame. Use this function to initialise a #GstBaseParseFrame allocated on the stack. Flags to be used in a #GstBaseParseFrame. #GstBaseSink is the base class for sink elements in GStreamer, such as xvimagesink or filesink. It is a layer on top of #GstElement that provides a simplified interface to plugin writers. #GstBaseSink handles many details activation in push or pull mode, and queries. In most cases, when writing sink elements, there is no need to implement class methods from #GstElement or to set functions on pads, because the #GstBaseSink infrastructure should be sufficient. #GstBaseSink provides support for exactly one sink pad, which should be named "sink". A sink implementation (subclass of #GstBaseSink) should install a pad template in its base_init function, like so: |[ static void my_element_base_init (gpointer g_class) { GstElementClass *gstelement_class = GST_ELEMENT_CLASS (g_class); // sinktemplate should be a #GstStaticPadTemplate with direction // #GST_PAD_SINK and name "sink" gst_element_class_add_pad_template (gstelement_class, gst_static_pad_template_get (&amp;sinktemplate)); // see #GstElementDetails gst_element_class_set_details (gstelement_class, &amp;details); } ]| #GstBaseSink will handle the prerolling correctly. This means that it will return #GST_STATE_CHANGE_ASYNC from a state change to PAUSED until the first buffer arrives in this element. The base class will call the #GstBaseSinkClass.preroll() vmethod with this preroll buffer and will then commit the state change to the next asynchronously pending state. When the element is set to PLAYING, #GstBaseSink will synchronise on the clock using the times returned from #GstBaseSinkClass.get_times(). If this function returns #GST_CLOCK_TIME_NONE for the start time, no synchronisation will be done. Synchronisation can be disabled entirely by setting the object #GstBaseSink:sync property to %FALSE. After synchronisation the virtual method #GstBaseSinkClass.render() will be called. Subclasses should minimally implement this method. Since 0.10.3 subclasses that synchronise on the clock in the #GstBaseSinkClass.render() method are supported as well. These classes typically receive a buffer in the render method and can then potentially block on the clock while rendering. A typical example is an audiosink. Since 0.10.11 these subclasses can use gst_base_sink_wait_preroll() to perform the blocking wait. Upon receiving the EOS event in the PLAYING state, #GstBaseSink will wait for the clock to reach the time indicated by the stop time of the last #GstBaseSinkClass.get_times() call before posting an EOS message. When the element receives EOS in PAUSED, preroll completes, the event is queued and an EOS message is posted when going to PLAYING. #GstBaseSink will internally use the #GST_EVENT_NEWSEGMENT events to schedule synchronisation and clipping of buffers. Buffers that fall completely outside of the current segment are dropped. Buffers that fall partially in the segment are rendered (and prerolled). Subclasses should do any subbuffer clipping themselves when needed. #GstBaseSink will by default report the current playback position in #GST_FORMAT_TIME based on the current clock time and segment information. If no clock has been set on the element, the query will be forwarded upstream. The #GstBaseSinkClass.set_caps() function will be called when the subclass should configure itself to process a specific media type. The #GstBaseSinkClass.start() and #GstBaseSinkClass.stop() virtual methods will be called when resources should be allocated. Any #GstBaseSinkClass.preroll(), #GstBaseSinkClass.render() and #GstBaseSinkClass.set_caps() function will be called between the #GstBaseSinkClass.start() and #GstBaseSinkClass.stop() calls. The #GstBaseSinkClass.event() virtual method will be called when an event is received by #GstBaseSink. Normally this method should only be overriden by very specific elements (such as file sinks) which need to handle the newsegment event specially. #GstBaseSink provides an overridable #GstBaseSinkClass.buffer_alloc() function that can be used by sinks that want to do reverse negotiation or to provide custom buffers (hardware buffers for example) to upstream elements. The #GstBaseSinkClass.unlock() method is called when the elements should unblock any blocking operations they perform in the #GstBaseSinkClass.render() method. This is mostly useful when the #GstBaseSinkClass.render() method performs a blocking write on a file descriptor, for example. The #GstBaseSink:max-lateness property affects how the sink deals with buffers that arrive too late in the sink. A buffer arrives too late in the sink when the presentation time (as a combination of the last segment, buffer timestamp and element base_time) plus the duration is before the current time of the clock. If the frame is later than max-lateness, the sink will drop the buffer without calling the render method. This feature is disabled if sync is disabled, the #GstBaseSinkClass.get_times() method does not return a valid start time or max-lateness is set to -1 (the default). Subclasses can use gst_base_sink_set_max_lateness() to configure the max-lateness value. The #GstBaseSink:qos property will enable the quality-of-service features of the basesink which gather statistics about the real-time performance of the clock synchronisation. For each buffer received in the sink, statistics are gathered and a QOS event is sent upstream with these numbers. This information can then be used by upstream elements to reduce their processing rate, for example. Since 0.10.15 the #GstBaseSink:async property can be used to instruct the sink to never perform an ASYNC state change. This feature is mostly usable when dealing with non-synchronized streams or sparse streams. Last reviewed on 2007-08-29 (0.10.15) If the @sink spawns its own thread for pulling buffers from upstream it should call this method after it has pulled a buffer. If the element needed to preroll, this function will perform the preroll and will then block until the element state is changed. This function should be called with the PREROLL_LOCK held. continue. Any other return value should be returned from the render vmethod. #GST_FLOW_OK if the preroll completed and processing can the mini object that caused the preroll Get the number of bytes that the sink will pull when it is operating in pull mode. the number of bytes @sink will pull in pull mode. Get the last buffer that arrived in the sink and was used for preroll or for rendering. This property can be used to generate thumbnails. The #GstCaps on the buffer can be used to determine the type of the buffer. This function returns NULL when no buffer has arrived in the sink yet or when the sink is not in PAUSED or PLAYING. a #GstBuffer. gst_buffer_unref() after usage. Get the currently configured latency. The configured latency. Gets the max lateness value. See gst_base_sink_set_max_lateness for more details. before it is dropped and not rendered. A value of -1 means an unlimited time. The maximum time in nanoseconds that a buffer can be late Get the render delay of @sink. see gst_base_sink_set_render_delay() for more information about the render delay. the render delay of @sink. Checks if @sink is currently configured to synchronize against the clock. TRUE if the sink is configured to synchronize against the clock. Get the time that will be inserted between frames to control the maximum buffers per second. the number of nanoseconds @sink will put between frames. Get the synchronisation offset of @sink. The synchronisation offset. Checks if @sink is currently configured to perform asynchronous state changes to PAUSED. changes. TRUE if the sink is configured to perform asynchronous state Checks if @sink is currently configured to store the last received buffer in the last-buffer property. TRUE if the sink is configured to store the last received buffer. Checks if @sink is currently configured to send Quality-of-Service events upstream. TRUE if the sink is configured to perform Quality-of-Service. Query the sink for the latency parameters. The latency will be queried from the upstream elements. @live will be TRUE if @sink is configured to synchronize against the clock. @upstream_live will be TRUE if an upstream element is live. If both @live and @upstream_live are TRUE, the sink will want to compensate for the latency introduced by the upstream elements by setting the This function is mostly used by subclasses. TRUE if the query succeeded. if the sink is live if an upstream element is live the min latency of the upstream elements the max latency of the upstream elements Configures @sink to perform all state changes asynchronusly. When async is disabled, the sink will immediatly go to PAUSED instead of waiting for a preroll buffer. This feature is usefull if the sink does not synchronize against the clock or when it is dealing with sparse streams. the new async value. Set the number of bytes that the sink will pull when it is operating in pull mode. the blocksize in bytes Configures @sink to store the last received buffer in the last-buffer property. the new enable-last-buffer value. Sets the new max lateness value to @max_lateness. This value is used to decide if a buffer should be dropped or not based on the buffer timestamp and the current clock time. A value of -1 means an unlimited time. the new max lateness value. Configures @sink to send Quality-of-Service events upstream. the new qos value. Set the render delay in @sink to @delay. The render delay is the time between actual rendering of a buffer and its synchronisation time. Some devices might delay media rendering which can be compensated for with this function. After calling this function, this sink will report additional latency and other sinks will adjust their latency to delay the rendering of their media. This function is usually called by subclasses. the new delay Configures @sink to synchronize on the clock or not. When possible. If @sync is TRUE, the timestamps of the incomming buffers will be used to schedule the exact render time of its contents. the new sync value. Set the time that will be inserted between rendered buffers. This can be used to control the maximum buffers per second that the sink will render. the throttle time in nanoseconds Adjust the synchronisation of @sink with @offset. A negative value will render buffers earlier than their timestamp. A positive value will delay rendering. This function can be used to fix playback of badly timestamped buffers. the new offset This function will block until @time is reached. It is usually called by subclasses that use their own internal synchronisation. If @time is not valid, no sycnhronisation is done and #GST_CLOCK_BADTIME is returned. Likewise, if synchronisation is disabled in the element or there is no clock, no synchronisation is done and #GST_CLOCK_BADTIME is returned. This function should only be called with the PREROLL_LOCK held, like when receiving an EOS event in the #GstBaseSinkClass.event() vmethod or when receiving a buffer in the #GstBaseSinkClass.render() vmethod. The @time argument should be the running_time of when this method should return and is not adjusted with any latency or offset configured in the sink. #GstClockReturn the running_time to be reached the jitter to be filled with time diff, or NULL This function will block until @time is reached. It is usually called by subclasses that use their own internal synchronisation but want to let the EOS be handled by the base class. This function should only be called with the PREROLL_LOCK held, like when receiving an EOS event in the ::event vmethod. The @time argument should be the running_time of when the EOS should happen and will be adjusted with any latency and offset configured in the sink. #GstFlowReturn the running_time to be reached the jitter to be filled with time diff, or NULL If the #GstBaseSinkClass.render() method performs its own synchronisation against the clock it must unblock when going from PLAYING to the PAUSED state and call this method before continuing to render the remaining data. This function will block until a state change to PLAYING happens (in which case this function returns #GST_FLOW_OK) or the processing must be stopped due to a state change to READY or a FLUSH event (in which case this function returns #GST_FLOW_WRONG_STATE). This function should only be called with the PREROLL_LOCK held, like in the render function. continue. Any other return value should be returned from the render vmethod. #GST_FLOW_OK if the preroll completed and processing can If set to #TRUE, the basesink will perform asynchronous state changes. When set to #FALSE, the sink will not signal the parent when it prerolls. Use this option when dealing with sparse streams or when synchronisation is not required. The amount of bytes to pull when operating in pull mode. Enable the last-buffer property. If FALSE, basesink doesn't keep a reference to the last buffer arrived and the last-buffer property is always set to NULL. This can be useful if you need buffers to be released as soon as possible, eg. if you're using a buffer pool. The last buffer that arrived in the sink and was used for preroll or for rendering. This property can be used to generate thumbnails. This property can be NULL when the sink has not yet received a bufer. The additional delay between synchronisation and actual rendering of the media. This property will add additional latency to the device in order to make other sinks compensate for the delay. The time to insert between buffers. This property can be used to control the maximum amount of buffers per second to render. Setting this property to a value bigger than 0 will make the sink create THROTTLE QoS events. Controls the final synchronisation, a negative value will render the buffer earlier while a positive value delays playback. This property can be used to fix synchronisation in bad files. Subclasses can override any of the available virtual methods or not, as needed. At the minimum, the @render method should be overridden to output/present buffers. This is a generice base class for source elements. The following types of sources are supported: <itemizedlist> <listitem><para>random access sources like files</para></listitem> <listitem><para>seekable sources</para></listitem> <listitem><para>live sources</para></listitem> </itemizedlist> The source can be configured to operate in any #GstFormat with the gst_base_src_set_format() method. The currently set format determines the format of the internal #GstSegment and any #GST_EVENT_NEWSEGMENT events. The default format for #GstBaseSrc is #GST_FORMAT_BYTES. #GstBaseSrc always supports push mode scheduling. If the following conditions are met, it also supports pull mode scheduling: <itemizedlist> <listitem><para>The format is set to #GST_FORMAT_BYTES (default).</para> </listitem> <listitem><para>#GstBaseSrcClass.is_seekable() returns %TRUE.</para> </listitem> </itemizedlist> Since 0.10.9, any #GstBaseSrc can enable pull based scheduling at any time by overriding #GstBaseSrcClass.check_get_range() so that it returns %TRUE. If all the conditions are met for operating in pull mode, #GstBaseSrc is automatically seekable in push mode as well. The following conditions must be met to make the element seekable in push mode when the format is not #GST_FORMAT_BYTES: <itemizedlist> <listitem><para> #GstBaseSrcClass.is_seekable() returns %TRUE. </para></listitem> <listitem><para> #GstBaseSrcClass.query() can convert all supported seek formats to the internal format as set with gst_base_src_set_format(). </para></listitem> <listitem><para> #GstBaseSrcClass.do_seek() is implemented, performs the seek and returns %TRUE. </para></listitem> </itemizedlist> When the element does not meet the requirements to operate in pull mode, the offset and length in the #GstBaseSrcClass.create() method should be ignored. It is recommended to subclass #GstPushSrc instead, in this situation. If the element can operate in pull mode but only with specific offsets and lengths, it is allowed to generate an error when the wrong values are passed to the #GstBaseSrcClass.create() function. #GstBaseSrc has support for live sources. Live sources are sources that when paused discard data, such as audio or video capture devices. A typical live source also produces data at a fixed rate and thus provides a clock to publish this rate. Use gst_base_src_set_live() to activate the live source mode. A live source does not produce data in the PAUSED state. This means that the #GstBaseSrcClass.create() method will not be called in PAUSED but only in PLAYING. To signal the pipeline that the element will not produce data, the return value from the READY to PAUSED state will be #GST_STATE_CHANGE_NO_PREROLL. A typical live source will timestamp the buffers it creates with the current running time of the pipeline. This is one reason why a live source can only produce data in the PLAYING state, when the clock is actually distributed and running. Live sources that synchronize and block on the clock (an audio source, for example) can since 0.10.12 use gst_base_src_wait_playing() when the #GstBaseSrcClass.create() function was interrupted by a state change to PAUSED. The #GstBaseSrcClass.get_times() method can be used to implement pseudo-live sources. It only makes sense to implement the #GstBaseSrcClass.get_times() function if the source is a live source. The #GstBaseSrcClass.get_times() function should return timestamps starting from 0, as if it were a non-live source. The base class will make sure that the timestamps are transformed into the current running_time. The base source will then wait for the calculated running_time before pushing out the buffer. For live sources, the base class will by default report a latency of 0. For pseudo live sources, the base class will by default measure the difference between the first buffer timestamp and the start time of get_times and will report this value as the latency. Subclasses should override the query function when this behaviour is not acceptable. There is only support in #GstBaseSrc for exactly one source pad, which should be named "src". A source implementation (subclass of #GstBaseSrc) should install a pad template in its class_init function, like so: |[ static void my_element_class_init (GstMyElementClass *klass) { GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass); // srctemplate should be a #GstStaticPadTemplate with direction // #GST_PAD_SRC and name "src" gst_element_class_add_pad_template (gstelement_class, gst_static_pad_template_get (&amp;srctemplate)); // see #GstElementDetails gst_element_class_set_details (gstelement_class, &amp;details); } ]| <refsect2> <title>Controlled shutdown of live sources in applications</title> <para> Applications that record from a live source may want to stop recording in a controlled way, so that the recording is stopped, but the data already in the pipeline is processed to the end (remember that many live sources would go on recording forever otherwise). For that to happen the application needs to make the source stop recording and send an EOS event down the pipeline. The application would then wait for an EOS message posted on the pipeline's bus to know when all data has been processed and the pipeline can safely be stopped. Since GStreamer 0.10.16 an application may send an EOS event to a source element to make it perform the EOS logic (send EOS event downstream or post a #GST_MESSAGE_SEGMENT_DONE on the bus). This can typically be done with the gst_element_send_event() function on the element or its parent bin. After the EOS has been sent to the element, the application should wait for an EOS message to be posted on the pipeline's bus. Once this EOS message is received, it may safely shut down the entire pipeline. The old behaviour for controlled shutdown introduced since GStreamer 0.10.3 is still available but deprecated as it is dangerous and less flexible. Last reviewed on 2007-12-19 (0.10.16) </para> </refsect2> Get the number of bytes that @src will push out with each buffer. the number of bytes pushed with each buffer. Query if @src timestamps outgoing buffers based on the current running_time. %TRUE if the base class will automatically timestamp outgoing buffers. Check if an element is in live mode. %TRUE if element is in live mode. Prepare a new seamless segment for emission downstream. This function must only be called by derived sub-classes, and only from the create() function, as the stream-lock needs to be held. The format for the new segment will be the current format of the source, as configured with gst_base_src_set_format() %TRUE if preparation of the seamless segment succeeded. The new start value for the segment Stop value for the new segment The position value for the new segent Query the source for the latency parameters. @live will be TRUE when @src is configured as a live source. @min_latency will be set to the difference between the running time and the timestamp of the first buffer. This function is mostly used by subclasses. TRUE if the query succeeded. if the source is live the min latency of the source the max latency of the source Set the number of bytes that @src will push out with each buffer. When the new blocksize in bytes Configure @src to automatically timestamp outgoing buffers based on the current running_time of the pipeline. This property is mostly useful for live sources. enable or disable timestamping Sets the default format of the source. This will be the format used for sending NEW_SEGMENT events and for performing seeks. If a format of GST_FORMAT_BYTES is set, the element will be able to operate in pull mode if the #GstBaseSrcClass.is_seekable() returns TRUE. This function must only be called in states < %GST_STATE_PAUSED. the format to use If the element listens to a live source, @live should be set to %TRUE. A live source will not produce data in the PAUSED state and will therefore not be able to participate in the PREROLL phase of a pipeline. To signal this fact to the application and the pipeline, the state change return value of the live source will be GST_STATE_CHANGE_NO_PREROLL. new live-mode If the #GstBaseSrcClass.create() method performs its own synchronisation against the clock it must unblock when going from PLAYING to the PAUSED state and call this method before continuing to produce the remaining data. This function will block until a state change to PLAYING happens (in which case this function returns #GST_FLOW_OK) or the processing must be stopped due to a state change to READY or a FLUSH event (in which case this function returns #GST_FLOW_WRONG_STATE). continue. Any other return value should be returned from the create vmethod. #GST_FLOW_OK if @src is PLAYING and processing can Subclasses can override any of the available virtual methods or not, as needed. At the minimum, the @create method should be overridden to produce buffers. The #GstElement flags that a basesrc element may have. This base class is for filter elements that process data. It provides for: <itemizedlist> <listitem><para>one sinkpad and one srcpad</para></listitem> <listitem><para> Possible formats on sink and source pad implemented with custom transform_caps function. By default uses same format on sink and source. </para></listitem> <listitem><para>Handles state changes</para></listitem> <listitem><para>Does flushing</para></listitem> <listitem><para>Push mode</para></listitem> <listitem><para> Pull mode if the sub-class transform can operate on arbitrary data </para></listitem> </itemizedlist> <refsect2> <title>Use Cases</title> <para> <orderedlist> <listitem> <itemizedlist><title>Passthrough mode</title> <listitem><para> Element has no interest in modifying the buffer. It may want to inspect it, in which case the element should have a transform_ip function. If there is no transform_ip function in passthrough mode, the buffer is pushed intact. </para></listitem> <listitem><para> On the GstBaseTransformClass is the passthrough_on_same_caps variable which will automatically set/unset passthrough based on whether the element negotiates the same caps on both pads. </para></listitem> <listitem><para> passthrough_on_same_caps on an element that doesn't implement a transform_caps function is useful for elements that only inspect data (such as level) </para></listitem> </itemizedlist> <itemizedlist> <title>Example elements</title> <listitem>Level</listitem> <listitem>Videoscale, audioconvert, ffmpegcolorspace, audioresample in certain modes.</listitem> </itemizedlist> </listitem> <listitem> <itemizedlist> <title>Modifications in-place - input buffer and output buffer are the same thing.</title> <listitem><para> The element must implement a transform_ip function. </para></listitem> <listitem><para> Output buffer size must <= input buffer size </para></listitem> <listitem><para> If the always_in_place flag is set, non-writable buffers will be copied and passed to the transform_ip function, otherwise a new buffer will be created and the transform function called. </para></listitem> <listitem><para> Incoming writable buffers will be passed to the transform_ip function immediately. </para></listitem> <listitem><para> only implementing transform_ip and not transform implies always_in_place = TRUE </para></listitem> </itemizedlist> <itemizedlist> <title>Example elements</title> <listitem>Volume</listitem> <listitem>Audioconvert in certain modes (signed/unsigned conversion)</listitem> <listitem>ffmpegcolorspace in certain modes (endianness swapping)</listitem> </itemizedlist> </listitem> <listitem> <itemizedlist> <title>Modifications only to the caps/metadata of a buffer</title> <listitem><para> The element does not require writable data, but non-writable buffers should be subbuffered so that the meta-information can be replaced. </para></listitem> <listitem><para> Elements wishing to operate in this mode should replace the prepare_output_buffer method to create subbuffers of the input buffer and set always_in_place to TRUE </para></listitem> </itemizedlist> <itemizedlist> <title>Example elements</title> <listitem>Capsfilter when setting caps on outgoing buffers that have none.</listitem> <listitem>identity when it is going to re-timestamp buffers by datarate.</listitem> </itemizedlist> </listitem> <listitem> <itemizedlist><title>Normal mode</title> <listitem><para> always_in_place flag is not set, or there is no transform_ip function </para></listitem> <listitem><para> Element will receive an input buffer and output buffer to operate on. </para></listitem> <listitem><para> Output buffer is allocated by calling the prepare_output_buffer function. </para></listitem> </itemizedlist> <itemizedlist> <title>Example elements</title> <listitem>Videoscale, ffmpegcolorspace, audioconvert when doing scaling/conversions</listitem> </itemizedlist> </listitem> <listitem> <itemizedlist><title>Special output buffer allocations</title> <listitem><para> Elements which need to do special allocation of their output buffers other than what gst_buffer_pad_alloc allows should implement a prepare_output_buffer method, which calls the parent implementation and passes the newly allocated buffer. </para></listitem> </itemizedlist> <itemizedlist> <title>Example elements</title> <listitem>efence</listitem> </itemizedlist> </listitem> </orderedlist> </para> </refsect2> <refsect2> <title>Sub-class settable flags on GstBaseTransform</title> <para> <itemizedlist> <listitem><para> <itemizedlist><title>passthrough</title> <listitem><para> Implies that in the current configuration, the sub-class is not interested in modifying the buffers. </para></listitem> <listitem><para> Elements which are always in passthrough mode whenever the same caps has been negotiated on both pads can set the class variable passthrough_on_same_caps to have this behaviour automatically. </para></listitem> </itemizedlist> </para></listitem> <listitem><para> <itemizedlist><title>always_in_place</title> <listitem><para> Determines whether a non-writable buffer will be copied before passing to the transform_ip function. </para></listitem> <listitem><para> Implied TRUE if no transform function is implemented. </para></listitem> <listitem><para> Implied FALSE if ONLY transform function is implemented. </para></listitem> </itemizedlist> </para></listitem> </itemizedlist> </para> </refsect2> See if @trans is configured as a in_place transform. MT safe. TRUE is the transform is configured in in_place mode. See if @trans is configured as a passthrough transform. MT safe. TRUE is the transform is configured in passthrough mode. Queries if the transform will handle QoS. MT safe. TRUE if QoS is enabled. Instructs @trans to renegotiate a new downstream transform on the next buffer. This function is typically called after properties on the transform were set that influence the output format. If @gap_aware is %FALSE (the default), output buffers will have the %GST_BUFFER_FLAG_GAP flag unset. If set to %TRUE, the element must handle output buffers with this flag set correctly, i.e. it can assume that the buffer contains neutral data but must unset the flag if the output is no neutral data. MT safe. New state Determines whether a non-writable buffer will be copied before passing to the transform_ip function. <itemizedlist> <listitem>Always TRUE if no transform function is implemented.</listitem> <listitem>Always FALSE if ONLY transform function is implemented.</listitem> </itemizedlist> MT safe. Boolean value indicating that we would like to operate on in_place buffers. Set passthrough mode for this filter by default. This is mostly useful for filters that do not care about negotiation. Always TRUE for filters which don't implement either a transform or transform_ip method. MT safe. boolean indicating passthrough mode. Enable or disable QoS handling in the transform. MT safe. new state Instructs @trans to suggest new @caps upstream. A copy of @caps will be taken. caps to suggest buffer size to suggest Set the QoS parameters in the transform. This function is called internally when a QOS event is received but subclasses can provide custom information when needed. MT safe. the proportion the diff against the clock the timestamp of the buffer generating the QoS expressed in running_time. Subclasses can override any of the available virtual methods or not, as needed. At minimum either @transform or @transform_ip need to be overridden. If the element can overwrite the input data with the results (data is of the same type and quantity) it should provide @transform_ip. #GstBitReader provides a bit reader that can read any number of bits from a memory buffer. It provides functions for reading any number of bits into 8, 16, 32 and 64 bit variables. Frees a #GstBitReader instance, which was previously allocated by gst_bit_reader_new() or gst_bit_reader_new_from_buffer(). Read @nbits bits into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint16 to store the result number of bits to read Read @nbits bits into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint32 to store the result number of bits to read Read @nbits bits into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint64 to store the result number of bits to read Read @nbits bits into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint8 to store the result number of bits to read Returns the current position of a #GstBitReader instance in bits. The current position of @reader in bits. Returns the remaining number of bits of a #GstBitReader instance. The remaining number of bits of @reader instance. Returns the total number of bits of a #GstBitReader instance. The total number of bits of @reader instance. Initializes a #GstBitReader instance to read from @data. This function can be called on already initialized instances. data from which the bit reader should read Size of @data in bytes Initializes a #GstBitReader instance to read from @buffer. This function can be called on already initialized instances. Buffer from which the #GstBitReader should read Read @nbits bits into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint16 to store the result number of bits to read Read @nbits bits into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint32 to store the result number of bits to read Read @nbits bits into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint64 to store the result number of bits to read Read @nbits bits into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint8 to store the result number of bits to read Sets the new position of a #GstBitReader instance to @pos in bits. otherwise. %TRUE if the position could be set successfully, %FALSE The new position in bits Skips @nbits bits of the #GstBitReader instance. %TRUE if @nbits bits could be skipped, %FALSE otherwise. the number of bits to skip Skips until the next byte. %TRUE if successful, %FALSE otherwise. #GstByteReader provides a byte reader that can read different integer and floating point types from a memory buffer. It provides functions for reading signed/unsigned, little/big endian integers of 8, 16, 24, 32 and 64 bits and functions for reading little/big endian floating points numbers of 32 and 64 bits. It also provides functions to read NUL-terminated strings in various character encodings. Returns a newly-allocated copy of the current data position if at least @size bytes are left and updates the current position. Free with g_free() when no longer needed. %TRUE if successful, %FALSE otherwise. Size in bytes address of a #guint8 pointer variable in which to store the result Returns a newly-allocated copy of the current data position if there is a NUL-terminated UTF-16 string in the data (this could be an empty string as well), and advances the current position. No input checking for valid UTF-16 is done. This function is endianness agnostic - you should not assume the UTF-16 characters are in host endianness. This function will fail if no NUL-terminator was found in in the data. byte alignment of the UTF-16 string. string put into @str must be freed with g_free() when no longer needed. %TRUE if a string could be read, %FALSE otherwise. The address of a #guint16 pointer varieble in which to store the result Returns a newly-allocated copy of the current data position if there is a NUL-terminated UTF-32 string in the data (this could be an empty string as well), and advances the current position. No input checking for valid UTF-32 is done. This function is endianness agnostic - you should not assume the UTF-32 characters are in host endianness. This function will fail if no NUL-terminator was found in in the data. byte alignment of the UTF-32 string. string put into @str must be freed with g_free() when no longer needed. %TRUE if a string could be read, %FALSE otherwise. The address of a #guint32 pointer varieble in which to store the result FIXME:Reads (copies) a NUL-terminated string in the #GstByteReader instance, advancing the current position to the byte after the string. This will work for any NUL-terminated string with a character width of 8 bits, so ASCII, UTF-8, ISO-8859-N etc. No input checking for valid UTF-8 is done. This function will fail if no NUL-terminator was found in in the data. string put into @str must be freed with g_free() when no longer needed. %TRUE if a string could be read into @str, %FALSE otherwise. The address of a #gchar pointer varieble in which to store the result Frees a #GstByteReader instance, which was previously allocated by gst_byte_reader_new() or gst_byte_reader_new_from_buffer(). Returns a constant pointer to the current data position if at least @size bytes are left and updates the current position. %TRUE if successful, %FALSE otherwise. Size in bytes address of a #guint8 pointer variable in which to store the result Read a 32 bit big endian floating point value into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gfloat to store the result Read a 32 bit little endian floating point value into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gfloat to store the result Read a 64 bit big endian floating point value into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gdouble to store the result Read a 64 bit little endian floating point value into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gdouble to store the result Read a signed 16 bit big endian integer into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gint16 to store the result Read a signed 16 bit little endian integer into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gint16 to store the result Read a signed 24 bit big endian integer into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gint32 to store the result Read a signed 24 bit little endian integer into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gint32 to store the result Read a signed 32 bit big endian integer into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gint32 to store the result Read a signed 32 bit little endian integer into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gint32 to store the result Read a signed 64 bit big endian integer into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gint64 to store the result Read a signed 64 bit little endian integer into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gint64 to store the result Read a signed 8 bit integer into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gint8 to store the result Returns the current position of a #GstByteReader instance in bytes. The current position of @reader in bytes. Returns the remaining number of bytes of a #GstByteReader instance. The remaining number of bytes of @reader instance. Returns the total number of bytes of a #GstByteReader instance. The total number of bytes of @reader instance. Returns a constant pointer to the current data position if there is a NUL-terminated string in the data (this could be just a NUL terminator), advancing the current position to the byte after the string. This will work for any NUL-terminated string with a character width of 8 bits, so ASCII, UTF-8, ISO-8859-N etc. No input checking for valid UTF-8 is done. This function will fail if no NUL-terminator was found in in the data. %TRUE if a string could be found, %FALSE otherwise. address of a #gchar pointer varieble in which to store the result Read an unsigned 16 bit big endian integer into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint16 to store the result Read an unsigned 16 bit little endian integer into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint16 to store the result Read an unsigned 24 bit big endian integer into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint32 to store the result Read an unsigned 24 bit little endian integer into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint32 to store the result Read an unsigned 32 bit big endian integer into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint32 to store the result Read an unsigned 32 bit little endian integer into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint32 to store the result Read an unsigned 64 bit big endian integer into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint64 to store the result Read an unsigned 64 bit little endian integer into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint64 to store the result Read an unsigned 8 bit integer into @val and update the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint8 to store the result Initializes a #GstByteReader instance to read from @data. This function can be called on already initialized instances. data from which the #GstByteReader should read Size of @data in bytes Initializes a #GstByteReader instance to read from @buffer. This function can be called on already initialized instances. Buffer from which the #GstByteReader should read Scan for pattern @pattern with applied mask @mask in the byte reader data, starting from offset @offset relative to the current position. The bytes in @pattern and @mask are interpreted left-to-right, regardless of endianness. All four bytes of the pattern must be present in the byte reader data for it to match, even if the first or last bytes are masked out. It is an error to call this function without making sure that there is enough data (offset+size bytes) in the byte reader. Example: <programlisting> // Assume the reader contains 0x00 0x01 0x02 ... 0xfe 0xff gst_byte_reader_masked_scan_uint32 (reader, 0xffffffff, 0x00010203, 0, 256); // -> returns 0 gst_byte_reader_masked_scan_uint32 (reader, 0xffffffff, 0x00010203, 1, 255); // -> returns -1 gst_byte_reader_masked_scan_uint32 (reader, 0xffffffff, 0x01020304, 1, 255); // -> returns 1 gst_byte_reader_masked_scan_uint32 (reader, 0xffff, 0x0001, 0, 256); // -> returns -1 gst_byte_reader_masked_scan_uint32 (reader, 0xffff, 0x0203, 0, 256); // -> returns 0 gst_byte_reader_masked_scan_uint32 (reader, 0xffff0000, 0x02030000, 0, 256); // -> returns 2 gst_byte_reader_masked_scan_uint32 (reader, 0xffff0000, 0x02030000, 0, 4); // -> returns -1 </programlisting> offset of the first match, or -1 if no match was found. mask to apply to data before matching against @pattern pattern to match (after mask is applied) offset from which to start scanning, relative to the current position number of bytes to scan from offset Returns a constant pointer to the current data position if at least @size bytes are left and keeps the current position. %TRUE if successful, %FALSE otherwise. Size in bytes address of a #guint8 pointer variable in which to store the result Read a 32 bit big endian floating point value into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gfloat to store the result Read a 32 bit little endian floating point value into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gfloat to store the result Read a 64 bit big endian floating point value into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gdouble to store the result Read a 64 bit little endian floating point value into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gdouble to store the result Read a signed 16 bit big endian integer into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gint16 to store the result Read a signed 16 bit little endian integer into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gint16 to store the result Read a signed 24 bit big endian integer into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gint32 to store the result Read a signed 24 bit little endian integer into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gint32 to store the result Read a signed 32 bit big endian integer into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gint32 to store the result Read a signed 32 bit little endian integer into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gint32 to store the result Read a signed 64 bit big endian integer into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gint64 to store the result Read a signed 64 bit little endian integer into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gint64 to store the result Read a signed 8 bit integer into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #gint8 to store the result Returns a constant pointer to the current data position if there is a NUL-terminated string in the data (this could be just a NUL terminator). The current position will be maintained. This will work for any NUL-terminated string with a character width of 8 bits, so ASCII, UTF-8, ISO-8859-N etc. No input checking for valid UTF-8 is done. This function will fail if no NUL-terminator was found in in the data. %TRUE if a string could be skipped, %FALSE otherwise. address of a #gchar pointer varieble in which to store the result Read an unsigned 16 bit big endian integer into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint16 to store the result Read an unsigned 16 bit little endian integer into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint16 to store the result Read an unsigned 24 bit big endian integer into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint32 to store the result Read an unsigned 24 bit little endian integer into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint32 to store the result Read an unsigned 32 bit big endian integer into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint32 to store the result Read an unsigned 32 bit little endian integer into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint32 to store the result Read an unsigned 64 bit big endian integer into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint64 to store the result Read an unsigned 64 bit little endian integer into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint64 to store the result Read an unsigned 8 bit integer into @val but keep the current position. %TRUE if successful, %FALSE otherwise. Pointer to a #guint8 to store the result Sets the new position of a #GstByteReader instance to @pos in bytes. otherwise. %TRUE if the position could be set successfully, %FALSE The new position in bytes Skips @nbytes bytes of the #GstByteReader instance. %TRUE if @nbytes bytes could be skipped, %FALSE otherwise. the number of bytes to skip Skips a NUL-terminated UTF-16 string in the #GstByteReader instance, advancing the current position to the byte after the string. No input checking for valid UTF-16 is done. This function will fail if no NUL-terminator was found in in the data. %TRUE if a string could be skipped, %FALSE otherwise. Skips a NUL-terminated UTF-32 string in the #GstByteReader instance, advancing the current position to the byte after the string. No input checking for valid UTF-32 is done. This function will fail if no NUL-terminator was found in in the data. %TRUE if a string could be skipped, %FALSE otherwise. Skips a NUL-terminated string in the #GstByteReader instance, advancing the current position to the byte after the string. This will work for any NUL-terminated string with a character width of 8 bits, so ASCII, UTF-8, ISO-8859-N etc. No input checking for valid UTF-8 is done. This function will fail if no NUL-terminator was found in in the data. %TRUE if a string could be skipped, %FALSE otherwise. #GstByteWriter provides a byte writer and reader that can write/read different integer and floating point types to/from a memory buffer. It provides functions for writing/reading signed/unsigned, little/big endian integers of 8, 16, 24, 32 and 64 bits and functions for reading little/big endian floating points numbers of 32 and 64 bits. It also provides functions to write/read NUL-terminated strings in various character encodings. Checks if enough free space from the current write cursor is available and reallocates if necessary. %TRUE if at least @size bytes are still available Number of bytes that should be available Writes @size bytes containing @value to @writer. %TRUE if the value could be written Value to be writen Number of bytes to be writen Frees @writer and all memory allocated by it. Frees @writer and all memory allocated by it except the current data, which is returned as #GstBuffer. after usage. the current data as buffer. gst_buffer_unref() Frees @writer and all memory allocated by it except the current data, which is returned. the current data. g_free() after usage. Returns the remaining size of data that can still be written. If -1 is returned the remaining size is only limited by system resources. the remaining size of data that can still be written Initializes @writer to an empty instance Initializes @writer with the given buffer. If @initialized is %TRUE it is possible to read the complete buffer from the #GstByteWriter from the beginning. <note>@buffer must be writable</note> Buffer used for writing If %TRUE the complete data can be read from the beginning Initializes @writer with the given memory area. If @initialized is %TRUE it is possible to read @size bytes from the #GstByteWriter from the beginning. Memory area for writing Size of @data in bytes If %TRUE the complete data can be read from the beginning Initializes @writer with the given initial data size. Initial size of data If %TRUE the data can't be reallocated Writes @size bytes of @data to @writer. %TRUE if the value could be written Data to write Size of @data in bytes Writes a big endian 32 bit float to @writer. %TRUE if the value could be written Value to write Writes a little endian 32 bit float to @writer. %TRUE if the value could be written Value to write Writes a big endian 64 bit float to @writer. %TRUE if the value could be written Value to write Writes a little endian 64 bit float to @writer. %TRUE if the value could be written Value to write Writes a signed big endian 16 bit integer to @writer. %TRUE if the value could be written Value to write Writes a signed little endian 16 bit integer to @writer. %TRUE if the value could be written Value to write Writes a signed big endian 24 bit integer to @writer. %TRUE if the value could be written Value to write Writes a signed little endian 24 bit integer to @writer. %TRUE if the value could be written Value to write Writes a signed big endian 32 bit integer to @writer. %TRUE if the value could be written Value to write Writes a signed little endian 32 bit integer to @writer. %TRUE if the value could be written Value to write Writes a signed big endian 64 bit integer to @writer. %TRUE if the value could be written Value to write Writes a signed little endian 64 bit integer to @writer. %TRUE if the value could be written Value to write Writes a signed 8 bit integer to @writer. %TRUE if the value could be written Value to write Writes a NUL-terminated UTF16 string to @writer (including the terminator). %TRUE if the value could be written UTF16 string to write Writes a NUL-terminated UTF32 string to @writer (including the terminator). %TRUE if the value could be written UTF32 string to write Writes a NUL-terminated UTF8 string to @writer (including the terminator). %TRUE if the value could be written UTF8 string to write Writes a unsigned big endian 16 bit integer to @writer. %TRUE if the value could be written Value to write Writes a unsigned little endian 16 bit integer to @writer. %TRUE if the value could be written Value to write Writes a unsigned big endian 24 bit integer to @writer. %TRUE if the value could be written Value to write Writes a unsigned little endian 24 bit integer to @writer. %TRUE if the value could be written Value to write Writes a unsigned big endian 32 bit integer to @writer. %TRUE if the value could be written Value to write Writes a unsigned little endian 32 bit integer to @writer. %TRUE if the value could be written Value to write Writes a unsigned big endian 64 bit integer to @writer. %TRUE if the value could be written Value to write Writes a unsigned little endian 64 bit integer to @writer. %TRUE if the value could be written Value to write Writes a unsigned 8 bit integer to @writer. %TRUE if the value could be written Value to write Resets @writer and frees the data if it's owned by @writer. Resets @writer and returns the current data as buffer. after usage. the current data as buffer. gst_buffer_unref() Resets @writer and returns the current data. the current data. g_free() after usage. Structure used by the collect_pads. A function that will be called when the #GstCollectData will be freed. It is passed the pointer to the structure and should free any custom memory and resources allocated for it. the #GstCollectData that will be freed Manages a set of pads that operate in collect mode. This means that control is given to the manager of this object when all pads have data. <itemizedlist> <listitem><para> Collectpads are created with gst_collect_pads_new(). A callback should then be installed with gst_collect_pads_set_function (). </para></listitem> <listitem><para> Pads are added to the collection with gst_collect_pads_add_pad()/ gst_collect_pads_remove_pad(). The pad has to be a sinkpad. The chain and event functions of the pad are overridden. The element_private of the pad is used to store private information for the collectpads. </para></listitem> <listitem><para> For each pad, data is queued in the _chain function or by performing a pull_range. </para></listitem> <listitem><para> When data is queued on all pads, the callback function is called. </para></listitem> <listitem><para> Data can be dequeued from the pad with the gst_collect_pads_pop() method. One can peek at the data with the gst_collect_pads_peek() function. These functions will return NULL if the pad received an EOS event. When all pads return NULL from a gst_collect_pads_peek(), the element can emit an EOS event itself. </para></listitem> <listitem><para> Data can also be dequeued in byte units using the gst_collect_pads_available(), gst_collect_pads_read() and gst_collect_pads_flush() calls. </para></listitem> <listitem><para> Elements should call gst_collect_pads_start() and gst_collect_pads_stop() in their state change functions to start and stop the processing of the collecpads. The gst_collect_pads_stop() call should be called before calling the parent element state change function in the PAUSED_TO_READY state change to ensure no pad is blocked and the element can finish streaming. </para></listitem> <listitem><para> gst_collect_pads_collect() and gst_collect_pads_collect_range() can be used by elements that start a #GstTask to drive the collect_pads. This feature is however not yet implemented. </para></listitem> </itemizedlist> Last reviewed on 2006-05-10 (0.10.6) Create a new instance of #GstCollectPads. MT safe. a new #GstCollectPads, or NULL in case of an error. Add a pad to the collection of collect pads. The pad has to be a sinkpad. The refcount of the pad is incremented. Use gst_collect_pads_remove_pad() to remove the pad from the collection again. This function will override the chain and event functions of the pad along with the element_private data, which is used to store private information for the collectpads. You specify a size for the returned #GstCollectData structure so that you can use it to store additional information. The pad will be automatically activated in push mode when @pads is started. This function calls gst_collect_pads_add_pad_full() passing a value of NULL for destroy_notify. MT safe. if wrong parameters are supplied. a new #GstCollectData to identify the new pad. Or NULL the pad to add the size of the returned #GstCollectData structure Add a pad to the collection of collect pads. The pad has to be a sinkpad. The refcount of the pad is incremented. Use gst_collect_pads_remove_pad() to remove the pad from the collection again. You specify a size for the returned #GstCollectData structure so that you can use it to store additional information. You can also specify a #GstCollectDataDestroyNotify that will be called just before the #GstCollectData structure is freed. It is passed the pointer to the structure and should free any custom memory and resources allocated for it. The pad will be automatically activated in push mode when @pads is started. MT safe. if wrong parameters are supplied. a new #GstCollectData to identify the new pad. Or NULL the pad to add the size of the returned #GstCollectData structure function to be called before the returned #GstCollectData structure is freed Query how much bytes can be read from each queued buffer. This means that the result of this call is the maximum number of bytes that can be read from each of the pads. This function should be called with @pads LOCK held, such as in the callback. MT safe. returns 0 if a pad has no queued buffer. The maximum number of bytes queued on all pads. This function Collect data on all pads. This function is usually called from a #GstTask function in an element. This function is currently not implemented. MT safe. #GstFlowReturn of the operation. Collect data with @offset and @length on all pads. This function is typically called in the getrange function of an element. This function is currently not implemented. MT safe. #GstFlowReturn of the operation. the offset to collect the length to collect Flush @size bytes from the pad @data. This function should be called with @pads LOCK held, such as in the callback. MT safe. is 0 if the pad was end-of-stream. The number of bytes flushed. This can be less than @size and the data to use the number of bytes to flush Check if a pad is active. This function is currently not implemented. MT safe. %TRUE if the pad is active. the pad to check Peek at the buffer currently queued in @data. This function should be called with the @pads LOCK held, such as in the callback handler. MT safe. should unref the buffer after usage. The buffer in @data or NULL if no buffer is queued. the data to use Pop the buffer currently queued in @data. This function should be called with the @pads LOCK held, such as in the callback handler. MT safe. queued. You should unref the buffer after usage. The buffer in @data or NULL if no buffer was the data to use Get a pointer in @bytes where @size bytes can be read from the given pad @data. This function should be called with @pads LOCK held, such as in the callback. MT safe. memory pointed to by @bytes. This can be less than @size and is 0 if the pad is end-of-stream. The number of bytes available for consumption in the the data to use a pointer to a byte array the number of bytes to read Get a buffer of @size bytes from the given pad @data. This function should be called with @pads LOCK held, such as in the callback. that requested. A return of NULL signals that the pad is end-of-stream. Unref the buffer with gst_buffer_unref() after use. MT safe. a #GstBuffer. The size of the buffer can be less the data to use the number of bytes to read Remove a pad from the collection of collect pads. This function will also free the #GstCollectData and all the resources that were allocated with gst_collect_pads_add_pad(). The pad will be deactivated automatically when @pads is stopped. MT safe. %TRUE if the pad could be removed. the pad to remove Install a clipping function that is called right after a buffer is received on a pad managed by @pads. See #GstCollectPadsClipFunction for more info. clip function to install user data to pass to @clip_func Change the flushing state of all the pads in the collection. No pad is able to accept anymore data when @flushing is %TRUE. Calling this function with @flushing %FALSE makes @pads accept data again. MT safe. desired state of the pads Set the callback function and user data that will be called when all the pads added to the collection have buffers queued. MT safe. the function to set user data passed to the function Starts the processing of data in the collect_pads. MT safe. Stops the processing of data in the collect_pads. this function will also unblock any blocking operations. MT safe. Get a buffer of @size bytes from the given pad @data. Flushes the amount of read bytes. This function should be called with @pads LOCK held, such as in the callback. MT safe. that requested. A return of NULL signals that the pad is end-of-stream. Unref the buffer after use. a #GstBuffer. The size of the buffer can be less the data to use the number of bytes to read A function that will be called when @buffer is received on the pad managed by @data in the collecpad object @pads. The function should use the segment of @data and the negotiated media type on the pad to perform clipping of @buffer. This function takes ownership of @buffer. the buffer has been clipped completely. a #GstBuffer that contains the clipped data of @buffer or NULL when a #GstCollectPads a #GstCollectData a #GstBuffer user data A function that will be called when all pads have received data. #GST_FLOW_OK for success the #GstCollectPads that triggered the callback user data passed to gst_collect_pads_set_function() #GstDataQueue is an object that handles threadsafe queueing of objects. It also provides size-related functionality. This object should be used for any #GstElement that wishes to provide some sort of queueing functionality. a new #GstDataQueue. the callback used to tell if the element considers the queue full or not. a #gpointer that will be given in the @checkfull callback. Creates a new #GstDataQueue. The difference with @gst_data_queue_new is that it will not emit the 'full' and 'empty' signals, but instead calling directly @fullcallback or @emptycallback. a new #GstDataQueue. the callback used to tell if the element considers the queue full or not. the callback which will be called when the queue is considered full. the callback which will be called when the queue is considered empty. a #gpointer that will be given in the @checkfull callback. Pop and unref the head-most #GstMiniObject with the given #GType. TRUE if an element was removed. The #GType of the item to drop. Flushes all the contents of the @queue. Any call to #gst_data_queue_push and #gst_data_queue_pop will be released. MT safe. Get the current level of the queue. the location to store the result Queries if there are any items in the @queue. MT safe. #TRUE if @queue is empty. Queries if @queue is full. This check will be done using the #GstDataQueueCheckFullFunction registered with @queue. MT safe. #TRUE if @queue is full. Inform the queue that the limits for the fullness check have changed and that any blocking gst_data_queue_push() should be unblocked to recheck the limts. Retrieves the first @item available on the @queue. If the queue is currently empty, the call will block until at least one item is available, OR the MT safe. #TRUE if an @item was successfully retrieved from the @queue. pointer to store the returned #GstDataQueueItem. Pushes a #GstDataQueueItem (or a structure that begins with the same fields) on the @queue. If the @queue is full, the call will block until space is available, OR the @queue is set to flushing state. MT safe. Note that this function has slightly different semantics than gst_pad_push() the #GstMiniObject contained in @item if the push was successful. If FALSE is returned, the caller is responsible for freeing @item and its contents. #TRUE if the @item was successfully pushed on the @queue. a #GstDataQueueItem. Sets the queue to flushing state if @flushing is #TRUE. If set to flushing state, any incoming data on the @queue will be discarded. Any call currently blocking on #gst_data_queue_push or #gst_data_queue_pop will return straight away with a return value of #FALSE. While the @queue is in flushing state, all calls to those two functions will return #FALSE. MT Safe. a #gboolean stating if the queue will be flushing or not. Reports that the queue became empty (empty). A queue is empty if the total amount of visible items inside it (num-visible, time, size) is lower than the boundary values which can be set through the GObject properties. Reports that the queue became full (full). A queue is full if the total amount of data inside it (num-visible, time, size) is higher than the boundary values which can be set through the GObject properties. The prototype of the function used to inform the queue that it should be considered as full. #TRUE if the queue should be considered full. a #GstDataQueue. The number of visible items currently in the queue. The amount of bytes currently in the queue. The accumulated duration of the items currently in the queue. The #gpointer registered when the #GstDataQueue was created. Structure used by #GstDataQueue. You can supply a different structure, as long as the top of the structure is identical to this structure. Structure describing the size of a queue. This class is mostly useful for elements that cannot do random access, or at least very slowly. The source usually prefers to push out a fixed size buffer. Subclasses usually operate in a format that is different from the default GST_FORMAT_BYTES format of #GstBaseSrc. Classes extending this base class will usually be scheduled in a push based mode. If the peer accepts to operate without offsets and within the limits of the allowed block size, this class can operate in getrange based mode automatically. To make this possible, the subclass should override the ::check_get_range method. The subclass should extend the methods from the baseclass in addition to the ::create method. Seeking, flushing, scheduling and sync is all handled by this base class. Last reviewed on 2006-07-04 (0.10.9) This function will be called by gst_type_find_helper_get_range() when typefinding functions request to peek at the data of a stream at certain offsets. If this function returns GST_FLOW_OK, the result buffer will be stored in @buffer. The contents of @buffer is invalid for any other return value. This function is supposed to behave exactly like a #GstPadGetRangeFunction. GST_FLOW_OK for success a #GstObject that will handle the getrange request the offset of the range the length of the range a memory location to hold the result buffer Create a new #GstBitReader instance, which will read from @data. a new #GstBitReader instance Data from which the #GstBitReader should read Size of @data in bytes Create a new #GstBitReader instance, which will read from the #GstBuffer @buffer. a new #GstBitReader instance Buffer from which the #GstBitReader should read Create a new #GstByteReader instance, which will read from @data. a new #GstByteReader instance data from which the #GstByteReader should read Size of @data in bytes Create a new #GstByteReader instance, which will read from the #GstBuffer @buffer. a new #GstByteReader instance Buffer from which the #GstByteReader should read Creates a new, empty #GstByteWriter instance a new, empty #GstByteWriter instance Creates a new #GstByteWriter instance with the given buffer. If @initialized is %TRUE it is possible to read the complete buffer from the #GstByteWriter from the beginning. <note>@buffer must be writable</note> a new #GstByteWriter instance Buffer used for writing If %TRUE the complete data can be read from the beginning Creates a new #GstByteWriter instance with the given memory area. If @initialized is %TRUE it is possible to read @size bytes from the #GstByteWriter from the beginning. a new #GstByteWriter instance Memory area for writing Size of @data in bytes If %TRUE the complete data can be read from the beginning Creates a new #GstByteWriter instance with the given initial data size. a new #GstByteWriter instance Initial size of data If %TRUE the data can't be reallocated Tries to find what type of data is flowing from the given source #GstPad. Returns #NULL if no #GstCaps matches the data stream. the #GstCaps corresponding to the data stream. A source #GstPad The length in bytes Tries to find what type of data is contained in the given #GstBuffer, the assumption being that the buffer represents the beginning of the stream or file. All available typefinders will be called on the data in order of rank. If a typefinding function returns a probability of #GST_TYPE_FIND_MAXIMUM, typefinding is stopped immediately and the found caps will be returned right away. Otherwise, all available typefind functions will the tried, and the caps with the highest probability will be returned, or #NULL if the content of the buffer could not be identified. if no type could be found. The caller should free the caps returned with gst_caps_unref(). the #GstCaps corresponding to the data, or #NULL object doing the typefinding, or NULL (used for logging) a #GstBuffer with data to typefind location to store the probability of the found caps, or #NULL Tries to find the best #GstCaps associated with @extension. All available typefinders will be checked against the extension in order of rank. The caps of the first typefinder that can handle @extension will be returned. #NULL if no type could be found. The caller should free the caps returned with gst_caps_unref(). the #GstCaps corresponding to @extension, or object doing the typefinding, or NULL (used for logging) an extension Utility function to do pull-based typefinding. Unlike gst_type_find_helper() however, this function will use the specified function @func to obtain the data needed by the typefind functions, rather than operating on a given source pad. This is useful mostly for elements like tag demuxers which strip off data at the beginning and/or end of a file and want to typefind the stripped data stream before adding their own source pad (the specified callback can then call the upstream peer pad with offsets adjusted for the tag size, for example). Returns #NULL if no #GstCaps matches the data stream. the #GstCaps corresponding to the data stream. A #GstObject that will be passed as first argument to @func A generic #GstTypeFindHelperGetRangeFunction that will be used to access data at random offsets when doing the typefinding The length in bytes location to store the probability of the found caps, or #NULL Utility function to do pull-based typefinding. Unlike gst_type_find_helper() however, this function will use the specified function @func to obtain the data needed by the typefind functions, rather than operating on a given source pad. This is useful mostly for elements like tag demuxers which strip off data at the beginning and/or end of a file and want to typefind the stripped data stream before adding their own source pad (the specified callback can then call the upstream peer pad with offsets adjusted for the tag size, for example). When @extension is not NULL, this function will first try the typefind functions for the given extension, which might speed up the typefinding in many cases. Returns #NULL if no #GstCaps matches the data stream. the #GstCaps corresponding to the data stream. A #GstObject that will be passed as first argument to @func A generic #GstTypeFindHelperGetRangeFunction that will be used to access data at random offsets when doing the typefinding The length in bytes extension of the media location to store the probability of the found caps, or #NULL