typedef void
(*FT_Raster_Span_Func)( int y,
int count,
FT_Span* spans,
void* user );
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.
input
y
The scanline's y-coordinate.
count
The number of spans to draw on this scanline.
spans
A table of `count' spans to draw on the scanline.
user
User-supplied data that is passed to the
callback.
note
This callback allows client applications to
directly render the gray spans of the
anti-aliased bitmap to any kind of surfaces.
This can be used to write anti-aliased outlines
directly to a given background bitmap, and even
perform translucency.
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 will be called
several times with the same `y' parameter in
order to draw all callbacks.
Otherwise, the callback is only called once per
scan-line, and only for those scanlines that do
have `gray' pixels on them.
typedef int
(*FT_Raster_BitTest_Func)( int y,
int x,
void* user );
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.
input
y
The pixel's y-coordinate.
x
The pixel's x-coordinate.
user
User-supplied data that is passed to the
callback.
typedef void
(*FT_Raster_BitSet_Func)( int y,
int x,
void* user );
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.
input
y
The pixel's y-coordinate.
x
The pixel's x-coordinate.
user
User-supplied data that is passed to the
callback.
An enumeration to list the bit flags as used in
the `flags' field of a FT_Raster_Params
structure.
fields
ft_raster_flag_default
This value is 0.
ft_raster_flag_aa
This flag is set to indicate that an anti-aliased
glyph image should be generated. Otherwise, it
will be monochrome (1-bit)
ft_raster_flag_direct
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.
Note that for now, direct rendering is only
possible with anti-aliased glyphs.
ft_raster_flag_clip
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.
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.
A structure to hold the arguments used by a
raster's render function.
fields
target
The target bitmap.
source
A pointer to the source glyph image (e.g. an
FT_Outline).
flags
The rendering flags.
gray_spans
The gray span drawing callback.
black_spans
The black span drawing callback.
bit_test
The bit test callback.
bit_set
The bit set callback.
user
User-supplied data that is passed to each drawing
callback.
clip_box
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).
note
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 will be
generated.
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.
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.
typedef int
(*FT_Raster_New_Func)( void* memory,
FT_Raster* raster );
A function used to create a new raster object.
input
memory
A handle to the memory allocator.
output
raster
A handle to the new raster object.
return
Error code. 0 means success.
note
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 a
FT_Memory, i.e., a handle to the standard
FreeType memory allocator. However, this field
can be completely ignored by a given raster
implementation.
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.
This function is called each time the render pool
changes, or just after a new raster object is
created.
input
raster
A handle to the new raster object.
pool_base
The address in memory of the render pool.
pool_size
The size in bytes of the render pool.
note
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.
typedef int
(*FT_Raster_Set_Mode_Func)( FT_Raster raster,
unsigned long mode,
void* args );
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.
typedef int
(*FT_Raster_Render_Func)( FT_Raster raster,
FT_Raster_Params* params );
Invokes a given raster to scan-convert a given
glyph image into a target bitmap.
input
raster
A handle to the raster object.
params
A pointer to a FT_Raster_Params structure used to
store the rendering parameters.
return
Error code. 0 means success.
note
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.
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.
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).