483ca48f67d62ba6bab49a3504a9546618af4a71
[vlc.git] / modules / video_filter / deinterlace / algo_yadif.h
1 /*****************************************************************************
2  * algo_yadif.h : Wrapper for FFmpeg's Yadif algorithm
3  *****************************************************************************
4  * Copyright (C) 2000-2011 the VideoLAN team
5  *
6  * Author: Laurent Aimar <fenrir@videolan.org>
7  *         Juha Jeronen  <juha.jeronen@jyu.fi> (soft field repeat hack)
8  *
9  * This program is free software; you can redistribute it and/or modify it
10  * under the terms of the GNU Lesser General Public License as published by
11  * the Free Software Foundation; either version 2.1 of the License, or
12  * (at your option) any later version.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17  * GNU Lesser General Public License for more details.
18  *
19  * You should have received a copy of the GNU Lesser General Public License
20  * along with this program; if not, write to the Free Software Foundation,
21  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
22  *****************************************************************************/
23
24 #ifndef VLC_DEINTERLACE_ALGO_YADIF_H
25 #define VLC_DEINTERLACE_ALGO_YADIF_H 1
26
27 /**
28  * \file
29  * Adapter to fit the Yadif (Yet Another DeInterlacing Filter) algorithm
30  * from FFmpeg into VLC. The algorithm itself is implemented in yadif.h.
31  */
32
33 /* Forward declarations */
34 struct filter_t;
35 struct picture_t;
36
37 /*****************************************************************************
38  * Functions
39  *****************************************************************************/
40
41 /**
42  * Yadif (Yet Another DeInterlacing Filter) from FFmpeg.
43  * One field is copied as-is (i_field), the other is interpolated.
44  *
45  * Comes with both interpolating and framerate doubling modes.
46  *
47  * If you do NOT want to use framerate doubling: use i_order = 0,
48  * and either 0 or 1 for i_field (keep it constant),
49  *
50  * If you DO want framerate doubling, do as instructed below.
51  *
52  * See Deinterlace() for usage examples of both modes.
53  *
54  * Needs three frames in the history buffer to operate.
55  * The first-ever frame is rendered using RenderX().
56  * The second is dropped. At the third frame, Yadif starts.
57  *
58  * Once Yadif starts, the frame that is rendered corresponds to the *previous*
59  * input frame (i_frame_offset = 1), complete with its original PTS.
60  * The latest input frame is used as the future/next frame, as reference
61  * for temporal interpolation.
62  *
63  * This wrapper adds support for soft field repeat (repeat_pict).
64  * Note that the generated "repeated" output picture is unique because
65  * of temporal interpolation.
66  *
67  * As many output frames should be requested for each input frame as is
68  * indicated by p_src->i_nb_fields. This is done by calling this function
69  * several times, first with i_order = 0, and then with all other parameters
70  * the same, but a new p_dst, increasing i_order (1 for second field,
71  * and then if i_nb_fields = 3, also i_order = 2 to get the repeated first
72  * field), and alternating i_field (starting, at i_order = 0, with the field
73  * according to p_src->b_top_field_first). See Deinterlace() for an example.
74  *
75  * @param p_filter The filter instance. Must be non-NULL.
76  * @param p_dst Output frame. Must be allocated by caller.
77  * @param p_src Input frame. Must exist.
78  * @param i_order Temporal field number: 0 = first, 1 = second, 2 = rep. first.
79  * @param i_field Keep which field? 0 = top field, 1 = bottom field.
80  * @return VLC error code (int).
81  * @retval VLC_SUCCESS The requested field was rendered into p_dst.
82  * @retval VLC_EGENERIC Frame dropped; only occurs at the second frame after start.
83  * @see Deinterlace()
84  */
85 int RenderYadif( filter_t *p_filter, picture_t *p_dst, picture_t *p_src,
86                  int i_order, int i_field );
87
88 /**
89  * Same as RenderYadif() but with no temporal references
90  */
91 int RenderYadifSingle( filter_t *p_filter, picture_t *p_dst, picture_t *p_src );
92
93 #endif