VLC  4.0.0-dev
vlc_filter.h
Go to the documentation of this file.
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 #include <vlc_picture.h>
30 
31 /**
32  * \defgroup filter Filters
33  * \ingroup output
34  * Audio, video, text filters
35  * @{
36  * \file
37  * Filter modules interface
38  */
39 
41 {
42  picture_t *(*buffer_new)(filter_t *);
43 };
44 
46 {
47  subpicture_t *(*buffer_new)(filter_t *);
48 };
49 
50 typedef struct filter_owner_t
51 {
52  union
53  {
54  const struct filter_video_callbacks *video;
55  const struct filter_subpicture_callbacks *sub;
56  };
57  void *sys;
59 
60 struct vlc_mouse_t;
61 
62 /** Structure describing a filter
63  * @warning BIG FAT WARNING : the code relies on the first 4 members of
64  * filter_t and decoder_t to be the same, so if you have anything to add,
65  * do it at the end of the structure.
66  */
67 struct filter_t
68 {
69  struct vlc_object_t obj;
70 
71  /* Module properties */
72  module_t * p_module;
73  void *p_sys;
74 
75  /* Input format */
76  es_format_t fmt_in;
77 
78  /* Output format of filter */
79  es_format_t fmt_out;
80  bool b_allow_fmt_out_change;
81 
82  /* Name of the "video filter" shortcut that is requested, can be NULL */
83  const char * psz_name;
84  /* Filter configuration */
85  config_chain_t * p_cfg;
86 
87  union
88  {
89  /** Filter a picture (video filter) */
90  picture_t * (*pf_video_filter)( filter_t *, picture_t * );
91 
92  /** Filter an audio block (audio filter) */
93  block_t * (*pf_audio_filter)( filter_t *, block_t * );
94 
95  /** Blend a subpicture onto a picture (blend) */
96  void (*pf_video_blend)( filter_t *, picture_t *, const picture_t *,
97  int, int, int );
98 
99  /** Generate a subpicture (sub source) */
100  subpicture_t *(*pf_sub_source)( filter_t *, vlc_tick_t );
102  /** Filter a subpicture (sub filter) */
103  subpicture_t *(*pf_sub_filter)( filter_t *, subpicture_t * );
105  /** Render text (text render) */
106  int (*pf_render)( filter_t *, subpicture_region_t *,
107  subpicture_region_t *, const vlc_fourcc_t * );
108  };
109 
110  union
111  {
112  /* TODO: video filter drain */
113  /** Drain (audio filter) */
114  block_t *(*pf_audio_drain) ( filter_t * );
115  };
116 
117  /** Flush
118  *
119  * Flush (i.e. discard) any internal buffer in a video or audio filter.
120  */
121  void (*pf_flush)( filter_t * );
123  /** Change viewpoint
124  *
125  * Pass a new viewpoint to audio filters. Filters like the spatialaudio one
126  * used for Ambisonics rendering will change its output according to this
127  * viewpoint.
128  */
129  void (*pf_change_viewpoint)( filter_t *, const vlc_viewpoint_t * );
131  union
132  {
133  /** Filter mouse state (video filter).
134  *
135  * If non-NULL, you must convert from output to input formats:
136  * - If VLC_SUCCESS is returned, the mouse state is propagated.
137  * - Otherwise, the mouse change is not propagated.
138  * If NULL, the mouse state is considered unchanged and will be
139  * propagated. */
140  int (*pf_video_mouse)( filter_t *, struct vlc_mouse_t *,
141  const struct vlc_mouse_t *p_old,
142  const struct vlc_mouse_t *p_new );
143  };
144 
145  /* Input attachments
146  * XXX use filter_GetInputAttachments */
147  int (*pf_get_attachments)( filter_t *, input_attachment_t ***, int * );
149  /** Private structure for the owner of the filter */
150  filter_owner_t owner;
151 };
152 
153 /**
154  * This function will return a new picture usable by p_filter as an output
155  * buffer. You have to release it using picture_Release or by returning
156  * it to the caller as a pf_video_filter return value.
157  * Provided for convenience.
158  *
159  * \param p_filter filter_t object
160  * \return new picture on success or NULL on failure
161  */
162 static inline picture_t *filter_NewPicture( filter_t *p_filter )
163 {
164  picture_t *pic = NULL;
165  if ( p_filter->owner.video != NULL && p_filter->owner.video->buffer_new != NULL)
166  pic = p_filter->owner.video->buffer_new( p_filter );
167  if ( pic == NULL )
168  {
169  // legacy filter owners not setting a default filter_allocator
170  pic = picture_NewFromFormat( &p_filter->fmt_out.video );
171  }
172  if( pic == NULL )
173  msg_Warn( p_filter, "can't get output picture" );
174  return pic;
175 }
176 
177 /**
178  * Flush a filter
179  *
180  * This function will flush the state of a filter (audio or video).
181  */
182 static inline void filter_Flush( filter_t *p_filter )
183 {
184  if( p_filter->pf_flush != NULL )
185  p_filter->pf_flush( p_filter );
186 }
187 
188 static inline void filter_ChangeViewpoint( filter_t *p_filter,
189  const vlc_viewpoint_t *vp)
190 {
191  if( p_filter->pf_change_viewpoint != NULL )
192  p_filter->pf_change_viewpoint( p_filter, vp );
193 }
194 
195 /**
196  * This function will drain, then flush an audio filter.
197  */
198 static inline block_t *filter_DrainAudio( filter_t *p_filter )
199 {
200  if( p_filter->pf_audio_drain )
201  return p_filter->pf_audio_drain( p_filter );
202  else
203  return NULL;
204 }
205 
206 /**
207  * This function will return a new subpicture usable by p_filter as an output
208  * buffer. You have to release it using subpicture_Delete or by returning it to
209  * the caller as a pf_sub_source return value.
210  * Provided for convenience.
211  *
212  * \param p_filter filter_t object
213  * \return new subpicture
214  */
215 static inline subpicture_t *filter_NewSubpicture( filter_t *p_filter )
216 {
217  subpicture_t *subpic = p_filter->owner.sub->buffer_new( p_filter );
218  if( subpic == NULL )
219  msg_Warn( p_filter, "can't get output subpicture" );
220  return subpic;
221 }
222 
223 /**
224  * This function gives all input attachments at once.
225  *
226  * You MUST release the returned values
227  */
228 static inline int filter_GetInputAttachments( filter_t *p_filter,
229  input_attachment_t ***ppp_attachment,
230  int *pi_attachment )
231 {
232  if( !p_filter->pf_get_attachments )
233  return VLC_EGENERIC;
234  return p_filter->pf_get_attachments( p_filter,
235  ppp_attachment, pi_attachment );
236 }
237 
238 /**
239  * This function duplicates every variables from the filter, and adds a proxy
240  * callback to trigger filter events from obj.
241  *
242  * \param restart_cb a vlc_callback_t to call if the event means restarting the
243  * filter (i.e. an event on a non-command variable)
244  */
246  vlc_callback_t restart_cb );
247 # define filter_AddProxyCallbacks(a, b, c) \
248  filter_AddProxyCallbacks(VLC_OBJECT(a), b, c)
249 
250 /**
251  * This function removes the callbacks previously added to every duplicated
252  * variables, and removes them afterward.
253  *
254  * \param restart_cb the same vlc_callback_t passed to filter_AddProxyCallbacks
255  */
257  vlc_callback_t restart_cb);
258 # define filter_DelProxyCallbacks(a, b, c) \
259  filter_DelProxyCallbacks(VLC_OBJECT(a), b, c)
260 
261 typedef filter_t vlc_blender_t;
263 /**
264  * It creates a blend filter.
265  *
266  * Only the chroma properties of the dest format is used (chroma
267  * type, rgb masks and shifts)
268  */
270 
271 /**
272  * It configures blend filter parameters that are allowed to changed
273  * after the creation.
274  */
275 VLC_API int filter_ConfigureBlend( vlc_blender_t *, int i_dst_width, int i_dst_height, const video_format_t *p_src );
276 
277 /**
278  * It blends a picture into another one.
279  *
280  * The input picture is not modified and not released.
281  */
282 VLC_API int filter_Blend( vlc_blender_t *, picture_t *p_dst, int i_dst_x, int i_dst_y, const picture_t *p_src, int i_alpha );
283 
284 /**
285  * It destroys a blend filter created by filter_NewBlend.
286  */
288 
289 /**
290  * Create a picture_t *(*)( filter_t *, picture_t * ) compatible wrapper
291  * using a void (*)( filter_t *, picture_t *, picture_t * ) function
292  *
293  * Currently used by the chroma video filters
294  */
295 #define VIDEO_FILTER_WRAPPER( name ) \
296  static picture_t *name ## _Filter ( filter_t *p_filter, \
297  picture_t *p_pic ) \
298  { \
299  picture_t *p_outpic = filter_NewPicture( p_filter ); \
300  if( p_outpic ) \
301  { \
302  name( p_filter, p_pic, p_outpic ); \
303  picture_CopyProperties( p_outpic, p_pic ); \
304  } \
305  picture_Release( p_pic ); \
306  return p_outpic; \
307  }
308 
309 /**
310  * Filter chain management API
311  * The filter chain management API is used to dynamically construct filters
312  * and add them in a chain.
313  */
314 
315 typedef struct filter_chain_t filter_chain_t;
317 /**
318  * Create new filter chain
319  *
320  * \param obj pointer to a vlc object
321  * \param psz_capability vlc capability of filters in filter chain
322  * \return pointer to a filter chain
323  */
324 filter_chain_t * filter_chain_NewSPU( vlc_object_t *obj, const char *psz_capability )
325 VLC_USED;
326 #define filter_chain_NewSPU( a, b ) filter_chain_NewSPU( VLC_OBJECT( a ), b )
328 /**
329  * Creates a new video filter chain.
330  *
331  * \param obj pointer to parent VLC object
332  * \param change whether to allow changing the output format
333  * \param owner owner video buffer callbacks
334  * \return new filter chain, or NULL on error
335  */
337  const filter_owner_t *owner )
338 VLC_USED;
339 #define filter_chain_NewVideo( a, b, c ) \
340  filter_chain_NewVideo( VLC_OBJECT( a ), b, c )
341 
342 /**
343  * Delete filter chain will delete all filters in the chain and free all
344  * allocated data. The pointer to the filter chain is then no longer valid.
345  *
346  * \param p_chain pointer to filter chain
347  */
349 
350 /**
351  * Reset filter chain will delete all filters in the chain and
352  * reset p_fmt_in and p_fmt_out to the new values.
353  *
354  * \param p_chain pointer to filter chain
355  * \param p_fmt_in new fmt_in params
356  * \param p_fmt_out new fmt_out params
357  */
359 
360 /**
361  * Remove all existing filters
362  *
363  * \param p_chain pointer to filter chain
364  */
366 
367 /**
368  * Append a filter to the chain.
369  *
370  * \param chain filter chain to append a filter to
371  * \param name filter name
372  * \param fmt_in filter input format
373  * \param fmt_out filter output format
374  * \return a pointer to the filter or NULL on error
375  */
377  const char *name, config_chain_t *cfg, const es_format_t *fmt_in,
378  const es_format_t *fmt_out);
379 
380 /**
381  * Append a conversion to the chain.
382  *
383  * \param chain filter chain to append a filter to
384  * \param fmt_in filter input format
385  * \param fmt_out filter output format
386  * \retval 0 on success
387  * \retval -1 on failure
388  */
390  const es_format_t *fmt_in, const es_format_t *fmt_out);
391 
392 /**
393  * Append new filter to filter chain from string.
394  *
395  * \param chain filter chain to append a filter to
396  * \param str filters chain nul-terminated string
397  */
399  const char *str);
400 
401 /**
402  * Delete filter from filter chain. This function also releases the filter
403  * object and unloads the filter modules. The pointer to p_filter is no
404  * longer valid after this function successfully returns.
405  *
406  * \param chain filter chain to remove the filter from
407  * \param filter filter to remove from the chain and delete
408  */
410  filter_t *filter);
411 
412 /**
413  * Checks if the filter chain is empty.
414  *
415  * \param chain pointer to filter chain
416  * \return true if and only if there are no filters in this filter chain
417  */
418 VLC_API bool filter_chain_IsEmpty(const filter_chain_t *chain);
419 
420 /**
421  * Get last output format of the last element in the filter chain.
422  *
423  * \param chain filter chain
424  */
426 
427 /**
428  * Apply the filter chain to a video picture.
429  *
430  * \param chain pointer to filter chain
431  * \param pic picture to apply filters to
432  * \return modified picture after applying all video filters
433  */
435  picture_t *pic);
436 
437 /**
438  * Flush a video filter chain.
439  */
441 
442 /**
443  * Generate subpictures from a chain of subpicture source "filters".
444  *
445  * \param chain filter chain
446  * \param display_date of subpictures
447  */
449  vlc_tick_t display_date);
450 
451 /**
452  * Apply filter chain to subpictures.
453  *
454  * \param chain filter chain
455  * \param subpic subpicture to apply filters on
456  * \return modified subpicture after applying all subpicture filters
457  */
459  subpicture_t *subpic);
460 
461 /**
462  * Apply the filter chain to a mouse state.
463  *
464  * It will be applied from the output to the input. It makes sense only
465  * for a video filter chain.
466  *
467  * The vlc_mouse_t* pointers may be the same.
468  */
470  const struct vlc_mouse_t * );
471 
473  int (*cb)( filter_t *, void * ), void *opaque );
474 
475 /** @} */
476 #endif /* _VLC_FILTER_H */
Definition: vlc_input.h:160
This file defines picture structures and functions in vlc.
const es_format_t * filter_chain_GetFmtOut(const filter_chain_t *chain)
Get last output format of the last element in the filter chain.
Definition: filter_chain.c:390
static int filter_GetInputAttachments(filter_t *p_filter, input_attachment_t ***ppp_attachment, int *pi_attachment)
This function gives all input attachments at once.
Definition: vlc_filter.h:229
void filter_chain_VideoFlush(filter_chain_t *)
Flush a video filter chain.
Definition: filter_chain.c:444
int filter_chain_ForEach(filter_chain_t *chain, int(*cb)(filter_t *, void *), void *opaque)
Definition: filter_chain.c:373
Video picture.
Definition: vlc_picture.h:126
filter_owner_t owner
Private structure for the owner of the filter.
Definition: vlc_filter.h:151
es_format_t fmt_out
Definition: vlc_filter.h:80
#define filter_chain_NewSPU(a, b)
Definition: vlc_filter.h:327
Video subtitle region.
Definition: vlc_subpicture.h:59
int(* pf_get_attachments)(filter_t *, input_attachment_t ***, int *)
Definition: vlc_filter.h:148
void(* pf_change_viewpoint)(filter_t *, const vlc_viewpoint_t *)
Change viewpoint.
Definition: vlc_filter.h:130
block_t *(* pf_audio_drain)(filter_t *)
Drain (audio filter)
Definition: vlc_filter.h:115
es_format_t fmt_in
Chain input format (constant)
Definition: filter_chain.c:53
int filter_chain_AppendFromString(filter_chain_t *chain, const char *str)
Append new filter to filter chain from string.
Definition: filter_chain.c:328
Video subtitle.
Definition: vlc_subpicture.h:166
void filter_DeleteBlend(vlc_blender_t *)
It destroys a blend filter created by filter_NewBlend.
Definition: filter.c:171
Internal module descriptor.
Definition: modules.h:75
subpicture_t * filter_chain_SubFilter(filter_chain_t *chain, subpicture_t *subpic)
Apply filter chain to subpictures.
Definition: filter_chain.c:469
subpicture_t *(* buffer_new)(filter_t *)
Definition: vlc_filter.h:48
#define msg_Warn(p_this,...)
Definition: vlc_messages.h:104
static block_t * filter_DrainAudio(filter_t *p_filter)
This function will drain, then flush an audio filter.
Definition: vlc_filter.h:199
picture_t * filter_chain_VideoFilter(filter_chain_t *chain, picture_t *pic)
Apply the filter chain to a video picture.
Definition: filter_chain.c:421
static picture_t * filter_NewPicture(filter_t *p_filter)
This function will return a new picture usable by p_filter as an output buffer.
Definition: vlc_filter.h:163
int64_t vlc_tick_t
High precision date or time interval.
Definition: vlc_tick.h:45
Definition: vlc_configuration.h:331
uint32_t vlc_fourcc_t
Definition: fourcc_gen.c:33
void filter_chain_Reset(filter_chain_t *, const es_format_t *, const es_format_t *)
Reset filter chain will delete all filters in the chain and reset p_fmt_in and p_fmt_out to the new v...
Definition: filter_chain.c:173
Viewpoints.
Definition: vlc_viewpoint.h:41
Definition: vlc_es.h:617
bool filter_chain_IsEmpty(const filter_chain_t *chain)
Checks if the filter chain is empty.
Definition: filter_chain.c:385
void filter_chain_DeleteFilter(filter_chain_t *chain, filter_t *filter)
Delete filter from filter chain.
Definition: filter_chain.c:293
video format description
Definition: vlc_es.h:349
#define filter_chain_NewVideo(a, b, c)
Definition: vlc_filter.h:340
filter_t * filter_chain_AppendFilter(filter_chain_t *chain, const char *name, config_chain_t *cfg, const es_format_t *fmt_in, const es_format_t *fmt_out)
Append a filter to the chain.
Definition: filter_chain.c:278
picture_t *(* buffer_new)(filter_t *)
Definition: vlc_filter.h:43
picture_t * picture_NewFromFormat(const video_format_t *restrict fmt)
Definition: picture.c:251
int filter_chain_AppendConverter(filter_chain_t *chain, const es_format_t *fmt_in, const es_format_t *fmt_out)
Append a conversion to the chain.
Definition: filter_chain.c:286
const char name[16]
Definition: httpd.c:1236
Mouse state.
Definition: vlc_mouse.h:45
void filter_chain_Clear(filter_chain_t *)
Remove all existing filters.
Definition: filter_chain.c:152
struct filter_owner_t filter_owner_t
int filter_Blend(vlc_blender_t *, picture_t *p_dst, int i_dst_x, int i_dst_y, const picture_t *p_src, int i_alpha)
It blends a picture into another one.
Definition: filter.c:160
#define filter_DelProxyCallbacks(a, b, c)
Definition: vlc_filter.h:259
Definition: vlc_filter.h:41
#define VLC_API
Definition: fourcc_gen.c:31
int filter_ConfigureBlend(vlc_blender_t *, int i_dst_width, int i_dst_height, const video_format_t *p_src)
It configures blend filter parameters that are allowed to changed after the creation.
Definition: filter.c:128
filter_t vlc_blender_t
Definition: vlc_filter.h:262
Subpicture unit descriptor.
Definition: vlc_spu.h:47
const struct filter_subpicture_callbacks * sub
Definition: vlc_filter.h:56
const char * psz_name
Definition: vlc_codecs.h:313
#define VLC_EGENERIC
Unspecified error.
Definition: vlc_common.h:472
video_format_t video
description of video format
Definition: vlc_es.h:646
Structure describing a filter.
Definition: vlc_filter.h:68
int(* vlc_callback_t)(vlc_object_t *, char const *, vlc_value_t, vlc_value_t, void *)
Definition: vlc_common.h:491
const struct filter_video_callbacks * video
Definition: vlc_filter.h:55
Definition: vlc_block.h:117
Definition: vlc_filter.h:46
Definition: filter_chain.c:46
static void filter_ChangeViewpoint(filter_t *p_filter, const vlc_viewpoint_t *vp)
Definition: vlc_filter.h:189
vlc_blender_t * filter_NewBlend(vlc_object_t *, const video_format_t *p_dst_chroma)
It creates a blend filter.
Definition: filter.c:104
static subpicture_t * filter_NewSubpicture(filter_t *p_filter)
This function will return a new subpicture usable by p_filter as an output buffer.
Definition: vlc_filter.h:216
static void filter_Flush(filter_t *p_filter)
Flush a filter.
Definition: vlc_filter.h:183
This file defines the elementary streams format types.
es_format_t fmt_out
Chain current output format.
Definition: filter_chain.c:54
VLC object common members.
Definition: vlc_objects.h:43
void(* pf_flush)(filter_t *)
Flush.
Definition: vlc_filter.h:122
int filter_chain_MouseFilter(filter_chain_t *, struct vlc_mouse_t *, const struct vlc_mouse_t *)
Apply the filter chain to a mouse state.
Definition: vlc_filter.h:51
#define VLC_USED
Definition: fourcc_gen.c:32
#define filter_AddProxyCallbacks(a, b, c)
Definition: vlc_filter.h:248
void filter_chain_SubSource(filter_chain_t *chain, spu_t *, vlc_tick_t display_date)
Generate subpictures from a chain of subpicture source "filters".
Definition: filter_chain.c:457
void filter_chain_Delete(filter_chain_t *)
Delete filter chain will delete all filters in the chain and free all allocated data.
Definition: filter_chain.c:161