1 /* 2 * Copyright (C) 2006 Evgeniy Stepanov <eugeni.stepanov@gmail.com> 3 * Copyright (C) 2011 Grigori Goronzy <greg@chown.ath.cx> 4 * 5 * This file is part of libass. 6 * 7 * Permission to use, copy, modify, and distribute this software for any 8 * purpose with or without fee is hereby granted, provided that the above 9 * copyright notice and this permission notice appear in all copies. 10 * 11 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 12 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 13 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 14 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 15 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 16 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 17 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 18 */ 19 20 #ifndef LIBASS_ASS_H 21 #define LIBASS_ASS_H 22 23 #include <stdio.h> 24 #include <stdarg.h> 25 #include "ass_types.h" 26 27 #define LIBASS_VERSION 0x01502000 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 #if (defined(__GNUC__) && ((__GNUC__ > 3) || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1))) || defined(__clang__) 34 #define ASS_DEPRECATED(msg) __attribute__((deprecated(msg))) 35 #if __GNUC__ > 5 || defined(__clang__) 36 #define ASS_DEPRECATED_ENUM(msg) __attribute__((deprecated(msg))) 37 #else 38 #define ASS_DEPRECATED_ENUM(msg) 39 #endif 40 #elif defined(_MSC_VER) 41 #define ASS_DEPRECATED(msg) __declspec(deprecated(msg)) 42 #define ASS_DEPRECATED_ENUM(msg) 43 #else 44 #define ASS_DEPRECATED(msg) 45 #define ASS_DEPRECATED_ENUM(msg) 46 #endif 47 48 49 /* 50 * A linked list of images produced by an ass renderer. 51 * 52 * These images have to be rendered in-order for the correct screen 53 * composition. The libass renderer clips these bitmaps to the frame size. 54 * w/h can be zero, in this case the bitmap should not be rendered at all. 55 * The last bitmap row is not guaranteed to be padded up to stride size, 56 * e.g. in the worst case a bitmap has the size stride * (h - 1) + w. 57 */ 58 typedef struct ass_image { 59 int w, h; // Bitmap width/height 60 int stride; // Bitmap stride 61 unsigned char *bitmap; // 1bpp stride*h alpha buffer 62 // Note: the last row may not be padded to 63 // bitmap stride! 64 uint32_t color; // Bitmap color and alpha, RGBA 65 int dst_x, dst_y; // Bitmap placement inside the video frame 66 67 struct ass_image *next; // Next image, or NULL 68 69 enum { 70 IMAGE_TYPE_CHARACTER, 71 IMAGE_TYPE_OUTLINE, 72 IMAGE_TYPE_SHADOW 73 } type; 74 75 // New fields can be added here in new ABI-compatible library releases. 76 } ASS_Image; 77 78 /* 79 * Hinting type. (see ass_set_hinting below) 80 * 81 * Setting hinting to anything but ASS_HINTING_NONE will put libass in a mode 82 * that reduces compatibility with vsfilter and many ASS scripts. The main 83 * problem is that hinting conflicts with smooth scaling, which precludes 84 * animations and precise positioning. 85 * 86 * In other words, enabling hinting might break some scripts severely. 87 * 88 * FreeType's native hinter is still buggy sometimes and it is recommended 89 * to use the light autohinter, ASS_HINTING_LIGHT, instead. For best 90 * compatibility with problematic fonts, disable hinting. 91 */ 92 typedef enum { 93 ASS_HINTING_NONE = 0, 94 ASS_HINTING_LIGHT, 95 ASS_HINTING_NORMAL, 96 ASS_HINTING_NATIVE 97 } ASS_Hinting; 98 99 /** 100 * \brief Text shaping levels. 101 * 102 * SIMPLE is a fast, font-agnostic shaper that can do only substitutions. 103 * COMPLEX is a slower shaper using OpenType for substitutions and positioning. 104 * 105 * libass uses the best shaper available by default. 106 */ 107 typedef enum { 108 ASS_SHAPING_SIMPLE = 0, 109 ASS_SHAPING_COMPLEX 110 } ASS_ShapingLevel; 111 112 /** 113 * \brief Style override options. See 114 * ass_set_selective_style_override_enabled() for details. 115 */ 116 typedef enum { 117 /** 118 * Default mode (with no other bits set). All selective override features 119 * as well as the style set with ass_set_selective_style_override() are 120 * disabled, but traditional overrides like ass_set_font_scale() are 121 * applied unconditionally. 122 */ 123 ASS_OVERRIDE_DEFAULT = 0, 124 /** 125 * Apply the style as set with ass_set_selective_style_override() on events 126 * which look like dialogue. Other style overrides are also applied this 127 * way, except ass_set_font_scale(). How ass_set_font_scale() is applied 128 * depends on the ASS_OVERRIDE_BIT_SELECTIVE_FONT_SCALE flag. 129 * 130 * This is equivalent to setting all of the following bits: 131 * 132 * ASS_OVERRIDE_BIT_FONT_NAME 133 * ASS_OVERRIDE_BIT_FONT_SIZE_FIELDS 134 * ASS_OVERRIDE_BIT_COLORS 135 * ASS_OVERRIDE_BIT_BORDER 136 * ASS_OVERRIDE_BIT_ATTRIBUTES 137 */ 138 ASS_OVERRIDE_BIT_STYLE = 1 << 0, 139 /** 140 * Apply ass_set_font_scale() only on events which look like dialogue. 141 * If not set, the font scale is applied to all events. (The behavior and 142 * name of this flag are unintuitive, but exist for compatibility) 143 */ 144 ASS_OVERRIDE_BIT_SELECTIVE_FONT_SCALE = 1 << 1, 145 /** 146 * Old alias for ASS_OVERRIDE_BIT_SELECTIVE_FONT_SCALE. Deprecated. Do not use. 147 */ 148 ASS_OVERRIDE_BIT_FONT_SIZE ASS_DEPRECATED_ENUM("replaced by ASS_OVERRIDE_BIT_SELECTIVE_FONT_SCALE") = 1 << 1, 149 /** 150 * On dialogue events override: FontSize, Spacing, Blur, ScaleX, ScaleY 151 */ 152 ASS_OVERRIDE_BIT_FONT_SIZE_FIELDS = 1 << 2, 153 /** 154 * On dialogue events override: FontName, treat_fontname_as_pattern 155 */ 156 ASS_OVERRIDE_BIT_FONT_NAME = 1 << 3, 157 /** 158 * On dialogue events override: PrimaryColour, SecondaryColour, OutlineColour, BackColour 159 */ 160 ASS_OVERRIDE_BIT_COLORS = 1 << 4, 161 /** 162 * On dialogue events override: Bold, Italic, Underline, StrikeOut 163 */ 164 ASS_OVERRIDE_BIT_ATTRIBUTES = 1 << 5, 165 /** 166 * On dialogue events override: BorderStyle, Outline, Shadow 167 */ 168 ASS_OVERRIDE_BIT_BORDER = 1 << 6, 169 /** 170 * On dialogue events override: Alignment 171 */ 172 ASS_OVERRIDE_BIT_ALIGNMENT = 1 << 7, 173 /** 174 * On dialogue events override: MarginL, MarginR, MarginV 175 */ 176 ASS_OVERRIDE_BIT_MARGINS = 1 << 8, 177 /** 178 * Unconditionally replace all fields of all styles with the one provided 179 * with ass_set_selective_style_override(). 180 * Does not apply ASS_OVERRIDE_BIT_SELECTIVE_FONT_SCALE. 181 * Add ASS_OVERRIDE_BIT_FONT_SIZE_FIELDS and ASS_OVERRIDE_BIT_BORDER if 182 * you want FontSize, Spacing, Outline, Shadow to be scaled to the script 183 * resolution given by the ASS_Track. 184 */ 185 ASS_OVERRIDE_FULL_STYLE = 1 << 9, 186 /** 187 * On dialogue events override: Justify 188 */ 189 ASS_OVERRIDE_BIT_JUSTIFY = 1 << 10, 190 // New enum values can be added here in new ABI-compatible library releases. 191 } ASS_OverrideBits; 192 193 /** 194 * \brief Return the version of library. This returns the value LIBASS_VERSION 195 * was set to when the library was compiled. 196 * \return library version 197 */ 198 int ass_library_version(void); 199 200 /** 201 * \brief Default Font provider to load fonts in libass' database 202 * 203 * NONE don't use any default font provider for font lookup 204 * AUTODETECT use the first available font provider 205 * CORETEXT force a CoreText based font provider (OS X only) 206 * FONTCONFIG force a Fontconfig based font provider 207 * 208 * libass uses the best shaper available by default. 209 */ 210 typedef enum { 211 ASS_FONTPROVIDER_NONE = 0, 212 ASS_FONTPROVIDER_AUTODETECT = 1, 213 ASS_FONTPROVIDER_CORETEXT, 214 ASS_FONTPROVIDER_FONTCONFIG, 215 ASS_FONTPROVIDER_DIRECTWRITE, 216 } ASS_DefaultFontProvider; 217 218 typedef enum { 219 /** 220 * Enable libass extensions that would display ASS subtitles incorrectly. 221 * These may be useful for applications, which use libass as renderer for 222 * subtitles converted from another format, or which use libass for other 223 * purposes that do not involve actual ASS subtitles authored for 224 * distribution. 225 */ 226 ASS_FEATURE_INCOMPATIBLE_EXTENSIONS, 227 228 /** 229 * Match bracket pairs in bidirectional text according to the revised 230 * Unicode Bidirectional Algorithm introduced in Unicode 6.3. 231 * This is incompatible with VSFilter and disabled by default. 232 * 233 * (Directional isolates, also introduced in Unicode 6.3, 234 * are unconditionally processed when FriBidi is new enough.) 235 * 236 * This feature may be unavailable at runtime (ass_track_set_feature 237 * may return -1) if libass was compiled against old FriBidi. 238 */ 239 ASS_FEATURE_BIDI_BRACKETS, 240 241 // New enum values can be added here in new ABI-compatible library releases. 242 } ASS_Feature; 243 244 /** 245 * \brief Initialize the library. 246 * \return library handle or NULL if failed 247 */ 248 ASS_Library *ass_library_init(void); 249 250 /** 251 * \brief Finalize the library 252 * \param priv library handle 253 */ 254 void ass_library_done(ASS_Library *priv); 255 256 /** 257 * \brief Set additional fonts directory. 258 * Optional directory that will be scanned for fonts recursively. The fonts 259 * found are used for font lookup. 260 * NOTE: A valid font directory is not needed to support embedded fonts. 261 * 262 * \param priv library handle 263 * \param fonts_dir directory with additional fonts 264 */ 265 void ass_set_fonts_dir(ASS_Library *priv, const char *fonts_dir); 266 267 /** 268 * \brief Whether fonts should be extracted from track data. 269 * \param priv library handle 270 * \param extract whether to extract fonts 271 */ 272 void ass_set_extract_fonts(ASS_Library *priv, int extract); 273 274 /** 275 * \brief Register style overrides with a library instance. 276 * The overrides should have the form [Style.]Param=Value, e.g. 277 * SomeStyle.Font=Arial 278 * ScaledBorderAndShadow=yes 279 * 280 * \param priv library handle 281 * \param list NULL-terminated list of strings 282 */ 283 void ass_set_style_overrides(ASS_Library *priv, char **list); 284 285 /** 286 * \brief Explicitly process style overrides for a track. 287 * \param track track handle 288 */ 289 void ass_process_force_style(ASS_Track *track); 290 291 /** 292 * \brief Register a callback for debug/info messages. 293 * If a callback is registered, it is called for every message emitted by 294 * libass. The callback receives a format string and a list of arguments, 295 * to be used for the printf family of functions. Additionally, a log level 296 * from 0 (FATAL errors) to 7 (verbose DEBUG) is passed. Usually, level 5 297 * should be used by applications. 298 * If no callback is set, all messages level < 5 are printed to stderr, 299 * prefixed with [ass]. 300 * 301 * \param priv library handle 302 * \param msg_cb pointer to callback function 303 * \param data additional data, will be passed to callback 304 */ 305 void ass_set_message_cb(ASS_Library *priv, void (*msg_cb) 306 (int level, const char *fmt, va_list args, void *data), 307 void *data); 308 309 /** 310 * \brief Initialize the renderer. 311 * \param priv library handle 312 * \return renderer handle or NULL if failed 313 */ 314 ASS_Renderer *ass_renderer_init(ASS_Library *); 315 316 /** 317 * \brief Finalize the renderer. 318 * \param priv renderer handle 319 */ 320 void ass_renderer_done(ASS_Renderer *priv); 321 322 /** 323 * \brief Set the frame size in pixels, including margins. 324 * The renderer will never return images that are outside of the frame area. 325 * The value set with this function can influence the pixel aspect ratio used 326 * for rendering. If the frame size doesn't equal to the video size, you may 327 * have to use ass_set_pixel_aspect(). 328 * @see ass_set_pixel_aspect() 329 * @see ass_set_margins() 330 * \param priv renderer handle 331 * \param w width 332 * \param h height 333 */ 334 void ass_set_frame_size(ASS_Renderer *priv, int w, int h); 335 336 /** 337 * \brief Set the source image size in pixels. 338 * This is used to calculate the source aspect ratio and the blur scale. 339 * The source image size can be reset to default by setting w and h to 0. 340 * The value set with this function can influence the pixel aspect ratio used 341 * for rendering. 342 * @see ass_set_pixel_aspect() 343 * \param priv renderer handle 344 * \param w width 345 * \param h height 346 */ 347 void ass_set_storage_size(ASS_Renderer *priv, int w, int h); 348 349 /** 350 * \brief Set shaping level. This is merely a hint, the renderer will use 351 * whatever is available if the request cannot be fulfilled. 352 * \param level shaping level 353 */ 354 void ass_set_shaper(ASS_Renderer *priv, ASS_ShapingLevel level); 355 356 /** 357 * \brief Set frame margins. These values may be negative if pan-and-scan 358 * is used. The margins are in pixels. Each value specifies the distance from 359 * the video rectangle to the renderer frame. If a given margin value is 360 * positive, there will be free space between renderer frame and video area. 361 * If a given margin value is negative, the frame is inside the video, i.e. 362 * the video has been cropped. 363 * 364 * The renderer will try to keep subtitles inside the frame area. If possible, 365 * text is layout so that it is inside the cropped area. Subtitle events 366 * that can't be moved are cropped against the frame area. 367 * 368 * ass_set_use_margins() can be used to allow libass to render subtitles into 369 * the empty areas if margins are positive, i.e. the video area is smaller than 370 * the frame. (Traditionally, this has been used to show subtitles in 371 * the bottom "black bar" between video bottom screen border when playing 16:9 372 * video on a 4:3 screen.) 373 * 374 * When using this function, it is recommended to calculate and set your own 375 * aspect ratio with ass_set_pixel_aspect(), as the defaults won't make any 376 * sense. 377 * @see ass_set_pixel_aspect() 378 * \param priv renderer handle 379 * \param t top margin 380 * \param b bottom margin 381 * \param l left margin 382 * \param r right margin 383 */ 384 void ass_set_margins(ASS_Renderer *priv, int t, int b, int l, int r); 385 386 /** 387 * \brief Whether margins should be used for placing regular events. 388 * \param priv renderer handle 389 * \param use whether to use the margins 390 */ 391 void ass_set_use_margins(ASS_Renderer *priv, int use); 392 393 /** 394 * \brief Set pixel aspect ratio correction. 395 * This is the ratio of pixel width to pixel height. 396 * 397 * Generally, this is (s_w / s_h) / (d_w / d_h), where s_w and s_h is the 398 * video storage size, and d_w and d_h is the video display size. (Display 399 * and storage size can be different for anamorphic video, such as DVDs.) 400 * 401 * If the pixel aspect ratio is 0, or if the aspect ratio has never been set 402 * by calling this function, libass will calculate a default pixel aspect ratio 403 * out of values set with ass_set_frame_size() and ass_set_storage_size(). Note 404 * that this is useful only if the frame size corresponds to the video display 405 * size. Keep in mind that the margins set with ass_set_margins() are ignored 406 * for aspect ratio calculations as well. 407 * If the storage size has not been set, a pixel aspect ratio of 1 is assumed. 408 * \param priv renderer handle 409 * \param par pixel aspect ratio (1.0 means square pixels, 0 means default) 410 */ 411 void ass_set_pixel_aspect(ASS_Renderer *priv, double par); 412 413 /** 414 * \brief Set aspect ratio parameters. 415 * This calls ass_set_pixel_aspect(priv, dar / sar). 416 * @deprecated New code should use ass_set_pixel_aspect(). 417 * \param priv renderer handle 418 * \param dar display aspect ratio (DAR), prescaled for output PAR 419 * \param sar storage aspect ratio (SAR) 420 */ 421 ASS_DEPRECATED("use 'ass_set_pixel_aspect' instead") void ass_set_aspect_ratio(ASS_Renderer *priv, double dar, double sar); 422 423 /** 424 * \brief Set a fixed font scaling factor. 425 * \param priv renderer handle 426 * \param font_scale scaling factor, default is 1.0 427 */ 428 void ass_set_font_scale(ASS_Renderer *priv, double font_scale); 429 430 /** 431 * \brief Set font hinting method. 432 * \param priv renderer handle 433 * \param ht hinting method 434 */ 435 void ass_set_hinting(ASS_Renderer *priv, ASS_Hinting ht); 436 437 /** 438 * \brief Set line spacing. Will not be scaled with frame size. 439 * \param priv renderer handle 440 * \param line_spacing line spacing in pixels 441 */ 442 void ass_set_line_spacing(ASS_Renderer *priv, double line_spacing); 443 444 /** 445 * \brief Set vertical line position. 446 * \param priv renderer handle 447 * \param line_position vertical line position of subtitles in percent 448 * (0-100: 0 = on the bottom (default), 100 = on top) 449 */ 450 void ass_set_line_position(ASS_Renderer *priv, double line_position); 451 452 /** 453 * \brief Get the list of available font providers. The output array 454 * is allocated with malloc and can be released with free(). If an 455 * allocation error occurs, size is set to (size_t)-1. 456 * \param priv library handle 457 * \param providers output, list of default providers (malloc'ed array) 458 * \param size output, number of providers 459 * \return list of available font providers (user owns the returned array) 460 */ 461 void ass_get_available_font_providers(ASS_Library *priv, 462 ASS_DefaultFontProvider **providers, 463 size_t *size); 464 465 /** 466 * \brief Set font lookup defaults. 467 * \param default_font path to default font to use. Must be supplied if 468 * fontconfig is disabled or unavailable. 469 * \param default_family fallback font family for fontconfig, or NULL 470 * \param dfp which font provider to use (one of ASS_DefaultFontProvider). In 471 * older libass version, this could be 0 or 1, where 1 enabled fontconfig. 472 * Newer relases also accept 0 (ASS_FONTPROVIDER_NONE) and 1 473 * (ASS_FONTPROVIDER_AUTODETECT), which is almost backward-compatible. 474 * If the requested fontprovider does not exist or fails to initialize, the 475 * behavior is the same as when ASS_FONTPROVIDER_NONE was passed. 476 * \param config path to fontconfig configuration file, or NULL. Only relevant 477 * if fontconfig is used. 478 * \param update whether fontconfig cache should be built/updated now. Only 479 * relevant if fontconfig is used. 480 * 481 * NOTE: font lookup must be configured before an ASS_Renderer can be used. 482 */ 483 void ass_set_fonts(ASS_Renderer *priv, const char *default_font, 484 const char *default_family, int dfp, 485 const char *config, int update); 486 487 /** 488 * \brief Set selective style override mode. 489 * If enabled, the renderer attempts to override the ASS script's styling of 490 * normal subtitles, without affecting explicitly positioned text. If an event 491 * looks like a normal subtitle, parts of the font style are copied from the 492 * user style set with ass_set_selective_style_override(). 493 * Warning: the heuristic used for deciding when to override the style is rather 494 * rough, and enabling this option can lead to incorrectly rendered 495 * subtitles. Since the ASS format doesn't have any support for 496 * allowing end-users to customize subtitle styling, this feature can 497 * only be implemented on "best effort" basis, and has to rely on 498 * heuristics that can easily break. 499 * \param priv renderer handle 500 * \param bits bit mask comprised of ASS_OverrideBits values. 501 */ 502 void ass_set_selective_style_override_enabled(ASS_Renderer *priv, int bits); 503 504 /** 505 * \brief Set style for selective style override. 506 * See ass_set_selective_style_override_enabled(). 507 * \param style style settings to use if override is enabled. Applications 508 * should initialize it with {0} before setting fields. Strings will be copied 509 * by the function. 510 */ 511 void ass_set_selective_style_override(ASS_Renderer *priv, ASS_Style *style); 512 513 /** 514 * \brief This is a stub and does nothing. Old documentation: Update/build font 515 * cache. This needs to be called if it was disabled when ass_set_fonts was set. 516 * 517 * \param priv renderer handle 518 * \return success 519 */ 520 ASS_DEPRECATED("it does nothing") int ass_fonts_update(ASS_Renderer *priv); 521 522 /** 523 * \brief Set hard cache limits. Do not set, or set to zero, for reasonable 524 * defaults. 525 * 526 * \param priv renderer handle 527 * \param glyph_max maximum number of cached glyphs 528 * \param bitmap_max_size maximum bitmap cache size (in MB) 529 */ 530 void ass_set_cache_limits(ASS_Renderer *priv, int glyph_max, 531 int bitmap_max_size); 532 533 /** 534 * \brief Render a frame, producing a list of ASS_Image. 535 * \param priv renderer handle 536 * \param track subtitle track 537 * \param now video timestamp in milliseconds 538 * \param detect_change compare to the previous call and set to 1 539 * if positions changed, or set to 2 if content changed. 540 */ 541 ASS_Image *ass_render_frame(ASS_Renderer *priv, ASS_Track *track, 542 long long now, int *detect_change); 543 544 545 /* 546 * The following functions operate on track objects and do not need 547 * an ass_renderer 548 */ 549 550 /** 551 * \brief Allocate a new empty track object. 552 * \param library handle 553 * \return pointer to empty track or NULL on failure 554 */ 555 ASS_Track *ass_new_track(ASS_Library *); 556 557 /** 558 * \brief Enable or disable certain features 559 * This manages flags that control the behavior of the renderer and how certain 560 * tags etc. within the track are interpreted. The defaults on a newly created 561 * ASS_Track are such that rendering is compatible with traditional renderers 562 * like VSFilter, and/or old versions of libass. Calling ass_process_data() or 563 * ass_process_codec_private() may change some of these flags according to file 564 * headers. (ass_process_chunk() will not change any of the flags.) 565 * Additions to ASS_Feature are backward compatible to old libass releases (ABI 566 * compatibility). 567 * \param track track 568 * \param feature the specific feature to enable or disable 569 * \param enable 0 for disable, any non-0 value for enable 570 * \return 0 if feature set, -1 if feature is unknown 571 */ 572 int ass_track_set_feature(ASS_Track *track, ASS_Feature feature, int enable); 573 574 /** 575 * \brief Deallocate track and all its child objects (styles and events). 576 * \param track track to deallocate or NULL 577 */ 578 void ass_free_track(ASS_Track *track); 579 580 /** 581 * \brief Allocate new style. 582 * \param track track 583 * \return newly allocated style id >= 0, or a value < 0 on failure 584 */ 585 int ass_alloc_style(ASS_Track *track); 586 587 /** 588 * \brief Allocate new event. 589 * \param track track 590 * \return newly allocated event id >= 0, or a value < 0 on failure 591 */ 592 int ass_alloc_event(ASS_Track *track); 593 594 /** 595 * \brief Delete a style. 596 * \param track track 597 * \param sid style id 598 * Deallocates style data. Does not modify track->n_styles. 599 */ 600 void ass_free_style(ASS_Track *track, int sid); 601 602 /** 603 * \brief Delete an event. 604 * \param track track 605 * \param eid event id 606 * Deallocates event data. Does not modify track->n_events. 607 */ 608 void ass_free_event(ASS_Track *track, int eid); 609 610 /** 611 * \brief Parse a chunk of subtitle stream data. 612 * \param track track 613 * \param data string to parse 614 * \param size length of data 615 */ 616 void ass_process_data(ASS_Track *track, char *data, int size); 617 618 /** 619 * \brief Parse Codec Private section of the subtitle stream, in Matroska 620 * format. See the Matroska specification for details. 621 * \param track target track 622 * \param data string to parse 623 * \param size length of data 624 */ 625 void ass_process_codec_private(ASS_Track *track, char *data, int size); 626 627 /** 628 * \brief Parse a chunk of subtitle stream data. A chunk contains exactly one 629 * event in Matroska format. See the Matroska specification for details. 630 * In later libass versions (since LIBASS_VERSION==0x01300001), using this 631 * function means you agree not to modify events manually, or using other 632 * functions manipulating the event list like ass_process_data(). If you do 633 * anyway, the internal duplicate checking might break. Calling 634 * ass_flush_events() is still allowed. 635 * \param track track 636 * \param data string to parse 637 * \param size length of data 638 * \param timecode starting time of the event (milliseconds) 639 * \param duration duration of the event (milliseconds) 640 */ 641 void ass_process_chunk(ASS_Track *track, char *data, int size, 642 long long timecode, long long duration); 643 644 /** 645 * \brief Set whether the ReadOrder field when processing a packet with 646 * ass_process_chunk() should be used for eliminating duplicates. 647 * \param check_readorder 0 means do not try to eliminate duplicates; 1 means 648 * use the ReadOrder field embedded in the packet as unique identifier, and 649 * discard the packet if there was already a packet with the same ReadOrder. 650 * Other values are undefined. 651 * If this function is not called, the default value is 1. 652 */ 653 void ass_set_check_readorder(ASS_Track *track, int check_readorder); 654 655 /** 656 * \brief Flush buffered events. 657 * \param track track 658 */ 659 void ass_flush_events(ASS_Track *track); 660 661 /** 662 * \brief Read subtitles from file. 663 * \param library library handle 664 * \param fname file name 665 * \param codepage encoding (iconv format) 666 * \return newly allocated track or NULL on failure 667 */ 668 ASS_Track *ass_read_file(ASS_Library *library, char *fname, 669 char *codepage); 670 671 /** 672 * \brief Read subtitles from memory. 673 * \param library library handle 674 * \param buf pointer to subtitles text 675 * \param bufsize size of buffer 676 * \param codepage encoding (iconv format) 677 * \return newly allocated track or NULL on failure 678 */ 679 ASS_Track *ass_read_memory(ASS_Library *library, char *buf, 680 size_t bufsize, char *codepage); 681 /** 682 * \brief Read styles from file into already initialized track. 683 * \param fname file name 684 * \param codepage encoding (iconv format) 685 * \return 0 on success 686 */ 687 int ass_read_styles(ASS_Track *track, char *fname, char *codepage); 688 689 /** 690 * \brief Add a memory font. 691 * \param library library handle 692 * \param name attachment name 693 * \param data binary font data 694 * \param data_size data size 695 */ 696 void ass_add_font(ASS_Library *library, const char *name, const char *data, 697 int data_size); 698 699 /** 700 * \brief Remove all fonts stored in an ass_library object. 701 * This can only be called safely if all ASS_Track and ASS_Renderer instances 702 * associated with the library handle have been released first. 703 * \param library library handle 704 */ 705 void ass_clear_fonts(ASS_Library *library); 706 707 /** 708 * \brief Calculates timeshift from now to the start of some other subtitle 709 * event, depending on movement parameter. 710 * \param track subtitle track 711 * \param now current time in milliseconds 712 * \param movement how many events to skip from the one currently displayed 713 * +2 means "the one after the next", -1 means "previous" 714 * \return timeshift in milliseconds 715 */ 716 long long ass_step_sub(ASS_Track *track, long long now, int movement); 717 718 #ifdef __cplusplus 719 } 720 #endif 721 722 #endif /* LIBASS_ASS_H */ 723