1 /*****************************************************************************
2 * deinterlace.h : deinterlacer plugin for vlc
3 *****************************************************************************
4 * Copyright (C) 2000-2011 the VideoLAN team
7 * Author: Sam Hocevar <sam@zoy.org>
8 * Christophe Massiot <massiot@via.ecp.fr>
9 * Laurent Aimar <fenrir@videolan.org>
10 * Juha Jeronen <juha.jeronen@jyu.fi>
13 * This program is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2 of the License, or
16 * (at your option) any later version.
18 * This program is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU General Public License for more details.
23 * You should have received a copy of the GNU General Public License
24 * along with this program; if not, write to the Free Software
25 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
26 *****************************************************************************/
28 #ifndef VLC_DEINTERLACE_H
29 #define VLC_DEINTERLACE_H 1
31 /* Forward declarations */
36 #include <vlc_common.h>
37 #include <vlc_mouse.h>
39 /* Local algorithm headers */
40 #include "algo_basic.h"
42 #include "algo_yadif.h"
43 #include "algo_phosphor.h"
44 #include "algo_ivtc.h"
46 /*****************************************************************************
48 *****************************************************************************/
50 /** Available deinterlace modes. */
51 static const char *const mode_list[] = {
52 "discard", "blend", "mean", "bob", "linear", "x",
53 "yadif", "yadif2x", "phosphor", "ivtc" };
55 /** User labels for the available deinterlace modes. */
56 static const char *const mode_list_text[] = {
57 N_("Discard"), N_("Blend"), N_("Mean"), N_("Bob"), N_("Linear"), "X",
58 "Yadif", "Yadif (2x)", N_("Phosphor"), N_("Film NTSC (IVTC)") };
60 /*****************************************************************************
62 *****************************************************************************/
65 * Available deinterlace algorithms.
66 * @see SetFilterMethod()
68 typedef enum { DEINTERLACE_DISCARD, DEINTERLACE_MEAN, DEINTERLACE_BLEND,
69 DEINTERLACE_BOB, DEINTERLACE_LINEAR, DEINTERLACE_X,
70 DEINTERLACE_YADIF, DEINTERLACE_YADIF2X, DEINTERLACE_PHOSPHOR,
71 DEINTERLACE_IVTC } deinterlace_mode;
73 #define METADATA_SIZE (3)
75 * Metadata history structure, used for framerate doublers.
76 * This is used for computing field duration in Deinterlace().
80 mtime_t pi_date[METADATA_SIZE];
81 int pi_nb_fields[METADATA_SIZE];
82 bool pb_top_field_first[METADATA_SIZE];
85 #define HISTORY_SIZE (3)
88 * Top-level deinterlace subsystem state.
92 int i_mode; /**< Deinterlace mode */
94 /* Algorithm behaviour flags */
95 bool b_double_rate; /**< Shall we double the framerate? */
96 bool b_half_height; /**< Shall be divide the height by 2 */
97 bool b_use_frame_history; /**< Use the input frame history buffer? */
99 /** Merge routine: C, MMX, SSE, ALTIVEC, NEON, ... */
100 void (*pf_merge) ( void *, const void *, const void *, size_t );
101 /** Merge finalization routine: C, MMX, SSE, ALTIVEC, NEON, ... */
102 void (*pf_end_merge) ( void );
105 * Metadata history (PTS, nb_fields, TFF). Used for framerate doublers.
106 * @see metadata_history_t
108 metadata_history_t meta;
110 /** Output frame timing / framerate doubler control
111 (see extra documentation in deinterlace.h) */
114 /** Input frame history buffer for algorithms with temporal filtering. */
115 picture_t *pp_history[HISTORY_SIZE];
117 /* Algorithm-specific substructures */
118 phosphor_sys_t phosphor; /**< Phosphor algorithm state. */
119 ivtc_sys_t ivtc; /**< IVTC algorithm state. */
122 /*****************************************************************************
123 * Filter control related internal functions for the deinterlace filter
124 *****************************************************************************/
127 * Setup the deinterlace method to use.
129 * FIXME: extract i_chroma from p_filter automatically?
131 * @param p_filter The filter instance.
132 * @param psz_method Desired method. See mode_list for available choices.
133 * @param i_chroma Input chroma. Set this to p_filter->fmt_in.video.i_chroma.
136 void SetFilterMethod( filter_t *p_filter, const char *psz_method,
137 vlc_fourcc_t i_chroma );
140 * Get the output video format of the chosen deinterlace method
141 * for the given input video format.
143 * Note that each algorithm is allowed to specify its output format,
144 * which may (for some input formats) differ from the input format.
146 * @param p_filter The filter instance.
147 * @param[out] p_dst Output video format. The structure must be allocated by caller.
148 * @param[in] p_src Input video format.
149 * @see SetFilterMethod()
151 void GetOutputFormat( filter_t *p_filter,
152 video_format_t *p_dst,
153 const video_format_t *p_src );
156 * Returns whether the specified chroma is implemented in the deinterlace
159 * Currently, supported chromas are I420, J420 (4:2:0 full scale),
160 * YV12 (like I420, but YVU), I422 and J422.
162 * Note for deinterlace hackers: adding support for a new chroma typically
163 * requires changes to all low-level functions across all the algorithms.
167 bool IsChromaSupported( vlc_fourcc_t i_chroma );
169 /*****************************************************************************
170 * video filter2 functions
171 *****************************************************************************/
174 * Top-level filtering method.
176 * Open() sets this up as the processing method (pf_video_filter)
177 * in the filter structure.
179 * Note that there is no guarantee that the returned picture directly
180 * corresponds to p_pic. The first few times, the filter may not even
181 * return a picture, if it is still filling the history for temporal
182 * filtering (although such filters often return *something* also
183 * while starting up). It should be assumed that N input pictures map to
184 * M output pictures, with no restrictions for N and M (except that there
185 * is not much delay).
187 * Also, there is no guarantee that the PTS of the frame stays untouched.
188 * In fact, framerate doublers automatically compute the proper PTSs for the
189 * two output frames for each input frame, and IVTC does a nontrivial
190 * framerate conversion (29.97 > 23.976 fps).
192 * Yadif has an offset of one frame between input and output, but introduces
193 * no delay: the returned frame is the *previous* input frame deinterlaced,
194 * complete with its original PTS.
196 * Finally, note that returning NULL sometimes can be normal behaviour for some
197 * algorithms (e.g. IVTC).
200 * Most algorithms: 1 -> 1, no offset
201 * All framerate doublers: 1 -> 2, no offset
202 * Yadif: 1 -> 1, offset of one frame
203 * IVTC: 1 -> 1 or 0 (depends on whether a drop was needed)
204 * with an offset of one frame (in most cases)
205 * and framerate conversion.
207 * @param p_filter The filter instance.
208 * @param p_pic The latest input picture.
209 * @return Deinterlaced picture(s). Linked list of picture_t's or NULL.
214 picture_t *Deinterlace( filter_t *p_filter, picture_t *p_pic );
217 * Reads the configuration, sets up and starts the filter.
219 * Possible reasons for returning VLC_EGENERIC:
220 * - Unsupported input chroma. See IsChromaSupported().
221 * - Caller has set p_filter->b_allow_fmt_out_change to false,
222 * but the algorithm chosen in the configuration
223 * wants to convert the output to a format different
224 * from the input. See SetFilterMethod().
226 * Open() is atomic: if an error occurs, the state of p_this
227 * is left as it was before the call to this function.
229 * @param p_this The filter instance as vlc_object_t.
230 * @return VLC error code
231 * @retval VLC_SUCCESS All ok, filter set up and started.
232 * @retval VLC_ENOMEM Memory allocation error, initialization aborted.
233 * @retval VLC_EGENERIC Something went wrong, initialization aborted.
234 * @see IsChromaSupported()
235 * @see SetFilterMethod()
237 int Open( vlc_object_t *p_this );
240 * Resets the filter state, including resetting all algorithm-specific state
241 * and discarding all histories, but does not stop the filter.
243 * Open() sets this up as the flush method (pf_video_flush)
244 * in the filter structure.
246 * @param p_filter The filter instance.
250 * @see metadata_history_t
251 * @see phosphor_sys_t
254 void Flush( filter_t *p_filter );
257 * Mouse callback for the deinterlace filter.
259 * Open() sets this up as the mouse callback method (pf_video_mouse)
260 * in the filter structure.
262 * Currently, this handles the scaling of the y coordinate for algorithms
263 * that halve the output height.
265 * @param p_filter The filter instance.
266 * @param[out] p_mouse Updated mouse position data.
267 * @param[in] p_old Previous mouse position data. Unused in this filter.
268 * @param[in] p_new Latest mouse position data.
269 * @return VLC error code; currently always VLC_SUCCESS.
270 * @retval VLC_SUCCESS All ok.
275 int Mouse( filter_t *p_filter,
276 vlc_mouse_t *p_mouse,
277 const vlc_mouse_t *p_old,
278 const vlc_mouse_t *p_new );
281 * Stops and uninitializes the filter, and deallocates memory.
282 * @param p_this The filter instance as vlc_object_t.
284 void Close( vlc_object_t *p_this );
286 /*****************************************************************************
287 * Extra documentation
288 *****************************************************************************/
292 * Deinterlacer plugin for vlc. Data structures and video filter2 functions.
294 * Note on i_frame_offset:
296 * This value indicates the offset between input and output frames in the
297 * currently active deinterlace algorithm. See the rationale below for why
298 * this is needed and how it is used.
300 * Valid range: 0 <= i_frame_offset < METADATA_SIZE, or
301 * i_frame_offset = CUSTOM_PTS.
302 * The special value CUSTOM_PTS is only allowed
303 * if b_double_rate is false.
305 * If CUSTOM_PTS is used, the algorithm must compute the outgoing
306 * PTSs itself, and additionally, read the TFF/BFF information
307 * itself (if it needs it) from the incoming frames.
310 * 0 = output frame corresponds to the current input frame
311 * (no frame offset; default if not set),
312 * 1 = output frame corresponds to the previous input frame
313 * (e.g. Yadif and Yadif2x work like this),
316 * If necessary, i_frame_offset should be updated by the active deinterlace
317 * algorithm to indicate the correct delay for the *next* input frame.
318 * It does not matter at which i_order the algorithm updates this information,
319 * but the new value will only take effect upon the next call to Deinterlace()
320 * (i.e. at the next incoming frame).
322 * The first-ever frame that arrives to the filter after Open() is always
323 * handled as having i_frame_offset = 0. For the second and all subsequent
324 * frames, each algorithm is responsible for setting the offset correctly.
325 * (The default is 0, so if that is correct, there's no need to do anything.)
327 * This solution guarantees that i_frame_offset:
328 * 1) is up to date at the start of each frame,
329 * 2) does not change (as far as Deinterlace() is concerned) during
331 * 3) does not need a special API for setting the value at the start of each
332 * input frame, before the algorithm starts rendering the (first) output
333 * frame for that input frame.
335 * The deinterlace algorithm is allowed to behave differently for different
336 * input frames. This is especially important for startup, when full history
337 * (as defined by each algorithm) is not yet available. During the first-ever
338 * input frame, it is clear that it is the only possible source for
339 * information, so i_frame_offset = 0 is necessarily correct. After that,
340 * what to do is up to each algorithm.
342 * Having the correct offset at the start of each input frame is critically
343 * important in order to:
344 * 1) Allocate the correct number of output frames for framerate doublers,
346 * 2) Pass correct TFF/BFF information to the algorithm.
348 * These points are important for proper soft field repeat support. This
349 * feature is used in some streams (especially NTSC) originating from film.
350 * For example, in soft NTSC telecine, the number of fields alternates
351 * as 3,2,3,2,... and the video field dominance flips every two frames (after
352 * every "3"). Also, some streams request an occasional field repeat
353 * (nb_fields = 3), after which the video field dominance flips.
354 * To render such streams correctly, the nb_fields and TFF/BFF information
355 * must be taken from the specific input frame that the algorithm intends
358 * Additionally, the output PTS is automatically computed by Deinterlace()
359 * from i_frame_offset and i_order.
361 * It is possible to use the special value CUSTOM_PTS to indicate that the
362 * algorithm computes the output PTSs itself. In this case, Deinterlace()
363 * will pass them through. This special value is not valid for framerate
364 * doublers, as by definition they are field renderers, so they need to
365 * use the original field timings to work correctly. Basically, this special
366 * value is only intended for algorithms that need to perform nontrivial
367 * framerate conversions (such as IVTC).