Mercurial > mplayer.hg
annotate libass/ass.h @ 34697:ac6b38cd0d45
Rename sub window video window.
It was a bad idea to name the video window "sub window" at the time
the GUI was written. The term "sub window" does make sense from the
programmer's point of view, but it doesn't make any sense at all from
the user's point of view, because the sub window simply is the window
where the video will be displayed.
Moreover, since the term "sub" is generally short for "subtitles",
the renaming makes the code much easier to understand.
author | ib |
---|---|
date | Sat, 03 Mar 2012 16:45:15 +0000 |
parents | 6e7f60f6f9d4 |
children | 49fc594fda43 |
rev | line source |
---|---|
20008
fa122b7c71c6
Add copyright notice and vim/emacs comments to libass and vf_ass.c.
eugeni
parents:
19652
diff
changeset
|
1 /* |
26723 | 2 * Copyright (C) 2006 Evgeniy Stepanov <eugeni.stepanov@gmail.com> |
3 * | |
26738
588ce97b44f2
Speak of libass instead of MPlayer in the libass license headers.
diego
parents:
26723
diff
changeset
|
4 * This file is part of libass. |
26723 | 5 * |
34011 | 6 * Permission to use, copy, modify, and distribute this software for any |
7 * purpose with or without fee is hereby granted, provided that the above | |
8 * copyright notice and this permission notice appear in all copies. | |
26723 | 9 * |
34011 | 10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES |
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | |
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | |
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
26723 | 17 */ |
20008
fa122b7c71c6
Add copyright notice and vim/emacs comments to libass and vf_ass.c.
eugeni
parents:
19652
diff
changeset
|
18 |
25897
aaebaf255b23
Consistently give all libass multiple inclusion guards a LIBASS_ prefix.
diego
parents:
25613
diff
changeset
|
19 #ifndef LIBASS_ASS_H |
aaebaf255b23
Consistently give all libass multiple inclusion guards a LIBASS_ prefix.
diego
parents:
25613
diff
changeset
|
20 #define LIBASS_ASS_H |
18937 | 21 |
26138
74055622161d
Add missing header #includes to fix 'make checkheaders'.
diego
parents:
25897
diff
changeset
|
22 #include <stdio.h> |
30200 | 23 #include <stdarg.h> |
18937 | 24 #include "ass_types.h" |
25 | |
34295 | 26 #define LIBASS_VERSION 0x01000000 |
30200 | 27 |
28 /* | |
29 * A linked list of images produced by an ass renderer. | |
30 * | |
31 * These images have to be rendered in-order for the correct screen | |
32 * composition. The libass renderer clips these bitmaps to the frame size. | |
33 * w/h can be zero, in this case the bitmap should not be rendered at all. | |
34 * The last bitmap row is not guaranteed to be padded up to stride size, | |
35 * e.g. in the worst case a bitmap has the size stride * (h - 1) + w. | |
36 */ | |
37 typedef struct ass_image { | |
38 int w, h; // Bitmap width/height | |
39 int stride; // Bitmap stride | |
40 unsigned char *bitmap; // 1bpp stride*h alpha buffer | |
41 // Note: the last row may not be padded to | |
42 // bitmap stride! | |
43 uint32_t color; // Bitmap color and alpha, RGBA | |
44 int dst_x, dst_y; // Bitmap placement inside the video frame | |
45 | |
46 struct ass_image *next; // Next image, or NULL | |
47 } ASS_Image; | |
18937 | 48 |
30200 | 49 /* |
50 * Hinting type. (see ass_set_hinting below) | |
51 * | |
52 * FreeType's native hinter is still buggy sometimes and it is recommended | |
53 * to use the light autohinter, ASS_HINTING_LIGHT, instead. For best | |
54 * compatibility with problematic fonts, disable hinting. | |
55 */ | |
56 typedef enum { | |
57 ASS_HINTING_NONE = 0, | |
58 ASS_HINTING_LIGHT, | |
59 ASS_HINTING_NORMAL, | |
60 ASS_HINTING_NATIVE | |
61 } ASS_Hinting; | |
18937 | 62 |
30200 | 63 /** |
34295 | 64 * \brief Text shaping levels. |
65 * | |
66 * SIMPLE is a fast, font-agnostic shaper that can do only substitutions. | |
67 * COMPLEX is a slower shaper using OpenType for substitutions and positioning. | |
68 * | |
69 * libass uses the best shaper available by default. | |
70 */ | |
71 typedef enum { | |
72 ASS_SHAPING_SIMPLE = 0, | |
73 ASS_SHAPING_COMPLEX | |
74 } ASS_ShapingLevel; | |
75 | |
76 /** | |
30200 | 77 * \brief Initialize the library. |
78 * \return library handle or NULL if failed | |
79 */ | |
80 ASS_Library *ass_library_init(void); | |
18937 | 81 |
30200 | 82 /** |
83 * \brief Finalize the library | |
84 * \param priv library handle | |
85 */ | |
86 void ass_library_done(ASS_Library *priv); | |
23134
1de2a46a0987
Add -ass-hinting option for setting font hinting method.
eugeni
parents:
21506
diff
changeset
|
87 |
18937 | 88 /** |
31853 | 89 * \brief Set additional fonts directory. |
90 * Optional directory that will be scanned for fonts recursively. The fonts | |
91 * found are used for font lookup. | |
92 * NOTE: A valid font directory is not needed to support embedded fonts. | |
30200 | 93 * |
94 * \param priv library handle | |
31853 | 95 * \param fonts_dir directory with additional fonts |
18937 | 96 */ |
30200 | 97 void ass_set_fonts_dir(ASS_Library *priv, const char *fonts_dir); |
18937 | 98 |
99 /** | |
30200 | 100 * \brief Whether fonts should be extracted from track data. |
18937 | 101 * \param priv library handle |
30200 | 102 * \param extract whether to extract fonts |
18937 | 103 */ |
30200 | 104 void ass_set_extract_fonts(ASS_Library *priv, int extract); |
20477 | 105 |
106 /** | |
30200 | 107 * \brief Register style overrides with a library instance. |
108 * The overrides should have the form [Style.]Param=Value, e.g. | |
109 * SomeStyle.Font=Arial | |
110 * ScaledBorderAndShadow=yes | |
111 * | |
112 * \param priv library handle | |
113 * \param list NULL-terminated list of strings | |
20477 | 114 */ |
30200 | 115 void ass_set_style_overrides(ASS_Library *priv, char **list); |
20477 | 116 |
30200 | 117 /** |
118 * \brief Explicitly process style overrides for a track. | |
119 * \param track track handle | |
120 */ | |
121 void ass_process_force_style(ASS_Track *track); | |
18937 | 122 |
20477 | 123 /** |
30200 | 124 * \brief Register a callback for debug/info messages. |
125 * If a callback is registered, it is called for every message emitted by | |
126 * libass. The callback receives a format string and a list of arguments, | |
127 * to be used for the printf family of functions. Additionally, a log level | |
128 * from 0 (FATAL errors) to 7 (verbose DEBUG) is passed. Usually, level 5 | |
129 * should be used by applications. | |
130 * If no callback is set, all messages level < 5 are printed to stderr, | |
131 * prefixed with [ass]. | |
132 * | |
133 * \param priv library handle | |
134 * \param msg_cb pointer to callback function | |
135 * \param data additional data, will be passed to callback | |
136 */ | |
137 void ass_set_message_cb(ASS_Library *priv, void (*msg_cb) | |
138 (int level, const char *fmt, va_list args, void *data), | |
139 void *data); | |
140 | |
141 /** | |
142 * \brief Initialize the renderer. | |
20477 | 143 * \param priv library handle |
144 * \return renderer handle or NULL if failed | |
145 */ | |
30200 | 146 ASS_Renderer *ass_renderer_init(ASS_Library *); |
20477 | 147 |
148 /** | |
30200 | 149 * \brief Finalize the renderer. |
20477 | 150 * \param priv renderer handle |
151 */ | |
30200 | 152 void ass_renderer_done(ASS_Renderer *priv); |
153 | |
154 /** | |
155 * \brief Set the frame size in pixels, including margins. | |
156 * \param priv renderer handle | |
157 * \param w width | |
158 * \param h height | |
159 */ | |
160 void ass_set_frame_size(ASS_Renderer *priv, int w, int h); | |
20477 | 161 |
30200 | 162 /** |
34295 | 163 * \brief Set shaping level. This is merely a hint, the renderer will use |
164 * whatever is available if the request cannot be fulfilled. | |
165 * \param level shaping level | |
166 */ | |
167 void ass_set_shaper(ASS_Renderer *priv, ASS_ShapingLevel level); | |
168 | |
169 /** | |
30200 | 170 * \brief Set frame margins. These values may be negative if pan-and-scan |
171 * is used. | |
172 * \param priv renderer handle | |
173 * \param t top margin | |
174 * \param b bottom margin | |
175 * \param l left margin | |
176 * \param r right margin | |
177 */ | |
178 void ass_set_margins(ASS_Renderer *priv, int t, int b, int l, int r); | |
20477 | 179 |
180 /** | |
30200 | 181 * \brief Whether margins should be used for placing regular events. |
182 * \param priv renderer handle | |
183 * \param use whether to use the margins | |
184 */ | |
185 void ass_set_use_margins(ASS_Renderer *priv, int use); | |
186 | |
187 /** | |
188 * \brief Set aspect ratio parameters. | |
189 * \param priv renderer handle | |
190 * \param dar display aspect ratio (DAR), prescaled for output PAR | |
191 * \param sar storage aspect ratio (SAR) | |
20477 | 192 */ |
30200 | 193 void ass_set_aspect_ratio(ASS_Renderer *priv, double dar, double sar); |
194 | |
195 /** | |
196 * \brief Set a fixed font scaling factor. | |
197 * \param priv renderer handle | |
198 * \param font_scale scaling factor, default is 1.0 | |
199 */ | |
200 void ass_set_font_scale(ASS_Renderer *priv, double font_scale); | |
201 | |
202 /** | |
203 * \brief Set font hinting method. | |
204 * \param priv renderer handle | |
205 * \param ht hinting method | |
206 */ | |
207 void ass_set_hinting(ASS_Renderer *priv, ASS_Hinting ht); | |
208 | |
209 /** | |
210 * \brief Set line spacing. Will not be scaled with frame size. | |
211 * \param priv renderer handle | |
212 * \param line_spacing line spacing in pixels | |
213 */ | |
214 void ass_set_line_spacing(ASS_Renderer *priv, double line_spacing); | |
18937 | 215 |
216 /** | |
30200 | 217 * \brief Set font lookup defaults. |
218 * \param default_font path to default font to use. Must be supplied if | |
219 * fontconfig is disabled or unavailable. | |
220 * \param default_family fallback font family for fontconfig, or NULL | |
221 * \param fc whether to use fontconfig | |
222 * \param config path to fontconfig configuration file, or NULL. Only relevant | |
223 * if fontconfig is used. | |
224 * \param update whether fontconfig cache should be built/updated now. Only | |
225 * relevant if fontconfig is used. | |
31853 | 226 * |
227 * NOTE: font lookup must be configured before an ASS_Renderer can be used. | |
26582
62ac4f8062ee
Remove libass dependency on global font_fontconfig variable.
eugeni
parents:
26138
diff
changeset
|
228 */ |
30200 | 229 void ass_set_fonts(ASS_Renderer *priv, const char *default_font, |
230 const char *default_family, int fc, const char *config, | |
231 int update); | |
26582
62ac4f8062ee
Remove libass dependency on global font_fontconfig variable.
eugeni
parents:
26138
diff
changeset
|
232 |
62ac4f8062ee
Remove libass dependency on global font_fontconfig variable.
eugeni
parents:
26138
diff
changeset
|
233 /** |
30200 | 234 * \brief Update/build font cache. This needs to be called if it was |
235 * disabled when ass_set_fonts was set. | |
236 * | |
237 * \param priv renderer handle | |
238 * \return success | |
239 */ | |
240 int ass_fonts_update(ASS_Renderer *priv); | |
241 | |
242 /** | |
243 * \brief Set hard cache limits. Do not set, or set to zero, for reasonable | |
244 * defaults. | |
245 * | |
246 * \param priv renderer handle | |
247 * \param glyph_max maximum number of cached glyphs | |
248 * \param bitmap_max_size maximum bitmap cache size (in MB) | |
249 */ | |
250 void ass_set_cache_limits(ASS_Renderer *priv, int glyph_max, | |
251 int bitmap_max_size); | |
252 | |
253 /** | |
254 * \brief Render a frame, producing a list of ASS_Image. | |
255 * \param priv renderer handle | |
18937 | 256 * \param track subtitle track |
257 * \param now video timestamp in milliseconds | |
30200 | 258 * \param detect_change will be set to 1 if a change occured compared |
259 * to the last invocation | |
18937 | 260 */ |
30200 | 261 ASS_Image *ass_render_frame(ASS_Renderer *priv, ASS_Track *track, |
262 long long now, int *detect_change); | |
18937 | 263 |
264 | |
30200 | 265 /* |
266 * The following functions operate on track objects and do not need | |
267 * an ass_renderer | |
268 */ | |
18937 | 269 |
270 /** | |
30200 | 271 * \brief Allocate a new empty track object. |
272 * \param library handle | |
18937 | 273 * \return pointer to empty track |
274 */ | |
30200 | 275 ASS_Track *ass_new_track(ASS_Library *); |
18937 | 276 |
277 /** | |
30200 | 278 * \brief Deallocate track and all its child objects (styles and events). |
18937 | 279 * \param track track to deallocate |
280 */ | |
30200 | 281 void ass_free_track(ASS_Track *track); |
18937 | 282 |
283 /** | |
30200 | 284 * \brief Allocate new style. |
18937 | 285 * \param track track |
286 * \return newly allocated style id | |
287 */ | |
30200 | 288 int ass_alloc_style(ASS_Track *track); |
18937 | 289 |
290 /** | |
30200 | 291 * \brief Allocate new event. |
18937 | 292 * \param track track |
293 * \return newly allocated event id | |
294 */ | |
30200 | 295 int ass_alloc_event(ASS_Track *track); |
18937 | 296 |
297 /** | |
30200 | 298 * \brief Delete a style. |
19474
07209f48e527
Add public functions for removal of styles and events.
eugeni
parents:
18937
diff
changeset
|
299 * \param track track |
07209f48e527
Add public functions for removal of styles and events.
eugeni
parents:
18937
diff
changeset
|
300 * \param sid style id |
07209f48e527
Add public functions for removal of styles and events.
eugeni
parents:
18937
diff
changeset
|
301 * Deallocates style data. Does not modify track->n_styles. |
07209f48e527
Add public functions for removal of styles and events.
eugeni
parents:
18937
diff
changeset
|
302 */ |
30200 | 303 void ass_free_style(ASS_Track *track, int sid); |
19474
07209f48e527
Add public functions for removal of styles and events.
eugeni
parents:
18937
diff
changeset
|
304 |
07209f48e527
Add public functions for removal of styles and events.
eugeni
parents:
18937
diff
changeset
|
305 /** |
30200 | 306 * \brief Delete an event. |
19474
07209f48e527
Add public functions for removal of styles and events.
eugeni
parents:
18937
diff
changeset
|
307 * \param track track |
07209f48e527
Add public functions for removal of styles and events.
eugeni
parents:
18937
diff
changeset
|
308 * \param eid event id |
07209f48e527
Add public functions for removal of styles and events.
eugeni
parents:
18937
diff
changeset
|
309 * Deallocates event data. Does not modify track->n_events. |
07209f48e527
Add public functions for removal of styles and events.
eugeni
parents:
18937
diff
changeset
|
310 */ |
30200 | 311 void ass_free_event(ASS_Track *track, int eid); |
19474
07209f48e527
Add public functions for removal of styles and events.
eugeni
parents:
18937
diff
changeset
|
312 |
07209f48e527
Add public functions for removal of styles and events.
eugeni
parents:
18937
diff
changeset
|
313 /** |
27498
d895515b366d
libass: add a new ass_process_data() to process demuxed subtitle packets
aurel
parents:
26738
diff
changeset
|
314 * \brief Parse a chunk of subtitle stream data. |
d895515b366d
libass: add a new ass_process_data() to process demuxed subtitle packets
aurel
parents:
26738
diff
changeset
|
315 * \param track track |
d895515b366d
libass: add a new ass_process_data() to process demuxed subtitle packets
aurel
parents:
26738
diff
changeset
|
316 * \param data string to parse |
d895515b366d
libass: add a new ass_process_data() to process demuxed subtitle packets
aurel
parents:
26738
diff
changeset
|
317 * \param size length of data |
d895515b366d
libass: add a new ass_process_data() to process demuxed subtitle packets
aurel
parents:
26738
diff
changeset
|
318 */ |
30200 | 319 void ass_process_data(ASS_Track *track, char *data, int size); |
27498
d895515b366d
libass: add a new ass_process_data() to process demuxed subtitle packets
aurel
parents:
26738
diff
changeset
|
320 |
d895515b366d
libass: add a new ass_process_data() to process demuxed subtitle packets
aurel
parents:
26738
diff
changeset
|
321 /** |
31853 | 322 * \brief Parse Codec Private section of the subtitle stream, in Matroska |
323 * format. See the Matroska specification for details. | |
18937 | 324 * \param track target track |
325 * \param data string to parse | |
326 * \param size length of data | |
327 */ | |
30200 | 328 void ass_process_codec_private(ASS_Track *track, char *data, int size); |
18937 | 329 |
330 /** | |
31853 | 331 * \brief Parse a chunk of subtitle stream data. A chunk contains exactly one |
332 * event in Matroska format. See the Matroska specification for details. | |
18937 | 333 * \param track track |
334 * \param data string to parse | |
335 * \param size length of data | |
336 * \param timecode starting time of the event (milliseconds) | |
337 * \param duration duration of the event (milliseconds) | |
30200 | 338 */ |
339 void ass_process_chunk(ASS_Track *track, char *data, int size, | |
340 long long timecode, long long duration); | |
23424
7286d245bf33
Move code for reading a file and recoding it to utf-8 to a separate function.
eugeni
parents:
23134
diff
changeset
|
341 |
18937 | 342 /** |
31227
ee7beb1a3a6e
backport ass_flush_events() from upstream libass and make use of it
aurel
parents:
30200
diff
changeset
|
343 * \brief Flush buffered events. |
ee7beb1a3a6e
backport ass_flush_events() from upstream libass and make use of it
aurel
parents:
30200
diff
changeset
|
344 * \param track track |
ee7beb1a3a6e
backport ass_flush_events() from upstream libass and make use of it
aurel
parents:
30200
diff
changeset
|
345 */ |
ee7beb1a3a6e
backport ass_flush_events() from upstream libass and make use of it
aurel
parents:
30200
diff
changeset
|
346 void ass_flush_events(ASS_Track *track); |
ee7beb1a3a6e
backport ass_flush_events() from upstream libass and make use of it
aurel
parents:
30200
diff
changeset
|
347 |
ee7beb1a3a6e
backport ass_flush_events() from upstream libass and make use of it
aurel
parents:
30200
diff
changeset
|
348 /** |
18937 | 349 * \brief Read subtitles from file. |
30200 | 350 * \param library library handle |
18937 | 351 * \param fname file name |
30200 | 352 * \param codepage encoding (iconv format) |
18937 | 353 * \return newly allocated track |
354 */ | |
30200 | 355 ASS_Track *ass_read_file(ASS_Library *library, char *fname, |
356 char *codepage); | |
18937 | 357 |
358 /** | |
20603 | 359 * \brief Read subtitles from memory. |
30200 | 360 * \param library library handle |
20603 | 361 * \param buf pointer to subtitles text |
362 * \param bufsize size of buffer | |
30200 | 363 * \param codepage encoding (iconv format) |
20603 | 364 * \return newly allocated track |
29263
0f1b5b68af32
whitespace cosmetics: Remove all trailing whitespace.
diego
parents:
27499
diff
changeset
|
365 */ |
30200 | 366 ASS_Track *ass_read_memory(ASS_Library *library, char *buf, |
367 size_t bufsize, char *codepage); | |
20603 | 368 /** |
30200 | 369 * \brief Read styles from file into already initialized track. |
370 * \param fname file name | |
371 * \param codepage encoding (iconv format) | |
19652
2c016957360a
Add -ass-styles option. It allows to load styles from a file and use them
eugeni
parents:
19638
diff
changeset
|
372 * \return 0 on success |
2c016957360a
Add -ass-styles option. It allows to load styles from a file and use them
eugeni
parents:
19638
diff
changeset
|
373 */ |
30200 | 374 int ass_read_styles(ASS_Track *track, char *fname, char *codepage); |
19652
2c016957360a
Add -ass-styles option. It allows to load styles from a file and use them
eugeni
parents:
19638
diff
changeset
|
375 |
2c016957360a
Add -ass-styles option. It allows to load styles from a file and use them
eugeni
parents:
19638
diff
changeset
|
376 /** |
21455 | 377 * \brief Add a memory font. |
30200 | 378 * \param library library handle |
18937 | 379 * \param name attachment name |
380 * \param data binary font data | |
381 * \param data_size data size | |
382 */ | |
30200 | 383 void ass_add_font(ASS_Library *library, char *name, char *data, |
384 int data_size); | |
18937 | 385 |
386 /** | |
30200 | 387 * \brief Remove all fonts stored in an ass_library object. |
388 * \param library library handle | |
25613
f00333e3facf
Copy font data to ass_library instead of referencing demuxer-owned memory.
eugeni
parents:
25535
diff
changeset
|
389 */ |
30200 | 390 void ass_clear_fonts(ASS_Library *library); |
25613
f00333e3facf
Copy font data to ass_library instead of referencing demuxer-owned memory.
eugeni
parents:
25535
diff
changeset
|
391 |
f00333e3facf
Copy font data to ass_library instead of referencing demuxer-owned memory.
eugeni
parents:
25535
diff
changeset
|
392 /** |
30200 | 393 * \brief Calculates timeshift from now to the start of some other subtitle |
394 * event, depending on movement parameter. | |
18937 | 395 * \param track subtitle track |
30200 | 396 * \param now current time in milliseconds |
18937 | 397 * \param movement how many events to skip from the one currently displayed |
398 * +2 means "the one after the next", -1 means "previous" | |
30200 | 399 * \return timeshift in milliseconds |
18937 | 400 */ |
30200 | 401 long long ass_step_sub(ASS_Track *track, long long now, int movement); |
18937 | 402 |
25897
aaebaf255b23
Consistently give all libass multiple inclusion guards a LIBASS_ prefix.
diego
parents:
25613
diff
changeset
|
403 #endif /* LIBASS_ASS_H */ |