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