#include <stdarg.h>
#include "ass_types.h"
-/// Libass renderer object. Contents are private.
+#define LIBASS_VERSION 0x00907000
+
+/* Libass renderer object. Contents are private. */
typedef struct ass_renderer_s ass_renderer_t;
-/// a linked list of images produced by ass renderer
+/* A linked list of images produced by ass renderer. */
typedef struct ass_image_s {
- int w, h; // bitmap width/height
- int stride; // bitmap stride
+ int w, h; // Bitmap width/height
+ int stride; // Bitmap stride
unsigned char *bitmap; // 1bpp stride*h alpha buffer
- uint32_t color; // RGBA
- int dst_x, dst_y; // bitmap placement inside the video frame
+ uint32_t color; // Bitmap color and alpha, RGBA
+ int dst_x, dst_y; // Bitmap placement inside the video frame
- struct ass_image_s *next; // linked list
+ struct ass_image_s *next; // Next image, or NULL
} ass_image_t;
-/// Hinting type
-typedef enum { ASS_HINTING_NONE = 0,
+/* Hinting type. */
+typedef enum {
+ ASS_HINTING_NONE = 0,
ASS_HINTING_LIGHT,
ASS_HINTING_NORMAL,
ASS_HINTING_NATIVE
} ass_hinting_t;
/**
- * \brief initialize the library
+ * \brief Initialize the library.
* \return library handle or NULL if failed
*/
ass_library_t *ass_library_init(void);
/**
- * \brief finalize the library
+ * \brief Finalize the library
* \param priv library handle
*/
void ass_library_done(ass_library_t *);
/**
- * \brief set private font directory
+ * \brief Set private font directory.
* It is used for saving embedded fonts and also in font lookup.
+ *
+ * \param priv library handle
+ * \param fonts_dir private directory for font extraction
*/
void ass_set_fonts_dir(ass_library_t *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_t *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_t *priv, char **list);
+/**
+ * \brief Explicitly process style overrides for a track.
+ * \param track track handle
+ */
void ass_process_force_style(ass_track_t *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_t *priv,
void (*msg_cb)(int, char *, va_list *, void *),
void *data);
/**
- * \brief initialize the renderer
+ * \brief Initialize the renderer.
* \param priv library handle
* \return renderer handle or NULL if failed
*/
ass_renderer_t *ass_renderer_init(ass_library_t *);
/**
- * \brief finalize the renderer
+ * \brief Finalize the renderer.
* \param priv renderer handle
*/
void ass_renderer_done(ass_renderer_t *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_t *priv, int w, int h);
+
+/**
+ * \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_t *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_t *priv, int use);
+
+/**
+ * \brief Set aspect ratio parameters.
+ * \param priv renderer handle
+ * \param ar physical aspect ratio
+ * \param par pixel ratio, e.g. width / height of the video
+ */
void ass_set_aspect_ratio(ass_renderer_t *priv, double ar, double par);
+
+/**
+ * \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_t *priv, double font_scale);
+
+/**
+ * \brief Set font hinting method.
+ * \param priv renderer handle
+ * \param ht hinting method
+ */
void ass_set_hinting(ass_renderer_t *priv, ass_hinting_t 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_t *priv, double line_spacing);
/**
- * \brief set font lookup defaults
- * \param fc bool, use fontconfig?
- * \param config path to fontconfig configuration file, or NULL. Only matters
- * if fontconfig is used
- * \param update whether fontconfig cache should be built/updated now. Make
- * sure to call ass_fonts_update later if 0! Only matters if fontconfig
- * is used.
- * \return success
+ * \brief Set font lookup defaults.
+ * \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.
*/
void ass_set_fonts(ass_renderer_t *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_t *priv);
/**
- * \brief render a frame, producing a list of ass_image_t
- * \param priv library
+ * \brief Render a frame, producing a list of ass_image_t.
+ * \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_t *ass_render_frame(ass_renderer_t *priv, ass_track_t *track,
long long now, int *detect_change);
-// The following functions operate on track objects and do not need an ass_renderer //
+/*
+ * The following functions operate on track objects and do not need
+ * an ass_renderer
+ */
/**
- * \brief allocate a new empty track object
+ * \brief Allocate a new empty track object.
+ * \param library handle
* \return pointer to empty track
*/
ass_track_t *ass_new_track(ass_library_t *);
/**
- * \brief deallocate track and all its child objects (styles and events)
+ * \brief Deallocate track and all its child objects (styles and events).
* \param track track to deallocate
*/
void ass_free_track(ass_track_t *track);
/**
- * \brief allocate new style
+ * \brief Allocate new style.
* \param track track
* \return newly allocated style id
*/
int ass_alloc_style(ass_track_t *track);
/**
- * \brief allocate new event
+ * \brief Allocate new event.
* \param track track
* \return newly allocated event id
*/
int ass_alloc_event(ass_track_t *track);
/**
- * \brief delete a style
+ * \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_t *track, int sid);
/**
- * \brief delete an event
+ * \brief Delete an event.
* \param track track
* \param eid event id
* Deallocates event data. Does not modify track->n_events.
void ass_process_data(ass_track_t *track, char *data, int size);
/**
- * \brief Parse Codec Private section of subtitle stream
+ * \brief Parse Codec Private section of subtitle stream.
* \param track target track
* \param data string to parse
* \param size length of data
void ass_process_codec_private(ass_track_t *track, char *data, int size);
/**
- * \brief Parse a chunk of subtitle stream data. In Matroska, this contains exactly 1 event (or a commentary).
+ * \brief Parse a chunk of subtitle stream data. In Matroska,
+ * this contains exactly 1 event (or a commentary).
* \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_t *track, char *data, int size,
long long timecode, long long duration);
/**
* \brief Read subtitles from file.
+ * \param library library handle
* \param fname file name
+ * \param codepage encoding (iconv format)
* \return newly allocated track
*/
ass_track_t *ass_read_file(ass_library_t *library, char *fname,
/**
* \brief Read subtitles from memory.
- * \param library libass library object
+ * \param library library handle
* \param buf pointer to subtitles text
* \param bufsize size of buffer
- * \param codepage recode buffer contents from given codepage
+ * \param codepage encoding (iconv format)
* \return newly allocated track
*/
ass_track_t *ass_read_memory(ass_library_t *library, char *buf,
size_t bufsize, char *codepage);
/**
- * \brief read styles from file into already initialized track
+ * \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_t *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
int data_size);
/**
- * \brief Remove all fonts stored in ass_library object
+ * \brief Remove all fonts stored in an ass_library object.
+ * \param library library handle
*/
void ass_clear_fonts(ass_library_t *library);
/**
- * \brief Calculates timeshift from now to the start of some other subtitle event, depending on movement parameter
+ * \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, ms
+ * \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, ms
+ * \return timeshift in milliseconds
*/
long long ass_step_sub(ass_track_t *track, long long now, int movement);
-#endif /* LIBASS_ASS_H */
+#endif /* LIBASS_ASS_H */
#define HALIGN_CENTER 2
#define HALIGN_RIGHT 3
-/// ass Style: line
+/* ASS Style: line */
typedef struct ass_style_s {
char *Name;
char *FontName;
int MarginL;
int MarginR;
int MarginV;
-// int AlphaLevel;
int Encoding;
int treat_fontname_as_pattern;
} ass_style_t;
typedef struct render_priv_s render_priv_t;
-/// ass_event_t corresponds to a single Dialogue line
-/// Text is stored as-is, style overrides will be parsed later
+/*
+ * ass_event_t corresponds to a single Dialogue line;
+ * text is stored as-is, style overrides will be parsed later.
+ */
typedef struct ass_event_s {
long long Start; // ms
long long Duration; // ms
} ass_event_t;
typedef struct parser_priv_s parser_priv_t;
-
typedef struct ass_library_s ass_library_t;
-/// ass track represent either an external script or a matroska subtitle stream (no real difference between them)
-/// it can be used in rendering after the headers are parsed (i.e. events format line read)
+/*
+ * ass track represent either an external script or a matroska subtitle stream
+ * (no real difference between them); it can be used in rendering after the
+ * headers are parsed (i.e. events format line read).
+ */
typedef struct ass_track_s {
- int n_styles; // amount used
- int max_styles; // amount allocated
+ int n_styles; // amount used
+ int max_styles; // amount allocated
int n_events;
int max_events;
- ass_style_t *styles; // array of styles, max_styles length, n_styles used
- ass_event_t *events; // the same as styles
+ ass_style_t *styles; // array of styles, max_styles length, n_styles used
+ ass_event_t *events; // the same as styles
- char *style_format; // style format line (everything after "Format: ")
- char *event_format; // event format line
+ char *style_format; // style format line (everything after "Format: ")
+ char *event_format; // event format line
- enum { TRACK_TYPE_UNKNOWN =
- 0, TRACK_TYPE_ASS, TRACK_TYPE_SSA } track_type;
+ enum {
+ TRACK_TYPE_UNKNOWN = 0,
+ TRACK_TYPE_ASS,
+ TRACK_TYPE_SSA
+ } track_type;
- // script header fields
+ // Script header fields
int PlayResX;
int PlayResY;
double Timer;
char ScaledBorderAndShadow;
- int default_style; // index of default style
- char *name; // file name in case of external subs, 0 for streams
+ int default_style; // index of default style
+ char *name; // file name in case of external subs, 0 for streams
ass_library_t *library;
parser_priv_t *parser_priv;
} ass_track_t;
-#endif /* LIBASS_TYPES_H */
+#endif /* LIBASS_TYPES_H */
projects / libass / commitdiff