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 0x00912000
  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 Initialize the library.
  65  * \return library handle or NULL if failed
  66  */
  67 ASS_Library *ass_library_init(void);
  68
  69 /**
  70  * \brief Finalize the library
  71  * \param priv library handle
  72  */
  73 void ass_library_done(ASS_Library *priv);
  74
  75 /**
  76  * \brief Set additional fonts directory.
  77  * Optional directory that will be scanned for fonts recursively.  The fonts
  78  * found are used for font lookup.
  79  * NOTE: A valid font directory is not needed to support embedded fonts.
  80  *
  81  * \param priv library handle
  82  * \param fonts_dir directory with additional fonts
  83  */
  84 void ass_set_fonts_dir(ASS_Library *priv, const char *fonts_dir);
  85
  86 /**
  87  * \brief Whether fonts should be extracted from track data.
  88  * \param priv library handle
  89  * \param extract whether to extract fonts
  90  */
  91 void ass_set_extract_fonts(ASS_Library *priv, int extract);
  92
  93 /**
  94  * \brief Register style overrides with a library instance.
  95  * The overrides should have the form [Style.]Param=Value, e.g.
  96  *   SomeStyle.Font=Arial
  97  *   ScaledBorderAndShadow=yes
  98  *
  99  * \param priv library handle
 100  * \param list NULL-terminated list of strings
 101  */
 102 void ass_set_style_overrides(ASS_Library *priv, char **list);
 103
 104 /**
 105  * \brief Explicitly process style overrides for a track.
 106  * \param track track handle
 107  */
 108 void ass_process_force_style(ASS_Track *track);
 109
 110 /**
 111  * \brief Register a callback for debug/info messages.
 112  * If a callback is registered, it is called for every message emitted by
 113  * libass.  The callback receives a format string and a list of arguments,
 114  * to be used for the printf family of functions. Additionally, a log level
 115  * from 0 (FATAL errors) to 7 (verbose DEBUG) is passed.  Usually, level 5
 116  * should be used by applications.
 117  * If no callback is set, all messages level < 5 are printed to stderr,
 118  * prefixed with [ass].
 119  *
 120  * \param priv library handle
 121  * \param msg_cb pointer to callback function
 122  * \param data additional data, will be passed to callback
 123  */
 124 void ass_set_message_cb(ASS_Library *priv, void (*msg_cb)
 125                         (int level, const char *fmt, va_list args, void *data),
 126                         void *data);
 127
 128 /**
 129  * \brief Initialize the renderer.
 130  * \param priv library handle
 131  * \return renderer handle or NULL if failed
 132  */
 133 ASS_Renderer *ass_renderer_init(ASS_Library *);
 134
 135 /**
 136  * \brief Finalize the renderer.
 137  * \param priv renderer handle
 138  */
 139 void ass_renderer_done(ASS_Renderer *priv);
 140
 141 /**
 142  * \brief Set the frame size in pixels, including margins.
 143  * \param priv renderer handle
 144  * \param w width
 145  * \param h height
 146  */
 147 void ass_set_frame_size(ASS_Renderer *priv, int w, int h);
 148
 149 /**
 150  * \brief Set frame margins.  These values may be negative if pan-and-scan
 151  * is used.
 152  * \param priv renderer handle
 153  * \param t top margin
 154  * \param b bottom margin
 155  * \param l left margin
 156  * \param r right margin
 157  */
 158 void ass_set_margins(ASS_Renderer *priv, int t, int b, int l, int r);
 159
 160 /**
 161  * \brief Whether margins should be used for placing regular events.
 162  * \param priv renderer handle
 163  * \param use whether to use the margins
 164  */
 165 void ass_set_use_margins(ASS_Renderer *priv, int use);
 166
 167 /**
 168  * \brief Set aspect ratio parameters.
 169  * \param priv renderer handle
 170  * \param dar display aspect ratio (DAR), prescaled for output PAR
 171  * \param sar storage aspect ratio (SAR)
 172  */
 173 void ass_set_aspect_ratio(ASS_Renderer *priv, double dar, double sar);
 174
 175 /**
 176  * \brief Set a fixed font scaling factor.
 177  * \param priv renderer handle
 178  * \param font_scale scaling factor, default is 1.0
 179  */
 180 void ass_set_font_scale(ASS_Renderer *priv, double font_scale);
 181
 182 /**
 183  * \brief Set font hinting method.
 184  * \param priv renderer handle
 185  * \param ht hinting method
 186  */
 187 void ass_set_hinting(ASS_Renderer *priv, ASS_Hinting ht);
 188
 189 /**
 190  * \brief Set line spacing. Will not be scaled with frame size.
 191  * \param priv renderer handle
 192  * \param line_spacing line spacing in pixels
 193  */
 194 void ass_set_line_spacing(ASS_Renderer *priv, double line_spacing);
 195
 196 /**
 197  * \brief Set font lookup defaults.
 198  * \param default_font path to default font to use. Must be supplied if
 199  * fontconfig is disabled or unavailable.
 200  * \param default_family fallback font family for fontconfig, or NULL
 201  * \param fc whether to use fontconfig
 202  * \param config path to fontconfig configuration file, or NULL.  Only relevant
 203  * if fontconfig is used.
 204  * \param update whether fontconfig cache should be built/updated now.  Only
 205  * relevant if fontconfig is used.
 206  *
 207  * NOTE: font lookup must be configured before an ASS_Renderer can be used.
 208  */
 209 void ass_set_fonts(ASS_Renderer *priv, const char *default_font,
 210                    const char *default_family, int fc, const char *config,
 211                    int update);
 212
 213 /**
 214  * \brief Update/build font cache.  This needs to be called if it was
 215  * disabled when ass_set_fonts was set.
 216  *
 217  * \param priv renderer handle
 218  * \return success
 219  */
 220 int ass_fonts_update(ASS_Renderer *priv);
 221
 222 /**
 223  * \brief Set hard cache limits.  Do not set, or set to zero, for reasonable
 224  * defaults.
 225  *
 226  * \param priv renderer handle
 227  * \param glyph_max maximum number of cached glyphs
 228  * \param bitmap_max_size maximum bitmap cache size (in MB)
 229  */
 230 void ass_set_cache_limits(ASS_Renderer *priv, int glyph_max,
 231                           int bitmap_max_size);
 232
 233 /**
 234  * \brief Render a frame, producing a list of ASS_Image.
 235  * \param priv renderer handle
 236  * \param track subtitle track
 237  * \param now video timestamp in milliseconds
 238  * \param detect_change will be set to 1 if a change occured compared
 239  * to the last invocation
 240  */
 241 ASS_Image *ass_render_frame(ASS_Renderer *priv, ASS_Track *track,
 242                             long long now, int *detect_change);
 243
 244
 245 /*
 246  * The following functions operate on track objects and do not need
 247  * an ass_renderer
 248  */
 249
 250 /**
 251  * \brief Allocate a new empty track object.
 252  * \param library handle
 253  * \return pointer to empty track
 254  */
 255 ASS_Track *ass_new_track(ASS_Library *);
 256
 257 /**
 258  * \brief Deallocate track and all its child objects (styles and events).
 259  * \param track track to deallocate
 260  */
 261 void ass_free_track(ASS_Track *track);
 262
 263 /**
 264  * \brief Allocate new style.
 265  * \param track track
 266  * \return newly allocated style id
 267  */
 268 int ass_alloc_style(ASS_Track *track);
 269
 270 /**
 271  * \brief Allocate new event.
 272  * \param track track
 273  * \return newly allocated event id
 274  */
 275 int ass_alloc_event(ASS_Track *track);
 276
 277 /**
 278  * \brief Delete a style.
 279  * \param track track
 280  * \param sid style id
 281  * Deallocates style data. Does not modify track->n_styles.
 282  */
 283 void ass_free_style(ASS_Track *track, int sid);
 284
 285 /**
 286  * \brief Delete an event.
 287  * \param track track
 288  * \param eid event id
 289  * Deallocates event data. Does not modify track->n_events.
 290  */
 291 void ass_free_event(ASS_Track *track, int eid);
 292
 293 /**
 294  * \brief Parse a chunk of subtitle stream data.
 295  * \param track track
 296  * \param data string to parse
 297  * \param size length of data
 298  */
 299 void ass_process_data(ASS_Track *track, char *data, int size);
 300
 301 /**
 302  * \brief Parse Codec Private section of the subtitle stream, in Matroska
 303  * format.  See the Matroska specification for details.
 304  * \param track target track
 305  * \param data string to parse
 306  * \param size length of data
 307  */
 308 void ass_process_codec_private(ASS_Track *track, char *data, int size);
 309
 310 /**
 311  * \brief Parse a chunk of subtitle stream data. A chunk contains exactly one
 312  * event in Matroska format.  See the Matroska specification for details.
 313  * \param track track
 314  * \param data string to parse
 315  * \param size length of data
 316  * \param timecode starting time of the event (milliseconds)
 317  * \param duration duration of the event (milliseconds)
 318  */
 319 void ass_process_chunk(ASS_Track *track, char *data, int size,
 320                        long long timecode, long long duration);
 321
 322 /**
 323  * \brief Flush buffered events.
 324  * \param track track
 325 */
 326 void ass_flush_events(ASS_Track *track);
 327
 328 /**
 329  * \brief Read subtitles from file.
 330  * \param library library handle
 331  * \param fname file name
 332  * \param codepage encoding (iconv format)
 333  * \return newly allocated track
 334 */
 335 ASS_Track *ass_read_file(ASS_Library *library, char *fname,
 336                          char *codepage);
 337
 338 /**
 339  * \brief Read subtitles from memory.
 340  * \param library library handle
 341  * \param buf pointer to subtitles text
 342  * \param bufsize size of buffer
 343  * \param codepage encoding (iconv format)
 344  * \return newly allocated track
 345 */
 346 ASS_Track *ass_read_memory(ASS_Library *library, char *buf,
 347                            size_t bufsize, char *codepage);
 348 /**
 349  * \brief Read styles from file into already initialized track.
 350  * \param fname file name
 351  * \param codepage encoding (iconv format)
 352  * \return 0 on success
 353  */
 354 int ass_read_styles(ASS_Track *track, char *fname, char *codepage);
 355
 356 /**
 357  * \brief Add a memory font.
 358  * \param library library handle
 359  * \param name attachment name
 360  * \param data binary font data
 361  * \param data_size data size
 362 */
 363 void ass_add_font(ASS_Library *library, char *name, char *data,
 364                   int data_size);
 365
 366 /**
 367  * \brief Remove all fonts stored in an ass_library object.
 368  * \param library library handle
 369  */
 370 void ass_clear_fonts(ASS_Library *library);
 371
 372 /**
 373  * \brief Calculates timeshift from now to the start of some other subtitle
 374  * event, depending on movement parameter.
 375  * \param track subtitle track
 376  * \param now current time in milliseconds
 377  * \param movement how many events to skip from the one currently displayed
 378  * +2 means "the one after the next", -1 means "previous"
 379  * \return timeshift in milliseconds
 380  */
 381 long long ass_step_sub(ASS_Track *track, long long now, int movement);
 382
 383 #endif /* LIBASS_ASS_H */