git.sesse.net Git - vlc/blob - modules/video_filter/deinterlace/helpers.h

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