Subversion Repositories Kolibri OS

Rev

Go to most recent revision | Details | Last modification | View Log | RSS feed








































Rev Author Line No. Line
4349 Serge 1
2
"http://www.w3.org/TR/html4/loose.dtd">
3
4
5
6
FreeType-2.5.0 API Reference
7
32
33
34
 
35
[Index]
36
37
[TOC]
38

FreeType-2.5.0 API Reference

39
 
40

41
Scanline Converter
42
43

Synopsis

44
45
FT_RasterFT_RASTER_FLAG_XXXFT_Raster_SetModeFunc
46
FT_SpanFT_Raster_ParamsFT_Raster_RenderFunc
47
FT_SpanFuncFT_Raster_NewFuncFT_Raster_Funcs
48
FT_Raster_BitTest_FuncFT_Raster_DoneFunc
49
FT_Raster_BitSet_FuncFT_Raster_ResetFunc
50


51
 
52
53

This section contains technical definitions.

54

55
56

FT_Raster

57
58
Defined in FT_IMAGE_H (freetype/ftimage.h).
59

60
61
 
62
  typedef struct FT_RasterRec_*  FT_Raster;
63
 
64

65
66

A handle (pointer) to a raster object. Each object can be used independently to convert an outline into a bitmap or pixmap.

67

68
69

70
[Index]
71
72
[TOC]
73
 
74
75

FT_Span

76
77
Defined in FT_IMAGE_H (freetype/ftimage.h).
78

79
80
 
81
  typedef struct  FT_Span_
82
  {
83
    short           x;
84
    unsigned short  len;
85
    unsigned char   coverage;
86
 
87
  } FT_Span;
88
 
89

90
91

A structure used to model a single span of gray (or black) pixels when rendering a monochrome or anti-aliased bitmap.

92

93
fields
94

95
96
x
97

The span's horizontal start position.

98
99
len
100

The span's length in pixels.

101
102
coverage
103

The span color/coverage, ranging from 0 (background) to 255 (foreground). Only used for anti-aliased rendering.

104
105
106
107
note
108

This structure is used by the span drawing callback type named FT_SpanFunc which takes the y coordinate of the span as a a parameter.

109

The coverage value is always between 0 and 255. If you want less gray values, the callback function has to reduce them.

110
111
112

113
[Index]
114
115
[TOC]
116
 
117
118

FT_SpanFunc

119
120
Defined in FT_IMAGE_H (freetype/ftimage.h).
121

122
123
 
124
  typedef void
125
  (*FT_SpanFunc)( int             y,
126
                  int             count,
127
                  const FT_Span*  spans,
128
                  void*           user );
129
 
130
#define FT_Raster_Span_Func  FT_SpanFunc
131
 
132

133
134

A function used as a call-back by the anti-aliased renderer in order to let client applications draw themselves the gray pixel spans on each scan line.

135

136
input
137

138
139
y
140

The scanline's y coordinate.

141
142
count
143

The number of spans to draw on this scanline.

144
145
spans
146

A table of ‘count’ spans to draw on the scanline.

147
148
user
149

User-supplied data that is passed to the callback.

150
151
152
153
note
154

This callback allows client applications to directly render the gray spans of the anti-aliased bitmap to any kind of surfaces.

155

This can be used to write anti-aliased outlines directly to a given background bitmap, and even perform translucency.

156

Note that the ‘count’ field cannot be greater than a fixed value defined by the ‘FT_MAX_GRAY_SPANS’ configuration macro in ‘ftoption.h’. By default, this value is set to 32, which means that if there are more than 32 spans on a given scanline, the callback is called several times with the same ‘y’ parameter in order to draw all callbacks.

157

Otherwise, the callback is only called once per scan-line, and only for those scanlines that do have ‘gray’ pixels on them.

158
159
160

161
[Index]
162
163
[TOC]
164
 
165
166

FT_Raster_BitTest_Func

167
168
Defined in FT_IMAGE_H (freetype/ftimage.h).
169

