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 private font directory.
  79  * It is used for saving embedded fonts and also in font lookup.
  80  *
  81  * \param priv library handle
  82  * \param fonts_dir private directory for font extraction
  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 void ass_set_fonts(ASS_Renderer *priv, const char *default_font,
 208                    const char *default_family, int fc, const char *config,
 209                    int update);
 210
 211 /**
 212  * \brief Update/build font cache.  This needs to be called if it was
 213  * disabled when ass_set_fonts was set.
 214  *
 215  * \param priv renderer handle
 216  * \return success
 217  */
 218 int ass_fonts_update(ASS_Renderer *priv);
 219
 220 /**
 221  * \brief Set hard cache limits.  Do not set, or set to zero, for reasonable
 222  * defaults.
 223  *
 224  * \param priv renderer handle
 225  * \param glyph_max maximum number of cached glyphs
 226  * \param bitmap_max_size maximum bitmap cache size (in MB)
 227  */
 228 void ass_set_cache_limits(ASS_Renderer *priv, int glyph_max,
 229                           int bitmap_max_size);
 230
 231 /**
 232  * \brief Render a frame, producing a list of ASS_Image.
 233  * \param priv renderer handle
 234  * \param track subtitle track
 235  * \param now video timestamp in milliseconds
 236  * \param detect_change will be set to 1 if a change occured compared
 237  * to the last invocation
 238  */
 239 ASS_Image *ass_render_frame(ASS_Renderer *priv, ASS_Track *track,
 240                             long long now, int *detect_change);
 241
 242
 243 /*
 244  * The following functions operate on track objects and do not need
 245  * an ass_renderer
 246  */
 247
 248 /**
 249  * \brief Allocate a new empty track object.
 250  * \param library handle
 251  * \return pointer to empty track
 252  */
 253 ASS_Track *ass_new_track(ASS_Library *);
 254
 255 /**
 256  * \brief Deallocate track and all its child objects (styles and events).
 257  * \param track track to deallocate
 258  */
 259 void ass_free_track(ASS_Track *track);
 260
 261 /**
 262  * \brief Allocate new style.
 263  * \param track track
 264  * \return newly allocated style id
 265  */
 266 int ass_alloc_style(ASS_Track *track);
 267
 268 /**
 269  * \brief Allocate new event.
 270  * \param track track
 271  * \return newly allocated event id
 272  */
 273 int ass_alloc_event(ASS_Track *track);
 274
 275 /**
 276  * \brief Delete a style.
 277  * \param track track
 278  * \param sid style id
 279  * Deallocates style data. Does not modify track->n_styles.
 280  */
 281 void ass_free_style(ASS_Track *track, int sid);
 282
 283 /**
 284  * \brief Delete an event.
 285  * \param track track
 286  * \param eid event id
 287  * Deallocates event data. Does not modify track->n_events.
 288  */
 289 void ass_free_event(ASS_Track *track, int eid);
 290
 291 /**
 292  * \brief Parse a chunk of subtitle stream data.
 293  * \param track track
 294  * \param data string to parse
 295  * \param size length of data
 296  */
 297 void ass_process_data(ASS_Track *track, char *data, int size);
 298
 299 /**
 300  * \brief Parse Codec Private section of subtitle stream.
 301  * \param track target track
 302  * \param data string to parse
 303  * \param size length of data
 304  */
 305 void ass_process_codec_private(ASS_Track *track, char *data, int size);
 306
 307 /**
 308  * \brief Parse a chunk of subtitle stream data. In Matroska,
 309  * this contains exactly 1 event (or a commentary).
 310  * \param track track
 311  * \param data string to parse
 312  * \param size length of data
 313  * \param timecode starting time of the event (milliseconds)
 314  * \param duration duration of the event (milliseconds)
 315  */
 316 void ass_process_chunk(ASS_Track *track, char *data, int size,
 317                        long long timecode, long long duration);
 318
 319 /**
 320  * \brief Flush buffered events.
 321  * \param track track
 322 */
 323 void ass_flush_events(ASS_Track *track);
 324
 325 /**
 326  * \brief Read subtitles from file.
 327  * \param library library handle
 328  * \param fname file name
 329  * \param codepage encoding (iconv format)
 330  * \return newly allocated track
 331 */
 332 ASS_Track *ass_read_file(ASS_Library *library, char *fname,
 333                          char *codepage);
 334
 335 /**
 336  * \brief Read subtitles from memory.
 337  * \param library library handle
 338  * \param buf pointer to subtitles text
 339  * \param bufsize size of buffer
 340  * \param codepage encoding (iconv format)
 341  * \return newly allocated track
 342 */
 343 ASS_Track *ass_read_memory(ASS_Library *library, char *buf,
 344                            size_t bufsize, char *codepage);
 345 /**
 346  * \brief Read styles from file into already initialized track.
 347  * \param fname file name
 348  * \param codepage encoding (iconv format)
 349  * \return 0 on success
 350  */
 351 int ass_read_styles(ASS_Track *track, char *fname, char *codepage);
 352
 353 /**
 354  * \brief Add a memory font.
 355  * \param library library handle
 356  * \param name attachment name
 357  * \param data binary font data
 358  * \param data_size data size
 359 */
 360 void ass_add_font(ASS_Library *library, char *name, char *data,
 361                   int data_size);
 362
 363 /**
 364  * \brief Remove all fonts stored in an ass_library object.
 365  * \param library library handle
 366  */
 367 void ass_clear_fonts(ASS_Library *library);
 368
 369 /**
 370  * \brief Calculates timeshift from now to the start of some other subtitle
 371  * event, depending on movement parameter.
 372  * \param track subtitle track
 373  * \param now current time in milliseconds
 374  * \param movement how many events to skip from the one currently displayed
 375  * +2 means "the one after the next", -1 means "previous"
 376  * \return timeshift in milliseconds
 377  */
 378 long long ass_step_sub(ASS_Track *track, long long now, int movement);
 379
 380 #endif /* LIBASS_ASS_H */