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 0x01010000
  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 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)
 221  */
 222 void ass_set_line_position(ASS_Renderer *priv, double line_position);
 223
 224 /**
 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.
 234  *
 235  * NOTE: font lookup must be configured before an ASS_Renderer can be used.
 236  */
 237 void ass_set_fonts(ASS_Renderer *priv, const char *default_font,
 238                    const char *default_family, int fc, const char *config,
 239                    int update);
 240
 241 /**
 242  * \brief Update/build font cache.  This needs to be called if it was
 243  * disabled when ass_set_fonts was set.
 244  *
 245  * \param priv renderer handle
 246  * \return success
 247  */
 248 int ass_fonts_update(ASS_Renderer *priv);
 249
 250 /**
 251  * \brief Set hard cache limits.  Do not set, or set to zero, for reasonable
 252  * defaults.
 253  *
 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)
 257  */
 258 void ass_set_cache_limits(ASS_Renderer *priv, int glyph_max,
 259                           int bitmap_max_size);
 260
 261 /**
 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
 268  */
 269 ASS_Image *ass_render_frame(ASS_Renderer *priv, ASS_Track *track,
 270                             long long now, int *detect_change);
 271
 272
 273 /*
 274  * The following functions operate on track objects and do not need
 275  * an ass_renderer
 276  */
 277
 278 /**
 279  * \brief Allocate a new empty track object.
 280  * \param library handle
 281  * \return pointer to empty track
 282  */
 283 ASS_Track *ass_new_track(ASS_Library *);
 284
 285 /**
 286  * \brief Deallocate track and all its child objects (styles and events).
 287  * \param track track to deallocate
 288  */
 289 void ass_free_track(ASS_Track *track);
 290
 291 /**
 292  * \brief Allocate new style.
 293  * \param track track
 294  * \return newly allocated style id
 295  */
 296 int ass_alloc_style(ASS_Track *track);
 297
 298 /**
 299  * \brief Allocate new event.
 300  * \param track track
 301  * \return newly allocated event id
 302  */
 303 int ass_alloc_event(ASS_Track *track);
 304
 305 /**
 306  * \brief Delete a style.
 307  * \param track track
 308  * \param sid style id
 309  * Deallocates style data. Does not modify track->n_styles.
 310  */
 311 void ass_free_style(ASS_Track *track, int sid);
 312
 313 /**
 314  * \brief Delete an event.
 315  * \param track track
 316  * \param eid event id
 317  * Deallocates event data. Does not modify track->n_events.
 318  */
 319 void ass_free_event(ASS_Track *track, int eid);
 320
 321 /**
 322  * \brief Parse a chunk of subtitle stream data.
 323  * \param track track
 324  * \param data string to parse
 325  * \param size length of data
 326  */
 327 void ass_process_data(ASS_Track *track, char *data, int size);
 328
 329 /**
 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
 335  */
 336 void ass_process_codec_private(ASS_Track *track, char *data, int size);
 337
 338 /**
 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.
 341  * \param track track
 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)
 346  */
 347 void ass_process_chunk(ASS_Track *track, char *data, int size,
 348                        long long timecode, long long duration);
 349
 350 /**
 351  * \brief Flush buffered events.
 352  * \param track track
 353 */
 354 void ass_flush_events(ASS_Track *track);
 355
 356 /**
 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
 362 */
 363 ASS_Track *ass_read_file(ASS_Library *library, char *fname,
 364                          char *codepage);
 365
 366 /**
 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
 373 */
 374 ASS_Track *ass_read_memory(ASS_Library *library, char *buf,
 375                            size_t bufsize, char *codepage);
 376 /**
 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
 381  */
 382 int ass_read_styles(ASS_Track *track, char *fname, char *codepage);
 383
 384 /**
 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
 390 */
 391 void ass_add_font(ASS_Library *library, char *name, char *data,
 392                   int data_size);
 393
 394 /**
 395  * \brief Remove all fonts stored in an ass_library object.
 396  * \param library library handle
 397  */
 398 void ass_clear_fonts(ASS_Library *library);
 399
 400 /**
 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
 408  */
 409 long long ass_step_sub(ASS_Track *track, long long now, int movement);
 410
 411 #endif /* LIBASS_ASS_H */