VLC 4.0.0-dev
Loading...
Searching...
No Matches
vlc_subpicture.h
Go to the documentation of this file.
1/*****************************************************************************
2 * vlc_subpicture.h: subpicture definitions
3 *****************************************************************************
4 * Copyright (C) 1999 - 2009 VLC authors and VideoLAN
5 *
6 * Authors: Vincent Seguin <seguin@via.ecp.fr>
7 * Samuel Hocevar <sam@via.ecp.fr>
8 * Olivier Aubert <oaubert 47 videolan d07 org>
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_SUBPICTURE_H
26#define VLC_SUBPICTURE_H 1
27
28/**
29 */
30
31#include <vlc_picture.h>
32#include <vlc_text_style.h>
33#include <vlc_list.h>
34#include <vlc_vector.h>
35#include <vlc_vout_display.h>
36
37/**
38 * \defgroup subpicture Video sub-pictures
39 * \ingroup video_output
40 * Subpictures are pictures that should be displayed on top of the video, like
41 * subtitles and OSD
42 * @{
43 * \file
44 * Subpictures functions
45 */
46
47/**
48 * Video subtitle region spu core private
49 */
52typedef struct filter_t vlc_blender_t;
54/**< render background under text only */
55#define VLC_SUBPIC_TEXT_FLAG_NO_REGION_BG (1 << 4)
56/** if the decoder sends row/cols based output */
57#define VLC_SUBPIC_TEXT_FLAG_GRID_MODE (1 << 5)
58/** don't try to balance wrapped text lines */
59#define VLC_SUBPIC_TEXT_FLAG_TEXT_NOT_BALANCED (1 << 6)
60/** mark the subpicture region as a text flag */
61#define VLC_SUBPIC_TEXT_FLAG_IS_TEXT (1 << 7)
63/**
64 * Video subtitle region
65 *
66 * A subtitle region is defined by a picture (graphic) and its rendering
67 * coordinates.
68 * Subtitles contain a list of regions.
69 */
72 video_format_t fmt; /**< format of the picture */
73 picture_t *p_picture; /**< picture comprising this region */
75 bool b_absolute; /**< position is absolute in the movie */
76 int i_x; /**< position of region, relative to alignment */
77 int i_y; /**< position of region, relative to alignment */
78 int i_align; /**< alignment flags of region */
79 int i_alpha; /**< transparency */
81 /* Parameters for text regions (p_picture to be rendered) */
82 text_segment_t *p_text; /**< subtitle text, made of a list of segments */
83 int text_flags; /**< VLC_SUBPIC_TEXT_FLAG_xxx and SUBPICTURE_ALIGN_xxx */
84 int i_max_width; /** horizontal rendering/cropping target/limit */
85 int i_max_height; /** vertical rendering/cropping target/limit */
87 struct vlc_list node; /**< for inclusion in a vlc_spu_regions */
88 subpicture_region_private_t *p_private; /**< Private data for spu_t *only* */
89};
90
91typedef struct vlc_list vlc_spu_regions;
93#define vlc_spu_regions_init(p_rs) \
94 vlc_list_init((p_rs))
95#define vlc_spu_regions_push(p_rs,reg) \
96 vlc_list_append(&(reg)->node, (p_rs))
97#define vlc_spu_regions_foreach(reg,p_rs) \
98 vlc_list_foreach(reg, (p_rs), node)
99#define vlc_spu_regions_foreach_const(reg,p_rs) \
100 vlc_list_foreach_const(reg, (p_rs), node)
101#define vlc_spu_regions_is_empty(p_rs) \
102 vlc_list_is_empty((p_rs))
103#define vlc_spu_regions_first_or_null(p_rs) \
104 vlc_list_first_entry_or_null((p_rs), subpicture_region_t, node)
105#define vlc_spu_regions_remove(p_rs, reg) \
106 vlc_list_remove(&(reg)->node)
107
117/* Subpicture region position flags */
118#define SUBPICTURE_ALIGN_LEFT 0x1
119#define SUBPICTURE_ALIGN_RIGHT 0x2
120#define SUBPICTURE_ALIGN_TOP 0x4
121#define SUBPICTURE_ALIGN_BOTTOM 0x8
122#define SUBPICTURE_ALIGN_MASK ( SUBPICTURE_ALIGN_LEFT|SUBPICTURE_ALIGN_RIGHT| \
123 SUBPICTURE_ALIGN_TOP |SUBPICTURE_ALIGN_BOTTOM )
124/**
125 * This function will create a new subpicture region.
126 *
127 * You must use subpicture_region_Delete to destroy it.
128 *
129 * \note use subpicture_region_NewText() to create a text region
130 */
132
133/**
134 * This function will create a new text subpicture region.
135 *
136 * You must use subpicture_region_Delete to destroy it.
137 */
139
140/**
141 * Create a subpicture region containing the picture.
142 *
143 * A reference will be added to the picture on success.
144 *
145 * You must use subpicture_region_Delete to destroy it.
146 *
147 * The chroma of the format must match the one of the picture.
148 * The dimensions of the format should not exceed the ones of the picture. This
149 * is not checked explicitly in the function.
150 *
151 * \param p_fmt format for the subpicture cropping/SAR (may be NULL)
152 *
153 * \note if p_fmt is NULL, the format of the picture will be used.
154 */
156
157/**
158 * This function will destroy a subpicture region allocated by
159 * subpicture_region_New.
160 *
161 * You may give it NULL.
162 */
164
165/**
166 * This function will clear a list of subpicture regions allocated by
167 * subpicture_region_New.
168 *
169 * Provided for convenience.
170 */
172
173/**
174 * Subpicture updater operation virtual table.
175 *
176 * This structure gathers the operations that are implemented by a
177 * subpicture_updater_t instance. */
180 /** Mandatory callback called after pf_validate and doing
181 * the main job of creating the subpicture regions for the
182 * current video_format */
183 void (*update)(subpicture_t *,
184 const video_format_t *prev_src, const video_format_t *p_fmt_src,
185 const video_format_t *prev_dst, const video_format_t *p_fmt_dst,
186 vlc_tick_t);
187
188 /** Optional callback for subpicture private data cleanup */
189 void (*destroy)(subpicture_t *);
191
192/**
193 * Tells if the region is a text-based region.
194 */
195#define subpicture_region_IsText(r) \
196 (((r)->text_flags & VLC_SUBPIC_TEXT_FLAG_IS_TEXT) != 0)
197
198/**
199 *
200 */
201typedef struct
203 void *sys;
204 const struct vlc_spu_updater_ops *ops;
206
211 picture_t *p_picture; /**< picture comprising this region */
212 vout_display_place_t place; /**< visible area in display coordinates */
213 int i_alpha; /**< transparency */
215
218 struct VLC_VECTOR(struct subpicture_region_rendered *) regions; /**< list of regions to render */
219 int64_t i_order; /** an increasing unique number */
221
224/**
225 * Video subtitle
226 *
227 * Any subtitle destined to be displayed by a video output thread should
228 * be stored in this structure from it's creation to it's effective display.
229 * Subtitle type and flags should only be modified by the output thread. Note
230 * that an empty subtitle MUST have its flags set to 0.
231 */
232struct subpicture_t
234 /** \name Channel ID */
235 /**@{*/
236 ssize_t i_channel; /**< subpicture channel ID */
237 /**@}*/
238
239 /** \name Type and flags
240 Should NOT be modified except by the vout thread */
241 /**@{*/
242 int64_t i_order; /** an increasing unique number */
243 subpicture_t * p_next; /**< next subtitle to be displayed */
244 /**@}*/
245
246 vlc_spu_regions regions; /**< region list composing this subtitle */
248 /** \name Date properties */
249 /**@{*/
250 vlc_tick_t i_start; /**< beginning of display date */
251 vlc_tick_t i_stop; /**< end of display date. Will be
252 considered invalid if set to TICK_INVALID
253 or less than i_start. See b_ephemer */
254 bool b_ephemer; /**< If this flag is set to true the subtitle
255 will be displayed until the next one appears
256 or if i_stop is reached when it is valid */
257 bool b_fade; /**< enable fading */
258 /**@}*/
259
260 /** \name Display properties
261 * These properties are only indicative and may be
262 * changed by the video output thread, or simply ignored depending of the
263 * subtitle type. */
264 /**@{*/
265 bool b_subtitle; /**< the picture is a movie subtitle */
266 unsigned i_original_picture_width; /**< original width of the movie */
267 unsigned i_original_picture_height;/**< original height of the movie */
268 int i_alpha; /**< transparency */
269 /**@}*/
270
273 subpicture_private_t *p_private; /* Reserved to the core */
275
276/**
277 * This function create a new empty subpicture.
278 *
279 * You must use subpicture_Delete to destroy it.
280 */
282
283/**
284 * This function delete a subpicture created by subpicture_New.
285 * You may give it NULL.
286 */
287VLC_API void subpicture_Delete( subpicture_t *p_subpic );
288
289/**
290 * This function will create a subpicture having one region in the requested
291 * chroma showing the given picture.
292 *
293 * The picture_t given is not released nor used inside the
294 * returned subpicture_t.
295 */
297
298/**
299 * This function will update the content of a subpicture created with
300 * a non NULL subpicture_updater_t.
301 */
303
304/**
305 * This function will blend a given subpicture onto a picture.
306 *
307 * The subpicture and all its region must:
308 * - be absolute.
309 * - not be ephemere.
310 * - not have the fade flag.
311 * - contains only picture (no text rendering).
312 * \return the number of region(s) successfully blent
313 */
315
316/**
317 * Create a vlc_render_subpicture.
318 *
319 * It should be released with \ref vlc_render_subpicture_Delete.
320 */
322
323/**
324 * Destroy a vlc_render_subpicture.
325 */
327
328/**@}*/
329
330#endif /* _VLC_SUBPICTURE_H */
#define VLC_API
Definition fourcc_gen.c:31
uint32_t vlc_fourcc_t
Definition fourcc_gen.c:33
vlc_render_subpicture * vlc_render_subpicture_New(void)
Create a vlc_render_subpicture.
Definition subpicture.c:100
void vlc_render_subpicture_Delete(vlc_render_subpicture *)
Destroy a vlc_render_subpicture.
Definition subpicture.c:109
subpicture_region_t * subpicture_region_New(const video_format_t *p_fmt)
This function will create a new subpicture region.
Definition subpicture.c:237
void subpicture_Delete(subpicture_t *p_subpic)
This function delete a subpicture created by subpicture_New.
Definition subpicture.c:80
void vlc_spu_regions_Clear(vlc_spu_regions *)
This function will clear a list of subpicture regions allocated by subpicture_region_New.
Definition subpicture.c:343
unsigned picture_BlendSubpicture(picture_t *, vlc_blender_t *, vlc_render_subpicture *)
This function will blend a given subpicture onto a picture.
Definition subpicture.c:355
void subpicture_region_Delete(subpicture_region_t *p_region)
This function will destroy a subpicture region allocated by subpicture_region_New.
Definition subpicture.c:327
subpicture_region_t * subpicture_region_NewText(void)
This function will create a new text subpicture region.
Definition subpicture.c:276
void subpicture_Update(subpicture_t *, const video_format_t *src, const video_format_t *, vlc_tick_t)
This function will update the content of a subpicture created with a non NULL subpicture_updater_t.
Definition subpicture.c:175
subpicture_region_t * subpicture_region_ForPicture(const video_format_t *p_fmt, picture_t *pic)
Create a subpicture region containing the picture.
Definition subpicture.c:289
subpicture_t * subpicture_New(const subpicture_updater_t *)
This function create a new empty subpicture.
Definition subpicture.c:45
subpicture_t * subpicture_NewFromPicture(vlc_object_t *, picture_t *, vlc_fourcc_t i_chroma)
This function will create a subpicture having one region in the requested chroma showing the given pi...
Definition subpicture.c:121
#define VLC_VECTOR(type)
Vector struct body.
Definition vlc_vector.h:66
Structure describing a filter.
Definition vlc_filter.h:219
Video picture.
Definition vlc_picture.h:130
Definition subpicture.c:40
Definition subpicture.h:23
Definition vlc_subpicture.h:211
picture_t * p_picture
picture comprising this region
Definition vlc_subpicture.h:212
int i_alpha
transparency
Definition vlc_subpicture.h:214
vout_display_place_t place
visible area in display coordinates
Definition vlc_subpicture.h:213
Video subtitle region.
Definition vlc_subpicture.h:72
int i_y
position of region, relative to alignment
Definition vlc_subpicture.h:78
int i_align
alignment flags of region
Definition vlc_subpicture.h:79
int i_x
position of region, relative to alignment
Definition vlc_subpicture.h:77
video_format_t fmt
format of the picture
Definition vlc_subpicture.h:73
picture_t * p_picture
picture comprising this region
Definition vlc_subpicture.h:74
subpicture_region_private_t * p_private
Private data for spu_t only
Definition vlc_subpicture.h:89
int i_max_width
Definition vlc_subpicture.h:85
struct vlc_list node
vertical rendering/cropping target/limit
Definition vlc_subpicture.h:88
int i_alpha
transparency
Definition vlc_subpicture.h:80
int i_max_height
horizontal rendering/cropping target/limit
Definition vlc_subpicture.h:86
int text_flags
VLC_SUBPIC_TEXT_FLAG_xxx and SUBPICTURE_ALIGN_xxx.
Definition vlc_subpicture.h:84
text_segment_t * p_text
subtitle text, made of a list of segments
Definition vlc_subpicture.h:83
bool b_absolute
position is absolute in the movie
Definition vlc_subpicture.h:76
Video subtitle.
Definition vlc_subpicture.h:234
vlc_tick_t i_start
beginning of display date
Definition vlc_subpicture.h:251
subpicture_t * p_next
an increasing unique number
Definition vlc_subpicture.h:244
bool b_ephemer
If this flag is set to true the subtitle will be displayed until the next one appears or if i_stop is...
Definition vlc_subpicture.h:255
unsigned i_original_picture_height
original height of the movie
Definition vlc_subpicture.h:268
bool b_fade
enable fading
Definition vlc_subpicture.h:258
unsigned i_original_picture_width
original width of the movie
Definition vlc_subpicture.h:267
subpicture_private_t * p_private
Definition vlc_subpicture.h:274
int i_alpha
transparency
Definition vlc_subpicture.h:269
bool b_subtitle
the picture is a movie subtitle
Definition vlc_subpicture.h:266
int64_t i_order
Definition vlc_subpicture.h:243
vlc_spu_regions regions
region list composing this subtitle
Definition vlc_subpicture.h:247
ssize_t i_channel
subpicture channel ID
Definition vlc_subpicture.h:237
vlc_tick_t i_stop
end of display date.
Definition vlc_subpicture.h:252
subpicture_updater_t updater
Definition vlc_subpicture.h:272
Definition vlc_subpicture.h:203
const struct vlc_spu_updater_ops * ops
Definition vlc_subpicture.h:205
void * sys
Definition vlc_subpicture.h:204
Text segment for subtitles.
Definition vlc_text_style.h:139
video format description
Definition vlc_es.h:356
Definition vlc_es.h:45
Doubly-linked list node.
Definition vlc_list.h:44
VLC object common members.
Definition vlc_objects.h:53
Definition vlc_subpicture.h:218
int64_t i_order
Definition vlc_subpicture.h:220
struct vlc_render_subpicture::@278 regions
list of regions to render
Definition vlc_subpicture.h:110
video_palette_t palette
Definition vlc_subpicture.h:115
int x_start
Definition vlc_subpicture.h:111
int y_end
Definition vlc_subpicture.h:114
int x_end
Definition vlc_subpicture.h:112
int y_start
Definition vlc_subpicture.h:113
Subpicture updater operation virtual table.
Definition vlc_subpicture.h:180
void(* update)(subpicture_t *, const video_format_t *prev_src, const video_format_t *p_fmt_src, const video_format_t *prev_dst, const video_format_t *p_fmt_dst, vlc_tick_t)
Mandatory callback called after pf_validate and doing the main job of creating the subpicture regions...
Definition vlc_subpicture.h:184
void(* destroy)(subpicture_t *)
Optional callback for subpicture private data cleanup.
Definition vlc_subpicture.h:190
Video placement.
Definition vlc_vout_display.h:502
This file is a collection of common definitions and types.
This provides convenience helpers for linked lists.
This file defines picture structures and functions in vlc.
int64_t vlc_tick_t
High precision date or time interval.
Definition vlc_tick.h:48
This provides convenience helpers for vectors.
Video output display modules interface.