Commit bbb5df4b authored by Rémi Denis-Courmont's avatar Rémi Denis-Courmont

input: document and annotate chain building functions

parent af5378d0
......@@ -40,7 +40,22 @@ unsigned demux_TestAndClearFlags( demux_t *, unsigned );
int demux_GetTitle( demux_t * );
int demux_GetSeekpoint( demux_t * );
demux_t *demux_FilterChainNew( demux_t *p_demux, const char *psz_name );
/**
* Builds an explicit chain of demux filters.
*
* This function creates a chain of filters according to a supplied list.
*
* See also stream_FilterChainNew(). Those two functions have identical
* semantics and ownership rules, except for the use of demux vs stream.
*
* @param source input stream around which to build a filter chain
* @param list colon-separated list of stream filters (upstream first)
*
* @return The last demux (filter) in the chain.
* The return value is always a valid (non-NULL) demux pointer.
*/
demux_t *demux_FilterChainNew( demux_t *source, const char *list ) VLC_USED;
bool demux_FilterEnable( demux_t *p_demux_chain, const char* psz_demux );
bool demux_FilterDisable( demux_t *p_demux_chain, const char* psz_demux );
......
......@@ -45,7 +45,7 @@ typedef struct
{
VLC_COMMON_MEMBERS
demux_t *p_demux; /**< Demux plugin instance */
demux_t *p_demux; /**< Demux object (most downstream) */
/* Title infos for that input */
bool b_title_demux; /* Titles/Seekpoints provided by demux */
......
......@@ -37,21 +37,50 @@ void stream_CommonDelete( stream_t *s );
stream_t *stream_AccessNew(vlc_object_t *, input_thread_t *, bool, const char *);
/**
* Automatically wraps a stream with any applicable stream filter.
* @return the (outermost/downstream) stream filter; if no filters were added,
* then the function return the source parameter.
* @note The function never returns NULL.
* Probes stream filters automatically.
*
* This function automatically and repeatedly probes for applicable stream
* filters to append downstream of an existing stream. Any such filter will
* convert the stream into another stream, e.g. decompressing it or extracting
* the list of contained files (playlist).
*
* This function transfers ownership of the supplied stream to the following
* stream filter, of the first stream filter to the second stream filter, and
* so on. Any attempt to access the original stream filter directly is
* explicitly undefined.
*
* If, and only if, no filters were probed succesfully, a pointer to the
* unchanged source stream will be returned. Otherwise, this returns a stream
* filter. The return value is thus guaranteed to be non-NULL.
*
* @param source input stream around which to build a filter chain
*
* @return the last, most downstream stream object.
*
* @note The return value must be freed with vlc_stream_Delete() after use.
* This will automatically free the whole chain and the underlying stream.
*/
stream_t *stream_FilterAutoNew( stream_t *source ) VLC_USED;
/**
* This function creates a chain of filters according to the colon-separated
* list.
* Builds an explicit chain of stream filters.
*
* This function creates a chain of filters according to a supplied list.
*
* See also stream_FilterAutoNew(). Those two functions have identical
* semantics; the only difference lies in how the list of probed filters is
* determined (manually versus automatically).
*
* If the list is empty, or if probing each of the requested filters failed,
* this function will return a pointer to the supplied source stream.
*
* @param source input stream around which to build a filter chain
* @param list colon-separated list of stream filters (upstream first)
*
* You must release the returned value using vlc_stream_Delete unless it is
* used as a source to another filter.
* @return The last stream (filter) in the chain.
* The return value is always a valid (non-NULL) stream pointer.
*/
stream_t *stream_FilterChainNew( stream_t *p_source, const char *psz_chain );
stream_t *stream_FilterChainNew( stream_t *source, const char *list ) VLC_USED;
/**
* Attach \ref stream_extractor%s according to specified data
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment