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
  89 /**
  90  * \brief set font lookup defaults
  91  */
  92 int  ass_set_fonts(ass_renderer_t* priv, const char* default_font, const char* default_family);
  93
  94 /**
  95  * \brief render a frame, producing a list of ass_image_t
  96  * \param priv library
  97  * \param track subtitle track
  98  * \param now video timestamp in milliseconds
  99  */
 100 ass_image_t* ass_render_frame(ass_renderer_t *priv, ass_track_t* track, long long now, int* detect_change);
 101
 102
 103 // The following functions operate on track objects and do not need an ass_renderer //
 104
 105 /**
 106  * \brief allocate a new empty track object
 107  * \return pointer to empty track
 108  */
 109 ass_track_t* ass_new_track(ass_library_t*);
 110
 111 /**
 112  * \brief deallocate track and all its child objects (styles and events)
 113  * \param track track to deallocate
 114  */
 115 void ass_free_track(ass_track_t* track);
 116
 117 /**
 118  * \brief allocate new style
 119  * \param track track
 120  * \return newly allocated style id
 121  */
 122 int ass_alloc_style(ass_track_t* track);
 123
 124 /**
 125  * \brief allocate new event
 126  * \param track track
 127  * \return newly allocated event id
 128  */
 129 int ass_alloc_event(ass_track_t* track);
 130
 131 /**
 132  * \brief delete a style
 133  * \param track track
 134  * \param sid style id
 135  * Deallocates style data. Does not modify track->n_styles.
 136  */
 137 void ass_free_style(ass_track_t* track, int sid);
 138
 139 /**
 140  * \brief delete an event
 141  * \param track track
 142  * \param eid event id
 143  * Deallocates event data. Does not modify track->n_events.
 144  */
 145 void ass_free_event(ass_track_t* track, int eid);
 146
 147 /**
 148  * \brief Process Codec Private section of subtitle stream
 149  * \param track target track
 150  * \param data string to parse
 151  * \param size length of data
 152  */
 153 void ass_process_codec_private(ass_track_t* track, char *data, int size);
 154
 155 /**
 156  * \brief Process a chunk of subtitle stream data. In matroska, this containes exactly 1 event (or a commentary)
 157  * \param track track
 158  * \param data string to parse
 159  * \param size length of data
 160  * \param timecode starting time of the event (milliseconds)
 161  * \param duration duration of the event (milliseconds)
 162 */
 163 void ass_process_chunk(ass_track_t* track, char *data, int size, long long timecode, long long duration);
 164
 165 char* read_file_recode(char* fname, char* codepage, int* size);
 166
 167 /**
 168  * \brief Read subtitles from file.
 169  * \param fname file name
 170  * \return newly allocated track
 171 */
 172 ass_track_t* ass_read_file(ass_library_t* library, char* fname, char* codepage);
 173
 174 /**
 175  * \brief Read subtitles from memory.
 176  * \param library libass library object
 177  * \param buf pointer to subtitles text
 178  * \param bufsize size of buffer
 179  * \param codepage recode buffer contents from given codepage
 180  * \return newly allocated track
 181 */
 182 ass_track_t* ass_read_memory(ass_library_t* library, char* buf, size_t bufsize, char* codepage);
 183 /**
 184  * \brief read styles from file into already initialized track
 185  * \return 0 on success
 186  */
 187 int ass_read_styles(ass_track_t* track, char* fname, char* codepage);
 188
 189 /**
 190  * \brief Add a memory font.
 191  * \param name attachment name
 192  * \param data binary font data
 193  * \param data_size data size
 194 */
 195 void ass_add_font(ass_library_t* library, char* name, char* data, int data_size);
 196
 197 /**
 198  * \brief Calculates timeshift from now to the start of some other subtitle event, depending on movement parameter
 199  * \param track subtitle track
 200  * \param now current time, ms
 201  * \param movement how many events to skip from the one currently displayed
 202  * +2 means "the one after the next", -1 means "previous"
 203  * \return timeshift, ms
 204  */
 205 long long ass_step_sub(ass_track_t* track, long long now, int movement);
 206
 207 #endif
 208