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 0x01010000
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
50 * Hinting type. (see ass_set_hinting below)
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.
64 * \brief Text shaping levels.
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.
69 * libass uses the best shaper available by default.
72 ASS_SHAPING_SIMPLE
= 0,
77 * \brief Initialize the library.
78 * \return library handle or NULL if failed
80 ASS_Library
*ass_library_init(void);
83 * \brief Finalize the library
84 * \param priv library handle
86 void ass_library_done(ASS_Library
*priv
);
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.
94 * \param priv library handle
95 * \param fonts_dir directory with additional fonts
97 void ass_set_fonts_dir(ASS_Library
*priv
, const char *fonts_dir
);
100 * \brief Whether fonts should be extracted from track data.
101 * \param priv library handle
102 * \param extract whether to extract fonts
104 void ass_set_extract_fonts(ASS_Library
*priv
, int extract
);
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
112 * \param priv library handle
113 * \param list NULL-terminated list of strings
115 void ass_set_style_overrides(ASS_Library
*priv
, char **list
);
118 * \brief Explicitly process style overrides for a track.
119 * \param track track handle
121 void ass_process_force_style(ASS_Track
*track
);
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].
133 * \param priv library handle
134 * \param msg_cb pointer to callback function
135 * \param data additional data, will be passed to callback
137 void ass_set_message_cb(ASS_Library
*priv
, void (*msg_cb
)
138 (int level
, const char *fmt
, va_list args
, void *data
),
142 * \brief Initialize the renderer.
143 * \param priv library handle
144 * \return renderer handle or NULL if failed
146 ASS_Renderer
*ass_renderer_init(ASS_Library
*);
149 * \brief Finalize the renderer.
150 * \param priv renderer handle
152 void ass_renderer_done(ASS_Renderer
*priv
);
155 * \brief Set the frame size in pixels, including margins.
156 * \param priv renderer handle
160 void ass_set_frame_size(ASS_Renderer
*priv
, int w
, int h
);
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
167 void ass_set_shaper(ASS_Renderer
*priv
, ASS_ShapingLevel level
);
170 * \brief Set frame margins. These values may be negative if pan-and-scan
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
178 void ass_set_margins(ASS_Renderer
*priv
, int t
, int b
, int l
, int r
);
181 * \brief Whether margins should be used for placing regular events.
182 * \param priv renderer handle
183 * \param use whether to use the margins
185 void ass_set_use_margins(ASS_Renderer
*priv
, int use
);
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)
193 void ass_set_aspect_ratio(ASS_Renderer
*priv
, double dar
, double sar
);
196 * \brief Set a fixed font scaling factor.
197 * \param priv renderer handle
198 * \param font_scale scaling factor, default is 1.0
200 void ass_set_font_scale(ASS_Renderer
*priv
, double font_scale
);
203 * \brief Set font hinting method.
204 * \param priv renderer handle
205 * \param ht hinting method
207 void ass_set_hinting(ASS_Renderer
*priv
, ASS_Hinting ht
);
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
214 void ass_set_line_spacing(ASS_Renderer
*priv
, double line_spacing
);
217 * \brief Set vertical line position.
218 * \param priv renderer handle
219 * \param line_position vertical line position of subtitles in percent
220 * (0-100: 0 = on the bottom (default), 100 = on top)
222 void ass_set_line_position(ASS_Renderer
*priv
, double line_position
);
225 * \brief Set font lookup defaults.
226 * \param default_font path to default font to use. Must be supplied if
227 * fontconfig is disabled or unavailable.
228 * \param default_family fallback font family for fontconfig, or NULL
229 * \param fc whether to use fontconfig
230 * \param config path to fontconfig configuration file, or NULL. Only relevant
231 * if fontconfig is used.
232 * \param update whether fontconfig cache should be built/updated now. Only
233 * relevant if fontconfig is used.
235 * NOTE: font lookup must be configured before an ASS_Renderer can be used.
237 void ass_set_fonts(ASS_Renderer
*priv
, const char *default_font
,
238 const char *default_family
, int fc
, const char *config
,
242 * \brief Update/build font cache. This needs to be called if it was
243 * disabled when ass_set_fonts was set.
245 * \param priv renderer handle
248 int ass_fonts_update(ASS_Renderer
*priv
);
251 * \brief Set hard cache limits. Do not set, or set to zero, for reasonable
254 * \param priv renderer handle
255 * \param glyph_max maximum number of cached glyphs
256 * \param bitmap_max_size maximum bitmap cache size (in MB)
258 void ass_set_cache_limits(ASS_Renderer
*priv
, int glyph_max
,
259 int bitmap_max_size
);
262 * \brief Render a frame, producing a list of ASS_Image.
263 * \param priv renderer handle
264 * \param track subtitle track
265 * \param now video timestamp in milliseconds
266 * \param detect_change will be set to 1 if a change occured compared
267 * to the last invocation
269 ASS_Image
*ass_render_frame(ASS_Renderer
*priv
, ASS_Track
*track
,
270 long long now
, int *detect_change
);
274 * The following functions operate on track objects and do not need
279 * \brief Allocate a new empty track object.
280 * \param library handle
281 * \return pointer to empty track
283 ASS_Track
*ass_new_track(ASS_Library
*);
286 * \brief Deallocate track and all its child objects (styles and events).
287 * \param track track to deallocate
289 void ass_free_track(ASS_Track
*track
);
292 * \brief Allocate new style.
294 * \return newly allocated style id
296 int ass_alloc_style(ASS_Track
*track
);
299 * \brief Allocate new event.
301 * \return newly allocated event id
303 int ass_alloc_event(ASS_Track
*track
);
306 * \brief Delete a style.
308 * \param sid style id
309 * Deallocates style data. Does not modify track->n_styles.
311 void ass_free_style(ASS_Track
*track
, int sid
);
314 * \brief Delete an event.
316 * \param eid event id
317 * Deallocates event data. Does not modify track->n_events.
319 void ass_free_event(ASS_Track
*track
, int eid
);
322 * \brief Parse a chunk of subtitle stream data.
324 * \param data string to parse
325 * \param size length of data
327 void ass_process_data(ASS_Track
*track
, char *data
, int size
);
330 * \brief Parse Codec Private section of the subtitle stream, in Matroska
331 * format. See the Matroska specification for details.
332 * \param track target track
333 * \param data string to parse
334 * \param size length of data
336 void ass_process_codec_private(ASS_Track
*track
, char *data
, int size
);
339 * \brief Parse a chunk of subtitle stream data. A chunk contains exactly one
340 * event in Matroska format. See the Matroska specification for details.
342 * \param data string to parse
343 * \param size length of data
344 * \param timecode starting time of the event (milliseconds)
345 * \param duration duration of the event (milliseconds)
347 void ass_process_chunk(ASS_Track
*track
, char *data
, int size
,
348 long long timecode
, long long duration
);
351 * \brief Flush buffered events.
354 void ass_flush_events(ASS_Track
*track
);
357 * \brief Read subtitles from file.
358 * \param library library handle
359 * \param fname file name
360 * \param codepage encoding (iconv format)
361 * \return newly allocated track
363 ASS_Track
*ass_read_file(ASS_Library
*library
, char *fname
,
367 * \brief Read subtitles from memory.
368 * \param library library handle
369 * \param buf pointer to subtitles text
370 * \param bufsize size of buffer
371 * \param codepage encoding (iconv format)
372 * \return newly allocated track
374 ASS_Track
*ass_read_memory(ASS_Library
*library
, char *buf
,
375 size_t bufsize
, char *codepage
);
377 * \brief Read styles from file into already initialized track.
378 * \param fname file name
379 * \param codepage encoding (iconv format)
380 * \return 0 on success
382 int ass_read_styles(ASS_Track
*track
, char *fname
, char *codepage
);
385 * \brief Add a memory font.
386 * \param library library handle
387 * \param name attachment name
388 * \param data binary font data
389 * \param data_size data size
391 void ass_add_font(ASS_Library
*library
, char *name
, char *data
,
395 * \brief Remove all fonts stored in an ass_library object.
396 * \param library library handle
398 void ass_clear_fonts(ASS_Library
*library
);
401 * \brief Calculates timeshift from now to the start of some other subtitle
402 * event, depending on movement parameter.
403 * \param track subtitle track
404 * \param now current time in milliseconds
405 * \param movement how many events to skip from the one currently displayed
406 * +2 means "the one after the next", -1 means "previous"
407 * \return timeshift in milliseconds
409 long long ass_step_sub(ASS_Track
*track
, long long now
, int movement
);
411 #endif /* LIBASS_ASS_H */