[vlc-commits] deinterlace: move function declarations
Thomas Guillem
git at videolan.org
Sat Nov 11 11:02:04 CET 2017
vlc | branch: master | Thomas Guillem <thomas at gllm.fr> | Sat Nov 11 11:00:12 2017 +0100| [480171b63fe4177ad28fef92a5db80d9ffd7f872] | committer: Thomas Guillem
deinterlace: move function declarations
Also move the documentation and set the functions static.
> http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=480171b63fe4177ad28fef92a5db80d9ffd7f872
---
modules/video_filter/deinterlace/deinterlace.c | 202 +++++++++++++++++++++++++
modules/video_filter/deinterlace/deinterlace.h | 201 ------------------------
2 files changed, 202 insertions(+), 201 deletions(-)
diff --git a/modules/video_filter/deinterlace/deinterlace.c b/modules/video_filter/deinterlace/deinterlace.c
index 1397aed9b8..ccabe5bb8c 100644
--- a/modules/video_filter/deinterlace/deinterlace.c
+++ b/modules/video_filter/deinterlace/deinterlace.c
@@ -48,6 +48,208 @@
#include "merge.h"
/*****************************************************************************
+ * video filter functions
+ *****************************************************************************/
+
+/**
+ * Top-level filtering method.
+ *
+ * Open() sets this up as the processing method (pf_video_filter)
+ * in the filter structure.
+ *
+ * Note that there is no guarantee that the returned picture directly
+ * corresponds to p_pic. The first few times, the filter may not even
+ * return a picture, if it is still filling the history for temporal
+ * filtering (although such filters often return *something* also
+ * while starting up). It should be assumed that N input pictures map to
+ * M output pictures, with no restrictions for N and M (except that there
+ * is not much delay).
+ *
+ * Also, there is no guarantee that the PTS of the frame stays untouched.
+ * In fact, framerate doublers automatically compute the proper PTSs for the
+ * two output frames for each input frame, and IVTC does a nontrivial
+ * framerate conversion (29.97 > 23.976 fps).
+ *
+ * Yadif has an offset of one frame between input and output, but introduces
+ * no delay: the returned frame is the *previous* input frame deinterlaced,
+ * complete with its original PTS.
+ *
+ * Finally, note that returning NULL sometimes can be normal behaviour for some
+ * algorithms (e.g. IVTC).
+ *
+ * Currently:
+ * Most algorithms: 1 -> 1, no offset
+ * All framerate doublers: 1 -> 2, no offset
+ * Yadif: 1 -> 1, offset of one frame
+ * IVTC: 1 -> 1 or 0 (depends on whether a drop was needed)
+ * with an offset of one frame (in most cases)
+ * and framerate conversion.
+ *
+ * @param p_filter The filter instance.
+ * @param p_pic The latest input picture.
+ * @return Deinterlaced picture(s). Linked list of picture_t's or NULL.
+ * @see Open()
+ * @see filter_t
+ * @see filter_sys_t
+ */
+static picture_t *Deinterlace( filter_t *p_filter, picture_t *p_pic );
+
+/**
+ * Reads the configuration, sets up and starts the filter.
+ *
+ * Possible reasons for returning VLC_EGENERIC:
+ * - Unsupported input chroma. See IsChromaSupported().
+ * - Caller has set p_filter->b_allow_fmt_out_change to false,
+ * but the algorithm chosen in the configuration
+ * wants to convert the output to a format different
+ * from the input. See SetFilterMethod().
+ *
+ * Open() is atomic: if an error occurs, the state of p_this
+ * is left as it was before the call to this function.
+ *
+ * @param p_this The filter instance as vlc_object_t.
+ * @return VLC error code
+ * @retval VLC_SUCCESS All ok, filter set up and started.
+ * @retval VLC_ENOMEM Memory allocation error, initialization aborted.
+ * @retval VLC_EGENERIC Something went wrong, initialization aborted.
+ * @see IsChromaSupported()
+ * @see SetFilterMethod()
+ */
+static int Open( vlc_object_t *p_this );
+
+/**
+ * Resets the filter state, including resetting all algorithm-specific state
+ * and discarding all histories, but does not stop the filter.
+ *
+ * Open() sets this up as the flush method (pf_flush)
+ * in the filter structure.
+ *
+ * @param p_filter The filter instance.
+ * @see Open()
+ * @see filter_t
+ * @see filter_sys_t
+ * @see metadata_history_t
+ * @see phosphor_sys_t
+ * @see ivtc_sys_t
+ */
+static void Flush( filter_t *p_filter );
+
+/**
+ * Mouse callback for the deinterlace filter.
+ *
+ * Open() sets this up as the mouse callback method (pf_video_mouse)
+ * in the filter structure.
+ *
+ * Currently, this handles the scaling of the y coordinate for algorithms
+ * that halve the output height.
+ *
+ * @param p_filter The filter instance.
+ * @param[out] p_mouse Updated mouse position data.
+ * @param[in] p_old Previous mouse position data. Unused in this filter.
+ * @param[in] p_new Latest mouse position data.
+ * @return VLC error code; currently always VLC_SUCCESS.
+ * @retval VLC_SUCCESS All ok.
+ * @see Open()
+ * @see filter_t
+ * @see vlc_mouse_t
+ */
+static int Mouse( filter_t *p_filter,
+ vlc_mouse_t *p_mouse,
+ const vlc_mouse_t *p_old,
+ const vlc_mouse_t *p_new );
+
+/**
+ * Stops and uninitializes the filter, and deallocates memory.
+ * @param p_this The filter instance as vlc_object_t.
+ */
+static void Close( vlc_object_t *p_this );
+
+/*****************************************************************************
+ * Extra documentation
+ *****************************************************************************/
+
+/**
+ * \file
+ * Deinterlacer plugin for vlc. Data structures and video filter functions.
+ *
+ * Note on i_frame_offset:
+ *
+ * This value indicates the offset between input and output frames in the
+ * currently active deinterlace algorithm. See the rationale below for why
+ * this is needed and how it is used.
+ *
+ * Valid range: 0 <= i_frame_offset < METADATA_SIZE, or
+ * i_frame_offset = CUSTOM_PTS.
+ * The special value CUSTOM_PTS is only allowed
+ * if b_double_rate is false.
+ *
+ * If CUSTOM_PTS is used, the algorithm must compute the outgoing
+ * PTSs itself, and additionally, read the TFF/BFF information
+ * itself (if it needs it) from the incoming frames.
+ *
+ * Meaning of values:
+ * 0 = output frame corresponds to the current input frame
+ * (no frame offset; default if not set),
+ * 1 = output frame corresponds to the previous input frame
+ * (e.g. Yadif and Yadif2x work like this),
+ * ...
+ *
+ * If necessary, i_frame_offset should be updated by the active deinterlace
+ * algorithm to indicate the correct delay for the *next* input frame.
+ * It does not matter at which i_order the algorithm updates this information,
+ * but the new value will only take effect upon the next call to Deinterlace()
+ * (i.e. at the next incoming frame).
+ *
+ * The first-ever frame that arrives to the filter after Open() is always
+ * handled as having i_frame_offset = 0. For the second and all subsequent
+ * frames, each algorithm is responsible for setting the offset correctly.
+ * (The default is 0, so if that is correct, there's no need to do anything.)
+ *
+ * This solution guarantees that i_frame_offset:
+ * 1) is up to date at the start of each frame,
+ * 2) does not change (as far as Deinterlace() is concerned) during
+ * a frame, and
+ * 3) does not need a special API for setting the value at the start of each
+ * input frame, before the algorithm starts rendering the (first) output
+ * frame for that input frame.
+ *
+ * The deinterlace algorithm is allowed to behave differently for different
+ * input frames. This is especially important for startup, when full history
+ * (as defined by each algorithm) is not yet available. During the first-ever
+ * input frame, it is clear that it is the only possible source for
+ * information, so i_frame_offset = 0 is necessarily correct. After that,
+ * what to do is up to each algorithm.
+ *
+ * Having the correct offset at the start of each input frame is critically
+ * important in order to:
+ * 1) Allocate the correct number of output frames for framerate doublers,
+ * and to
+ * 2) Pass correct TFF/BFF information to the algorithm.
+ *
+ * These points are important for proper soft field repeat support. This
+ * feature is used in some streams (especially NTSC) originating from film.
+ * For example, in soft NTSC telecine, the number of fields alternates
+ * as 3,2,3,2,... and the video field dominance flips every two frames (after
+ * every "3"). Also, some streams request an occasional field repeat
+ * (nb_fields = 3), after which the video field dominance flips.
+ * To render such streams correctly, the nb_fields and TFF/BFF information
+ * must be taken from the specific input frame that the algorithm intends
+ * to render.
+ *
+ * Additionally, the output PTS is automatically computed by Deinterlace()
+ * from i_frame_offset and i_order.
+ *
+ * It is possible to use the special value CUSTOM_PTS to indicate that the
+ * algorithm computes the output PTSs itself. In this case, Deinterlace()
+ * will pass them through. This special value is not valid for framerate
+ * doublers, as by definition they are field renderers, so they need to
+ * use the original field timings to work correctly. Basically, this special
+ * value is only intended for algorithms that need to perform nontrivial
+ * framerate conversions (such as IVTC).
+ */
+
+
+/*****************************************************************************
* Module descriptor
*****************************************************************************/
diff --git a/modules/video_filter/deinterlace/deinterlace.h b/modules/video_filter/deinterlace/deinterlace.h
index ecc26e0d60..355f2f4882 100644
--- a/modules/video_filter/deinterlace/deinterlace.h
+++ b/modules/video_filter/deinterlace/deinterlace.h
@@ -85,205 +85,4 @@ struct filter_sys_t
};
};
-/*****************************************************************************
- * video filter functions
- *****************************************************************************/
-
-/**
- * Top-level filtering method.
- *
- * Open() sets this up as the processing method (pf_video_filter)
- * in the filter structure.
- *
- * Note that there is no guarantee that the returned picture directly
- * corresponds to p_pic. The first few times, the filter may not even
- * return a picture, if it is still filling the history for temporal
- * filtering (although such filters often return *something* also
- * while starting up). It should be assumed that N input pictures map to
- * M output pictures, with no restrictions for N and M (except that there
- * is not much delay).
- *
- * Also, there is no guarantee that the PTS of the frame stays untouched.
- * In fact, framerate doublers automatically compute the proper PTSs for the
- * two output frames for each input frame, and IVTC does a nontrivial
- * framerate conversion (29.97 > 23.976 fps).
- *
- * Yadif has an offset of one frame between input and output, but introduces
- * no delay: the returned frame is the *previous* input frame deinterlaced,
- * complete with its original PTS.
- *
- * Finally, note that returning NULL sometimes can be normal behaviour for some
- * algorithms (e.g. IVTC).
- *
- * Currently:
- * Most algorithms: 1 -> 1, no offset
- * All framerate doublers: 1 -> 2, no offset
- * Yadif: 1 -> 1, offset of one frame
- * IVTC: 1 -> 1 or 0 (depends on whether a drop was needed)
- * with an offset of one frame (in most cases)
- * and framerate conversion.
- *
- * @param p_filter The filter instance.
- * @param p_pic The latest input picture.
- * @return Deinterlaced picture(s). Linked list of picture_t's or NULL.
- * @see Open()
- * @see filter_t
- * @see filter_sys_t
- */
-picture_t *Deinterlace( filter_t *p_filter, picture_t *p_pic );
-
-/**
- * Reads the configuration, sets up and starts the filter.
- *
- * Possible reasons for returning VLC_EGENERIC:
- * - Unsupported input chroma. See IsChromaSupported().
- * - Caller has set p_filter->b_allow_fmt_out_change to false,
- * but the algorithm chosen in the configuration
- * wants to convert the output to a format different
- * from the input. See SetFilterMethod().
- *
- * Open() is atomic: if an error occurs, the state of p_this
- * is left as it was before the call to this function.
- *
- * @param p_this The filter instance as vlc_object_t.
- * @return VLC error code
- * @retval VLC_SUCCESS All ok, filter set up and started.
- * @retval VLC_ENOMEM Memory allocation error, initialization aborted.
- * @retval VLC_EGENERIC Something went wrong, initialization aborted.
- * @see IsChromaSupported()
- * @see SetFilterMethod()
- */
-int Open( vlc_object_t *p_this );
-
-/**
- * Resets the filter state, including resetting all algorithm-specific state
- * and discarding all histories, but does not stop the filter.
- *
- * Open() sets this up as the flush method (pf_flush)
- * in the filter structure.
- *
- * @param p_filter The filter instance.
- * @see Open()
- * @see filter_t
- * @see filter_sys_t
- * @see metadata_history_t
- * @see phosphor_sys_t
- * @see ivtc_sys_t
- */
-void Flush( filter_t *p_filter );
-
-/**
- * Mouse callback for the deinterlace filter.
- *
- * Open() sets this up as the mouse callback method (pf_video_mouse)
- * in the filter structure.
- *
- * Currently, this handles the scaling of the y coordinate for algorithms
- * that halve the output height.
- *
- * @param p_filter The filter instance.
- * @param[out] p_mouse Updated mouse position data.
- * @param[in] p_old Previous mouse position data. Unused in this filter.
- * @param[in] p_new Latest mouse position data.
- * @return VLC error code; currently always VLC_SUCCESS.
- * @retval VLC_SUCCESS All ok.
- * @see Open()
- * @see filter_t
- * @see vlc_mouse_t
- */
-int Mouse( filter_t *p_filter,
- vlc_mouse_t *p_mouse,
- const vlc_mouse_t *p_old,
- const vlc_mouse_t *p_new );
-
-/**
- * Stops and uninitializes the filter, and deallocates memory.
- * @param p_this The filter instance as vlc_object_t.
- */
-void Close( vlc_object_t *p_this );
-
-/*****************************************************************************
- * Extra documentation
- *****************************************************************************/
-
-/**
- * \file
- * Deinterlacer plugin for vlc. Data structures and video filter functions.
- *
- * Note on i_frame_offset:
- *
- * This value indicates the offset between input and output frames in the
- * currently active deinterlace algorithm. See the rationale below for why
- * this is needed and how it is used.
- *
- * Valid range: 0 <= i_frame_offset < METADATA_SIZE, or
- * i_frame_offset = CUSTOM_PTS.
- * The special value CUSTOM_PTS is only allowed
- * if b_double_rate is false.
- *
- * If CUSTOM_PTS is used, the algorithm must compute the outgoing
- * PTSs itself, and additionally, read the TFF/BFF information
- * itself (if it needs it) from the incoming frames.
- *
- * Meaning of values:
- * 0 = output frame corresponds to the current input frame
- * (no frame offset; default if not set),
- * 1 = output frame corresponds to the previous input frame
- * (e.g. Yadif and Yadif2x work like this),
- * ...
- *
- * If necessary, i_frame_offset should be updated by the active deinterlace
- * algorithm to indicate the correct delay for the *next* input frame.
- * It does not matter at which i_order the algorithm updates this information,
- * but the new value will only take effect upon the next call to Deinterlace()
- * (i.e. at the next incoming frame).
- *
- * The first-ever frame that arrives to the filter after Open() is always
- * handled as having i_frame_offset = 0. For the second and all subsequent
- * frames, each algorithm is responsible for setting the offset correctly.
- * (The default is 0, so if that is correct, there's no need to do anything.)
- *
- * This solution guarantees that i_frame_offset:
- * 1) is up to date at the start of each frame,
- * 2) does not change (as far as Deinterlace() is concerned) during
- * a frame, and
- * 3) does not need a special API for setting the value at the start of each
- * input frame, before the algorithm starts rendering the (first) output
- * frame for that input frame.
- *
- * The deinterlace algorithm is allowed to behave differently for different
- * input frames. This is especially important for startup, when full history
- * (as defined by each algorithm) is not yet available. During the first-ever
- * input frame, it is clear that it is the only possible source for
- * information, so i_frame_offset = 0 is necessarily correct. After that,
- * what to do is up to each algorithm.
- *
- * Having the correct offset at the start of each input frame is critically
- * important in order to:
- * 1) Allocate the correct number of output frames for framerate doublers,
- * and to
- * 2) Pass correct TFF/BFF information to the algorithm.
- *
- * These points are important for proper soft field repeat support. This
- * feature is used in some streams (especially NTSC) originating from film.
- * For example, in soft NTSC telecine, the number of fields alternates
- * as 3,2,3,2,... and the video field dominance flips every two frames (after
- * every "3"). Also, some streams request an occasional field repeat
- * (nb_fields = 3), after which the video field dominance flips.
- * To render such streams correctly, the nb_fields and TFF/BFF information
- * must be taken from the specific input frame that the algorithm intends
- * to render.
- *
- * Additionally, the output PTS is automatically computed by Deinterlace()
- * from i_frame_offset and i_order.
- *
- * It is possible to use the special value CUSTOM_PTS to indicate that the
- * algorithm computes the output PTSs itself. In this case, Deinterlace()
- * will pass them through. This special value is not valid for framerate
- * doublers, as by definition they are field renderers, so they need to
- * use the original field timings to work correctly. Basically, this special
- * value is only intended for algorithms that need to perform nontrivial
- * framerate conversions (such as IVTC).
- */
-
#endif
More information about the vlc-commits
mailing list