1 /*****************************************************************************
2 * vlc_filter.h: filter related structures and functions
3 *****************************************************************************
4 * Copyright (C) 1999-2014 VLC authors and VideoLAN
6 * Authors: Gildas Bazin <gbazin@videolan.org>
7 * Antoine Cellerier <dionoea at videolan dot org>
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.
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.
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 *****************************************************************************/
26 #define VLC_FILTER_H 1
29 #include <vlc_picture.h>
30 #include <vlc_subpicture.h>
31 #include <vlc_mouse.h>
35 * This file defines the structure and types used by video and audio filters
38 typedef struct filter_owner_sys_t filter_owner_sys_t;
40 typedef struct filter_owner_t
48 picture_t * (*buffer_new)( filter_t * );
49 void (*buffer_del)( filter_t *, picture_t * );
53 subpicture_t * (*buffer_new)( filter_t * );
54 void (*buffer_del)( filter_t *, subpicture_t * );
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.
69 /* Module properties */
76 /* Output format of filter */
78 bool b_allow_fmt_out_change;
80 /* Filter configuration */
81 config_chain_t * p_cfg;
87 picture_t * (*pf_filter) ( filter_t *, picture_t * );
88 void (*pf_flush)( filter_t * );
89 /* Filter mouse state.
91 * If non-NULL, you must convert from output to input formats:
92 * - If VLC_SUCCESS is returned, the mouse state is propagated.
93 * - Otherwise, the mouse change is not propagated.
94 * If NULL, the mouse state is considered unchanged and will be
97 int (*pf_mouse)( filter_t *, vlc_mouse_t *,
98 const vlc_mouse_t *p_old,
99 const vlc_mouse_t *p_new );
101 #define pf_video_filter u.video.pf_filter
102 #define pf_video_flush u.video.pf_flush
103 #define pf_video_mouse u.video.pf_mouse
107 block_t * (*pf_filter) ( filter_t *, block_t * );
109 #define pf_audio_filter u.audio.pf_filter
113 void (*pf_blend) ( filter_t *, picture_t *,
114 const picture_t *, int, int, int );
116 #define pf_video_blend u.blend.pf_blend
120 subpicture_t * (*pf_source) ( filter_t *, mtime_t );
121 int (*pf_mouse) ( filter_t *,
122 const vlc_mouse_t *p_old,
123 const vlc_mouse_t *p_new,
124 const video_format_t * );
126 #define pf_sub_source u.sub.pf_source
127 #define pf_sub_mouse u.sub.pf_mouse
131 subpicture_t * (*pf_filter) ( filter_t *, subpicture_t * );
133 #define pf_sub_filter u.subf.pf_filter
137 int (*pf_text) ( filter_t *, subpicture_region_t *,
138 subpicture_region_t *,
139 const vlc_fourcc_t * );
140 int (*pf_html) ( filter_t *, subpicture_region_t *,
141 subpicture_region_t *,
142 const vlc_fourcc_t * );
144 #define pf_render_text u.render.pf_text
145 #define pf_render_html u.render.pf_html
150 * XXX use filter_GetInputAttachments */
151 int (*pf_get_attachments)( filter_t *, input_attachment_t ***, int * );
153 /* Private structure for the owner of the decoder */
154 filter_owner_t owner;
158 * This function will return a new picture usable by p_filter as an output
159 * buffer. You have to release it using filter_DeletePicture or by returning
160 * it to the caller as a pf_video_filter return value.
161 * Provided for convenience.
163 * \param p_filter filter_t object
164 * \return new picture on success or NULL on failure
166 static inline picture_t *filter_NewPicture( filter_t *p_filter )
168 picture_t *pic = p_filter->owner.video.buffer_new( p_filter );
170 msg_Warn( p_filter, "can't get output picture" );
175 * This function will release a picture create by filter_NewPicture.
176 * Provided for convenience.
178 * \param p_filter filter_t object
179 * \param p_picture picture to be deleted
181 static inline void filter_DeletePicture( filter_t *p_filter, picture_t *pic )
183 p_filter->owner.video.buffer_del( p_filter, pic );
187 * This function will flush the state of a video filter.
189 static inline void filter_FlushPictures( filter_t *p_filter )
191 if( p_filter->pf_video_flush )
192 p_filter->pf_video_flush( p_filter );
196 * This function will return a new subpicture usable by p_filter as an output
197 * buffer. You have to release it using filter_DeleteSubpicture or by returning
198 * it to the caller as a pf_sub_source return value.
199 * Provided for convenience.
201 * \param p_filter filter_t object
202 * \return new subpicture
204 static inline subpicture_t *filter_NewSubpicture( filter_t *p_filter )
206 subpicture_t *subpic = p_filter->owner.sub.buffer_new( p_filter );
208 msg_Warn( p_filter, "can't get output subpicture" );
213 * This function will release a subpicture create by filter_NewSubicture.
214 * Provided for convenience.
216 * \param p_filter filter_t object
217 * \param p_subpicture to be released
219 static inline void filter_DeleteSubpicture( filter_t *p_filter,
220 subpicture_t *subpic )
222 p_filter->owner.sub.buffer_del( p_filter, subpic );
226 * This function gives all input attachments at once.
228 * You MUST release the returned values
230 static inline int filter_GetInputAttachments( filter_t *p_filter,
231 input_attachment_t ***ppp_attachment,
234 if( !p_filter->pf_get_attachments )
236 return p_filter->pf_get_attachments( p_filter,
237 ppp_attachment, pi_attachment );
241 * It creates a blend filter.
243 * Only the chroma properties of the dest format is used (chroma
244 * type, rgb masks and shifts)
246 VLC_API filter_t * filter_NewBlend( vlc_object_t *, const video_format_t *p_dst_chroma ) VLC_USED;
249 * It configures blend filter parameters that are allowed to changed
250 * after the creation.
252 VLC_API int filter_ConfigureBlend( filter_t *, int i_dst_width, int i_dst_height, const video_format_t *p_src );
255 * It blends a picture into another one.
257 * The input picture is not modified and not released.
259 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 );
262 * It destroys a blend filter created by filter_NewBlend.
264 VLC_API void filter_DeleteBlend( filter_t * );
267 * Create a picture_t *(*)( filter_t *, picture_t * ) compatible wrapper
268 * using a void (*)( filter_t *, picture_t *, picture_t * ) function
270 * Currently used by the chroma video filters
272 #define VIDEO_FILTER_WRAPPER( name ) \
273 static picture_t *name ## _Filter ( filter_t *p_filter, \
276 picture_t *p_outpic = filter_NewPicture( p_filter ); \
279 name( p_filter, p_pic, p_outpic ); \
280 picture_CopyProperties( p_outpic, p_pic ); \
282 picture_Release( p_pic ); \
287 * Filter chain management API
288 * The filter chain management API is used to dynamically construct filters
289 * and add them in a chain.
292 typedef struct filter_chain_t filter_chain_t;
295 * Create new filter chain
297 * \param p_object pointer to a vlc object
298 * \param psz_capability vlc capability of filters in filter chain
299 * \param b_allow_format_fmt_change allow changing of fmt
300 * \return pointer to a filter chain
302 VLC_API filter_chain_t * filter_chain_New( vlc_object_t *, const char *, bool )
304 #define filter_chain_New( a, b, c ) filter_chain_New( VLC_OBJECT( a ), b, c )
307 * Creates a new video filter chain.
309 * \param obj pointer to parent VLC object
310 * \param change whether to allow changing the output format
311 * \param owner owner video buffer callbacks
312 * \return new filter chain, or NULL on error
314 VLC_API filter_chain_t * filter_chain_NewVideo( vlc_object_t *obj, bool change,
315 const filter_owner_t *owner )
317 #define filter_chain_NewVideo( a, b, c ) \
318 filter_chain_NewVideo( VLC_OBJECT( a ), b, c )
321 * Delete filter chain will delete all filters in the chain and free all
322 * allocated data. The pointer to the filter chain is then no longer valid.
324 * \param p_chain pointer to filter chain
326 VLC_API void filter_chain_Delete( filter_chain_t * );
329 * Reset filter chain will delete all filters in the chain and
330 * reset p_fmt_in and p_fmt_out to the new values.
332 * \param p_chain pointer to filter chain
333 * \param p_fmt_in new fmt_in params
334 * \param p_fmt_out new fmt_out params
336 VLC_API void filter_chain_Reset( filter_chain_t *, const es_format_t *, const es_format_t * );
339 * Append filter to the end of the chain.
341 * \param p_chain pointer to filter chain
342 * \param psz_name name of filter
344 * \param p_fmt_in input es_format_t
345 * \param p_fmt_out output es_format_t
346 * \return pointer to filter chain
348 VLC_API filter_t * filter_chain_AppendFilter( filter_chain_t *, const char *, config_chain_t *, const es_format_t *, const es_format_t * );
351 * Append new filter to filter chain from string.
353 * \param p_chain pointer to filter chain
354 * \param psz_string string of filters
355 * \return 0 for success
357 VLC_API int filter_chain_AppendFromString( filter_chain_t *, const char * );
360 * Delete filter from filter chain. This function also releases the filter
361 * object and unloads the filter modules. The pointer to p_filter is no
362 * longer valid after this function successfully returns.
364 * \param p_chain pointer to filter chain
365 * \param p_filter pointer to filter object
367 VLC_API void filter_chain_DeleteFilter( filter_chain_t *, filter_t * );
370 * Get the number of filters in the filter chain.
372 * \param p_chain pointer to filter chain
373 * \return number of filters in this filter chain
375 VLC_API int filter_chain_GetLength( filter_chain_t * );
378 * Get last p_fmt_out in the chain.
380 * \param p_chain pointer to filter chain
381 * \return last p_fmt (es_format_t) of this filter chain
383 VLC_API const es_format_t * filter_chain_GetFmtOut( filter_chain_t * );
386 * Apply the filter chain to a video picture.
388 * \param p_chain pointer to filter chain
389 * \param p_picture picture to apply filters on
390 * \return modified picture after applying all video filters
392 VLC_API picture_t * filter_chain_VideoFilter( filter_chain_t *, picture_t * );
395 * Flush a video filter chain.
397 VLC_API void filter_chain_VideoFlush( filter_chain_t * );
400 * Apply the filter chain to a audio block.
402 * \param p_chain pointer to filter chain
403 * \param p_block audio frame to apply filters on
404 * \return modified audio frame after applying all audio filters
406 VLC_API block_t * filter_chain_AudioFilter( filter_chain_t *, block_t * );
409 * Apply filter chain to subpictures.
411 * \param p_chain pointer to filter chain
412 * \param display_date of subpictures
414 void filter_chain_SubSource( filter_chain_t *, spu_t *, mtime_t );
417 * Apply filter chain to subpictures.
419 * \param p_chain pointer to filter chain
420 * \param p_subpicture subpicture to apply filters on
421 * \return modified subpicture after applying all subpicture filters
423 VLC_API subpicture_t * filter_chain_SubFilter( filter_chain_t *, subpicture_t * );
426 * Apply the filter chain to a mouse state.
428 * It will be applied from the output to the input. It makes sense only
429 * for a video filter chain.
431 * The vlc_mouse_t* pointers may be the same.
433 VLC_API int filter_chain_MouseFilter( filter_chain_t *, vlc_mouse_t *, const vlc_mouse_t * );
436 * Inform the filter chain of mouse state.
438 * It makes sense only for a sub source chain.
440 VLC_API int filter_chain_MouseEvent( filter_chain_t *, const vlc_mouse_t *, const video_format_t * );
442 int filter_chain_ForEach( filter_chain_t *chain,
443 int (*cb)( filter_t *, void * ), void *opaque );
445 #endif /* _VLC_FILTER_H */