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