From c3ace011c01dfd0817622171613de5c014f61d44 Mon Sep 17 00:00:00 2001 From: Grigori Goronzy Date: Fri, 17 Jul 2009 14:39:20 +0200 Subject: Improve API headers and documentation Improve APi documentation; each function is properly documented now. Add a new macro LIBASS_VERSION that encodes the version in a hexadecimal format, similar to OpenSSL. Fix formatting of the headers. --- libass/ass.h | 188 +++++++++++++++++++++++++++++++++++++++++------------ libass/ass_types.h | 44 +++++++------ 2 files changed, 171 insertions(+), 61 deletions(-) diff --git a/libass/ass.h b/libass/ass.h index b7eab3c..6efcc0f 100644 --- a/libass/ass.h +++ b/libass/ass.h @@ -25,132 +25,228 @@ #include #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. @@ -158,7 +254,7 @@ int ass_alloc_event(ass_track_t *track); 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. @@ -174,7 +270,7 @@ void ass_free_event(ass_track_t *track, int eid); 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 @@ -182,19 +278,22 @@ void ass_process_data(ass_track_t *track, char *data, int size); 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, @@ -202,22 +301,25 @@ 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 @@ -226,18 +328,20 @@ void ass_add_font(ass_library_t *library, char *name, char *data, 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 */ diff --git a/libass/ass_types.h b/libass/ass_types.h index cdea14e..fb74872 100644 --- a/libass/ass_types.h +++ b/libass/ass_types.h @@ -30,7 +30,7 @@ #define HALIGN_CENTER 2 #define HALIGN_RIGHT 3 -/// ass Style: line +/* ASS Style: line */ typedef struct ass_style_s { char *Name; char *FontName; @@ -54,15 +54,16 @@ typedef struct ass_style_s { 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 @@ -81,26 +82,31 @@ typedef struct ass_event_s { } 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; @@ -108,11 +114,11 @@ typedef struct ass_track_s { 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 */ -- cgit v1.2.3