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