libass/ass.h

   1 // -*- c-basic-offset: 8; indent-tabs-mode: t -*-
   2 // vim:ts=8:sw=8:noet:ai:
   3 /*
   4  * Copyright (C) 2006 Evgeniy Stepanov <eugeni.stepanov@gmail.com>
   5  *
   6  * This file is part of libass.
   7  *
   8  * libass is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 2 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * libass is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License along
  19  * with libass; if not, write to the Free Software Foundation, Inc.,
  20  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  21  */
  22
  23 #ifndef LIBASS_ASS_H
  24 #define LIBASS_ASS_H
  25
  26 #include <stdio.h>
  27 #include "ass_types.h"
  28
  29 /// Libass renderer object. Contents are private.
  30 typedef struct ass_renderer_s ass_renderer_t;
  31
  32 /// a linked list of images produced by ass renderer
  33 typedef struct ass_image_s {
  34         int w, h; // bitmap width/height
  35         int stride; // bitmap stride
  36         unsigned char* bitmap; // 1bpp stride*h alpha buffer
  37         uint32_t color; // RGBA
  38         int dst_x, dst_y; // bitmap placement inside the video frame
  39
  40         struct ass_image_s* next; // linked list
  41 } ass_image_t;
  42
  43 /// Hinting type
  44 typedef enum {ASS_HINTING_NONE = 0,
  45               ASS_HINTING_LIGHT,
  46               ASS_HINTING_NORMAL,
  47               ASS_HINTING_NATIVE
  48 } ass_hinting_t;
  49
  50 /**
  51  * \brief initialize the library
  52  * \return library handle or NULL if failed
  53  */
  54 ass_library_t* ass_library_init(void);
  55
  56 /**
  57  * \brief finalize the library
  58  * \param priv library handle
  59  */
  60 void ass_library_done(ass_library_t*);
  61
  62 /**
  63  * \brief set private font directory
  64  * It is used for saving embedded fonts and also in font lookup.
  65  */
  66 void ass_set_fonts_dir(ass_library_t* priv, const char* fonts_dir);
  67
  68 void ass_set_extract_fonts(ass_library_t* priv, int extract);
  69
  70 void ass_set_style_overrides(ass_library_t* priv, char** list);
  71
  72 /**
  73  * \brief initialize the renderer
  74  * \param priv library handle
  75  * \return renderer handle or NULL if failed
  76  */
  77 ass_renderer_t* ass_renderer_init(ass_library_t*);
  78
  79 /**
  80  * \brief finalize the renderer
  81  * \param priv renderer handle
  82  */
  83 void ass_renderer_done(ass_renderer_t* priv);
  84
  85 void ass_set_frame_size(ass_renderer_t* priv, int w, int h);
  86 void ass_set_margins(ass_renderer_t* priv, int t, int b, int l, int r);
  87 void ass_set_use_margins(ass_renderer_t* priv, int use);
  88 void ass_set_aspect_ratio(ass_renderer_t* priv, double ar);
  89 void ass_set_font_scale(ass_renderer_t* priv, double font_scale);
  90 void ass_set_hinting(ass_renderer_t* priv, ass_hinting_t ht);
  91 void ass_set_line_spacing(ass_renderer_t* priv, double line_spacing);
  92
  93 /**
  94  * \brief set font lookup defaults
  95  */
  96 int  ass_set_fonts(ass_renderer_t* priv, const char* default_font, const char* default_family);
  97
  98 /**
  99  * \brief set font lookup defaults, don't use fontconfig even if it is available
 100  */
 101 int  ass_set_fonts_nofc(ass_renderer_t* priv, const char* default_font, const char* default_family);
 102
 103 /**
 104  * \brief render a frame, producing a list of ass_image_t
 105  * \param priv library
 106  * \param track subtitle track
 107  * \param now video timestamp in milliseconds
 108  */
 109 ass_image_t* ass_render_frame(ass_renderer_t *priv, ass_track_t* track, long long now, int* detect_change);
 110
 111
 112 // The following functions operate on track objects and do not need an ass_renderer //
 113
 114 /**
 115  * \brief allocate a new empty track object
 116  * \return pointer to empty track
 117  */
 118 ass_track_t* ass_new_track(ass_library_t*);
 119
 120 /**
 121  * \brief deallocate track and all its child objects (styles and events)
 122  * \param track track to deallocate
 123  */
 124 void ass_free_track(ass_track_t* track);
 125
 126 /**
 127  * \brief allocate new style
 128  * \param track track
 129  * \return newly allocated style id
 130  */
 131 int ass_alloc_style(ass_track_t* track);
 132
 133 /**
 134  * \brief allocate new event
 135  * \param track track
 136  * \return newly allocated event id
 137  */
 138 int ass_alloc_event(ass_track_t* track);
 139
 140 /**
 141  * \brief delete a style
 142  * \param track track
 143  * \param sid style id
 144  * Deallocates style data. Does not modify track->n_styles.
 145  */
 146 void ass_free_style(ass_track_t* track, int sid);
 147
 148 /**
 149  * \brief delete an event
 150  * \param track track
 151  * \param eid event id
 152  * Deallocates event data. Does not modify track->n_events.
 153  */
 154 void ass_free_event(ass_track_t* track, int eid);
 155
 156 /**
 157  * \brief Parse a chunk of subtitle stream data.
 158  * \param track track
 159  * \param data string to parse
 160  * \param size length of data
 161  */
 162 void ass_process_data(ass_track_t* track, char* data, int size);
 163
 164 /**
 165  * \brief Parse Codec Private section of subtitle stream
 166  * \param track target track
 167  * \param data string to parse
 168  * \param size length of data
 169  */
 170 void ass_process_codec_private(ass_track_t* track, char *data, int size);
 171
 172 /**
 173  * \brief Parse a chunk of subtitle stream data. In Matroska, this contains exactly 1 event (or a commentary).
 174  * \param track track
 175  * \param data string to parse
 176  * \param size length of data
 177  * \param timecode starting time of the event (milliseconds)
 178  * \param duration duration of the event (milliseconds)
 179 */
 180 void ass_process_chunk(ass_track_t* track, char *data, int size, long long timecode, long long duration);
 181
 182 char* read_file_recode(char* fname, char* codepage, size_t* size);
 183
 184 /**
 185  * \brief Read subtitles from file.
 186  * \param fname file name
 187  * \return newly allocated track
 188 */
 189 ass_track_t* ass_read_file(ass_library_t* library, char* fname, char* codepage);
 190
 191 /**
 192  * \brief Read subtitles from memory.
 193  * \param library libass library object
 194  * \param buf pointer to subtitles text
 195  * \param bufsize size of buffer
 196  * \param codepage recode buffer contents from given codepage
 197  * \return newly allocated track
 198 */
 199 ass_track_t* ass_read_memory(ass_library_t* library, char* buf, size_t bufsize, char* codepage);
 200 /**
 201  * \brief read styles from file into already initialized track
 202  * \return 0 on success
 203  */
 204 int ass_read_styles(ass_track_t* track, char* fname, char* codepage);
 205
 206 /**
 207  * \brief Add a memory font.
 208  * \param name attachment name
 209  * \param data binary font data
 210  * \param data_size data size
 211 */
 212 void ass_add_font(ass_library_t* library, char* name, char* data, int data_size);
 213
 214 /**
 215  * \brief Remove all fonts stored in ass_library object
 216  */
 217 void ass_clear_fonts(ass_library_t* library);
 218
 219 /**
 220  * \brief Calculates timeshift from now to the start of some other subtitle event, depending on movement parameter
 221  * \param track subtitle track
 222  * \param now current time, ms
 223  * \param movement how many events to skip from the one currently displayed
 224  * +2 means "the one after the next", -1 means "previous"
 225  * \return timeshift, ms
 226  */
 227 long long ass_step_sub(ass_track_t* track, long long now, int movement);
 228
 229 #endif /* LIBASS_ASS_H */