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