00001 /***************************************************************************** 00002 * vlc_filter.h: filter related structures and functions 00003 ***************************************************************************** 00004 * Copyright (C) 1999-2008 the VideoLAN team 00005 * $Id: 38d9ea64dfbf96db050810822772e81f65cd2474 $ 00006 * 00007 * Authors: Gildas Bazin <gbazin@videolan.org> 00008 * Antoine Cellerier <dionoea at videolan dot org> 00009 * 00010 * This program is free software; you can redistribute it and/or modify 00011 * it under the terms of the GNU General Public License as published by 00012 * the Free Software Foundation; either version 2 of the License, or 00013 * (at your option) any later version. 00014 * 00015 * This program is distributed in the hope that it will be useful, 00016 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00017 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00018 * GNU General Public License for more details. 00019 * 00020 * You should have received a copy of the GNU General Public License 00021 * along with this program; if not, write to the Free Software 00022 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA. 00023 *****************************************************************************/ 00024 00025 #ifndef VLC_FILTER_H 00026 #define VLC_FILTER_H 1 00027 00028 #include <vlc_es.h> 00029 #include <vlc_picture.h> 00030 #include <vlc_subpicture.h> 00031 #include <vlc_mouse.h> 00032 00033 /** 00034 * \file 00035 * This file defines the structure and types used by video and audio filters 00036 */ 00037 00038 typedef struct filter_owner_sys_t filter_owner_sys_t; 00039 00040 /** Structure describing a filter 00041 * @warning BIG FAT WARNING : the code relies on the first 4 members of 00042 * filter_t and decoder_t to be the same, so if you have anything to add, 00043 * do it at the end of the structure. 00044 */ 00045 struct filter_t 00046 { 00047 VLC_COMMON_MEMBERS 00048 00049 /* Module properties */ 00050 module_t * p_module; 00051 filter_sys_t * p_sys; 00052 00053 /* Input format */ 00054 es_format_t fmt_in; 00055 00056 /* Output format of filter */ 00057 es_format_t fmt_out; 00058 bool b_allow_fmt_out_change; 00059 00060 /* Filter configuration */ 00061 config_chain_t * p_cfg; 00062 00063 union 00064 { 00065 picture_t * (*pf_video_filter) ( filter_t *, picture_t * ); 00066 block_t * (*pf_audio_filter) ( filter_t *, block_t * ); 00067 void (*pf_video_blend) ( filter_t *, 00068 picture_t *, const picture_t *, 00069 int, int, int ); 00070 00071 subpicture_t * (*pf_sub_filter) ( filter_t *, mtime_t ); 00072 int (*pf_render_text) ( filter_t *, subpicture_region_t *, 00073 subpicture_region_t * ); 00074 }; 00075 union 00076 { 00077 /* Filter mouse state. 00078 * 00079 * If non-NULL, you must convert from output format to input format: 00080 * - If VLC_SUCCESS is returned, the mouse state is then propagated. 00081 * - Otherwise, the mouse change is not propagated. 00082 * If NULL, the mouse state is considered unchanged and will be 00083 * propagated. 00084 */ 00085 int (*pf_mouse)( filter_t *, vlc_mouse_t *, 00086 const vlc_mouse_t *p_old, 00087 const vlc_mouse_t *p_new ); 00088 int (*pf_render_html) ( filter_t *, subpicture_region_t *, 00089 subpicture_region_t * ); 00090 }; 00091 00092 /* 00093 * Buffers allocation 00094 */ 00095 union 00096 { 00097 block_t * (*pf_audio_buffer_new) ( filter_t *, int ); 00098 picture_t * (*pf_vout_buffer_new) ( filter_t * ); 00099 subpicture_t * (*pf_sub_buffer_new) ( filter_t * ); 00100 }; 00101 union 00102 { 00103 void (*pf_vout_buffer_del) ( filter_t *, picture_t * ); 00104 void (*pf_sub_buffer_del) ( filter_t *, subpicture_t * ); 00105 }; 00106 00107 /* Private structure for the owner of the decoder */ 00108 filter_owner_sys_t *p_owner; 00109 }; 00110 00111 /** 00112 * This function will return a new picture usable by p_filter as an output 00113 * buffer. You have to release it using filter_DeletePicture or by returning 00114 * it to the caller as a pf_video_filter return value. 00115 * Provided for convenience. 00116 * 00117 * \param p_filter filter_t object 00118 * \return new picture on success or NULL on failure 00119 */ 00120 static inline picture_t *filter_NewPicture( filter_t *p_filter ) 00121 { 00122 picture_t *p_picture = p_filter->pf_vout_buffer_new( p_filter ); 00123 if( !p_picture ) 00124 msg_Warn( p_filter, "can't get output picture" ); 00125 return p_picture; 00126 } 00127 00128 /** 00129 * This function will release a picture create by filter_NewPicture. 00130 * Provided for convenience. 00131 * 00132 * \param p_filter filter_t object 00133 * \param p_picture picture to be deleted 00134 */ 00135 static inline void filter_DeletePicture( filter_t *p_filter, picture_t *p_picture ) 00136 { 00137 p_filter->pf_vout_buffer_del( p_filter, p_picture ); 00138 } 00139 00140 /** 00141 * This function will return a new subpicture usable by p_filter as an output 00142 * buffer. You have to release it using filter_DeleteSubpicture or by returning 00143 * it to the caller as a pf_sub_filter return value. 00144 * Provided for convenience. 00145 * 00146 * \param p_filter filter_t object 00147 * \return new subpicture 00148 */ 00149 static inline subpicture_t *filter_NewSubpicture( filter_t *p_filter ) 00150 { 00151 subpicture_t *p_subpicture = p_filter->pf_sub_buffer_new( p_filter ); 00152 if( !p_subpicture ) 00153 msg_Warn( p_filter, "can't get output subpicture" ); 00154 return p_subpicture; 00155 } 00156 00157 /** 00158 * This function will release a subpicture create by filter_NewSubicture. 00159 * Provided for convenience. 00160 * 00161 * \param p_filter filter_t object 00162 * \param p_subpicture to be released 00163 */ 00164 static inline void filter_DeleteSubpicture( filter_t *p_filter, subpicture_t *p_subpicture ) 00165 { 00166 p_filter->pf_sub_buffer_del( p_filter, p_subpicture ); 00167 } 00168 00169 /** 00170 * This function will return a new audio buffer usable by p_filter as an 00171 * output buffer. You have to release it using block_Release or by returning 00172 * it to the caller as a pf_audio_filter return value. 00173 * Provided for convenience. 00174 * 00175 * \param p_filter filter_t object 00176 * \param i_size size of audio buffer requested 00177 * \return block to be used as audio output buffer 00178 */ 00179 static inline block_t *filter_NewAudioBuffer( filter_t *p_filter, int i_size ) 00180 { 00181 block_t *p_block = p_filter->pf_audio_buffer_new( p_filter, i_size ); 00182 if( !p_block ) 00183 msg_Warn( p_filter, "can't get output block" ); 00184 return p_block; 00185 } 00186 00187 /** 00188 * It creates a blend filter. 00189 * 00190 * Only the chroma properties of the dest format is used (chroma 00191 * type, rgb masks and shifts) 00192 */ 00193 VLC_EXPORT( filter_t *, filter_NewBlend, ( vlc_object_t *, const video_format_t *p_dst_chroma ) ); 00194 00195 /** 00196 * It configures blend filter parameters that are allowed to changed 00197 * after the creation. 00198 */ 00199 VLC_EXPORT( int, filter_ConfigureBlend, ( filter_t *, int i_dst_width, int i_dst_height, const video_format_t *p_src ) ); 00200 00201 /** 00202 * It blends a picture into another one. 00203 * 00204 * The input picture is not modified and not released. 00205 */ 00206 VLC_EXPORT( 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 ) ); 00207 00208 /** 00209 * It destroys a blend filter created by filter_NewBlend. 00210 */ 00211 VLC_EXPORT( void, filter_DeleteBlend, ( filter_t * ) ); 00212 00213 /** 00214 * Create a picture_t *(*)( filter_t *, picture_t * ) compatible wrapper 00215 * using a void (*)( filter_t *, picture_t *, picture_t * ) function 00216 * 00217 * Currently used by the chroma video filters 00218 */ 00219 #define VIDEO_FILTER_WRAPPER( name ) \ 00220 static picture_t *name ## _Filter ( filter_t *p_filter, \ 00221 picture_t *p_pic ) \ 00222 { \ 00223 picture_t *p_outpic = filter_NewPicture( p_filter ); \ 00224 if( p_outpic ) \ 00225 { \ 00226 name( p_filter, p_pic, p_outpic ); \ 00227 picture_CopyProperties( p_outpic, p_pic ); \ 00228 } \ 00229 picture_Release( p_pic ); \ 00230 return p_outpic; \ 00231 } 00232 00233 /** 00234 * Filter chain management API 00235 * The filter chain management API is used to dynamically construct filters 00236 * and add them in a chain. 00237 */ 00238 00239 typedef struct filter_chain_t filter_chain_t; 00240 00241 /** 00242 * Create new filter chain 00243 * 00244 * \param p_object pointer to a vlc object 00245 * \param psz_capability vlc capability of filters in filter chain 00246 * \param b_allow_format_fmt_change allow changing of fmt 00247 * \param pf_buffer_allocation_init callback function to initialize buffer allocations 00248 * \param pf_buffer_allocation_clear callback function to clear buffer allocation initialization 00249 * \param p_buffer_allocation_data pointer to private allocation data 00250 * \return pointer to a filter chain 00251 */ 00252 VLC_EXPORT( filter_chain_t *, __filter_chain_New, ( vlc_object_t *, const char *, bool, int (*)( filter_t *, void * ), void (*)( filter_t * ), void * ) ); 00253 #define filter_chain_New( a, b, c, d, e, f ) __filter_chain_New( VLC_OBJECT( a ), b, c, d, e, f ) 00254 00255 /** 00256 * Delete filter chain will delete all filters in the chain and free all 00257 * allocated data. The pointer to the filter chain is then no longer valid. 00258 * 00259 * \param p_chain pointer to filter chain 00260 */ 00261 VLC_EXPORT( void, filter_chain_Delete, ( filter_chain_t * ) ); 00262 00263 /** 00264 * Reset filter chain will delete all filters in the chain and 00265 * reset p_fmt_in and p_fmt_out to the new values. 00266 * 00267 * \param p_chain pointer to filter chain 00268 * \param p_fmt_in new fmt_in params 00269 * \param p_fmt_out new fmt_out params 00270 */ 00271 VLC_EXPORT( void, filter_chain_Reset, ( filter_chain_t *, const es_format_t *, const es_format_t * ) ); 00272 00273 /** 00274 * Append filter to the end of the chain. 00275 * 00276 * \param p_chain pointer to filter chain 00277 * \param psz_name name of filter 00278 * \param p_cfg 00279 * \param p_fmt_in input es_format_t 00280 * \param p_fmt_out output es_format_t 00281 * \return pointer to filter chain 00282 */ 00283 VLC_EXPORT( filter_t *, filter_chain_AppendFilter, ( filter_chain_t *, const char *, config_chain_t *, const es_format_t *, const es_format_t * ) ); 00284 00285 /** 00286 * Append new filter to filter chain from string. 00287 * 00288 * \param p_chain pointer to filter chain 00289 * \param psz_string string of filters 00290 * \return 0 for success 00291 */ 00292 VLC_EXPORT( int, filter_chain_AppendFromString, ( filter_chain_t *, const char * ) ); 00293 00294 /** 00295 * Delete filter from filter chain. This function also releases the filter 00296 * object and unloads the filter modules. The pointer to p_filter is no 00297 * longer valid after this function successfully returns. 00298 * 00299 * \param p_chain pointer to filter chain 00300 * \param p_filter pointer to filter object 00301 * \return VLC_SUCCESS on succes, else VLC_EGENERIC 00302 */ 00303 VLC_EXPORT( int, filter_chain_DeleteFilter, ( filter_chain_t *, filter_t * ) ); 00304 00305 /** 00306 * Get the number of filters in the filter chain. 00307 * 00308 * \param p_chain pointer to filter chain 00309 * \return number of filters in this filter chain 00310 */ 00311 VLC_EXPORT( int, filter_chain_GetLength, ( filter_chain_t * ) ); 00312 00313 /** 00314 * Get last p_fmt_out in the chain. 00315 * 00316 * \param p_chain pointer to filter chain 00317 * \return last p_fmt (es_format_t) of this filter chain 00318 */ 00319 VLC_EXPORT( const es_format_t *, filter_chain_GetFmtOut, ( filter_chain_t * ) ); 00320 00321 /** 00322 * Apply the filter chain to a video picture. 00323 * 00324 * \param p_chain pointer to filter chain 00325 * \param p_picture picture to apply filters on 00326 * \return modified picture after applying all video filters 00327 */ 00328 VLC_EXPORT( picture_t *, filter_chain_VideoFilter, ( filter_chain_t *, picture_t * ) ); 00329 00330 /** 00331 * Apply the filter chain to a audio block. 00332 * 00333 * \param p_chain pointer to filter chain 00334 * \param p_block audio frame to apply filters on 00335 * \return modified audio frame after applying all audio filters 00336 */ 00337 VLC_EXPORT( block_t *, filter_chain_AudioFilter, ( filter_chain_t *, block_t * ) ); 00338 00339 /** 00340 * Apply filter chain to subpictures. 00341 * 00342 * \param p_chain pointer to filter chain 00343 * \param display_date of subpictures 00344 */ 00345 VLC_EXPORT( void, filter_chain_SubFilter, ( filter_chain_t *, mtime_t ) ); 00346 00347 /** 00348 * Apply the filter chain to a mouse state. 00349 * 00350 * It will be applied from the output to the input. It makes sense only 00351 * for a video filter chain. 00352 * 00353 * The vlc_mouse_t* pointers may be the same. 00354 */ 00355 VLC_EXPORT( int, filter_chain_MouseFilter, ( filter_chain_t *, vlc_mouse_t *, const vlc_mouse_t * ) ); 00356 00357 #endif /* _VLC_FILTER_H */ 00358
1.5.6