libass/ass.h

   1 /*
   2  * Copyright (C) 2006 Evgeniy Stepanov <eugeni.stepanov@gmail.com>
   3  *
   4  * This file is part of libass.
   5  *
   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.
   9  *
  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.
  17  */
  18
  19 #ifndef LIBASS_ASS_H
  20 #define LIBASS_ASS_H
  21
  22 #include <stdio.h>
  23 #include <stdarg.h>
  24 #include "ass_types.h"
  25
  26 #define LIBASS_VERSION 0x01000000
  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;
  48
  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;
  62
  63 /**
  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 /**
  77  * \brief Initialize the library.
  78  * \return library handle or NULL if failed
  79  */
  80 ASS_Library *ass_library_init(void);
  81
  82 /**
  83  * \brief Finalize the library
  84  * \param priv library handle
  85  */
  86 void ass_library_done(ASS_Library *priv);
  87
  88 /**
  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.
  93  *
  94  * \param priv library handle
  95  * \param fonts_dir directory with additional fonts
  96  */
  97 void ass_set_fonts_dir(ASS_Library *priv, const char *fonts_dir);
  98
  99 /**
 100  * \brief Whether fonts should be extracted from track data.
 101  * \param priv library handle
 102  * \param extract whether to extract fonts
 103  */
 104 void ass_set_extract_fonts(ASS_Library *priv, int extract);
 105
 106 /**
 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
 114  */
 115 void ass_set_style_overrides(ASS_Library *priv, char **list);
 116
 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);
 122
 123 /**
 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.
 143  * \param priv library handle
 144  * \return renderer handle or NULL if failed
 145  */
 146 ASS_Renderer *ass_renderer_init(ASS_Library *);
 147
 148 /**
 149  * \brief Finalize the renderer.
 150  * \param priv renderer handle
 151  */
 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);
 161
 162 /**
 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 /**
 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);
 179
 180 /**
 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)
 192  */
 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);
 215
 216 /**
 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.
 226  *
 227  * NOTE: font lookup must be configured before an ASS_Renderer can be used.
 228  */
 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);
 232
 233 /**
 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
 256  * \param track subtitle track
 257  * \param now video timestamp in milliseconds
 258  * \param detect_change will be set to 1 if a change occured compared
 259  * to the last invocation
 260  */
 261 ASS_Image *ass_render_frame(ASS_Renderer *priv, ASS_Track *track,
 262                             long long now, int *detect_change);
 263
 264
 265 /*
 266  * The following functions operate on track objects and do not need
 267  * an ass_renderer
 268  */
 269
 270 /**
 271  * \brief Allocate a new empty track object.
 272  * \param library handle
 273  * \return pointer to empty track
 274  */
 275 ASS_Track *ass_new_track(ASS_Library *);
 276
 277 /**
 278  * \brief Deallocate track and all its child objects (styles and events).
 279  * \param track track to deallocate
 280  */
 281 void ass_free_track(ASS_Track *track);
 282
 283 /**
 284  * \brief Allocate new style.
 285  * \param track track
 286  * \return newly allocated style id
 287  */
 288 int ass_alloc_style(ASS_Track *track);
 289
 290 /**
 291  * \brief Allocate new event.
 292  * \param track track
 293  * \return newly allocated event id
 294  */
 295 int ass_alloc_event(ASS_Track *track);
 296
 297 /**
 298  * \brief Delete a style.
 299  * \param track track
 300  * \param sid style id
 301  * Deallocates style data. Does not modify track->n_styles.
 302  */
 303 void ass_free_style(ASS_Track *track, int sid);
 304
 305 /**
 306  * \brief Delete an event.
 307  * \param track track
 308  * \param eid event id
 309  * Deallocates event data. Does not modify track->n_events.
 310  */
 311 void ass_free_event(ASS_Track *track, int eid);
 312
 313 /**
 314  * \brief Parse a chunk of subtitle stream data.
 315  * \param track track
 316  * \param data string to parse
 317  * \param size length of data
 318  */
 319 void ass_process_data(ASS_Track *track, char *data, int size);
 320
 321 /**
 322  * \brief Parse Codec Private section of the subtitle stream, in Matroska
 323  * format.  See the Matroska specification for details.
 324  * \param track target track
 325  * \param data string to parse
 326  * \param size length of data
 327  */
 328 void ass_process_codec_private(ASS_Track *track, char *data, int size);
 329
 330 /**
 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.
 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)
 338  */
 339 void ass_process_chunk(ASS_Track *track, char *data, int size,
 340                        long long timecode, long long duration);
 341
 342 /**
 343  * \brief Flush buffered events.
 344  * \param track track
 345 */
 346 void ass_flush_events(ASS_Track *track);
 347
 348 /**
 349  * \brief Read subtitles from file.
 350  * \param library library handle
 351  * \param fname file name
 352  * \param codepage encoding (iconv format)
 353  * \return newly allocated track
 354 */
 355 ASS_Track *ass_read_file(ASS_Library *library, char *fname,
 356                          char *codepage);
 357
 358 /**
 359  * \brief Read subtitles from memory.
 360  * \param library library handle
 361  * \param buf pointer to subtitles text
 362  * \param bufsize size of buffer
 363  * \param codepage encoding (iconv format)
 364  * \return newly allocated track
 365 */
 366 ASS_Track *ass_read_memory(ASS_Library *library, char *buf,
 367                            size_t bufsize, char *codepage);
 368 /**
 369  * \brief Read styles from file into already initialized track.
 370  * \param fname file name
 371  * \param codepage encoding (iconv format)
 372  * \return 0 on success
 373  */
 374 int ass_read_styles(ASS_Track *track, char *fname, char *codepage);
 375
 376 /**
 377  * \brief Add a memory font.
 378  * \param library library handle
 379  * \param name attachment name
 380  * \param data binary font data
 381  * \param data_size data size
 382 */
 383 void ass_add_font(ASS_Library *library, char *name, char *data,
 384                   int data_size);
 385
 386 /**
 387  * \brief Remove all fonts stored in an ass_library object.
 388  * \param library library handle
 389  */
 390 void ass_clear_fonts(ASS_Library *library);
 391
 392 /**
 393  * \brief Calculates timeshift from now to the start of some other subtitle
 394  * event, depending on movement parameter.
 395  * \param track subtitle track
 396  * \param now current time in milliseconds
 397  * \param movement how many events to skip from the one currently displayed
 398  * +2 means "the one after the next", -1 means "previous"
 399  * \return timeshift in milliseconds
 400  */
 401 long long ass_step_sub(ASS_Track *track, long long now, int movement);
 402
 403 #endif /* LIBASS_ASS_H */