2 * Copyright (C) 2006 Evgeniy Stepanov <eugeni.stepanov@gmail.com>
4 * This file is part of libass.
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.
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.
24 #include "ass_types.h"
26 #define LIBASS_VERSION 0x01201000
29 * A linked list of images produced by an ass renderer.
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.
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
43 uint32_t color; // Bitmap color and alpha, RGBA
44 int dst_x, dst_y; // Bitmap placement inside the video frame
46 struct ass_image *next; // Next image, or NULL
57 * Hinting type. (see ass_set_hinting below)
59 * Setting hinting to anything but ASS_HINTING_NONE will put libass in a mode
60 * that reduces compatibility with vsfilter and many ASS scripts. The main
61 * problem is that hinting conflicts with smooth scaling, which precludes
62 * animations and precise positioning.
64 * In other words, enabling hinting might break some scripts severely.
66 * FreeType's native hinter is still buggy sometimes and it is recommended
67 * to use the light autohinter, ASS_HINTING_LIGHT, instead. For best
68 * compatibility with problematic fonts, disable hinting.
78 * \brief Text shaping levels.
80 * SIMPLE is a fast, font-agnostic shaper that can do only substitutions.
81 * COMPLEX is a slower shaper using OpenType for substitutions and positioning.
83 * libass uses the best shaper available by default.
86 ASS_SHAPING_SIMPLE = 0,
91 * \brief Style override options. See
92 * ass_set_selective_style_override_enabled() for details.
95 ASS_OVERRIDE_BIT_STYLE = 1,
96 ASS_OVERRIDE_BIT_FONT_SIZE = 2,
100 * \brief Return the version of library. This returns the value LIBASS_VERSION
101 * was set to when the library was compiled.
102 * \return library version
104 int ass_library_version(void);
107 * \brief Initialize the library.
108 * \return library handle or NULL if failed
110 ASS_Library *ass_library_init(void);
113 * \brief Finalize the library
114 * \param priv library handle
116 void ass_library_done(ASS_Library *priv);
119 * \brief Set additional fonts directory.
120 * Optional directory that will be scanned for fonts recursively. The fonts
121 * found are used for font lookup.
122 * NOTE: A valid font directory is not needed to support embedded fonts.
124 * \param priv library handle
125 * \param fonts_dir directory with additional fonts
127 void ass_set_fonts_dir(ASS_Library *priv, const char *fonts_dir);
130 * \brief Whether fonts should be extracted from track data.
131 * \param priv library handle
132 * \param extract whether to extract fonts
134 void ass_set_extract_fonts(ASS_Library *priv, int extract);
137 * \brief Register style overrides with a library instance.
138 * The overrides should have the form [Style.]Param=Value, e.g.
139 * SomeStyle.Font=Arial
140 * ScaledBorderAndShadow=yes
142 * \param priv library handle
143 * \param list NULL-terminated list of strings
145 void ass_set_style_overrides(ASS_Library *priv, char **list);
148 * \brief Explicitly process style overrides for a track.
149 * \param track track handle
151 void ass_process_force_style(ASS_Track *track);
154 * \brief Register a callback for debug/info messages.
155 * If a callback is registered, it is called for every message emitted by
156 * libass. The callback receives a format string and a list of arguments,
157 * to be used for the printf family of functions. Additionally, a log level
158 * from 0 (FATAL errors) to 7 (verbose DEBUG) is passed. Usually, level 5
159 * should be used by applications.
160 * If no callback is set, all messages level < 5 are printed to stderr,
161 * prefixed with [ass].
163 * \param priv library handle
164 * \param msg_cb pointer to callback function
165 * \param data additional data, will be passed to callback
167 void ass_set_message_cb(ASS_Library *priv, void (*msg_cb)
168 (int level, const char *fmt, va_list args, void *data),
172 * \brief Initialize the renderer.
173 * \param priv library handle
174 * \return renderer handle or NULL if failed
176 ASS_Renderer *ass_renderer_init(ASS_Library *);
179 * \brief Finalize the renderer.
180 * \param priv renderer handle
182 void ass_renderer_done(ASS_Renderer *priv);
185 * \brief Set the frame size in pixels, including margins.
186 * The renderer will never return images that are outside of the frame area.
187 * The value set with this function can influence the pixel aspect ratio used
188 * for rendering. If the frame size doesn't equal to the video size, you may
189 * have to use ass_set_pixel_aspect().
190 * @see ass_set_pixel_aspect()
191 * @see ass_set_margins()
192 * \param priv renderer handle
196 void ass_set_frame_size(ASS_Renderer *priv, int w, int h);
199 * \brief Set the source image size in pixels.
200 * This is used to calculate the source aspect ratio and the blur scale.
201 * The source image size can be reset to default by setting w and h to 0.
202 * The value set with this function can influence the pixel aspect ratio used
204 * @see ass_set_pixel_aspect()
205 * \param priv renderer handle
209 void ass_set_storage_size(ASS_Renderer *priv, int w, int h);
212 * \brief Set shaping level. This is merely a hint, the renderer will use
213 * whatever is available if the request cannot be fulfilled.
214 * \param level shaping level
216 void ass_set_shaper(ASS_Renderer *priv, ASS_ShapingLevel level);
219 * \brief Set frame margins. These values may be negative if pan-and-scan
220 * is used. The margins are in pixels. Each value specifies the distance from
221 * the video rectangle to the renderer frame. If a given margin value is
222 * positive, there will be free space between renderer frame and video area.
223 * If a given margin value is negative, the frame is inside the video, i.e.
224 * the video has been cropped.
226 * The renderer will try to keep subtitles inside the frame area. If possible,
227 * text is layout so that it is inside the cropped area. Subtitle events
228 * that can't be moved are cropped against the frame area.
230 * ass_set_use_margins() can be used to allow libass to render subtitles into
231 * the empty areas if margins are positive, i.e. the video area is smaller than
232 * the frame. (Traditionally, this has been used to show subtitles in
233 * the bottom "black bar" between video bottom screen border when playing 16:9
234 * video on a 4:3 screen.)
236 * When using this function, it is recommended to calculate and set your own
237 * aspect ratio with ass_set_pixel_aspect(), as the defaults won't make any
239 * @see ass_set_pixel_aspect()
240 * \param priv renderer handle
241 * \param t top margin
242 * \param b bottom margin
243 * \param l left margin
244 * \param r right margin
246 void ass_set_margins(ASS_Renderer *priv, int t, int b, int l, int r);
249 * \brief Whether margins should be used for placing regular events.
250 * \param priv renderer handle
251 * \param use whether to use the margins
253 void ass_set_use_margins(ASS_Renderer *priv, int use);
256 * \brief Set pixel aspect ratio correction.
257 * This is the ratio of pixel width to pixel height.
259 * Generally, this is (s_w / s_h) / (d_w / d_h), where s_w and s_h is the
260 * video storage size, and d_w and d_h is the video display size. (Display
261 * and storage size can be different for anamorphic video, such as DVDs.)
263 * If the pixel aspect ratio is 0, or if the aspect ratio has never been set
264 * by calling this function, libass will calculate a default pixel aspect ratio
265 * out of values set with ass_set_frame_size() and ass_set_storage_size(). Note
266 * that this is useful only if the frame size corresponds to the video display
267 * size. Keep in mind that the margins set with ass_set_margins() are ignored
268 * for aspect ratio calculations as well.
269 * If the storage size has not been set, a pixel aspect ratio of 1 is assumed.
270 * \param priv renderer handle
271 * \param par pixel aspect ratio (1.0 means square pixels, 0 means default)
273 void ass_set_pixel_aspect(ASS_Renderer *priv, double par);
276 * \brief Set aspect ratio parameters.
277 * This calls ass_set_pixel_aspect(priv, dar / sar).
278 * @deprecated New code should use ass_set_pixel_aspect().
279 * \param priv renderer handle
280 * \param dar display aspect ratio (DAR), prescaled for output PAR
281 * \param sar storage aspect ratio (SAR)
283 void ass_set_aspect_ratio(ASS_Renderer *priv, double dar, double sar);
286 * \brief Set a fixed font scaling factor.
287 * \param priv renderer handle
288 * \param font_scale scaling factor, default is 1.0
290 void ass_set_font_scale(ASS_Renderer *priv, double font_scale);
293 * \brief Set font hinting method.
294 * \param priv renderer handle
295 * \param ht hinting method
297 void ass_set_hinting(ASS_Renderer *priv, ASS_Hinting ht);
300 * \brief Set line spacing. Will not be scaled with frame size.
301 * \param priv renderer handle
302 * \param line_spacing line spacing in pixels
304 void ass_set_line_spacing(ASS_Renderer *priv, double line_spacing);
307 * \brief Set vertical line position.
308 * \param priv renderer handle
309 * \param line_position vertical line position of subtitles in percent
310 * (0-100: 0 = on the bottom (default), 100 = on top)
312 void ass_set_line_position(ASS_Renderer *priv, double line_position);
315 * \brief Set font lookup defaults.
316 * \param default_font path to default font to use. Must be supplied if
317 * fontconfig is disabled or unavailable.
318 * \param default_family fallback font family for fontconfig, or NULL
319 * \param fc whether to use fontconfig
320 * \param config path to fontconfig configuration file, or NULL. Only relevant
321 * if fontconfig is used.
322 * \param update whether fontconfig cache should be built/updated now. Only
323 * relevant if fontconfig is used.
325 * NOTE: font lookup must be configured before an ASS_Renderer can be used.
327 void ass_set_fonts(ASS_Renderer *priv, const char *default_font,
328 const char *default_family, int fc, const char *config,
332 * \brief Set selective style override mode.
333 * If enabled, the renderer attempts to override the ASS script's styling of
334 * normal subtitles, without affecting explicitly positioned text. If an event
335 * looks like a normal subtitle, parts of the font style are copied from the
336 * user style set with ass_set_selective_style_override().
337 * Warning: the heuristic used for deciding when to override the style is rather
338 * rough, and enabling this option can lead to incorrectly rendered
339 * subtitles. Since the ASS format doesn't have any support for
340 * allowing end-users to customize subtitle styling, this feature can
341 * only be implemented on "best effort" basis, and has to rely on
342 * heuristics that can easily break.
343 * \param priv renderer handle
344 * \param bits bit mask comprised of ASS_OverrideBits values. If the value is
345 * 0, all override features are disabled, and libass will behave like libass
346 * versions before this feature was introduced. Possible values:
347 * ASS_OVERRIDE_BIT_STYLE: apply the style as set with
348 * ass_set_selective_style_override() on events which look like
349 * dialogue. Other style overrides are also applied this way, except
350 * ass_set_font_scale(). How ass_set_font_scale() is applied depends
351 * on the ASS_OVERRIDE_BIT_FONT_SIZE flag.
352 * ASS_OVERRIDE_BIT_FONT_SIZE: apply ass_set_font_scale() only on events
353 * which look like dialogue. If not set, it is applied to all
355 * 0: ignore ass_set_selective_style_override(), but apply all other
356 * overrides (traditional behavior).
358 void ass_set_selective_style_override_enabled(ASS_Renderer *priv, int bits);
361 * \brief Set style for selective style override.
362 * See ass_set_selective_style_override_enabled().
363 * \param style style settings to use if override is enabled. Applications
364 * should initialize it with {0} before setting fields. Strings will be copied
367 void ass_set_selective_style_override(ASS_Renderer *priv, ASS_Style *style);
370 * \brief Update/build font cache. This needs to be called if it was
371 * disabled when ass_set_fonts was set.
373 * \param priv renderer handle
376 int ass_fonts_update(ASS_Renderer *priv);
379 * \brief Set hard cache limits. Do not set, or set to zero, for reasonable
382 * \param priv renderer handle
383 * \param glyph_max maximum number of cached glyphs
384 * \param bitmap_max_size maximum bitmap cache size (in MB)
386 void ass_set_cache_limits(ASS_Renderer *priv, int glyph_max,
387 int bitmap_max_size);
390 * \brief Render a frame, producing a list of ASS_Image.
391 * \param priv renderer handle
392 * \param track subtitle track
393 * \param now video timestamp in milliseconds
394 * \param detect_change compare to the previous call and set to 1
395 * if positions changed, or set to 2 if content changed.
397 ASS_Image *ass_render_frame(ASS_Renderer *priv, ASS_Track *track,
398 long long now, int *detect_change);
402 * The following functions operate on track objects and do not need
407 * \brief Allocate a new empty track object.
408 * \param library handle
409 * \return pointer to empty track
411 ASS_Track *ass_new_track(ASS_Library *);
414 * \brief Deallocate track and all its child objects (styles and events).
415 * \param track track to deallocate
417 void ass_free_track(ASS_Track *track);
420 * \brief Allocate new style.
422 * \return newly allocated style id
424 int ass_alloc_style(ASS_Track *track);
427 * \brief Allocate new event.
429 * \return newly allocated event id
431 int ass_alloc_event(ASS_Track *track);
434 * \brief Delete a style.
436 * \param sid style id
437 * Deallocates style data. Does not modify track->n_styles.
439 void ass_free_style(ASS_Track *track, int sid);
442 * \brief Delete an event.
444 * \param eid event id
445 * Deallocates event data. Does not modify track->n_events.
447 void ass_free_event(ASS_Track *track, int eid);
450 * \brief Parse a chunk of subtitle stream data.
452 * \param data string to parse
453 * \param size length of data
455 void ass_process_data(ASS_Track *track, char *data, int size);
458 * \brief Parse Codec Private section of the subtitle stream, in Matroska
459 * format. See the Matroska specification for details.
460 * \param track target track
461 * \param data string to parse
462 * \param size length of data
464 void ass_process_codec_private(ASS_Track *track, char *data, int size);
467 * \brief Parse a chunk of subtitle stream data. A chunk contains exactly one
468 * event in Matroska format. See the Matroska specification for details.
470 * \param data string to parse
471 * \param size length of data
472 * \param timecode starting time of the event (milliseconds)
473 * \param duration duration of the event (milliseconds)
475 void ass_process_chunk(ASS_Track *track, char *data, int size,
476 long long timecode, long long duration);
479 * \brief Flush buffered events.
482 void ass_flush_events(ASS_Track *track);
485 * \brief Read subtitles from file.
486 * \param library library handle
487 * \param fname file name
488 * \param codepage encoding (iconv format)
489 * \return newly allocated track
491 ASS_Track *ass_read_file(ASS_Library *library, char *fname,
495 * \brief Read subtitles from memory.
496 * \param library library handle
497 * \param buf pointer to subtitles text
498 * \param bufsize size of buffer
499 * \param codepage encoding (iconv format)
500 * \return newly allocated track
502 ASS_Track *ass_read_memory(ASS_Library *library, char *buf,
503 size_t bufsize, char *codepage);
505 * \brief Read styles from file into already initialized track.
506 * \param fname file name
507 * \param codepage encoding (iconv format)
508 * \return 0 on success
510 int ass_read_styles(ASS_Track *track, char *fname, char *codepage);
513 * \brief Add a memory font.
514 * \param library library handle
515 * \param name attachment name
516 * \param data binary font data
517 * \param data_size data size
519 void ass_add_font(ASS_Library *library, char *name, char *data,
523 * \brief Remove all fonts stored in an ass_library object.
524 * \param library library handle
526 void ass_clear_fonts(ASS_Library *library);
529 * \brief Calculates timeshift from now to the start of some other subtitle
530 * event, depending on movement parameter.
531 * \param track subtitle track
532 * \param now current time in milliseconds
533 * \param movement how many events to skip from the one currently displayed
534 * +2 means "the one after the next", -1 means "previous"
535 * \return timeshift in milliseconds
537 long long ass_step_sub(ASS_Track *track, long long now, int movement);
539 #endif /* LIBASS_ASS_H */