Add a bunch of help strings. Feel free to correct them, and add more
[vlc.git] / modules / video_filter / canvas.c
1 /*****************************************************************************
2  * canvas.c : automatically resize and padd a video to fit in canvas
3  *****************************************************************************
4  * Copyright (C) 2008 the VideoLAN team
5  * $Id$
6  *
7  * Authors: Antoine Cellerier <dionoea at videolan dot org>
8  *
9  * This program is free software; you can redistribute it and/or modify
10  * it under the terms of the GNU General Public License as published by
11  * the Free Software Foundation; either version 2 of the License, or
12  * (at your option) any later version.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17  * GNU General Public License for more details.
18  *
19  * You should have received a copy of the GNU General Public License
20  * along with this program; if not, write to the Free Software
21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
22  *****************************************************************************/
23
24 /*****************************************************************************
25  * Preamble
26  *****************************************************************************/
27
28 #ifdef HAVE_CONFIG_H
29 # include "config.h"
30 #endif
31
32 #include <limits.h>
33
34 #include <vlc_common.h>
35 #include <vlc_plugin.h>
36 #include <vlc_filter.h>
37
38 /*****************************************************************************
39  * Local and extern prototypes.
40  *****************************************************************************/
41 static int  Activate( vlc_object_t * );
42 static void Destroy( vlc_object_t * );
43 static picture_t *Filter( filter_t *, picture_t * );
44 static int alloc_init( filter_t *, void * );
45
46 /* This module effectively implements a form of picture-in-picture.
47  *  - The outer picture is called the canvas.
48  *  - The innter picture is callsed the subpicture.
49  *
50  * NB, all of the following operatons take into account aspect ratio
51  *
52  * A canvas is of canvas_{width,height}.
53  * In Pad mode:
54  *  - The subpicture is upconverted with a inverse scalefactor of:
55  *     (The size of subpicture's largest dimension)
56  *     --------------------------------------------
57  *     (The size of canvas's equivalent dimension)
58  *
59  *   Ie, The subpicture's largest dimension is made equal to the
60  *   equivalent canvas dimension.
61  *
62  *  - The upconverted subpicture's smallest dimension is then padded
63  *    to make the upconverted subpicture have the same dimensions of
64  *    the canvas.
65  *
66  * In Crop mode:
67  *  - The subpicture is upconverted with an inverse scalefactor of:
68  *     (The size of subpicture's smallest dimension)
69  *     --------------------------------------------
70  *     (The size of canvas's equivalent dimension)
71  *
72  *   Ie, The subpicture's smallest dimension is made equal to the
73  *   equivalent canvas dimension. (The subpicture will then be
74  *   larger than the canvas)
75  *
76  *  - The upconverted subpicture's largest dimension is then cropped
77  *    to make the upconverted subpicture have the same dimensions of
78  *    the canvas.
79  */
80
81 /* NB, use of `padd' in this module is a 16-17th Century spelling of `pad' */
82
83 #define WIDTH_TEXT N_( "Output width" )
84 #define WIDTH_LONGTEXT N_( \
85     "Output (canvas) image width" )
86 #define HEIGHT_TEXT N_( "Output height" )
87 #define HEIGHT_LONGTEXT N_( \
88     "Output (canvas) image height" )
89 #define ASPECT_TEXT N_( "Output picture aspect ratio" )
90 #define ASPECT_LONGTEXT N_( \
91     "Set the canvas' picture aspect ratio. " \
92     "If omitted, the canvas is assumed to have the same SAR as the input." )
93 #define PADD_TEXT N_( "Pad video" )
94 #define PADD_LONGTEXT N_( \
95     "If enabled, video will be padded to fit in canvas after scaling. " \
96     "Otherwise, video will be cropped to fix in canvas after scaling." )
97 #define CANVAS_HELP N_( "Automatically resize and pad a video" )
98
99 #define CFG_PREFIX "canvas-"
100
101 /*****************************************************************************
102  * Module descriptor
103  *****************************************************************************/
104 vlc_module_begin ()
105     set_shortname( N_("Canvas") )
106     set_description( N_("Canvas video filter") )
107     set_capability( "video filter2", 0 )
108     set_help( CANVAS_HELP )
109     set_callbacks( Activate, Destroy )
110
111     set_category( CAT_VIDEO )
112     set_subcategory( SUBCAT_VIDEO_VFILTER )
113
114     add_integer_with_range( CFG_PREFIX "width", 0, 0, INT_MAX, NULL,
115                             WIDTH_TEXT, WIDTH_LONGTEXT, false )
116     add_integer_with_range( CFG_PREFIX "height", 0, 0, INT_MAX, NULL,
117                             HEIGHT_TEXT, HEIGHT_LONGTEXT, false )
118
119     add_string( CFG_PREFIX "aspect", NULL, NULL,
120                 ASPECT_TEXT, ASPECT_LONGTEXT, false )
121
122     add_bool( CFG_PREFIX "padd", true, NULL,
123               PADD_TEXT, PADD_LONGTEXT, false )
124 vlc_module_end ()
125
126 static const char *const ppsz_filter_options[] = {
127     "width", "height", "aspect", "padd", NULL
128 };
129
130 struct filter_sys_t
131 {
132     filter_chain_t *p_chain;
133 };
134
135 /*****************************************************************************
136  *
137  *****************************************************************************/
138 static int Activate( vlc_object_t *p_this )
139 {
140     filter_t *p_filter = (filter_t *)p_this;
141     unsigned i_canvas_width; /* width of output canvas */
142     unsigned i_canvas_height; /* height of output canvas */
143     unsigned i_canvas_aspect; /* canvas PictureAspectRatio */
144     es_format_t fmt; /* target format after up/down conversion */
145     char psz_croppadd[100];
146     int i_padd,i_offset;
147     char *psz_aspect, *psz_parser;
148     bool b_padd;
149     unsigned i_fmt_in_aspect;
150
151     if( !p_filter->b_allow_fmt_out_change )
152     {
153         msg_Err( p_filter, "Picture format change isn't allowed" );
154         return VLC_EGENERIC;
155     }
156
157     if( p_filter->fmt_in.video.i_chroma != p_filter->fmt_out.video.i_chroma )
158     {
159         msg_Err( p_filter, "Input and output chromas don't match" );
160         return VLC_EGENERIC;
161     }
162
163     config_ChainParse( p_filter, CFG_PREFIX, ppsz_filter_options,
164                        p_filter->p_cfg );
165
166     i_canvas_width = var_CreateGetInteger( p_filter, CFG_PREFIX "width" );
167     i_canvas_height = var_CreateGetInteger( p_filter, CFG_PREFIX "height" );
168
169     if( i_canvas_width == 0 || i_canvas_height == 0 )
170     {
171         msg_Err( p_filter, "Width and height options must be set" );
172         return VLC_EGENERIC;
173     }
174
175     if( i_canvas_width & 1 || i_canvas_height & 1 )
176     {
177         /* If this restriction were ever relaxed, it is very important to
178          * get the field polatiry correct */
179         msg_Err( p_filter, "Width and height options must be even integers" );
180         return VLC_EGENERIC;
181     }
182
183     i_fmt_in_aspect = (int64_t)p_filter->fmt_in.video.i_sar_num *
184                       p_filter->fmt_in.video.i_width *
185                       VOUT_ASPECT_FACTOR /
186                       p_filter->fmt_in.video.i_sar_den /
187                       p_filter->fmt_in.video.i_height;
188     psz_aspect = var_CreateGetNonEmptyString( p_filter, CFG_PREFIX "aspect" );
189     if( psz_aspect )
190     {
191         psz_parser = strchr( psz_aspect, ':' );
192         int numerator = atoi( psz_aspect );
193         int denominator = psz_parser ? atoi( psz_parser+1 ) : 0;
194         denominator = denominator == 0 ? 1 : denominator;
195         i_canvas_aspect = numerator * VOUT_ASPECT_FACTOR / denominator;
196         free( psz_aspect );
197
198         if( numerator <= 0 || denominator < 0 )
199         {
200             msg_Err( p_filter, "Aspect ratio must be strictly positive" );
201             return VLC_EGENERIC;
202         }
203     }
204     else
205     {
206         /* if there is no user supplied aspect ratio, assume the canvas
207          * has the same sample aspect ratio as the subpicture */
208         /* aspect = subpic_sar * canvas_width / canvas_height
209          *  where subpic_sar = subpic_ph * subpic_par / subpic_pw */
210         i_canvas_aspect = (uint64_t) p_filter->fmt_in.video.i_height
211                         * i_fmt_in_aspect
212                         * i_canvas_width
213                         / (i_canvas_height * p_filter->fmt_in.video.i_width);
214     }
215
216     b_padd = var_CreateGetBool( p_filter, CFG_PREFIX "padd" );
217
218     filter_sys_t *p_sys = (filter_sys_t *)malloc( sizeof( filter_sys_t ) );
219     if( !p_sys )
220         return VLC_ENOMEM;
221     p_filter->p_sys = p_sys;
222
223     p_sys->p_chain = filter_chain_New( p_filter, "video filter2", true,
224                                        alloc_init, NULL, p_filter );
225     if( !p_sys->p_chain )
226     {
227         msg_Err( p_filter, "Could not allocate filter chain" );
228         free( p_sys );
229         return VLC_EGENERIC;
230     }
231
232     es_format_Copy( &fmt, &p_filter->fmt_in );
233
234     /* one dimension will end up with one of the following: */
235     fmt.video.i_width = i_canvas_width;
236     fmt.video.i_height = i_canvas_height;
237
238     if( b_padd )
239     {
240         /* Padd */
241         if( i_canvas_aspect > i_fmt_in_aspect )
242         {
243             /* The canvas has a wider aspect than the subpicture:
244              *  ie, pillarbox the [scaled] subpicture */
245             /* The following is derived form:
246              * width = upconverted_subpic_height * subpic_par / canvas_sar
247              *  where canvas_sar = canvas_width / (canvas_height * canvas_par)
248              * then simplify */
249             fmt.video.i_width = i_canvas_width
250                               * i_fmt_in_aspect
251                               / i_canvas_aspect;
252             if( fmt.video.i_width & 1 ) fmt.video.i_width -= 1;
253
254             i_padd = (i_canvas_width - fmt.video.i_width) / 2;
255             i_offset = (i_padd & 1);
256             snprintf( psz_croppadd, 100, "croppadd{paddleft=%d,paddright=%d}",
257                       i_padd - i_offset, i_padd + i_offset );
258         }
259         else
260         {
261             /* The canvas has a taller aspect than the subpicture:
262              *  ie, letterbox the [scaled] subpicture */
263             fmt.video.i_height = i_canvas_height
264                                * i_canvas_aspect
265                                / i_fmt_in_aspect;
266             if( fmt.video.i_height & 1 ) fmt.video.i_height -= 1;
267
268             i_padd = (i_canvas_height - fmt.video.i_height ) / 2;
269             i_offset = (i_padd & 1);
270             snprintf( psz_croppadd, 100, "croppadd{paddtop=%d,paddbottom=%d}",
271                       i_padd - i_offset, i_padd + i_offset );
272         }
273     }
274     else
275     {
276         /* Crop */
277         if( i_canvas_aspect < i_fmt_in_aspect )
278         {
279             /* The canvas has a narrower aspect than the subpicture:
280              *  ie, crop the [scaled] subpicture horizontally */
281             fmt.video.i_width = i_canvas_width
282                               * i_fmt_in_aspect
283                               / i_canvas_aspect;
284             if( fmt.video.i_width & 1 ) fmt.video.i_width -= 1;
285
286             i_padd = (fmt.video.i_width - i_canvas_width) / 2;
287             i_offset = (i_padd & 1);
288             snprintf( psz_croppadd, 100, "croppadd{cropleft=%d,cropright=%d}",
289                       i_padd - i_offset, i_padd + i_offset );
290         }
291         else
292         {
293             /* The canvas has a shorter aspect than the subpicture:
294              *  ie, crop the [scaled] subpicture vertically */
295             fmt.video.i_height = i_canvas_height
296                                * i_canvas_aspect
297                                / i_fmt_in_aspect;
298             if( fmt.video.i_height & 1 ) fmt.video.i_height -= 1;
299
300             i_padd = (fmt.video.i_height - i_canvas_height) / 2;
301             i_offset = (i_padd & 1);
302             snprintf( psz_croppadd, 100, "croppadd{croptop=%d,cropbottom=%d}",
303                       i_padd - i_offset, i_padd + i_offset );
304         }
305     }
306
307     /* xxx, should the clean area include the letter-boxing?
308      *  probably not, as some codecs can make use of that information
309      *  and it should be a scaled version of the input clean area
310      *   -- davidf */
311     fmt.video.i_visible_width = fmt.video.i_width;
312     fmt.video.i_visible_height = fmt.video.i_height;
313
314     filter_chain_Reset( p_sys->p_chain, &p_filter->fmt_in, &fmt );
315     /* Append scaling module */
316     filter_chain_AppendFilter( p_sys->p_chain, NULL, NULL, NULL, NULL );
317     /* Append padding module */
318     filter_chain_AppendFromString( p_sys->p_chain, psz_croppadd );
319
320     fmt = *filter_chain_GetFmtOut( p_sys->p_chain );
321     es_format_Copy( &p_filter->fmt_out, &fmt );
322
323     p_filter->fmt_out.video.i_sar_num =
324         i_canvas_aspect    * p_filter->fmt_out.video.i_height;
325     p_filter->fmt_out.video.i_sar_den =
326         VOUT_ASPECT_FACTOR * p_filter->fmt_out.video.i_width;
327
328     if( p_filter->fmt_out.video.i_width != i_canvas_width
329      || p_filter->fmt_out.video.i_height != i_canvas_height )
330     {
331         msg_Warn( p_filter, "Looks like something went wrong. "
332                   "Output size is %dx%d while we asked for %dx%d",
333                   p_filter->fmt_out.video.i_width,
334                   p_filter->fmt_out.video.i_height,
335                   i_canvas_width, i_canvas_height );
336     }
337
338     p_filter->pf_video_filter = Filter;
339
340     return VLC_SUCCESS;
341 }
342
343 /*****************************************************************************
344  *
345  *****************************************************************************/
346 static void Destroy( vlc_object_t *p_this )
347 {
348     filter_t *p_filter = (filter_t *)p_this;
349     filter_chain_Delete( p_filter->p_sys->p_chain );
350     free( p_filter->p_sys );
351 }
352
353 /*****************************************************************************
354  *
355  *****************************************************************************/
356 static picture_t *Filter( filter_t *p_filter, picture_t *p_pic )
357 {
358     return filter_chain_VideoFilter( p_filter->p_sys->p_chain, p_pic );
359 }
360
361 /*****************************************************************************
362  *
363  *****************************************************************************/
364 static picture_t *video_new( filter_t *p_filter )
365 {
366     return filter_NewPicture( (filter_t*)p_filter->p_owner );
367 }
368
369 static void video_del( filter_t *p_filter, picture_t *p_pic )
370 {
371     return filter_DeletePicture( (filter_t*)p_filter->p_owner, p_pic );
372 }
373
374 static int alloc_init( filter_t *p_filter, void *p_data )
375 {
376     p_filter->p_owner = p_data;
377     p_filter->pf_vout_buffer_new = video_new;
378     p_filter->pf_vout_buffer_del = video_del;
379     return VLC_SUCCESS;
380 }