170
171
 
172
  typedef int
173
  (*FT_Raster_BitTest_Func)( int    y,
174
                             int    x,
175
                             void*  user );
176
 
177

178
179

THIS TYPE IS DEPRECATED. DO NOT USE IT.

180

A function used as a call-back by the monochrome scan-converter to test whether a given target pixel is already set to the drawing ‘color’. These tests are crucial to implement drop-out control per-se the TrueType spec.

181

182
input
183

184
185
y
186

The pixel's y coordinate.

187
188
x
189

The pixel's x coordinate.

190
191
user
192

User-supplied data that is passed to the callback.

193
194
195
196
return
197

1 if the pixel is ‘set’, 0 otherwise.

198
199
200

201
[Index]
202
203
[TOC]
204
 
205
206

FT_Raster_BitSet_Func

207
208
Defined in FT_IMAGE_H (freetype/ftimage.h).
209

210
211
 
212
  typedef void
213
  (*FT_Raster_BitSet_Func)( int    y,
214
                            int    x,
215
                            void*  user );
216
 
217

218
219

THIS TYPE IS DEPRECATED. DO NOT USE IT.

220

A function used as a call-back by the monochrome scan-converter to set an individual target pixel. This is crucial to implement drop-out control according to the TrueType specification.

221

222
input
223

224
225
y
226

The pixel's y coordinate.

227
228
x
229

The pixel's x coordinate.

230
231
user
232

User-supplied data that is passed to the callback.

233
234
235
236
return
237

1 if the pixel is ‘set’, 0 otherwise.

238
239
240

241
[Index]
242
243
[TOC]
244
 
245
246

FT_RASTER_FLAG_XXX

247
248
Defined in FT_IMAGE_H (freetype/ftimage.h).
249

250
251
 
252
#define FT_RASTER_FLAG_DEFAULT  0x0
253
#define FT_RASTER_FLAG_AA       0x1
254
#define FT_RASTER_FLAG_DIRECT   0x2
255
#define FT_RASTER_FLAG_CLIP     0x4
256
 
257
  /* deprecated */
258
#define ft_raster_flag_default  FT_RASTER_FLAG_DEFAULT
259
#define ft_raster_flag_aa       FT_RASTER_FLAG_AA
260
#define ft_raster_flag_direct   FT_RASTER_FLAG_DIRECT
261
#define ft_raster_flag_clip     FT_RASTER_FLAG_CLIP
262
 
263

264
265

A list of bit flag constants as used in the ‘flags’ field of a FT_Raster_Params structure.

266

267
values
268

269
270
FT_RASTER_FLAG_DEFAULT
271

This value is 0.

272
273
FT_RASTER_FLAG_AA
274

This flag is set to indicate that an anti-aliased glyph image should be generated. Otherwise, it will be monochrome (1-bit).

275
276
FT_RASTER_FLAG_DIRECT
277

This flag is set to indicate direct rendering. In this mode, client applications must provide their own span callback. This lets them directly draw or compose over an existing bitmap. If this bit is not set, the target pixmap's buffer must be zeroed before rendering.

278

Note that for now, direct rendering is only possible with anti-aliased glyphs.

279
280
FT_RASTER_FLAG_CLIP
281

This flag is only used in direct rendering mode. If set, the output will be clipped to a box specified in the ‘clip_box’ field of the FT_Raster_Params structure.

282

Note that by default, the glyph bitmap is clipped to the target pixmap, except in direct rendering mode where all spans are generated if no clipping box is set.

283
284
285
286
287

288
[Index]
289
290
[TOC]
291
 
292
293

FT_Raster_Params

294
295
Defined in FT_IMAGE_H (freetype/ftimage.h).
296

297
298
 
299
  typedef struct  FT_Raster_Params_
