libass/ass.h

   1 /*
   2  * Copyright (C) 2006 Evgeniy Stepanov <eugeni.stepanov@gmail.com>
   3  *
   4  * This file is part of libass.
   5  *
   6  * libass is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * libass is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License along
  17  * with libass; if not, write to the Free Software Foundation, Inc.,
  18  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  19  */
  20
  21 #ifndef LIBASS_ASS_H
  22 #define LIBASS_ASS_H
  23
  24 #include <stdio.h>
  25 #include <stdarg.h>
  26 #include "ass_types.h"
  27
  28 #define LIBASS_VERSION 0x00910000
  29
  30 /*
  31  * A linked list of images produced by an ass renderer.
  32  *
  33  * These images have to be rendered in-order for the correct screen
  34  * composition.  The libass renderer clips these bitmaps to the frame size.
  35  * w/h can be zero, in this case the bitmap should not be rendered at all.
  36  * The last bitmap row is not guaranteed to be padded up to stride size,
  37  * e.g. in the worst case a bitmap has the size stride * (h - 1) + w.
  38  */
  39 typedef struct ass_image {
  40     int w, h;                   // Bitmap width/height
  41     int stride;                 // Bitmap stride
  42     unsigned char *bitmap;      // 1bpp stride*h alpha buffer
  43                                 // Note: the last row may not be padded to
  44                                 // bitmap stride!
  45     uint32_t color;             // Bitmap color and alpha, RGBA
  46     int dst_x, dst_y;           // Bitmap placement inside the video frame
  47
  48     struct ass_image *next;   // Next image, or NULL
  49 } ASS_Image;
  50
  51 /*
  52  * Hinting type. (see ass_set_hinting below)
  53  *
  54  * FreeType's native hinter is still buggy sometimes and it is recommended
  55  * to use the light autohinter, ASS_HINTING_LIGHT, instead.  For best
  56  * compatibility with problematic fonts, disable hinting.
  57  */
  58 typedef enum {
  59     ASS_HINTING_NONE = 0,
  60     ASS_HINTING_LIGHT,
  61     ASS_HINTING_NORMAL,
  62     ASS_HINTING_NATIVE
  63 } ASS_Hinting;
  64
  65 /**
  66  * \brief Initialize the library.
  67  * \return library handle or NULL if failed
  68  */
  69 ASS_Library *ass_library_init(void);
  70
  71 /**
  72  * \brief Finalize the library
  73  * \param priv library handle
  74  */
  75 void ass_library_done(ASS_Library *priv);
  76
  77 /**
  78  * \brief Set additional fonts directory.
  79  * Optional directory that will be scanned for fonts recursively.  The fonts
  80  * found are used for font lookup.
  81  * NOTE: A valid font directory is not needed to support embedded fonts.
  82  *
  83  * \param priv library handle
  84  * \param fonts_dir directory with additional fonts
  85  */
  86 void ass_set_fonts_dir(ASS_Library *priv, const char *fonts_dir);
  87
  88 /**
  89  * \brief Whether fonts should be extracted from track data.
  90  * \param priv library handle
  91  * \param extract whether to extract fonts
  92  */
  93 void ass_set_extract_fonts(ASS_Library *priv, int extract);
  94
  95 /**
  96  * \brief Register style overrides with a library instance.
  97  * The overrides should have the form [Style.]Param=Value, e.g.
  98  *   SomeStyle.Font=Arial
  99  *   ScaledBorderAndShadow=yes
 100  *
 101  * \param priv library handle
 102  * \param list NULL-terminated list of strings
 103  */
 104 void ass_set_style_overrides(ASS_Library *priv, char **list);
 105
 106 /**
 107  * \brief Explicitly process style overrides for a track.
 108  * \param track track handle
 109  */
 110 void ass_process_force_style(ASS_Track *track);
 111
 112 /**
 113  * \brief Register a callback for debug/info messages.
 114  * If a callback is registered, it is called for every message emitted by
 115  * libass.  The callback receives a format string and a list of arguments,
 116  * to be used for the printf family of functions. Additionally, a log level
 117  * from 0 (FATAL errors) to 7 (verbose DEBUG) is passed.  Usually, level 5
 118  * should be used by applications.
 119  * If no callback is set, all messages level < 5 are printed to stderr,
 120  * prefixed with [ass].
 121  *
 122  * \param priv library handle
 123  * \param msg_cb pointer to callback function
 124  * \param data additional data, will be passed to callback
 125  */
 126 void ass_set_message_cb(ASS_Library *priv, void (*msg_cb)
 127                         (int level, const char *fmt, va_list args, void *data),
 128                         void *data);
 129
 130 /**
 131  * \brief Initialize the renderer.
 132  * \param priv library handle
 133  * \return renderer handle or NULL if failed
 134  */
 135 ASS_Renderer *ass_renderer_init(ASS_Library *);
 136
 137 /**
 138  * \brief Finalize the renderer.
 139  * \param priv renderer handle
 140  */
 141 void ass_renderer_done(ASS_Renderer *priv);
 142
 143 /**
 144  * \brief Set the frame size in pixels, including margins.
 145  * \param priv renderer handle
 146  * \param w width
 147  * \param h height
 148  */
 149 void ass_set_frame_size(ASS_Renderer *priv, int w, int h);
 150
 151 /**
 152  * \brief Set frame margins.  These values may be negative if pan-and-scan
 153  * is used.
 154  * \param priv renderer handle
 155  * \param t top margin
 156  * \param b bottom margin
 157  * \param l left margin
 158  * \param r right margin
 159  */
 160 void ass_set_margins(ASS_Renderer *priv, int t, int b, int l, int r);
 161
 162 /**
 163  * \brief Whether margins should be used for placing regular events.
 164  * \param priv renderer handle
 165  * \param use whether to use the margins
 166  */
 167 void ass_set_use_margins(ASS_Renderer *priv, int use);
 168
 169 /**
 170  * \brief Set aspect ratio parameters.
 171  * \param priv renderer handle
 172  * \param dar display aspect ratio (DAR), prescaled for output PAR
 173  * \param sar storage aspect ratio (SAR)
 174  */
 175 void ass_set_aspect_ratio(ASS_Renderer *priv, double dar, double sar);
 176
 177 /**
 178  * \brief Set a fixed font scaling factor.
 179  * \param priv renderer handle
 180  * \param font_scale scaling factor, default is 1.0
 181  */
 182 void ass_set_font_scale(ASS_Renderer *priv, double font_scale);
 183
 184 /**
 185  * \brief Set font hinting method.
 186  * \param priv renderer handle
 187  * \param ht hinting method
 188  */
 189 void ass_set_hinting(ASS_Renderer *priv, ASS_Hinting ht);
 190
 191 /**
 192  * \brief Set line spacing. Will not be scaled with frame size.
 193  * \param priv renderer handle
 194  * \param line_spacing line spacing in pixels
 195  */
 196 void ass_set_line_spacing(ASS_Renderer *priv, double line_spacing);
 197
 198 /**
 199  * \brief Set font lookup defaults.
 200  * \param default_font path to default font to use. Must be supplied if
 201  * fontconfig is disabled or unavailable.
 202  * \param default_family fallback font family for fontconfig, or NULL
 203  * \param fc whether to use fontconfig
 204  * \param config path to fontconfig configuration file, or NULL.  Only relevant
 205  * if fontconfig is used.
 206  * \param update whether fontconfig cache should be built/updated now.  Only
 207  * relevant if fontconfig is used.
 208  *
 209  * NOTE: font lookup must be configured before an ASS_Renderer can be used.
 210  */
 211 void ass_set_fonts(ASS_Renderer *priv, const char *default_font,
 212                    const char *default_family, int fc, const char *config,
 213                    int update);
 214
 215 /**
 216  * \brief Update/build font cache.  This needs to be called if it was
 217  * disabled when ass_set_fonts was set.
 218  *
 219  * \param priv renderer handle
 220  * \return success
 221  */
 222 int ass_fonts_update(ASS_Renderer *priv);
 223
 224 /**
 225  * \brief Set hard cache limits.  Do not set, or set to zero, for reasonable
 226  * defaults.
 227  *
 228  * \param priv renderer handle
 229  * \param glyph_max maximum number of cached glyphs
 230  * \param bitmap_max_size maximum bitmap cache size (in MB)
 231  */
 232 void ass_set_cache_limits(ASS_Renderer *priv, int glyph_max,
 233                           int bitmap_max_size);
 234
 235 /**
 236  * \brief Render a frame, producing a list of ASS_Image.
 237  * \param priv renderer handle
 238  * \param track subtitle track
 239  * \param now video timestamp in milliseconds
 240  * \param detect_change will be set to 1 if a change occured compared
 241  * to the last invocation
 242  */
 243 ASS_Image *ass_render_frame(ASS_Renderer *priv, ASS_Track *track,
 244                             long long now, int *detect_change);
 245
 246
 247 /*
 248  * The following functions operate on track objects and do not need
 249  * an ass_renderer
 250  */
 251
 252 /**
 253  * \brief Allocate a new empty track object.
 254  * \param library handle
 255  * \return pointer to empty track
 256  */
 257 ASS_Track *ass_new_track(ASS_Library *);
 258
 259 /**
 260  * \brief Deallocate track and all its child objects (styles and events).
 261  * \param track track to deallocate
 262  */
 263 void ass_free_track(ASS_Track *track);
 264
 265 /**
 266  * \brief Allocate new style.
 267  * \param track track
 268  * \return newly allocated style id
 269  */
 270 int ass_alloc_style(ASS_Track *track);
 271
 272 /**
 273  * \brief Allocate new event.
 274  * \param track track
 275  * \return newly allocated event id
 276  */
 277 int ass_alloc_event(ASS_Track *track);
 278
 279 /**
 280  * \brief Delete a style.
 281  * \param track track
 282  * \param sid style id
 283  * Deallocates style data. Does not modify track->n_styles.
 284  */
 285 void ass_free_style(ASS_Track *track, int sid);
 286
 287 /**
 288  * \brief Delete an event.
 289  * \param track track
 290  * \param eid event id
 291  * Deallocates event data. Does not modify track->n_events.
 292  */
 293 void ass_free_event(ASS_Track *track, int eid);
 294
 295 /**
 296  * \brief Parse a chunk of subtitle stream data.
 297  * \param track track
 298  * \param data string to parse
 299  * \param size length of data
 300  */
 301 void ass_process_data(ASS_Track *track, char *data, int size);
 302
 303 /**
 304  * \brief Parse Codec Private section of the subtitle stream, in Matroska
 305  * format.  See the Matroska specification for details.
 306  * \param track target track
 307  * \param data string to parse
 308  * \param size length of data
 309  */
 310 void ass_process_codec_private(ASS_Track *track, char *data, int size);
 311
 312 /**
 313  * \brief Parse a chunk of subtitle stream data. A chunk contains exactly one
 314  * event in Matroska format.  See the Matroska specification for details.
 315  * \param track track
 316  * \param data string to parse
 317  * \param size length of data
 318  * \param timecode starting time of the event (milliseconds)
 319  * \param duration duration of the event (milliseconds)
 320  */
 321 void ass_process_chunk(ASS_Track *track, char *data, int size,
 322                        long long timecode, long long duration);
 323
 324 /**
 325  * \brief Flush buffered events.
 326  * \param track track
 327 */
 328 void ass_flush_events(ASS_Track *track);
 329
 330 /**
 331  * \brief Read subtitles from file.
 332  * \param library library handle
 333  * \param fname file name
 334  * \param codepage encoding (iconv format)
 335  * \return newly allocated track
 336 */
 337 ASS_Track *ass_read_file(ASS_Library *library, char *fname,
 338                          char *codepage);
 339
 340 /**
 341  * \brief Read subtitles from memory.
 342  * \param library library handle
 343  * \param buf pointer to subtitles text
 344  * \param bufsize size of buffer
 345  * \param codepage encoding (iconv format)
 346  * \return newly allocated track
 347 */
 348 ASS_Track *ass_read_memory(ASS_Library *library, char *buf,
 349                            size_t bufsize, char *codepage);
 350 /**
 351  * \brief Read styles from file into already initialized track.
 352  * \param fname file name
 353  * \param codepage encoding (iconv format)
 354  * \return 0 on success
 355  */
 356 int ass_read_styles(ASS_Track *track, char *fname, char *codepage);
 357
 358 /**
 359  * \brief Add a memory font.
 360  * \param library library handle
 361  * \param name attachment name
 362  * \param data binary font data
 363  * \param data_size data size
 364 */
 365 void ass_add_font(ASS_Library *library, char *name, char *data,
 366                   int data_size);
 367
 368 /**
 369  * \brief Remove all fonts stored in an ass_library object.
 370  * \param library library handle
 371  */
 372 void ass_clear_fonts(ASS_Library *library);
 373
 374 /**
 375  * \brief Calculates timeshift from now to the start of some other subtitle
 376  * event, depending on movement parameter.
 377  * \param track subtitle track
 378  * \param now current time in milliseconds
 379  * \param movement how many events to skip from the one currently displayed
 380  * +2 means "the one after the next", -1 means "previous"
 381  * \return timeshift in milliseconds
 382  */
 383 long long ass_step_sub(ASS_Track *track, long long now, int movement);
 384
 385 #endif /* LIBASS_ASS_H */