001da60169858ba804543945cc8ca2cd83f69a17
[vlc.git] / modules / video_filter / deinterlace / helpers.h
1 /*****************************************************************************
2  * helpers.h : Generic helper functions for the VLC deinterlacer
3  *****************************************************************************
4  * Copyright (C) 2011 VLC authors and VideoLAN
5  *
6  * Author: Juha Jeronen <juha.jeronen@jyu.fi>
7  *
8  * This program is free software; you can redistribute it and/or modify it
9  * under the terms of the GNU Lesser General Public License as published by
10  * the Free Software Foundation; either version 2.1 of the License, or
11  * (at your option) any later version.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16  * GNU Lesser General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public License
19  * along with this program; if not, write to the Free Software Foundation,
20  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
21  *****************************************************************************/
22
23 #ifndef VLC_DEINTERLACE_HELPERS_H
24 #define VLC_DEINTERLACE_HELPERS_H 1
25
26 /**
27  * \file
28  * Generic helper functions for the VLC deinterlacer, used in
29  * some of the advanced algorithms.
30  */
31
32 /* Forward declarations */
33 struct filter_t;
34 struct picture_t;
35 struct plane_t;
36
37 /**
38  * Chroma operation types for composing 4:2:0 frames.
39  * @see ComposeFrame()
40  */
41 typedef enum { CC_ALTLINE, CC_UPCONVERT, CC_SOURCE_TOP, CC_SOURCE_BOTTOM,
42                CC_MERGE } compose_chroma_t;
43
44 /**
45  * Helper function: composes a frame from the given field pair.
46  *
47  * Caller must manage allocation/deallocation of p_outpic.
48  *
49  * The inputs are full pictures (frames); only one field
50  * will be used from each.
51  *
52  * Chroma formats of the inputs must match. It is also desirable that the
53  * visible pitches of both inputs are the same, so that this will do something
54  * sensible. The pitch or visible pitch of the output does not need to match
55  * with the input; the compatible (smaller) part of the visible pitch will
56  * be filled.
57  *
58  * The i_output_chroma parameter must always be supplied, but it is only used
59  * when the chroma format of the input is detected as 4:2:0. Available modes:
60  *   - CC_ALTLINE:       Alternate line copy, like for luma. Chroma line 0
61  *                       comes from top field picture, chroma line 1 comes
62  *                       from bottom field picture, chroma line 2 from top
63  *                       field picture, and so on. This is usually the right
64  *                       choice for IVTCing NTSC DVD material, but rarely
65  *                       for any other use cases.
66  *   - CC_UPCONVERT:     The output will have 4:2:2 chroma. All 4:2:0 chroma
67  *                       data from both input fields will be used to generate
68  *                       the 4:2:2 chroma data of the output. Each output line
69  *                       will thus have independent chroma. This is a good
70  *                       choice for most purposes except IVTC, if the machine
71  *                       can handle the increased throughput. (Make sure to
72  *                       allocate a 4:2:2 output picture first!)
73  *                       This mode can also be used for converting a 4:2:0
74  *                       frame to 4:2:2 format (by passing the same input
75  *                       picture for both input fields).
76  *                       Conversions: I420, YV12 --> I422
77  *                                    J420       --> J422
78  *   - CC_SOURCE_TOP:    Copy chroma of source top field picture.
79  *                       Ignore chroma of source bottom field picture.
80  *   - CC_SOURCE_BOTTOM: Copy chroma of source bottom field picture.
81  *                       Ignore chroma of source top field picture.
82  *   - CC_MERGE:         Average the chroma of the input field pictures.
83  *                       (Note that this has no effect if the input fields
84  *                        come from the same frame.)
85  *
86  * @param p_filter The filter instance (determines input chroma).
87  * @param p_outpic Composed picture is written here. Allocated by caller.
88  * @param p_inpic_top Picture to extract the top field from.
89  * @param p_inpic_bottom Picture to extract the bottom field from.
90  * @param i_output_chroma Chroma operation mode for 4:2:0 (see function doc)
91  * @param swapped_uv_conversion Swap UV while up converting (for YV12)
92  * @see compose_chroma_t
93  * @see RenderPhosphor()
94  * @see RenderIVTC()
95  */
96 void ComposeFrame( filter_t *p_filter,
97                    picture_t *p_outpic,
98                    picture_t *p_inpic_top, picture_t *p_inpic_bottom,
99                    compose_chroma_t i_output_chroma, bool swapped_uv_conversion );
100
101 /**
102  * Helper function: Estimates the number of 8x8 blocks which have motion
103  * between the given pictures. Needed for various detectors in RenderIVTC().
104  *
105  * Number of planes and visible lines in each plane, in the inputs must match.
106  * If the visible pitches do not match, only the compatible (smaller)
107  * part will be tested.
108  *
109  * Note that the return value is NOT simply *pi_top + *pi_bot, because
110  * the fields and the full block use different motion thresholds.
111  *
112  * If you do not want the separate field scores, pass NULL for pi_top and
113  * pi_bot. This does not affect computation speed, and is only provided as
114  * a syntactic convenience.
115  *
116  * Motion in each picture plane (Y, U, V) counts separately.
117  * The sum of number of blocks with motion across all planes is returned.
118  *
119  * For 4:2:0 chroma, even-numbered chroma lines make up the "top field" for
120  * chroma, and odd-numbered chroma lines the "bottom field" for chroma.
121  * This is correct for IVTC purposes.
122  *
123  * @param[in] p_prev Previous picture
124  * @param[in] p_curr Current picture
125  * @param[out] pi_top Number of 8x8 blocks where top field has motion.
126  * @param[out] pi_bot Number of 8x8 blocks where bottom field has motion.
127  * @return Number of 8x8 blocks that have motion.
128  * @retval -1 Error: incompatible input pictures.
129  * @see TestForMotionInBlock()
130  * @see RenderIVTC()
131  */
132 int EstimateNumBlocksWithMotion( const picture_t* p_prev,
133                                  const picture_t* p_curr,
134                                  int *pi_top, int *pi_bot);
135
136 /**
137  * Helper function: estimates "how much interlaced" the given field pair is.
138  *
139  * It is allowed that p_pic_top == p_pic_bottom.
140  *
141  * If p_pic_top != p_pic_bot (fields come from different pictures), you can use
142  * ComposeFrame() to actually construct the picture if needed.
143  *
144  * Number of planes, and number of lines in each plane, in p_pic_top and
145  * p_pic_bot must match. If the visible pitches differ, only the compatible
146  * (smaller) part will be tested.
147  *
148  * Luma and chroma planes are tested in the same way. This is correct for
149  * telecined input, where in the interlaced frames also chroma alternates
150  * every chroma line, even if the chroma format is 4:2:0!
151  *
152  * This is just a raw detector that produces a score. The overall score
153  * indicating a progressive or interlaced frame may vary wildly, depending on
154  * the material, especially in anime. The scores should be compared to
155  * each other locally (in the temporal sense) to make meaningful decisions
156  * about progressive or interlaced frames.
157  *
158  * @param p_pic_top Picture to take the top field from.
159  * @param p_pic_bot Picture to take the bottom field from (same or different).
160  * @return Interlace score, >= 0. Higher values mean more interlaced.
161  * @retval -1 Error: incompatible input pictures.
162  * @see RenderIVTC()
163  * @see ComposeFrame()
164  */
165 int CalculateInterlaceScore( const picture_t* p_pic_top,
166                              const picture_t* p_pic_bot );
167
168 #endif