2 * Copyright (C) 2006 Evgeniy Stepanov <eugeni.stepanov@gmail.com>
3 * Copyright (C) 2011 Grigori Goronzy <greg@chown.ath.cx>
5 * This file is part of libass.
7 * Permission to use, copy, modify, and distribute this software for any
8 * purpose with or without fee is hereby granted, provided that the above
9 * copyright notice and this permission notice appear in all copies.
11 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
12 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
13 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
14 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
15 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
16 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
17 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
25 #include "ass_types.h"
27 #define LIBASS_VERSION 0x01301000
34 * A linked list of images produced by an ass renderer.
36 * These images have to be rendered in-order for the correct screen
37 * composition. The libass renderer clips these bitmaps to the frame size.
38 * w/h can be zero, in this case the bitmap should not be rendered at all.
39 * The last bitmap row is not guaranteed to be padded up to stride size,
40 * e.g. in the worst case a bitmap has the size stride * (h - 1) + w.
42 typedef struct ass_image {
43 int w, h; // Bitmap width/height
44 int stride; // Bitmap stride
45 unsigned char *bitmap; // 1bpp stride*h alpha buffer
46 // Note: the last row may not be padded to
48 uint32_t color; // Bitmap color and alpha, RGBA
49 int dst_x, dst_y; // Bitmap placement inside the video frame
51 struct ass_image *next; // Next image, or NULL
62 * Hinting type. (see ass_set_hinting below)
64 * Setting hinting to anything but ASS_HINTING_NONE will put libass in a mode
65 * that reduces compatibility with vsfilter and many ASS scripts. The main
66 * problem is that hinting conflicts with smooth scaling, which precludes
67 * animations and precise positioning.
69 * In other words, enabling hinting might break some scripts severely.
71 * FreeType's native hinter is still buggy sometimes and it is recommended
72 * to use the light autohinter, ASS_HINTING_LIGHT, instead. For best
73 * compatibility with problematic fonts, disable hinting.
83 * \brief Text shaping levels.
85 * SIMPLE is a fast, font-agnostic shaper that can do only substitutions.
86 * COMPLEX is a slower shaper using OpenType for substitutions and positioning.
88 * libass uses the best shaper available by default.
91 ASS_SHAPING_SIMPLE = 0,
96 * \brief Style override options. See
97 * ass_set_selective_style_override_enabled() for details.
101 * Default mode (with no other bits set). All selective override features
102 * as well as the style set with ass_set_selective_style_override() are
103 * disabled, but traditional overrides like ass_set_font_scale() are
104 * applied unconditionally.
106 ASS_OVERRIDE_DEFAULT = 0,
108 * Apply the style as set with ass_set_selective_style_override() on events
109 * which look like dialogue. Other style overrides are also applied this
110 * way, except ass_set_font_scale(). How ass_set_font_scale() is applied
111 * depends on the ASS_OVERRIDE_BIT_SELECTIVE_FONT_SCALE flag.
113 * This is equivalent to setting all of the following bits:
115 * ASS_OVERRIDE_BIT_FONT_NAME
116 * ASS_OVERRIDE_BIT_FONT_SIZE_FIELDS
117 * ASS_OVERRIDE_BIT_COLORS
118 * ASS_OVERRIDE_BIT_BORDER
119 * ASS_OVERRIDE_BIT_ATTRIBUTES
121 ASS_OVERRIDE_BIT_STYLE = 1 << 0,
123 * Apply ass_set_font_scale() only on events which look like dialogue.
124 * If not set, the font scale is applied to all events. (The behavior and
125 * name of this flag are unintuitive, but exist for compatibility)
127 ASS_OVERRIDE_BIT_SELECTIVE_FONT_SCALE = 1 << 1,
129 * Old alias for ASS_OVERRIDE_BIT_SELECTIVE_FONT_SCALE. Deprecated. Do not use.
131 ASS_OVERRIDE_BIT_FONT_SIZE = 1 << 1,
133 * On dialogue events override: FontSize, Spacing, Blur, ScaleX, ScaleY
135 ASS_OVERRIDE_BIT_FONT_SIZE_FIELDS = 1 << 2,
137 * On dialogue events override: FontName, treat_fontname_as_pattern
139 ASS_OVERRIDE_BIT_FONT_NAME = 1 << 3,
141 * On dialogue events override: PrimaryColour, SecondaryColour, OutlineColour, BackColour
143 ASS_OVERRIDE_BIT_COLORS = 1 << 4,
145 * On dialogue events override: Bold, Italic, Underline, StrikeOut
147 ASS_OVERRIDE_BIT_ATTRIBUTES = 1 << 5,
149 * On dialogue events override: BorderStyle, Outline, Shadow
151 ASS_OVERRIDE_BIT_BORDER = 1 << 6,
153 * On dialogue events override: Alignment
155 ASS_OVERRIDE_BIT_ALIGNMENT = 1 << 7,
157 * On dialogue events override: MarginL, MarginR, MarginV
159 ASS_OVERRIDE_BIT_MARGINS = 1 << 8,
161 * Unconditionally replace all fields of all styles with the one provided
162 * with ass_set_selective_style_override().
163 * Does not apply ASS_OVERRIDE_BIT_SELECTIVE_FONT_SCALE.
164 * Add ASS_OVERRIDE_BIT_FONT_SIZE_FIELDS and ASS_OVERRIDE_BIT_BORDER if
165 * you want FontSize, Spacing, Outline, Shadow to be scaled to the script
166 * resolution given by the ASS_Track.
168 ASS_OVERRIDE_FULL_STYLE = 1 << 9,
172 * \brief Return the version of library. This returns the value LIBASS_VERSION
173 * was set to when the library was compiled.
174 * \return library version
176 int ass_library_version(void);
179 * \brief Default Font provider to load fonts in libass' database
181 * NONE don't use any default font provider for font lookup
182 * AUTODETECT use the first available font provider
183 * CORETEXT force a CoreText based font provider (OS X only)
184 * FONTCONFIG force a Fontconfig based font provider
186 * libass uses the best shaper available by default.
189 ASS_FONTPROVIDER_NONE = 0,
190 ASS_FONTPROVIDER_AUTODETECT = 1,
191 ASS_FONTPROVIDER_CORETEXT,
192 ASS_FONTPROVIDER_FONTCONFIG,
193 ASS_FONTPROVIDER_DIRECTWRITE,
194 } ASS_DefaultFontProvider;
197 * \brief Initialize the library.
198 * \return library handle or NULL if failed
200 ASS_Library *ass_library_init(void);
203 * \brief Finalize the library
204 * \param priv library handle
206 void ass_library_done(ASS_Library *priv);
209 * \brief Set additional fonts directory.
210 * Optional directory that will be scanned for fonts recursively. The fonts
211 * found are used for font lookup.
212 * NOTE: A valid font directory is not needed to support embedded fonts.
214 * \param priv library handle
215 * \param fonts_dir directory with additional fonts
217 void ass_set_fonts_dir(ASS_Library *priv, const char *fonts_dir);
220 * \brief Whether fonts should be extracted from track data.
221 * \param priv library handle
222 * \param extract whether to extract fonts
224 void ass_set_extract_fonts(ASS_Library *priv, int extract);
227 * \brief Register style overrides with a library instance.
228 * The overrides should have the form [Style.]Param=Value, e.g.
229 * SomeStyle.Font=Arial
230 * ScaledBorderAndShadow=yes
232 * \param priv library handle
233 * \param list NULL-terminated list of strings
235 void ass_set_style_overrides(ASS_Library *priv, char **list);
238 * \brief Explicitly process style overrides for a track.
239 * \param track track handle
241 void ass_process_force_style(ASS_Track *track);
244 * \brief Register a callback for debug/info messages.
245 * If a callback is registered, it is called for every message emitted by
246 * libass. The callback receives a format string and a list of arguments,
247 * to be used for the printf family of functions. Additionally, a log level
248 * from 0 (FATAL errors) to 7 (verbose DEBUG) is passed. Usually, level 5
249 * should be used by applications.
250 * If no callback is set, all messages level < 5 are printed to stderr,
251 * prefixed with [ass].
253 * \param priv library handle
254 * \param msg_cb pointer to callback function
255 * \param data additional data, will be passed to callback
257 void ass_set_message_cb(ASS_Library *priv, void (*msg_cb)
258 (int level, const char *fmt, va_list args, void *data),
262 * \brief Initialize the renderer.
263 * \param priv library handle
264 * \return renderer handle or NULL if failed
266 ASS_Renderer *ass_renderer_init(ASS_Library *);
269 * \brief Finalize the renderer.
270 * \param priv renderer handle
272 void ass_renderer_done(ASS_Renderer *priv);
275 * \brief Set the frame size in pixels, including margins.
276 * The renderer will never return images that are outside of the frame area.
277 * The value set with this function can influence the pixel aspect ratio used
278 * for rendering. If the frame size doesn't equal to the video size, you may
279 * have to use ass_set_pixel_aspect().
280 * @see ass_set_pixel_aspect()
281 * @see ass_set_margins()
282 * \param priv renderer handle
286 void ass_set_frame_size(ASS_Renderer *priv, int w, int h);
289 * \brief Set the source image size in pixels.
290 * This is used to calculate the source aspect ratio and the blur scale.
291 * The source image size can be reset to default by setting w and h to 0.
292 * The value set with this function can influence the pixel aspect ratio used
294 * @see ass_set_pixel_aspect()
295 * \param priv renderer handle
299 void ass_set_storage_size(ASS_Renderer *priv, int w, int h);
302 * \brief Set shaping level. This is merely a hint, the renderer will use
303 * whatever is available if the request cannot be fulfilled.
304 * \param level shaping level
306 void ass_set_shaper(ASS_Renderer *priv, ASS_ShapingLevel level);
309 * \brief Set frame margins. These values may be negative if pan-and-scan
310 * is used. The margins are in pixels. Each value specifies the distance from
311 * the video rectangle to the renderer frame. If a given margin value is
312 * positive, there will be free space between renderer frame and video area.
313 * If a given margin value is negative, the frame is inside the video, i.e.
314 * the video has been cropped.
316 * The renderer will try to keep subtitles inside the frame area. If possible,
317 * text is layout so that it is inside the cropped area. Subtitle events
318 * that can't be moved are cropped against the frame area.
320 * ass_set_use_margins() can be used to allow libass to render subtitles into
321 * the empty areas if margins are positive, i.e. the video area is smaller than
322 * the frame. (Traditionally, this has been used to show subtitles in
323 * the bottom "black bar" between video bottom screen border when playing 16:9
324 * video on a 4:3 screen.)
326 * When using this function, it is recommended to calculate and set your own
327 * aspect ratio with ass_set_pixel_aspect(), as the defaults won't make any
329 * @see ass_set_pixel_aspect()
330 * \param priv renderer handle
331 * \param t top margin
332 * \param b bottom margin
333 * \param l left margin
334 * \param r right margin
336 void ass_set_margins(ASS_Renderer *priv, int t, int b, int l, int r);
339 * \brief Whether margins should be used for placing regular events.
340 * \param priv renderer handle
341 * \param use whether to use the margins
343 void ass_set_use_margins(ASS_Renderer *priv, int use);
346 * \brief Set pixel aspect ratio correction.
347 * This is the ratio of pixel width to pixel height.
349 * Generally, this is (s_w / s_h) / (d_w / d_h), where s_w and s_h is the
350 * video storage size, and d_w and d_h is the video display size. (Display
351 * and storage size can be different for anamorphic video, such as DVDs.)
353 * If the pixel aspect ratio is 0, or if the aspect ratio has never been set
354 * by calling this function, libass will calculate a default pixel aspect ratio
355 * out of values set with ass_set_frame_size() and ass_set_storage_size(). Note
356 * that this is useful only if the frame size corresponds to the video display
357 * size. Keep in mind that the margins set with ass_set_margins() are ignored
358 * for aspect ratio calculations as well.
359 * If the storage size has not been set, a pixel aspect ratio of 1 is assumed.
360 * \param priv renderer handle
361 * \param par pixel aspect ratio (1.0 means square pixels, 0 means default)
363 void ass_set_pixel_aspect(ASS_Renderer *priv, double par);
366 * \brief Set aspect ratio parameters.
367 * This calls ass_set_pixel_aspect(priv, dar / sar).
368 * @deprecated New code should use ass_set_pixel_aspect().
369 * \param priv renderer handle
370 * \param dar display aspect ratio (DAR), prescaled for output PAR
371 * \param sar storage aspect ratio (SAR)
373 void ass_set_aspect_ratio(ASS_Renderer *priv, double dar, double sar);
376 * \brief Set a fixed font scaling factor.
377 * \param priv renderer handle
378 * \param font_scale scaling factor, default is 1.0
380 void ass_set_font_scale(ASS_Renderer *priv, double font_scale);
383 * \brief Set font hinting method.
384 * \param priv renderer handle
385 * \param ht hinting method
387 void ass_set_hinting(ASS_Renderer *priv, ASS_Hinting ht);
390 * \brief Set line spacing. Will not be scaled with frame size.
391 * \param priv renderer handle
392 * \param line_spacing line spacing in pixels
394 void ass_set_line_spacing(ASS_Renderer *priv, double line_spacing);
397 * \brief Set vertical line position.
398 * \param priv renderer handle
399 * \param line_position vertical line position of subtitles in percent
400 * (0-100: 0 = on the bottom (default), 100 = on top)
402 void ass_set_line_position(ASS_Renderer *priv, double line_position);
405 * \brief Get the list of available font providers. The output array
406 * is allocated with malloc and can be released with free(). If an
407 * allocation error occurs, size is set to (size_t)-1.
408 * \param priv library handle
409 * \param providers output, list of default providers (malloc'ed array)
410 * \param size output, number of providers
411 * \return list of available font providers (user owns the returned array)
413 void ass_get_available_font_providers(ASS_Library *priv,
414 ASS_DefaultFontProvider **providers,
418 * \brief Set font lookup defaults.
419 * \param default_font path to default font to use. Must be supplied if
420 * fontconfig is disabled or unavailable.
421 * \param default_family fallback font family for fontconfig, or NULL
422 * \param dfp which font provider to use (one of ASS_DefaultFontProvider). In
423 * older libass version, this could be 0 or 1, where 1 enabled fontconfig.
424 * Newer relases also accept 0 (ASS_FONTPROVIDER_NONE) and 1
425 * (ASS_FONTPROVIDER_AUTODETECT), which is almost backward-compatible.
426 * If the requested fontprovider does not exist or fails to initialize, the
427 * behavior is the same as when ASS_FONTPROVIDER_NONE was passed.
428 * \param config path to fontconfig configuration file, or NULL. Only relevant
429 * if fontconfig is used.
430 * \param update whether fontconfig cache should be built/updated now. Only
431 * relevant if fontconfig is used.
433 * NOTE: font lookup must be configured before an ASS_Renderer can be used.
435 void ass_set_fonts(ASS_Renderer *priv, const char *default_font,
436 const char *default_family, int dfp,
437 const char *config, int update);
440 * \brief Set selective style override mode.
441 * If enabled, the renderer attempts to override the ASS script's styling of
442 * normal subtitles, without affecting explicitly positioned text. If an event
443 * looks like a normal subtitle, parts of the font style are copied from the
444 * user style set with ass_set_selective_style_override().
445 * Warning: the heuristic used for deciding when to override the style is rather
446 * rough, and enabling this option can lead to incorrectly rendered
447 * subtitles. Since the ASS format doesn't have any support for
448 * allowing end-users to customize subtitle styling, this feature can
449 * only be implemented on "best effort" basis, and has to rely on
450 * heuristics that can easily break.
451 * \param priv renderer handle
452 * \param bits bit mask comprised of ASS_OverrideBits values.
454 void ass_set_selective_style_override_enabled(ASS_Renderer *priv, int bits);
457 * \brief Set style for selective style override.
458 * See ass_set_selective_style_override_enabled().
459 * \param style style settings to use if override is enabled. Applications
460 * should initialize it with {0} before setting fields. Strings will be copied
463 void ass_set_selective_style_override(ASS_Renderer *priv, ASS_Style *style);
466 * \brief This is a stub and does nothing. Old documentation: Update/build font
467 * cache. This needs to be called if it was disabled when ass_set_fonts was set.
469 * \param priv renderer handle
472 int ass_fonts_update(ASS_Renderer *priv);
475 * \brief Set hard cache limits. Do not set, or set to zero, for reasonable
478 * \param priv renderer handle
479 * \param glyph_max maximum number of cached glyphs
480 * \param bitmap_max_size maximum bitmap cache size (in MB)
482 void ass_set_cache_limits(ASS_Renderer *priv, int glyph_max,
483 int bitmap_max_size);
486 * \brief Render a frame, producing a list of ASS_Image.
487 * \param priv renderer handle
488 * \param track subtitle track
489 * \param now video timestamp in milliseconds
490 * \param detect_change compare to the previous call and set to 1
491 * if positions changed, or set to 2 if content changed.
493 ASS_Image *ass_render_frame(ASS_Renderer *priv, ASS_Track *track,
494 long long now, int *detect_change);
498 * The following functions operate on track objects and do not need
503 * \brief Allocate a new empty track object.
504 * \param library handle
505 * \return pointer to empty track
507 ASS_Track *ass_new_track(ASS_Library *);
510 * \brief Deallocate track and all its child objects (styles and events).
511 * \param track track to deallocate
513 void ass_free_track(ASS_Track *track);
516 * \brief Allocate new style.
518 * \return newly allocated style id
520 int ass_alloc_style(ASS_Track *track);
523 * \brief Allocate new event.
525 * \return newly allocated event id
527 int ass_alloc_event(ASS_Track *track);
530 * \brief Delete a style.
532 * \param sid style id
533 * Deallocates style data. Does not modify track->n_styles.
535 void ass_free_style(ASS_Track *track, int sid);
538 * \brief Delete an event.
540 * \param eid event id
541 * Deallocates event data. Does not modify track->n_events.
543 void ass_free_event(ASS_Track *track, int eid);
546 * \brief Parse a chunk of subtitle stream data.
548 * \param data string to parse
549 * \param size length of data
551 void ass_process_data(ASS_Track *track, char *data, int size);
554 * \brief Parse Codec Private section of the subtitle stream, in Matroska
555 * format. See the Matroska specification for details.
556 * \param track target track
557 * \param data string to parse
558 * \param size length of data
560 void ass_process_codec_private(ASS_Track *track, char *data, int size);
563 * \brief Parse a chunk of subtitle stream data. A chunk contains exactly one
564 * event in Matroska format. See the Matroska specification for details.
565 * In later libass versions (since LIBASS_VERSION==0x01300001), using this
566 * function means you agree not to modify events manually, or using other
567 * functions manipulating the event list like ass_process_data(). If you do
568 * anyway, the internal duplicate checking might break. Calling
569 * ass_flush_events() is still allowed.
571 * \param data string to parse
572 * \param size length of data
573 * \param timecode starting time of the event (milliseconds)
574 * \param duration duration of the event (milliseconds)
576 void ass_process_chunk(ASS_Track *track, char *data, int size,
577 long long timecode, long long duration);
580 * \brief Flush buffered events.
583 void ass_flush_events(ASS_Track *track);
586 * \brief Read subtitles from file.
587 * \param library library handle
588 * \param fname file name
589 * \param codepage encoding (iconv format)
590 * \return newly allocated track
592 ASS_Track *ass_read_file(ASS_Library *library, char *fname,
596 * \brief Read subtitles from memory.
597 * \param library library handle
598 * \param buf pointer to subtitles text
599 * \param bufsize size of buffer
600 * \param codepage encoding (iconv format)
601 * \return newly allocated track
603 ASS_Track *ass_read_memory(ASS_Library *library, char *buf,
604 size_t bufsize, char *codepage);
606 * \brief Read styles from file into already initialized track.
607 * \param fname file name
608 * \param codepage encoding (iconv format)
609 * \return 0 on success
611 int ass_read_styles(ASS_Track *track, char *fname, char *codepage);
614 * \brief Add a memory font.
615 * \param library library handle
616 * \param name attachment name
617 * \param data binary font data
618 * \param data_size data size
620 void ass_add_font(ASS_Library *library, char *name, char *data,
624 * \brief Remove all fonts stored in an ass_library object.
625 * \param library library handle
627 void ass_clear_fonts(ASS_Library *library);
630 * \brief Calculates timeshift from now to the start of some other subtitle
631 * event, depending on movement parameter.
632 * \param track subtitle track
633 * \param now current time in milliseconds
634 * \param movement how many events to skip from the one currently displayed
635 * +2 means "the one after the next", -1 means "previous"
636 * \return timeshift in milliseconds
638 long long ass_step_sub(ASS_Track *track, long long now, int movement);
644 #endif /* LIBASS_ASS_H */