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

   1 /*****************************************************************************
   2  * deinterlace.h : deinterlacer plugin for vlc
   3  *****************************************************************************
   4  * Copyright (C) 2000-2011 VLC authors and VideoLAN
   5  * $Id$
   6  *
   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>
  11  *         ...and others
  12  *
  13  * This program is free software; you can redistribute it and/or modify it
  14  * under the terms of the GNU Lesser General Public License as published by
  15  * the Free Software Foundation; either version 2.1 of the License, or
  16  * (at your option) any later version.
  17  *
  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 Lesser General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU Lesser General Public License
  24  * along with this program; if not, write to the Free Software Foundation,
  25  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  26  *****************************************************************************/
  27
  28 #ifndef VLC_DEINTERLACE_H
  29 #define VLC_DEINTERLACE_H 1
  30
  31 /* Forward declarations */
  32 struct filter_t;
  33 struct picture_t;
  34 struct vlc_object_t;
  35
  36 #include <vlc_common.h>
  37 #include <vlc_mouse.h>
  38
  39 /* Local algorithm headers */
  40 #include "algo_basic.h"
  41 #include "algo_x.h"
  42 #include "algo_yadif.h"
  43 #include "algo_phosphor.h"
  44 #include "algo_ivtc.h"
  45
  46 /*****************************************************************************
  47  * Local data
  48  *****************************************************************************/
  49
  50 /** Available deinterlace modes. */
  51 static const char *const mode_list[] = {
  52     "discard", "blend", "mean", "bob", "linear", "x",
  53     "yadif", "yadif2x", "phosphor", "ivtc" };
  54
  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)") };
  59
  60 /*****************************************************************************
  61  * Data structures
  62  *****************************************************************************/
  63
  64 /**
  65  * Available deinterlace algorithms.
  66  * @see SetFilterMethod()
  67  */
  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;
  72
  73 #define METADATA_SIZE (3)
  74 /**
  75  * Metadata history structure, used for framerate doublers.
  76  * This is used for computing field duration in Deinterlace().
  77  * @see Deinterlace()
  78  */
  79 typedef struct {
  80     mtime_t pi_date[METADATA_SIZE];
  81     int     pi_nb_fields[METADATA_SIZE];
  82     bool    pb_top_field_first[METADATA_SIZE];
  83 } metadata_history_t;
  84
  85 #define HISTORY_SIZE (3)
  86 #define CUSTOM_PTS -1
  87 /**
  88  * Top-level deinterlace subsystem state.
  89  */
  90 struct filter_sys_t
  91 {
  92     const vlc_chroma_description_t *chroma;
  93
  94     uint8_t  i_mode;              /**< Deinterlace mode */
  95
  96     /* Algorithm behaviour flags */
  97     bool b_double_rate;       /**< Shall we double the framerate? */
  98     bool b_half_height;       /**< Shall be divide the height by 2 */
  99     bool b_use_frame_history; /**< Use the input frame history buffer? */
 100
 101     /** Merge routine: C, MMX, SSE, ALTIVEC, NEON, ... */
 102     void (*pf_merge) ( void *, const void *, const void *, size_t );
 103 #if defined (__i386__) || defined (__x86_64__)
 104     /** Merge finalization routine for SSE */
 105     void (*pf_end_merge) ( void );
 106 #endif
 107
 108     /**
 109      * Metadata history (PTS, nb_fields, TFF). Used for framerate doublers.
 110      * @see metadata_history_t
 111      */
 112     metadata_history_t meta;
 113
 114     /** Output frame timing / framerate doubler control
 115         (see extra documentation in deinterlace.h) */
 116     int i_frame_offset;
 117
 118     /** Input frame history buffer for algorithms with temporal filtering. */
 119     picture_t *pp_history[HISTORY_SIZE];
 120
 121     /* Algorithm-specific substructures */
 122     phosphor_sys_t phosphor; /**< Phosphor algorithm state. */
 123     ivtc_sys_t ivtc;         /**< IVTC algorithm state. */
 124 };
 125
 126 /*****************************************************************************
 127  * Filter control related internal functions for the deinterlace filter
 128  *****************************************************************************/
 129
 130 /**
 131  * Setup the deinterlace method to use.
 132  *
 133  * FIXME: extract i_chroma from p_filter automatically?
 134  *
 135  * @param p_filter The filter instance.
 136  * @param psz_method Desired method. See mode_list for available choices.
 137  * @see mode_list
 138  */
 139 void SetFilterMethod( filter_t *p_filter, const char *psz_method );
 140
 141 /**
 142  * Get the output video format of the chosen deinterlace method
 143  * for the given input video format.
 144  *
 145  * Note that each algorithm is allowed to specify its output format,
 146  * which may (for some input formats) differ from the input format.
 147  *
 148  * @param p_filter The filter instance.
 149  * @param[out] p_dst Output video format. The structure must be allocated by caller.
 150  * @param[in] p_src Input video format.
 151  * @see SetFilterMethod()
 152  */
 153 void GetOutputFormat( filter_t *p_filter,
 154                       video_format_t *p_dst,
 155                       const video_format_t *p_src );
 156
 157 /*****************************************************************************
 158  * video filter2 functions
 159  *****************************************************************************/
 160
 161 /**
 162  * Top-level filtering method.
 163  *
 164  * Open() sets this up as the processing method (pf_video_filter)
 165  * in the filter structure.
 166  *
 167  * Note that there is no guarantee that the returned picture directly
 168  * corresponds to p_pic. The first few times, the filter may not even
 169  * return a picture, if it is still filling the history for temporal
 170  * filtering (although such filters often return *something* also
 171  * while starting up). It should be assumed that N input pictures map to
 172  * M output pictures, with no restrictions for N and M (except that there
 173  * is not much delay).
 174  *
 175  * Also, there is no guarantee that the PTS of the frame stays untouched.
 176  * In fact, framerate doublers automatically compute the proper PTSs for the
 177  * two output frames for each input frame, and IVTC does a nontrivial
 178  * framerate conversion (29.97 > 23.976 fps).
 179  *
 180  * Yadif has an offset of one frame between input and output, but introduces
 181  * no delay: the returned frame is the *previous* input frame deinterlaced,
 182  * complete with its original PTS.
 183  *
 184  * Finally, note that returning NULL sometimes can be normal behaviour for some
 185  * algorithms (e.g. IVTC).
 186  *
 187  * Currently:
 188  *   Most algorithms:        1 -> 1, no offset
 189  *   All framerate doublers: 1 -> 2, no offset
 190  *   Yadif:                  1 -> 1, offset of one frame
 191  *   IVTC:                   1 -> 1 or 0 (depends on whether a drop was needed)
 192  *                                with an offset of one frame (in most cases)
 193  *                                and framerate conversion.
 194  *
 195  * @param p_filter The filter instance.
 196  * @param p_pic The latest input picture.
 197  * @return Deinterlaced picture(s). Linked list of picture_t's or NULL.
 198  * @see Open()
 199  * @see filter_t
 200  * @see filter_sys_t
 201  */
 202 picture_t *Deinterlace( filter_t *p_filter, picture_t *p_pic );
 203
 204 /**
 205  * Reads the configuration, sets up and starts the filter.
 206  *
 207  * Possible reasons for returning VLC_EGENERIC:
 208  *  - Unsupported input chroma. See IsChromaSupported().
 209  *  - Caller has set p_filter->b_allow_fmt_out_change to false,
 210  *    but the algorithm chosen in the configuration
 211  *    wants to convert the output to a format different
 212  *    from the input. See SetFilterMethod().
 213  *
 214  * Open() is atomic: if an error occurs, the state of p_this
 215  * is left as it was before the call to this function.
 216  *
 217  * @param p_this The filter instance as vlc_object_t.
 218  * @return VLC error code
 219  * @retval VLC_SUCCESS All ok, filter set up and started.
 220  * @retval VLC_ENOMEM Memory allocation error, initialization aborted.
 221  * @retval VLC_EGENERIC Something went wrong, initialization aborted.
 222  * @see IsChromaSupported()
 223  * @see SetFilterMethod()
 224  */
 225 int Open( vlc_object_t *p_this );
 226
 227 /**
 228  * Resets the filter state, including resetting all algorithm-specific state
 229  * and discarding all histories, but does not stop the filter.
 230  *
 231  * Open() sets this up as the flush method (pf_video_flush)
 232  * in the filter structure.
 233  *
 234  * @param p_filter The filter instance.
 235  * @see Open()
 236  * @see filter_t
 237  * @see filter_sys_t
 238  * @see metadata_history_t
 239  * @see phosphor_sys_t
 240  * @see ivtc_sys_t
 241  */
 242 void Flush( filter_t *p_filter );
 243
 244 /**
 245  * Mouse callback for the deinterlace filter.
 246  *
 247  * Open() sets this up as the mouse callback method (pf_video_mouse)
 248  * in the filter structure.
 249  *
 250  * Currently, this handles the scaling of the y coordinate for algorithms
 251  * that halve the output height.
 252  *
 253  * @param p_filter The filter instance.
 254  * @param[out] p_mouse Updated mouse position data.
 255  * @param[in] p_old Previous mouse position data. Unused in this filter.
 256  * @param[in] p_new Latest mouse position data.
 257  * @return VLC error code; currently always VLC_SUCCESS.
 258  * @retval VLC_SUCCESS All ok.
 259  * @see Open()
 260  * @see filter_t
 261  * @see vlc_mouse_t
 262  */
 263 int Mouse( filter_t *p_filter,
 264            vlc_mouse_t *p_mouse,
 265            const vlc_mouse_t *p_old,
 266            const vlc_mouse_t *p_new );
 267
 268 /**
 269  * Stops and uninitializes the filter, and deallocates memory.
 270  * @param p_this The filter instance as vlc_object_t.
 271  */
 272 void Close( vlc_object_t *p_this );
 273
 274 /*****************************************************************************
 275  * Extra documentation
 276  *****************************************************************************/
 277
 278 /**
 279  * \file
 280  * Deinterlacer plugin for vlc. Data structures and video filter2 functions.
 281  *
 282  * Note on i_frame_offset:
 283  *
 284  * This value indicates the offset between input and output frames in the
 285  * currently active deinterlace algorithm. See the rationale below for why
 286  * this is needed and how it is used.
 287  *
 288  * Valid range: 0 <= i_frame_offset < METADATA_SIZE, or
 289  *              i_frame_offset = CUSTOM_PTS.
 290  *              The special value CUSTOM_PTS is only allowed
 291  *              if b_double_rate is false.
 292  *
 293  *              If CUSTOM_PTS is used, the algorithm must compute the outgoing
 294  *              PTSs itself, and additionally, read the TFF/BFF information
 295  *              itself (if it needs it) from the incoming frames.
 296  *
 297  * Meaning of values:
 298  * 0 = output frame corresponds to the current input frame
 299  *     (no frame offset; default if not set),
 300  * 1 = output frame corresponds to the previous input frame
 301  *     (e.g. Yadif and Yadif2x work like this),
 302  * ...
 303  *
 304  * If necessary, i_frame_offset should be updated by the active deinterlace
 305  * algorithm to indicate the correct delay for the *next* input frame.
 306  * It does not matter at which i_order the algorithm updates this information,
 307  * but the new value will only take effect upon the next call to Deinterlace()
 308  * (i.e. at the next incoming frame).
 309  *
 310  * The first-ever frame that arrives to the filter after Open() is always
 311  * handled as having i_frame_offset = 0. For the second and all subsequent
 312  * frames, each algorithm is responsible for setting the offset correctly.
 313  * (The default is 0, so if that is correct, there's no need to do anything.)
 314  *
 315  * This solution guarantees that i_frame_offset:
 316  *   1) is up to date at the start of each frame,
 317  *   2) does not change (as far as Deinterlace() is concerned) during
 318  *      a frame, and
 319  *   3) does not need a special API for setting the value at the start of each
 320  *      input frame, before the algorithm starts rendering the (first) output
 321  *      frame for that input frame.
 322  *
 323  * The deinterlace algorithm is allowed to behave differently for different
 324  * input frames. This is especially important for startup, when full history
 325  * (as defined by each algorithm) is not yet available. During the first-ever
 326  * input frame, it is clear that it is the only possible source for
 327  * information, so i_frame_offset = 0 is necessarily correct. After that,
 328  * what to do is up to each algorithm.
 329  *
 330  * Having the correct offset at the start of each input frame is critically
 331  * important in order to:
 332  *   1) Allocate the correct number of output frames for framerate doublers,
 333  *      and to
 334  *   2) Pass correct TFF/BFF information to the algorithm.
 335  *
 336  * These points are important for proper soft field repeat support. This
 337  * feature is used in some streams (especially NTSC) originating from film.
 338  * For example, in soft NTSC telecine, the number of fields alternates
 339  * as 3,2,3,2,... and the video field dominance flips every two frames (after
 340  * every "3"). Also, some streams request an occasional field repeat
 341  * (nb_fields = 3), after which the video field dominance flips.
 342  * To render such streams correctly, the nb_fields and TFF/BFF information
 343  * must be taken from the specific input frame that the algorithm intends
 344  * to render.
 345  *
 346  * Additionally, the output PTS is automatically computed by Deinterlace()
 347  * from i_frame_offset and i_order.
 348  *
 349  * It is possible to use the special value CUSTOM_PTS to indicate that the
 350  * algorithm computes the output PTSs itself. In this case, Deinterlace()
 351  * will pass them through. This special value is not valid for framerate
 352  * doublers, as by definition they are field renderers, so they need to
 353  * use the original field timings to work correctly. Basically, this special
 354  * value is only intended for algorithms that need to perform nontrivial
 355  * framerate conversions (such as IVTC).
 356  */
 357
 358 #endif