1 /****************************************************************************
2 *
3 * ftrender.h
4 *
5 * FreeType renderer modules public interface (specification).
6 *
7 * Copyright (C) 1996-2023 by
8 * David Turner, Robert Wilhelm, and Werner Lemberg.
9 *
10 * This file is part of the FreeType project, and may only be used,
11 * modified, and distributed under the terms of the FreeType project
12 * license, LICENSE.TXT. By continuing to use, modify, or distribute
13 * this file you indicate that you have read the license and
14 * understand and accept it fully.
15 *
16 */
17
18
19 #ifndef FTRENDER_H_
20 #define FTRENDER_H_
21
22
23 #include <freetype/ftmodapi.h>
24 #include <freetype/ftglyph.h>
25
26
27 FT_BEGIN_HEADER
28
29
30 /**************************************************************************
31 *
32 * @section:
33 * module_management
34 *
35 */
36
37
38 /* create a new glyph object */
39 typedef FT_Error
40 (*FT_Glyph_InitFunc)( FT_Glyph glyph,
41 FT_GlyphSlot slot );
42
43 /* destroys a given glyph object */
44 typedef void
45 (*FT_Glyph_DoneFunc)( FT_Glyph glyph );
46
47 typedef void
48 (*FT_Glyph_TransformFunc)( FT_Glyph glyph,
49 const FT_Matrix* matrix,
50 const FT_Vector* delta );
51
52 typedef void
53 (*FT_Glyph_GetBBoxFunc)( FT_Glyph glyph,
54 FT_BBox* abbox );
55
56 typedef FT_Error
57 (*FT_Glyph_CopyFunc)( FT_Glyph source,
58 FT_Glyph target );
59
60 typedef FT_Error
61 (*FT_Glyph_PrepareFunc)( FT_Glyph glyph,
62 FT_GlyphSlot slot );
63
64 /* deprecated */
65 #define FT_Glyph_Init_Func FT_Glyph_InitFunc
66 #define FT_Glyph_Done_Func FT_Glyph_DoneFunc
67 #define FT_Glyph_Transform_Func FT_Glyph_TransformFunc
68 #define FT_Glyph_BBox_Func FT_Glyph_GetBBoxFunc
69 #define FT_Glyph_Copy_Func FT_Glyph_CopyFunc
70 #define FT_Glyph_Prepare_Func FT_Glyph_PrepareFunc
71
72
73 struct FT_Glyph_Class_
74 {
75 FT_Long glyph_size;
76 FT_Glyph_Format glyph_format;
77
78 FT_Glyph_InitFunc glyph_init;
79 FT_Glyph_DoneFunc glyph_done;
80 FT_Glyph_CopyFunc glyph_copy;
81 FT_Glyph_TransformFunc glyph_transform;
82 FT_Glyph_GetBBoxFunc glyph_bbox;
83 FT_Glyph_PrepareFunc glyph_prepare;
84 };
85
86
87 typedef FT_Error
88 (*FT_Renderer_RenderFunc)( FT_Renderer renderer,
89 FT_GlyphSlot slot,
90 FT_Render_Mode mode,
91 const FT_Vector* origin );
92
93 typedef FT_Error
94 (*FT_Renderer_TransformFunc)( FT_Renderer renderer,
95 FT_GlyphSlot slot,
96 const FT_Matrix* matrix,
97 const FT_Vector* delta );
98
99
100 typedef void
101 (*FT_Renderer_GetCBoxFunc)( FT_Renderer renderer,
102 FT_GlyphSlot slot,
103 FT_BBox* cbox );
104
105
106 typedef FT_Error
107 (*FT_Renderer_SetModeFunc)( FT_Renderer renderer,
108 FT_ULong mode_tag,
109 FT_Pointer mode_ptr );
110
111 /* deprecated identifiers */
112 #define FTRenderer_render FT_Renderer_RenderFunc
113 #define FTRenderer_transform FT_Renderer_TransformFunc
114 #define FTRenderer_getCBox FT_Renderer_GetCBoxFunc
115 #define FTRenderer_setMode FT_Renderer_SetModeFunc
116
117
118 /**************************************************************************
119 *
120 * @struct:
121 * FT_Renderer_Class
122 *
123 * @description:
124 * The renderer module class descriptor.
125 *
126 * @fields:
127 * root ::
128 * The root @FT_Module_Class fields.
129 *
130 * glyph_format ::
131 * The glyph image format this renderer handles.
132 *
133 * render_glyph ::
134 * A method used to render the image that is in a given glyph slot into
135 * a bitmap.
136 *
137 * transform_glyph ::
138 * A method used to transform the image that is in a given glyph slot.
139 *
140 * get_glyph_cbox ::
141 * A method used to access the glyph's cbox.
142 *
143 * set_mode ::
144 * A method used to pass additional parameters.
145 *
146 * raster_class ::
147 * For @FT_GLYPH_FORMAT_OUTLINE renderers only. This is a pointer to
148 * its raster's class.
149 */
150 typedef struct FT_Renderer_Class_
151 {
152 FT_Module_Class root;
153
154 FT_Glyph_Format glyph_format;
155
156 FT_Renderer_RenderFunc render_glyph;
157 FT_Renderer_TransformFunc transform_glyph;
158 FT_Renderer_GetCBoxFunc get_glyph_cbox;
159 FT_Renderer_SetModeFunc set_mode;
160
161 const FT_Raster_Funcs* raster_class;
162
163 } FT_Renderer_Class;
164
165
166 /**************************************************************************
167 *
168 * @function:
169 * FT_Get_Renderer
170 *
171 * @description:
172 * Retrieve the current renderer for a given glyph format.
173 *
174 * @input:
175 * library ::
176 * A handle to the library object.
177 *
178 * format ::
179 * The glyph format.
180 *
181 * @return:
182 * A renderer handle. 0~if none found.
183 *
184 * @note:
185 * An error will be returned if a module already exists by that name, or
186 * if the module requires a version of FreeType that is too great.
187 *
188 * To add a new renderer, simply use @FT_Add_Module. To retrieve a
189 * renderer by its name, use @FT_Get_Module.
190 */
191 FT_EXPORT( FT_Renderer )
192 FT_Get_Renderer( FT_Library library,
193 FT_Glyph_Format format );
194
195
196 /**************************************************************************
197 *
198 * @function:
199 * FT_Set_Renderer
200 *
201 * @description:
202 * Set the current renderer to use, and set additional mode.
203 *
204 * @inout:
205 * library ::
206 * A handle to the library object.
207 *
208 * @input:
209 * renderer ::
210 * A handle to the renderer object.
211 *
212 * num_params ::
213 * The number of additional parameters.
214 *
215 * parameters ::
216 * Additional parameters.
217 *
218 * @return:
219 * FreeType error code. 0~means success.
220 *
221 * @note:
222 * In case of success, the renderer will be used to convert glyph images
223 * in the renderer's known format into bitmaps.
224 *
225 * This doesn't change the current renderer for other formats.
226 *
227 * Currently, no FreeType renderer module uses `parameters`; you should
228 * thus always pass `NULL` as the value.
229 */
230 FT_EXPORT( FT_Error )
231 FT_Set_Renderer( FT_Library library,
232 FT_Renderer renderer,
233 FT_UInt num_params,
234 FT_Parameter* parameters );
235
236 /* */
237
238
239 FT_END_HEADER
240
241 #endif /* FTRENDER_H_ */
242
243
244 /* END */