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