300
  {
301
    const FT_Bitmap*        target;
302
    const void*             source;
303
    int                     flags;
304
    FT_SpanFunc             gray_spans;
305
    FT_SpanFunc             black_spans;  /* doesn't work! */
306
    FT_Raster_BitTest_Func  bit_test;     /* doesn't work! */
307
    FT_Raster_BitSet_Func   bit_set;      /* doesn't work! */
308
    void*                   user;
309
    FT_BBox                 clip_box;
310
 
311
  } FT_Raster_Params;
312
 
313

314
315

A structure to hold the arguments used by a raster's render function.

316

317
fields
318

319
320
target
321

The target bitmap.

322
323
source
324

A pointer to the source glyph image (e.g., an FT_Outline).

325
326
flags
327

The rendering flags.

328
329
gray_spans
330

The gray span drawing callback.

331
332
black_spans
333

The black span drawing callback. UNIMPLEMENTED!

334
335
bit_test
336

The bit test callback. UNIMPLEMENTED!

337
338
bit_set
339

The bit set callback. UNIMPLEMENTED!

340
341
user
342

User-supplied data that is passed to each drawing callback.

343
344
clip_box
345

An optional clipping box. It is only used in direct rendering mode. Note that coordinates here should be expressed in integer pixels (and not in 26.6 fixed-point units).

346
347
348
349
note
350

An anti-aliased glyph bitmap is drawn if the FT_RASTER_FLAG_AA bit flag is set in the ‘flags’ field, otherwise a monochrome bitmap is generated.

351

If the FT_RASTER_FLAG_DIRECT bit flag is set in ‘flags’, the raster will call the ‘gray_spans’ callback to draw gray pixel spans, in the case of an aa glyph bitmap, it will call ‘black_spans’, and ‘bit_test’ and ‘bit_set’ in the case of a monochrome bitmap. This allows direct composition over a pre-existing bitmap through user-provided callbacks to perform the span drawing/composition.

352

Note that the ‘bit_test’ and ‘bit_set’ callbacks are required when rendering a monochrome bitmap, as they are crucial to implement correct drop-out control as defined in the TrueType specification.

353
354
355

356
[Index]
357
358
[TOC]
359
 
360
361

FT_Raster_NewFunc

362
363
Defined in FT_IMAGE_H (freetype/ftimage.h).
364

365
366
 
367
  typedef int
368
  (*FT_Raster_NewFunc)( void*       memory,
369
                        FT_Raster*  raster );
370
 
371
#define FT_Raster_New_Func  FT_Raster_NewFunc
372
 
373

374
375

A function used to create a new raster object.

376

377
input
378

379
380
memory
381

A handle to the memory allocator.

382
383
384
385
output
386

387
388
raster
389

A handle to the new raster object.

390
391
392
393
return
394

Error code. 0 means success.

395
396
note
397

The ‘memory’ parameter is a typeless pointer in order to avoid un-wanted dependencies on the rest of the FreeType code. In practice, it is an FT_Memory object, i.e., a handle to the standard FreeType memory allocator. However, this field can be completely ignored by a given raster implementation.

398
399
400

401
[Index]
402
403
[TOC]
404
 
405
406

FT_Raster_DoneFunc

407
408
Defined in FT_IMAGE_H (freetype/ftimage.h).
409

410
411
 
412
  typedef void
413
  (*FT_Raster_DoneFunc)( FT_Raster  raster );
414
 
415
#define FT_Raster_Done_Func  FT_Raster_DoneFunc
416
 
417

418
419

A function used to destroy a given raster object.

420

421
input
422

423
424
raster
425

A handle to the raster object.

426
427
428
429
430

431
[Index]
432
433
[TOC]
434
 
435
436

FT_Raster_ResetFunc

437
438
Defined in FT_IMAGE_H (freetype/ftimage.h).
439

440
441
 
442
  typedef void
443
  (*FT_Raster_ResetFunc)( FT_Raster       raster,
444
                          unsigned char*  pool_base,
445
                          unsigned long   pool_size );
446
 
447
#define FT_Raster_Reset_Func  FT_Raster_ResetFunc
448
 
449

