include/vlc_filter.h

   1 /*****************************************************************************
   2  * vlc_filter.h: filter related structures and functions
   3  *****************************************************************************
   4  * Copyright (C) 1999-2014 VLC authors and VideoLAN
   5  *
   6  * Authors: Gildas Bazin <gbazin@videolan.org>
   7  *          Antoine Cellerier <dionoea at videolan dot org>
   8  *          Rémi Denis-Courmont
   9  *
  10  * This program is free software; you can redistribute it and/or modify it
  11  * under the terms of the GNU Lesser General Public License as published by
  12  * the Free Software Foundation; either version 2.1 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18  * GNU Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public License
  21  * along with this program; if not, write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  23  *****************************************************************************/
  24
  25 #ifndef VLC_FILTER_H
  26 #define VLC_FILTER_H 1
  27
  28 #include <vlc_es.h>
  29
  30 /**
  31  * \defgroup filter Filters
  32  * \ingroup output
  33  * Audio, video, text filters
  34  * @{
  35  * \file
  36  * Filter modules interface
  37  */
  38
  39 typedef struct filter_owner_sys_t filter_owner_sys_t;
  40
  41 struct filter_video_callbacks
  42 {
  43     picture_t *(*buffer_new)(filter_t *);
  44 };
  45
  46 struct filter_subpicture_callbacks
  47 {
  48     subpicture_t *(*buffer_new)(filter_t *);
  49 };
  50
  51 typedef struct filter_owner_t
  52 {
  53     union
  54     {
  55         const struct filter_video_callbacks *video;
  56         const struct filter_subpicture_callbacks *sub;
  57     };
  58     void *sys;
  59 } filter_owner_t;
  60
  61 struct vlc_mouse_t;
  62
  63 /** Structure describing a filter
  64  * @warning BIG FAT WARNING : the code relies on the first 4 members of
  65  * filter_t and decoder_t to be the same, so if you have anything to add,
  66  * do it at the end of the structure.
  67  */
  68 struct filter_t
  69 {
  70     struct vlc_common_members obj;
  71
  72     /* Module properties */
  73     module_t *          p_module;
  74     void               *p_sys;
  75
  76     /* Input format */
  77     es_format_t         fmt_in;
  78
  79     /* Output format of filter */
  80     es_format_t         fmt_out;
  81     bool                b_allow_fmt_out_change;
  82
  83     /* Name of the "video filter" shortcut that is requested, can be NULL */
  84     const char *        psz_name;
  85     /* Filter configuration */
  86     config_chain_t *    p_cfg;
  87
  88     union
  89     {
  90         /** Filter a picture (video filter) */
  91         picture_t * (*pf_video_filter)( filter_t *, picture_t * );
  92
  93         /** Filter an audio block (audio filter) */
  94         block_t * (*pf_audio_filter)( filter_t *, block_t * );
  95
  96         /** Blend a subpicture onto a picture (blend) */
  97         void (*pf_video_blend)( filter_t *,  picture_t *, const picture_t *,
  98                                  int, int, int );
  99
 100         /** Generate a subpicture (sub source) */
 101         subpicture_t *(*pf_sub_source)( filter_t *, vlc_tick_t );
 102
 103         /** Filter a subpicture (sub filter) */
 104         subpicture_t *(*pf_sub_filter)( filter_t *, subpicture_t * );
 105
 106         /** Render text (text render) */
 107         int (*pf_render)( filter_t *, subpicture_region_t *,
 108                           subpicture_region_t *, const vlc_fourcc_t * );
 109     };
 110
 111     union
 112     {
 113         /* TODO: video filter drain */
 114         /** Drain (audio filter) */
 115         block_t *(*pf_audio_drain) ( filter_t * );
 116     };
 117
 118     /** Flush
 119      *
 120      * Flush (i.e. discard) any internal buffer in a video or audio filter.
 121      */
 122     void (*pf_flush)( filter_t * );
 123
 124     /** Change viewpoint
 125      *
 126      * Pass a new viewpoint to audio filters. Filters like the spatialaudio one
 127      * used for Ambisonics rendering will change its output according to this
 128      * viewpoint.
 129      */
 130     void (*pf_change_viewpoint)( filter_t *, const vlc_viewpoint_t * );
 131
 132     union
 133     {
 134         /** Filter mouse state (video filter).
 135          *
 136          * If non-NULL, you must convert from output to input formats:
 137          * - If VLC_SUCCESS is returned, the mouse state is propagated.
 138          * - Otherwise, the mouse change is not propagated.
 139          * If NULL, the mouse state is considered unchanged and will be
 140          * propagated. */
 141         int (*pf_video_mouse)( filter_t *, struct vlc_mouse_t *,
 142                                const struct vlc_mouse_t *p_old,
 143                                const struct vlc_mouse_t *p_new );
 144         int (*pf_sub_mouse)( filter_t *, const struct vlc_mouse_t *p_old,
 145                              const struct vlc_mouse_t *p_new,
 146                              const video_format_t * );
 147     };
 148
 149     /* Input attachments
 150      * XXX use filter_GetInputAttachments */
 151     int (*pf_get_attachments)( filter_t *, input_attachment_t ***, int * );
 152
 153     /** Private structure for the owner of the filter */
 154     filter_owner_t      owner;
 155 };
 156
 157 /**
 158  * This function will return a new picture usable by p_filter as an output
 159  * buffer. You have to release it using picture_Release or by returning
 160  * it to the caller as a pf_video_filter return value.
 161  * Provided for convenience.
 162  *
 163  * \param p_filter filter_t object
 164  * \return new picture on success or NULL on failure
 165  */
 166 static inline picture_t *filter_NewPicture( filter_t *p_filter )
 167 {
 168     picture_t *pic = p_filter->owner.video->buffer_new( p_filter );
 169     if( pic == NULL )
 170         msg_Warn( p_filter, "can't get output picture" );
 171     return pic;
 172 }
 173
 174 /**
 175  * Flush a filter
 176  *
 177  * This function will flush the state of a filter (audio or video).
 178  */
 179 static inline void filter_Flush( filter_t *p_filter )
 180 {
 181     if( p_filter->pf_flush != NULL )
 182         p_filter->pf_flush( p_filter );
 183 }
 184
 185 static inline void filter_ChangeViewpoint( filter_t *p_filter,
 186                                            const vlc_viewpoint_t *vp)
 187 {
 188     if( p_filter->pf_change_viewpoint != NULL )
 189         p_filter->pf_change_viewpoint( p_filter, vp );
 190 }
 191
 192 /**
 193  * This function will drain, then flush an audio filter.
 194  */
 195 static inline block_t *filter_DrainAudio( filter_t *p_filter )
 196 {
 197     if( p_filter->pf_audio_drain )
 198         return p_filter->pf_audio_drain( p_filter );
 199     else
 200         return NULL;
 201 }
 202
 203 /**
 204  * This function will return a new subpicture usable by p_filter as an output
 205  * buffer. You have to release it using subpicture_Delete or by returning it to
 206  * the caller as a pf_sub_source return value.
 207  * Provided for convenience.
 208  *
 209  * \param p_filter filter_t object
 210  * \return new subpicture
 211  */
 212 static inline subpicture_t *filter_NewSubpicture( filter_t *p_filter )
 213 {
 214     subpicture_t *subpic = p_filter->owner.sub->buffer_new( p_filter );
 215     if( subpic == NULL )
 216         msg_Warn( p_filter, "can't get output subpicture" );
 217     return subpic;
 218 }
 219
 220 /**
 221  * This function gives all input attachments at once.
 222  *
 223  * You MUST release the returned values
 224  */
 225 static inline int filter_GetInputAttachments( filter_t *p_filter,
 226                                               input_attachment_t ***ppp_attachment,
 227                                               int *pi_attachment )
 228 {
 229     if( !p_filter->pf_get_attachments )
 230         return VLC_EGENERIC;
 231     return p_filter->pf_get_attachments( p_filter,
 232                                          ppp_attachment, pi_attachment );
 233 }
 234
 235 /**
 236  * This function duplicates every variables from the filter, and adds a proxy
 237  * callback to trigger filter events from obj.
 238  *
 239  * \param restart_cb a vlc_callback_t to call if the event means restarting the
 240  * filter (i.e. an event on a non-command variable)
 241  */
 242 VLC_API void filter_AddProxyCallbacks( vlc_object_t *obj, filter_t *filter,
 243                                        vlc_callback_t restart_cb );
 244 # define filter_AddProxyCallbacks(a, b, c) \
 245     filter_AddProxyCallbacks(VLC_OBJECT(a), b, c)
 246
 247 /**
 248  * This function removes the callbacks previously added to every duplicated
 249  * variables, and removes them afterward.
 250  *
 251  * \param restart_cb the same vlc_callback_t passed to filter_AddProxyCallbacks
 252  */
 253 VLC_API void filter_DelProxyCallbacks( vlc_object_t *obj, filter_t *filter,
 254                                        vlc_callback_t restart_cb);
 255 # define filter_DelProxyCallbacks(a, b, c) \
 256     filter_DelProxyCallbacks(VLC_OBJECT(a), b, c)
 257
 258 /**
 259  * It creates a blend filter.
 260  *
 261  * Only the chroma properties of the dest format is used (chroma
 262  * type, rgb masks and shifts)
 263  */
 264 VLC_API filter_t * filter_NewBlend( vlc_object_t *, const video_format_t *p_dst_chroma ) VLC_USED;
 265
 266 /**
 267  * It configures blend filter parameters that are allowed to changed
 268  * after the creation.
 269  */
 270 VLC_API int filter_ConfigureBlend( filter_t *, int i_dst_width, int i_dst_height, const video_format_t *p_src );
 271
 272 /**
 273  * It blends a picture into another one.
 274  *
 275  * The input picture is not modified and not released.
 276  */
 277 VLC_API int filter_Blend( filter_t *, picture_t *p_dst, int i_dst_x, int i_dst_y, const picture_t *p_src, int i_alpha );
 278
 279 /**
 280  * It destroys a blend filter created by filter_NewBlend.
 281  */
 282 VLC_API void filter_DeleteBlend( filter_t * );
 283
 284 /**
 285  * Create a picture_t *(*)( filter_t *, picture_t * ) compatible wrapper
 286  * using a void (*)( filter_t *, picture_t *, picture_t * ) function
 287  *
 288  * Currently used by the chroma video filters
 289  */
 290 #define VIDEO_FILTER_WRAPPER( name )                                    \
 291     static picture_t *name ## _Filter ( filter_t *p_filter,             \
 292                                         picture_t *p_pic )              \
 293     {                                                                   \
 294         picture_t *p_outpic = filter_NewPicture( p_filter );            \
 295         if( p_outpic )                                                  \
 296         {                                                               \
 297             name( p_filter, p_pic, p_outpic );                          \
 298             picture_CopyProperties( p_outpic, p_pic );                  \
 299         }                                                               \
 300         picture_Release( p_pic );                                       \
 301         return p_outpic;                                                \
 302     }
 303
 304 /**
 305  * Filter chain management API
 306  * The filter chain management API is used to dynamically construct filters
 307  * and add them in a chain.
 308  */
 309
 310 typedef struct filter_chain_t filter_chain_t;
 311
 312 /**
 313  * Create new filter chain
 314  *
 315  * \param p_object pointer to a vlc object
 316  * \param psz_capability vlc capability of filters in filter chain
 317  * \return pointer to a filter chain
 318  */
 319 filter_chain_t * filter_chain_New( vlc_object_t *, const char *, enum es_format_category_e )
 320 VLC_USED;
 321 #define filter_chain_New( a, b, c ) filter_chain_New( VLC_OBJECT( a ), b, c )
 322
 323 /**
 324  * Creates a new video filter chain.
 325  *
 326  * \param obj pointer to parent VLC object
 327  * \param change whether to allow changing the output format
 328  * \param owner owner video buffer callbacks
 329  * \return new filter chain, or NULL on error
 330  */
 331 VLC_API filter_chain_t * filter_chain_NewVideo( vlc_object_t *obj, bool change,
 332                                                 const filter_owner_t *owner )
 333 VLC_USED;
 334 #define filter_chain_NewVideo( a, b, c ) \
 335         filter_chain_NewVideo( VLC_OBJECT( a ), b, c )
 336
 337 /**
 338  * Delete filter chain will delete all filters in the chain and free all
 339  * allocated data. The pointer to the filter chain is then no longer valid.
 340  *
 341  * \param p_chain pointer to filter chain
 342  */
 343 VLC_API void filter_chain_Delete( filter_chain_t * );
 344
 345 /**
 346  * Reset filter chain will delete all filters in the chain and
 347  * reset p_fmt_in and p_fmt_out to the new values.
 348  *
 349  * \param p_chain pointer to filter chain
 350  * \param p_fmt_in new fmt_in params, may be NULL to leave input fmt unchanged
 351  * \param p_fmt_out new fmt_out params, may be NULL to leave output fmt unchanged
 352  */
 353 VLC_API void filter_chain_Reset( filter_chain_t *, const es_format_t *, const es_format_t * );
 354
 355 /**
 356  * Append a filter to the chain.
 357  *
 358  * \param chain filter chain to append a filter to
 359  * \param name filter name
 360  * \param fmt_in filter input format
 361  * \param fmt_out filter output format
 362  * \return a pointer to the filter or NULL on error
 363  */
 364 VLC_API filter_t *filter_chain_AppendFilter(filter_chain_t *chain,
 365     const char *name, config_chain_t *cfg, const es_format_t *fmt_in,
 366     const es_format_t *fmt_out);
 367
 368 /**
 369  * Append a conversion to the chain.
 370  *
 371  * \param chain filter chain to append a filter to
 372  * \param fmt_in filter input format
 373  * \param fmt_out filter output format
 374  * \retval 0 on success
 375  * \retval -1 on failure
 376  */
 377 VLC_API int filter_chain_AppendConverter(filter_chain_t *chain,
 378     const es_format_t *fmt_in, const es_format_t *fmt_out);
 379
 380 /**
 381  * Append new filter to filter chain from string.
 382  *
 383  * \param chain filter chain to append a filter to
 384  * \param str filters chain nul-terminated string
 385  */
 386 VLC_API int filter_chain_AppendFromString(filter_chain_t *chain,
 387                                           const char *str);
 388
 389 /**
 390  * Delete filter from filter chain. This function also releases the filter
 391  * object and unloads the filter modules. The pointer to p_filter is no
 392  * longer valid after this function successfully returns.
 393  *
 394  * \param chain filter chain to remove the filter from
 395  * \param filter filter to remove from the chain and delete
 396  */
 397 VLC_API void filter_chain_DeleteFilter(filter_chain_t *chain,
 398                                        filter_t *filter);
 399
 400 /**
 401  * Checks if the filter chain is empty.
 402  *
 403  * \param chain pointer to filter chain
 404  * \return true if and only if there are no filters in this filter chain
 405  */
 406 VLC_API bool filter_chain_IsEmpty(const filter_chain_t *chain);
 407
 408 /**
 409  * Get last output format of the last element in the filter chain.
 410  *
 411  * \param chain filter chain
 412  */
 413 VLC_API const es_format_t *filter_chain_GetFmtOut(filter_chain_t *chain);
 414
 415 /**
 416  * Apply the filter chain to a video picture.
 417  *
 418  * \param chain pointer to filter chain
 419  * \param pic picture to apply filters to
 420  * \return modified picture after applying all video filters
 421  */
 422 VLC_API picture_t *filter_chain_VideoFilter(filter_chain_t *chain,
 423                                             picture_t *pic);
 424
 425 /**
 426  * Flush a video filter chain.
 427  */
 428 VLC_API void filter_chain_VideoFlush( filter_chain_t * );
 429
 430 /**
 431  * Generate subpictures from a chain of subpicture source "filters".
 432  *
 433  * \param chain filter chain
 434  * \param display_date of subpictures
 435  */
 436 void filter_chain_SubSource(filter_chain_t *chain, spu_t *,
 437                             vlc_tick_t display_date);
 438
 439 /**
 440  * Apply filter chain to subpictures.
 441  *
 442  * \param chain filter chain
 443  * \param subpic subpicture to apply filters on
 444  * \return modified subpicture after applying all subpicture filters
 445  */
 446 VLC_API subpicture_t *filter_chain_SubFilter(filter_chain_t *chain,
 447                                              subpicture_t *subpic);
 448
 449 /**
 450  * Apply the filter chain to a mouse state.
 451  *
 452  * It will be applied from the output to the input. It makes sense only
 453  * for a video filter chain.
 454  *
 455  * The vlc_mouse_t* pointers may be the same.
 456  */
 457 VLC_API int filter_chain_MouseFilter( filter_chain_t *, struct vlc_mouse_t *,
 458                                       const struct vlc_mouse_t * );
 459
 460 /**
 461  * Inform the filter chain of mouse state.
 462  *
 463  * It makes sense only for a sub source chain.
 464  */
 465 VLC_API int filter_chain_MouseEvent( filter_chain_t *,
 466                                      const struct vlc_mouse_t *,
 467                                      const video_format_t * );
 468
 469 int filter_chain_ForEach( filter_chain_t *chain,
 470                           int (*cb)( filter_t *, void * ), void *opaque );
 471
 472 /** @} */
 473 #endif /* _VLC_FILTER_H */