emoved unused pf_render function in subpicture_t.
[vlc.git] / include / vlc_subpicture.h
1 /*****************************************************************************
2  * vlc_subpicture.h: subpicture definitions
3  *****************************************************************************
4  * Copyright (C) 1999 - 2009 the VideoLAN team
5  * $Id$
6  *
7  * Authors: Vincent Seguin <seguin@via.ecp.fr>
8  *          Samuel Hocevar <sam@via.ecp.fr>
9  *          Olivier Aubert <oaubert 47 videolan d07 org>
10  *
11  * This program is free software; you can redistribute it and/or modify
12  * it under the terms of the GNU General Public License as published by
13  * the Free Software Foundation; either version 2 of the License, or
14  * (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program; if not, write to the Free Software
23  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
24  *****************************************************************************/
25
26 #ifndef VLC_SUBPICTURE_H
27 #define VLC_SUBPICTURE_H 1
28
29 /**
30  * \file
31  * This file defines subpicture structures and functions in vlc
32  */
33
34 #include <vlc_picture.h>
35
36 /**
37  * \defgroup subpicture Video Subpictures
38  * Subpictures are pictures that should be displayed on top of the video, like
39  * subtitles and OSD
40  * \ingroup video_output
41  * @{
42  */
43
44 /**
45  * Video subtitle region spu core private
46  */
47 typedef struct subpicture_region_private_t subpicture_region_private_t;
48
49 /**
50  * Video subtitle region
51  *
52  * A subtitle region is defined by a picture (graphic) and its rendering
53  * coordinates.
54  * Subtitles contain a list of regions.
55  */
56 struct subpicture_region_t
57 {
58     video_format_t  fmt;                          /**< format of the picture */
59     picture_t       *p_picture;          /**< picture comprising this region */
60
61     int             i_x;                             /**< position of region */
62     int             i_y;                             /**< position of region */
63     int             i_align;                  /**< alignment within a region */
64     int             i_alpha;                               /**< transparency */
65
66     char            *psz_text;       /**< text string comprising this region */
67     char            *psz_html;       /**< HTML version of subtitle (NULL = use psz_text) */
68     text_style_t    *p_style;        /**< a description of the text style formatting */
69
70     subpicture_region_t *p_next;                /**< next region in the list */
71     subpicture_region_private_t *p_private;  /**< Private data for spu_t *only* */
72 };
73
74 /* Subpicture region position flags */
75 #define SUBPICTURE_ALIGN_LEFT 0x1
76 #define SUBPICTURE_ALIGN_RIGHT 0x2
77 #define SUBPICTURE_ALIGN_TOP 0x4
78 #define SUBPICTURE_ALIGN_BOTTOM 0x8
79 #define SUBPICTURE_ALIGN_MASK ( SUBPICTURE_ALIGN_LEFT|SUBPICTURE_ALIGN_RIGHT| \
80                                 SUBPICTURE_ALIGN_TOP |SUBPICTURE_ALIGN_BOTTOM )
81
82 /**
83  * This function will create a new subpicture region.
84  *
85  * You must use subpicture_region_Delete to destroy it.
86  */
87 VLC_EXPORT( subpicture_region_t *, subpicture_region_New, ( const video_format_t *p_fmt ) );
88
89 /**
90  * This function will destroy a subpicture region allocated by
91  * subpicture_region_New.
92  *
93  * You may give it NULL.
94  */
95 VLC_EXPORT( void, subpicture_region_Delete, ( subpicture_region_t *p_region ) );
96
97 /**
98  * This function will destroy a list of subpicture regions allocated by
99  * subpicture_region_New.
100  *
101  * Provided for convenience.
102  */
103 VLC_EXPORT( void, subpicture_region_ChainDelete, ( subpicture_region_t *p_head ) );
104
105 /**
106  * Video subtitle
107  *
108  * Any subtitle destined to be displayed by a video output thread should
109  * be stored in this structure from it's creation to it's effective display.
110  * Subtitle type and flags should only be modified by the output thread. Note
111  * that an empty subtitle MUST have its flags set to 0.
112  */
113 struct subpicture_t
114 {
115     /** \name Channel ID */
116     /**@{*/
117     int             i_channel;                    /**< subpicture channel ID */
118     /**@}*/
119
120     /** \name Type and flags
121        Should NOT be modified except by the vout thread */
122     /**@{*/
123     int64_t         i_order;                 /** an increasing unique number */
124     subpicture_t *  p_next;               /**< next subtitle to be displayed */
125     /**@}*/
126
127     /** \name Date properties */
128     /**@{*/
129     mtime_t         i_start;                  /**< beginning of display date */
130     mtime_t         i_stop;                         /**< end of display date */
131     bool            b_ephemer;    /**< If this flag is set to true the subtitle
132                                 will be displayed untill the next one appear */
133     bool            b_fade;                               /**< enable fading */
134     /**@}*/
135
136     subpicture_region_t *p_region;  /**< region list composing this subtitle */
137
138     /** \name Display properties
139      * These properties are only indicative and may be
140      * changed by the video output thread, or simply ignored depending of the
141      * subtitle type. */
142     /**@{*/
143     int          i_original_picture_width;  /**< original width of the movie */
144     int          i_original_picture_height;/**< original height of the movie */
145     bool         b_subtitle;            /**< the picture is a movie subtitle */
146     bool         b_absolute;                       /**< position is absolute */
147     int          i_alpha;                                  /**< transparency */
148      /**@}*/
149
150     /** Pointer to function that cleans up the private data of this subtitle */
151     void ( *pf_destroy ) ( subpicture_t * );
152
153     /** Pointer to function that update the regions before rendering (optionnal) */
154     void (*pf_update_regions)( spu_t *,
155                                subpicture_t *, const video_format_t *, mtime_t );
156
157     /** Private data - the subtitle plugin might want to put stuff here to
158      * keep track of the subpicture */
159     subpicture_sys_t *p_sys;                              /* subpicture data */
160 };
161
162
163 /**
164  * This function create a new empty subpicture.
165  *
166  * You must use subpicture_Delete to destroy it.
167  */
168 VLC_EXPORT( subpicture_t *, subpicture_New, ( void ) );
169
170 /**
171  * This function delete a subpicture created by subpicture_New.
172  * You may give it NULL.
173  */
174 VLC_EXPORT( void,  subpicture_Delete, ( subpicture_t *p_subpic ) );
175
176 /**
177  * This function will create a subpicture having one region in the requested
178  * chroma showing the given picture.
179  *
180  * The picture_t given is not released nor used inside the
181  * returned subpicture_t.
182  */
183 VLC_EXPORT( subpicture_t *, subpicture_NewFromPicture, ( vlc_object_t *, picture_t *, vlc_fourcc_t i_chroma ) );
184
185 /**@}*/
186
187 #endif /* _VLC_VIDEO_H */