450
451

FreeType provides an area of memory called the ‘render pool’, available to all registered rasters. This pool can be freely used during a given scan-conversion but is shared by all rasters. Its content is thus transient.

452

This function is called each time the render pool changes, or just after a new raster object is created.

453

454
input
455

456
457
raster
458

A handle to the new raster object.

459
460
pool_base
461

The address in memory of the render pool.

462
463
pool_size
464

The size in bytes of the render pool.

465
466
467
468
note
469

Rasters can ignore the render pool and rely on dynamic memory allocation if they want to (a handle to the memory allocator is passed to the raster constructor). However, this is not recommended for efficiency purposes.

470
471
472

473
[Index]
474
475
[TOC]
476
 
477
478

FT_Raster_SetModeFunc

479
480
Defined in FT_IMAGE_H (freetype/ftimage.h).
481

482
483
 
484
  typedef int
485
  (*FT_Raster_SetModeFunc)( FT_Raster      raster,
486
                            unsigned long  mode,
487
                            void*          args );
488
 
489
#define FT_Raster_Set_Mode_Func  FT_Raster_SetModeFunc
490
 
491

492
493

This function is a generic facility to change modes or attributes in a given raster. This can be used for debugging purposes, or simply to allow implementation-specific ‘features’ in a given raster module.

494

495
input
496

497
498
raster
499

A handle to the new raster object.

500
501
mode
502

A 4-byte tag used to name the mode or property.

503
504
args
505

A pointer to the new mode/property to use.

506
507
508
509
510

511
[Index]
512
513
[TOC]
514
 
515
516

FT_Raster_RenderFunc

517
518
Defined in FT_IMAGE_H (freetype/ftimage.h).
519

520
521
 
522
  typedef int
523
  (*FT_Raster_RenderFunc)( FT_Raster                raster,
524
                           const FT_Raster_Params*  params );
525
 
526
#define FT_Raster_Render_Func  FT_Raster_RenderFunc
527
 
528

529
530

Invoke a given raster to scan-convert a given glyph image into a target bitmap.

531

532
input
533

534
535
raster
536

A handle to the raster object.

537
538
params
539

A pointer to an FT_Raster_Params structure used to store the rendering parameters.

540
541
542
543
return
544

Error code. 0 means success.

545
546
note
547

The exact format of the source image depends on the raster's glyph format defined in its FT_Raster_Funcs structure. It can be an FT_Outline or anything else in order to support a large array of glyph formats.

548

Note also that the render function can fail and return a ‘FT_Err_Unimplemented_Feature’ error code if the raster used does not support direct composition.

549

XXX: For now, the standard raster doesn't support direct composition but this should change for the final release (see the files ‘demos/src/ftgrays.c’ and ‘demos/src/ftgrays2.c’ for examples of distinct implementations which support direct composition).

550
551
552

553
[Index]
554
555
[TOC]
556
 
557
558

FT_Raster_Funcs

559
560
Defined in FT_IMAGE_H (freetype/ftimage.h).
561

562
563
 
564
  typedef struct  FT_Raster_Funcs_
565
  {
566
    FT_Glyph_Format        glyph_format;
567
    FT_Raster_NewFunc      raster_new;
568
    FT_Raster_ResetFunc    raster_reset;
569
    FT_Raster_SetModeFunc  raster_set_mode;
570
    FT_Raster_RenderFunc   raster_render;
571
    FT_Raster_DoneFunc     raster_done;
572
 
573
  } FT_Raster_Funcs;
574
 
575

576
577

A structure used to describe a given raster class to the library.

578

579
fields
580

581
582
glyph_format
583

The supported glyph format for this raster.

584
585
raster_new
586

The raster constructor.

587
588
raster_reset
589

Used to reset the render pool within the raster.

590
591
raster_render
592

A function to render a glyph into a given bitmap.

593
594
raster_done
595

The raster destructor.

596
597
598
599
600

601
[Index]
602
603
[TOC]
604
 
605
606