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 /**
  41  * \brief initialize the library
  42  * \return library handle or NULL if failed
  43  */
  44 ass_library_t* ass_library_init(void);
  45
  46 /**
  47  * \brief finalize the library
  48  * \param priv library handle
  49  */
  50 void ass_library_done(ass_library_t*);
  51
  52 /**
  53  * \brief set private font directory
  54  * It is used for saving embedded fonts and also in font lookup.
  55  */
  56 void ass_set_fonts_dir(ass_library_t* priv, const char* fonts_dir);
  57
  58 void ass_set_extract_fonts(ass_library_t* priv, int extract);
  59
  60 void ass_set_style_overrides(ass_library_t* priv, char** list);
  61
  62 /**
  63  * \brief initialize the renderer
  64  * \param priv library handle
  65  * \return renderer handle or NULL if failed
  66  */
  67 ass_renderer_t* ass_renderer_init(ass_library_t*);
  68
  69 /**
  70  * \brief finalize the renderer
  71  * \param priv renderer handle
  72  */
  73 void ass_renderer_done(ass_renderer_t* priv);
  74
  75 void ass_set_frame_size(ass_renderer_t* priv, int w, int h);
  76 void ass_set_margins(ass_renderer_t* priv, int t, int b, int l, int r);
  77 void ass_set_use_margins(ass_renderer_t* priv, int use);
  78 void ass_set_aspect_ratio(ass_renderer_t* priv, double ar);
  79 void ass_set_font_scale(ass_renderer_t* priv, double font_scale);
  80
  81 /**
  82  * \brief set font lookup defaults
  83  */
  84 int  ass_set_fonts(ass_renderer_t* priv, const char* default_font, const char* default_family);
  85
  86 /**
  87  * \brief render a frame, producing a list of ass_image_t
  88  * \param priv library
  89  * \param track subtitle track
  90  * \param now video timestamp in milliseconds
  91  */
  92 ass_image_t* ass_render_frame(ass_renderer_t *priv, ass_track_t* track, long long now, int* detect_change);
  93
  94
  95 // The following functions operate on track objects and do not need an ass_renderer //
  96
  97 /**
  98  * \brief allocate a new empty track object
  99  * \return pointer to empty track
 100  */
 101 ass_track_t* ass_new_track(ass_library_t*);
 102
 103 /**
 104  * \brief deallocate track and all its child objects (styles and events)
 105  * \param track track to deallocate
 106  */
 107 void ass_free_track(ass_track_t* track);
 108
 109 /**
 110  * \brief allocate new style
 111  * \param track track
 112  * \return newly allocated style id
 113  */
 114 int ass_alloc_style(ass_track_t* track);
 115
 116 /**
 117  * \brief allocate new event
 118  * \param track track
 119  * \return newly allocated event id
 120  */
 121 int ass_alloc_event(ass_track_t* track);
 122
 123 /**
 124  * \brief delete a style
 125  * \param track track
 126  * \param sid style id
 127  * Deallocates style data. Does not modify track->n_styles.
 128  */
 129 void ass_free_style(ass_track_t* track, int sid);
 130
 131 /**
 132  * \brief delete an event
 133  * \param track track
 134  * \param eid event id
 135  * Deallocates event data. Does not modify track->n_events.
 136  */
 137 void ass_free_event(ass_track_t* track, int eid);
 138
 139 /**
 140  * \brief Process Codec Private section of subtitle stream
 141  * \param track target track
 142  * \param data string to parse
 143  * \param size length of data
 144  */
 145 void ass_process_codec_private(ass_track_t* track, char *data, int size);
 146
 147 /**
 148  * \brief Process a chunk of subtitle stream data. In matroska, this containes exactly 1 event (or a commentary)
 149  * \param track track
 150  * \param data string to parse
 151  * \param size length of data
 152  * \param timecode starting time of the event (milliseconds)
 153  * \param duration duration of the event (milliseconds)
 154 */
 155 void ass_process_chunk(ass_track_t* track, char *data, int size, long long timecode, long long duration);
 156
 157 /**
 158  * \brief Read subtitles from file.
 159  * \param fname file name
 160  * \return newly allocated track
 161 */
 162 ass_track_t* ass_read_file(ass_library_t* library, char* fname, char* codepage);
 163
 164 /**
 165  * \brief Read subtitles from memory.
 166  * \param library libass library object
 167  * \param buf pointer to subtitles text
 168  * \param bufsize size of buffer
 169  * \param codepage recode buffer contents from given codepage
 170  * \return newly allocated track
 171 */
 172 ass_track_t* ass_read_memory(ass_library_t* library, char* buf, size_t bufsize, char* codepage);
 173 /**
 174  * \brief read styles from file into already initialized track
 175  * \return 0 on success
 176  */
 177 int ass_read_styles(ass_track_t* track, char* fname, char* codepage);
 178
 179 /**
 180  * \brief Add a memory font.
 181  * \param name attachment name
 182  * \param data binary font data
 183  * \param data_size data size
 184 */
 185 void ass_add_font(ass_library_t* library, char* name, char* data, int data_size);
 186
 187 /**
 188  * \brief Calculates timeshift from now to the start of some other subtitle event, depending on movement parameter
 189  * \param track subtitle track
 190  * \param now current time, ms
 191  * \param movement how many events to skip from the one currently displayed
 192  * +2 means "the one after the next", -1 means "previous"
 193  * \return timeshift, ms
 194  */
 195 long long ass_step_sub(ass_track_t* track, long long now, int movement);
 196
 197 #endif
 198