src/filters/transform/vsfilter/csri.h

   1 /*****************************************************************************
   2  * csri: common subtitle renderer interface
   3  *****************************************************************************
   4  * Copyright (C) 2007  David Lamparter
   5  * All rights reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions
   9  * are met:
  10  *
  11  *  - Redistributions of source code must retain the above copyright
  12  *    notice, this list of conditions and the following disclaimer.
  13  *  - Redistributions in binary form must reproduce the above copyright
  14  *    notice, this list of conditions and the following disclaimer in the
  15  *    documentation and/or other materials provided with the distribution.
  16  *  - The name of the author may not be used to endorse or promote products
  17  *    derived from this software without specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  20  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  21  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  22  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  23  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  24  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  28  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE
  29  ****************************************************************************/
  30
  31 /** \file csri.h - main CSRI (common subtitle renderer interface) include.
  32  * $Id: csri.h 45 2007-06-20 01:00:40Z equinox $ */
  33
  34 #ifndef _CSRI_H
  35 /** \cond */
  36 #define _CSRI_H 20070119
  37 /** \endcond */
  38
  39 #include <stddef.h>                     /* ptrdiff_t */
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 #ifndef CSRIAPI
  46 /** CSRI API attributes.
  47  * defaults to \c extern.
  48  */
  49 #define CSRIAPI extern
  50 #endif
  51
  52 /** \defgroup base CSRI base API. */
  53 /*@{*/
  54
  55 /** pixel format specification for frames */
  56 enum csri_pixfmt {
  57         CSRI_F_RGBA = 0,
  58         CSRI_F_ARGB,
  59         CSRI_F_BGRA,
  60         CSRI_F_ABGR,
  61
  62         CSRI_F_RGB_ = 0x100,
  63         CSRI_F__RGB,
  64         CSRI_F_BGR_,                    /**< Windows "RGB32" */
  65         CSRI_F__BGR,
  66
  67         CSRI_F_RGB  = 0x200,
  68         CSRI_F_BGR,                     /**< Windows "RGB24" */
  69
  70         CSRI_F_AYUV = 0x1000,
  71         CSRI_F_YUVA,
  72         CSRI_F_YVUA,
  73
  74         CSRI_F_YUY2 = 0x1100,
  75
  76         CSRI_F_YV12A = 0x2011,          /**< planar YUV 2x2 + alpha plane */
  77         CSRI_F_YV12 = 0x2111            /**< planar YUV 2x2 */
  78 };
  79
  80 #define csri_is_rgb(x) ((x) < 0x1000)
  81 #define csri_is_yuv(x) ((x) >= 0x1000)
  82 #define csri_is_yuv_planar(x) ((x) >= 0x2000)
  83 #define csri_get_yuv_planar_xred(x) (0xf & (x))
  84 #define csri_get_yuv_planar_yred(x) (0xf & ((x) >> 4))
  85 #define csri_is_yuv_packed(x) ((x) >= 0x1000 && (x) < 0x2000)
  86 #define csri_has_alpha(x) (((x) & 0xfff) < 0x100)
  87
  88 /** frame/image format specification pre-fed to the renderer */
  89 struct csri_fmt {
  90         /** format to be used */
  91         enum csri_pixfmt pixfmt;
  92         /** image width, full frame.
  93          *
  94          * This should specify the full size of the frame.
  95          * Specifying the video sub-size (in case of added black
  96          * borders) is left to an extension.
  97          */
  98         unsigned width;
  99         /** image height */
 100         unsigned height;
 101 };
 102
 103 /** single frame to be fed to the renderer. */
 104 struct csri_frame {
 105         /** frame format.
 106          * It is an application bug if this differs from the one
 107          * passed in struct #csri_fmt to csri_query_fmt()
 108          */
 109         enum csri_pixfmt pixfmt;
 110         /** the frame's data.
 111          * Packed formats only use planes[0]; planar formats
 112          * have the data ordered as Y, U, V[, A].
 113          *
 114          * Also note that the topmost line always comes first.
 115          * The Windows biHeight strange-ity is \a NOT duplicated.
 116          */
 117         unsigned char *planes[4];
 118         /** strides for the individual planes.
 119          * Stride means full byte offset, i.e. do \a not add
 120          * frame width
 121          */
 122         ptrdiff_t strides[4];
 123 };
 124
 125 #ifndef CSRI_OWN_HANDLES
 126 /** opaque renderer data */
 127 typedef void csri_rend;
 128 /** opaque instance data */
 129 typedef void csri_inst;
 130 #endif
 131
 132 #ifdef DOXYGEN
 133 /** disable the emission of the csri_rend and csri_inst typedefs.
 134  * define this if you are in a renderer and are typedef'ing
 135  * csri_rend and csri_inst to your own structs.
 136  */
 137 #define CSRI_OWN_HANDLES
 138 #endif
 139
 140 /** renderer description.
 141  * \ingroup loader
 142  */
 143 struct csri_info {
 144         /** an identifier for the renderer.
 145          * - MUST match the regular expression
 146          *   \code ^[a-zA-Z]([a-zA-Z0-9_]*[a-zA-Z0-9])? \endcode
 147          *   i.e. consists only of letters, numbers and underscores;
 148          *   must start with a letter and doesnt have an underscore
 149          *   as the last character.
 150          */
 151         const char *name;
 152         /** an identifier to the exact version of the renderer.
 153          * most likely a version number or revision identifier.
 154          *
 155          * The helper library does a strcmp over this field in order
 156          * to order multiple instances of the same renderer. Use
 157          * higher-byte-value strings for newer renderers.
 158          */
 159         const char *specific;
 160
 161         /** a nice name to be presented to the user */
 162         const char *longname;
 163         /** the renderer's author */
 164         const char *author;
 165         /** a copyright string. Copyright (c) 2042 by Mr. Nice Guy */
 166         const char *copyright;
 167 };
 168
 169 /** data of extension-dependent type.
 170  * The field to be used MUST be specified in the extension where it is used.
 171  */
 172 union csri_vardata {
 173         long lval;
 174         double dval;
 175         const char *utf8val;
 176         void *otherval;
 177 };
 178
 179 /** extension identifier.
 180  * This follows reverse DNS syntax, i.e.:
 181  * \code root.branch.leaf \endcode
 182  * you can either reverse a registered domain name, e.g.
 183  * \code com.microsoft.csri.usegdiplus \endcode
 184  * or ask the CSRI maintainers to assign a namespace to you.
 185  *
 186  * currently registered namespaces are:
 187  *
 188  * \code
 189  * csri.* - official extensions
 190  * asa.*  - custom extensions of the asa renderer
 191  * \endcode
 192  */
 193 typedef const char *csri_ext_id;
 194
 195 /** script loading parameters.
 196  * each flag MUST have an associated extension, which can be queried
 197  * with csri_query_ext(). If the open flag constitutes an extension on its
 198  * sole own, csri_query_ext() can return a meaningless non-NULL value for
 199  * it.
 200  *
 201  * The data field used must be specified.
 202  *
 203  * An extension can have multiple flags. In that case, the flags should have
 204  * the extension name as common prefix, separated with a dot.
 205  *
 206  * A renderer MUST ignore unknown open flags. It MUST NOT return an error
 207  * just because it does not support a particular flag.
 208  */
 209 struct csri_openflag {
 210         /** flag name */
 211         csri_ext_id name;
 212         /** flag data argument */
 213         union csri_vardata data;
 214         /** link to next flag */
 215         struct csri_openflag *next;
 216 };
 217
 218 /** load a script from a file.
 219  * \param renderer the handle to the renderer
 220  * \param filename the path to the file to be loaded. \n
 221  *   The filename should be encoded as UTF-8. Windows renderers are
 222  *   expected to convert it to UTF-16 and use the Unicode Windows API
 223  *   functions.
 224  * \param flags a linked list of open flags. \n
 225  *   The caller manages memory allocation, i.e. static allocation is OK.
 226  * \return the renderer instance handle, or NULL on error.
 227  */
 228 CSRIAPI csri_inst *csri_open_file(csri_rend *renderer,
 229         const char *filename, struct csri_openflag *flags);
 230
 231 /** load a script from memory.
 232  * \param renderer the handle to the renderer
 233  * \param data pointer to the first data byte. \n
 234  *   The caller manages memory allocation and should free the data after
 235  *   calling csri_open_mem(). If the renderer needs to keep the data, it
 236  *   must copy it. \n
 237  *   The renderer is not allowed to write to the data.
 238  * \param length length, in bytes, of the data
 239  * \param flags see csri_open_file()
 240  * \return the render instance handle, or NULL on error.
 241  */
 242
 243 CSRIAPI csri_inst *csri_open_mem(csri_rend *renderer,
 244         const void *data, size_t length, struct csri_openflag *flags);
 245
 246 /** close a renderer instance.
 247  * \param inst the instance handle.
 248  */
 249 CSRIAPI void csri_close(csri_inst *inst);
 250
 251
 252 /** query / set the image format and size.
 253  * \param inst the renderer instance handle
 254  * \param fmt the format and image size to be used
 255  * \return 0 if the format was successfully set,
 256  *   any other value in case of error.
 257  */
 258 CSRIAPI int csri_request_fmt(csri_inst *inst, const struct csri_fmt *fmt);
 259
 260 /** render a single frame
 261  * \param inst the renderer instance handle
 262  * \param frame frame data to render to
 263  * \param time associated timestamp of the frame
 264  */
 265 CSRIAPI void csri_render(csri_inst *inst, struct csri_frame *frame,
 266         double time);
 267
 268
 269 /** query for an extension.
 270  * \param rend the renderer handle
 271  * \param extname the extension's identifier
 272  * \return NULL if the extension is not supported,
 273  *   a pointer to extension-specific data otherwise
 274  *
 275  * The data pointed to by the return value does not neccessarily need to
 276  * have any meaning; An extension that does not need to return data
 277  * can return a pointer to whatever it wants, as long as that pointer is
 278  * not NULL.
 279  *
 280  * In the usual case, the pointer is supposed to point to a struct with
 281  * function pointers and other information as needed.
 282  */
 283 CSRIAPI void *csri_query_ext(csri_rend *rend, csri_ext_id extname);
 284
 285 /*@}*/
 286
 287 /** \defgroup loader CSRI loader API.
 288  *
 289  * These functions locate renderers based on given parameters.
 290  *
 291  * <b>Renderers must implement these functions as well.</b>
 292  *
 293  * They are used by the library to grab renderer information
 294  * from a shared object; and also this way a single renderer
 295  * can be linked directly into an appliaction.
 296  */
 297 /*@{*/
 298
 299 /** get renderer information
 300  * \param rend the renderer handle
 301  * \return information about the renderer, or NULL in case the renderer
 302  *   encountered an internal error.
 303  */
 304 CSRIAPI struct csri_info *csri_renderer_info(csri_rend *rend);
 305
 306 /** try to load a given renderer
 307  * \param name the name of the renderer, as in csri_info.name
 308  * \param specific the specific version of the renderer,
 309  *   as in csri_info.specific;\n
 310  *   alternatively NULL if any version of the renderer is ok.
 311  * \return a handle to the renderer if it was successfully loaded,
 312  *   NULL otherwise.
 313  */
 314 CSRIAPI csri_rend *csri_renderer_byname(const char *name,
 315         const char *specific);
 316
 317 /** try to find an implementation of the given extensions.
 318  * \param next number of extensions pointed to by ext
 319  * \param ext array of extensions to search for
 320  * \return a handle to a renderer supporting ALL of the
 321  *   extensions, NULL if none was found.
 322  */
 323 CSRIAPI csri_rend *csri_renderer_byext(unsigned n_ext, csri_ext_id *ext);
 324
 325 /** get the default (highest priority) renderer
 326  * \return a handle to the default renderer, or NULL if
 327  *   no renderer is installed.
 328  *
 329  * Together with csri_renderer_next(), this can be used
 330  * to enumerate all installed renderers.
 331  */
 332 CSRIAPI csri_rend *csri_renderer_default();
 333
 334 /** get the next lower priority renderer
 335  * \param prev the current renderer
 336  * \return the renderer with the next lower priority than
 337  *   the one named in prev, or NULL if prev is the last
 338  *   renderer installed.
 339  */
 340 CSRIAPI csri_rend *csri_renderer_next(csri_rend *prev);
 341
 342 /*@}*/
 343
 344 #ifdef __cplusplus
 345 }
 346 #endif
 347
 348 #endif /* _CSRI_H */