FreeType-2.1.10 API Reference
Scanline Converter
Synopsis
#FT_Raster
FT_Raster
#FT_Raster_RenderFunc
FT_Raster_RenderFunc
#FT_Span
FT_Span
#FT_Raster_Funcs
FT_Raster_Funcs
#FT_SpanFunc
FT_SpanFunc
#FT_Incremental
FT_Incremental
#FT_Raster_BitTest_Func
FT_Raster_BitTest_Func
#FT_Incremental_Metrics
FT_Incremental_Metrics
#FT_Raster_BitSet_Func
FT_Raster_BitSet_Func
#FT_Incremental_GetGlyphDataFunc
FT_Incremental_GetGlyphDataFunc
#FT_RASTER_FLAG_XXX
FT_RASTER_FLAG_XXX
#FT_Incremental_FreeGlyphDataFunc
FT_Incremental_FreeGlyphDataFunc
#FT_Raster_Params
FT_Raster_Params
#FT_Incremental_GetGlyphMetricsFunc
FT_Incremental_GetGlyphMetricsFunc
#FT_Raster_NewFunc
FT_Raster_NewFunc
#FT_Incremental_FuncsRec
FT_Incremental_FuncsRec
#FT_Raster_DoneFunc
FT_Raster_DoneFunc
#FT_Incremental_InterfaceRec
FT_Incremental_InterfaceRec
#FT_Raster_ResetFunc
FT_Raster_ResetFunc
#FT_PARAM_TAG_INCREMENTAL
FT_PARAM_TAG_INCREMENTAL
#FT_Raster_SetModeFunc
FT_Raster_SetModeFunc
This section contains technical definitions.
FT_Raster
typedef
struct
FT_RasterRec_*
FT_Raster
;
A handle (pointer) to a raster object. Each object can be used independently to convert an outline into a bitmap or pixmap.
FT_Span
typedef
struct
FT_Span_
{
short
x;
unsigned
short
len;
unsigned
char
coverage;
}
FT_Span
;
A structure used to model a single span of gray (or black) pixels when rendering a monochrome or anti-aliased bitmap.
fields
x
The span's horizontal start position.
len
The span's length in pixels.
coverage
The span color/coverage, ranging from 0 (background) to 255 (foreground). Only used for anti-aliased rendering.
note
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.
The coverage value is always between 0 and 255, even if the number of gray levels have been set through FT_Set_Gray_Levels().
FT_SpanFunc
typedef
void
(*
FT_SpanFunc
)(
int
y,
int
count,
ft2-raster.html#FT_Span
FT_Span
*  spans,
void
*     user );
#define FT_Raster_Span_Func
FT_SpanFunc
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.
FT_Raster_BitTest_Func
typedef
int
(*
FT_Raster_BitTest_Func
)(
int
y,
int
x,
void
*  user );
THIS TYPE IS DEPRECATED. DO NOT USE IT.
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.
return
1 if the pixel is `set', 0 otherwise.
FT_Raster_BitSet_Func
typedef
void
(*
FT_Raster_BitSet_Func
)(
int
y,
int
x,
void
*  user );
THIS TYPE IS DEPRECATED. DO NOT USE IT.
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.
return
1 if the pixel is `set', 0 otherwise.
FT_RASTER_FLAG_XXX
#define
ft2-raster.html#FT_RASTER_FLAG_XXX
FT_RASTER_FLAG_DEFAULT
0x0
#define
ft2-raster.html#FT_RASTER_FLAG_XXX
FT_RASTER_FLAG_AA
0x1
#define
ft2-raster.html#FT_RASTER_FLAG_XXX
FT_RASTER_FLAG_DIRECT
0x2
#define
ft2-raster.html#FT_RASTER_FLAG_XXX
FT_RASTER_FLAG_CLIP
0x4
/* deprecated */
#define ft_raster_flag_default
ft2-raster.html#FT_RASTER_FLAG_XXX
FT_RASTER_FLAG_DEFAULT
#define ft_raster_flag_aa
ft2-raster.html#FT_RASTER_FLAG_XXX
FT_RASTER_FLAG_AA
#define ft_raster_flag_direct
ft2-raster.html#FT_RASTER_FLAG_XXX
FT_RASTER_FLAG_DIRECT
#define ft_raster_flag_clip
ft2-raster.html#FT_RASTER_FLAG_XXX
FT_RASTER_FLAG_CLIP
A list of bit flag constants as used in the `flags' field of a
ft2-raster.html#FT_Raster_Params
FT_Raster_Params
structure.
values
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.
FT_Raster_Params
typedef
struct
FT_Raster_Params_
{
const
ft2-basic_types.html#FT_Bitmap
FT_Bitmap
*        target;
const
void
*             source;
int
flags;
ft2-raster.html#FT_SpanFunc
FT_SpanFunc
gray_spans;
ft2-raster.html#FT_SpanFunc
FT_SpanFunc
black_spans;
ft2-raster.html#FT_Raster_BitTest_Func
FT_Raster_BitTest_Func
bit_test;     /* doesn't work! */
ft2-raster.html#FT_Raster_BitSet_Func
FT_Raster_BitSet_Func
bit_set;      /* doesn't work! */
void
*                   user;
ft2-basic_types.html#FT_BBox
FT_BBox
clip_box;
}
FT_Raster_Params
;
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. UNIMPLEMENTED!
bit_set
The bit set callback. UNIMPLEMENTED!
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.
FT_Raster_NewFunc
typedef
int
(*
FT_Raster_NewFunc
)(
void
*       memory,
ft2-raster.html#FT_Raster
FT_Raster
*  raster );
#define  FT_Raster_New_Func
FT_Raster_NewFunc
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.
FT_Raster_DoneFunc
typedef
void
(*
FT_Raster_DoneFunc
)(
ft2-raster.html#FT_Raster
FT_Raster
raster );
#define  FT_Raster_Done_Func
FT_Raster_DoneFunc
A function used to destroy a given raster object.
input
raster
A handle to the raster object.
FT_Raster_ResetFunc
typedef
void
(*
FT_Raster_ResetFunc
)(
ft2-raster.html#FT_Raster
FT_Raster
raster,
unsigned
char
*  pool_base,
unsigned
long
pool_size );
#define  FT_Raster_Reset_Func
FT_Raster_ResetFunc
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.
FT_Raster_SetModeFunc
typedef
int
(*
FT_Raster_SetModeFunc
)(
ft2-raster.html#FT_Raster
FT_Raster
raster,
unsigned
long
mode,
void
*          args );
#define  FT_Raster_Set_Mode_Func
FT_Raster_SetModeFunc
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.
input
raster
A handle to the new raster object.
mode
A 4-byte tag used to name the mode or property.
args
A pointer to the new mode/property to use.
FT_Raster_RenderFunc
typedef
int
(*
FT_Raster_RenderFunc
)(
ft2-raster.html#FT_Raster
FT_Raster
raster,
ft2-raster.html#FT_Raster_Params
FT_Raster_Params
*  params );
#define  FT_Raster_Render_Func
FT_Raster_RenderFunc
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).
FT_Raster_Funcs
typedef
struct
FT_Raster_Funcs_
{
ft2-basic_types.html#FT_Glyph_Format
FT_Glyph_Format
glyph_format;
ft2-raster.html#FT_Raster_NewFunc
FT_Raster_NewFunc
raster_new;
ft2-raster.html#FT_Raster_ResetFunc
FT_Raster_ResetFunc
raster_reset;
ft2-raster.html#FT_Raster_SetModeFunc
FT_Raster_SetModeFunc
raster_set_mode;
ft2-raster.html#FT_Raster_RenderFunc
FT_Raster_RenderFunc
raster_render;
ft2-raster.html#FT_Raster_DoneFunc
FT_Raster_DoneFunc
raster_done;
}
FT_Raster_Funcs
;
A structure used to describe a given raster class to the library.
fields
glyph_format
The supported glyph format for this raster.
raster_new
The raster constructor.
raster_reset
Used to reset the render pool within the raster.
raster_render
A function to render a glyph into a given bitmap.
raster_done
The raster destructor.
FT_Incremental
typedef
struct
FT_IncrementalRec_*
FT_Incremental
;
An opaque type describing a user-provided object used to implement "incremental" glyph loading within FreeType. This is used to support embedded fonts in certain environments (e.g. Postscript interpreters), where the glyph data isn't in the font file, or must be overridden by different values.
note
It is up to client applications to create and implement
ft2-raster.html#FT_Incremental
FT_Incremental
objects, as long as they provide implementations for the methods
ft2-raster.html#FT_Incremental_GetGlyphDataFunc
FT_Incremental_GetGlyphDataFunc
,
ft2-raster.html#FT_Incremental_FreeGlyphDataFunc
FT_Incremental_FreeGlyphDataFunc
and
ft2-raster.html#FT_Incremental_GetGlyphMetricsFunc
FT_Incremental_GetGlyphMetricsFunc
.
See the description of
ft2-raster.html#FT_Incremental_InterfaceRec
FT_Incremental_InterfaceRec
to understand how to use incremental objects with FreeType.
FT_Incremental_Metrics
typedef
struct
FT_Incremental_MetricsRec_
{
ft2-basic_types.html#FT_Long
FT_Long
bearing_x;
ft2-basic_types.html#FT_Long
FT_Long
bearing_y;
ft2-basic_types.html#FT_Long
FT_Long
advance;
} FT_Incremental_MetricsRec, *
FT_Incremental_Metrics
;
A small structure used to contain the basic glyph metrics returned by the
ft2-raster.html#FT_Incremental_GetGlyphMetricsFunc
FT_Incremental_GetGlyphMetricsFunc
method.
fields
bearing_x
Left bearing, in font units.
bearing_y
Top bearing, in font units.
advance
Glyph advance, in font units.
note
These correspond to horizontal or vertical metrics depending on the value of the 'vertical' argument to the function
ft2-raster.html#FT_Incremental_GetGlyphMetricsFunc
FT_Incremental_GetGlyphMetricsFunc
.
FT_Incremental_GetGlyphDataFunc
typedef
ft2-basic_types.html#FT_Error
FT_Error
(*
FT_Incremental_GetGlyphDataFunc
)(
ft2-raster.html#FT_Incremental
FT_Incremental
incremental,
ft2-basic_types.html#FT_UInt
FT_UInt
glyph_index,
ft2-basic_types.html#FT_Data
FT_Data
*        adata );
A function called by FreeType to access a given glyph's data bytes during
ft2-base_interface.html#FT_Load_Glyph
FT_Load_Glyph
or
ft2-base_interface.html#FT_Load_Char
FT_Load_Char
if incremental loading is enabled.
Note that the format of the glyph's data bytes depends on the font file format. For TrueType, it must correspond to the raw bytes within the 'glyf' table. For Postscript formats, it must correspond to the
unencrypted
charstring bytes, without any 'lenIV' header. It is undefined for any other format.
input
incremental
Handle to an opaque
ft2-raster.html#FT_Incremental
FT_Incremental
handle provided by the client application.
glyph_index
Index of relevant glyph.
output
adata
A structure describing the returned glyph data bytes (which will be accessed as a read-only byte block).
return
FreeType error code. 0 means success.
note
If this function returns succesfully the method
ft2-raster.html#FT_Incremental_FreeGlyphDataFunc
FT_Incremental_FreeGlyphDataFunc
will be called later to release the data bytes.
Nested calls to
ft2-raster.html#FT_Incremental_GetGlyphDataFunc
FT_Incremental_GetGlyphDataFunc
can happen for compound glyphs.
FT_Incremental_FreeGlyphDataFunc
typedef
void
(*
FT_Incremental_FreeGlyphDataFunc
)(
ft2-raster.html#FT_Incremental
FT_Incremental
incremental,
ft2-basic_types.html#FT_Data
FT_Data
*        data );
A function used to release the glyph data bytes returned by a successful call to
ft2-raster.html#FT_Incremental_GetGlyphDataFunc
FT_Incremental_GetGlyphDataFunc
.
input
incremental
A handle to an opaque
ft2-raster.html#FT_Incremental
FT_Incremental
handle provided by the client application.
data
A structure describing the glyph data bytes (which will be accessed as a read-only byte block).
FT_Incremental_GetGlyphMetricsFunc
typedef
ft2-basic_types.html#FT_Error
FT_Error
(*
FT_Incremental_GetGlyphMetricsFunc
)
(
ft2-raster.html#FT_Incremental
FT_Incremental
incremental,
ft2-basic_types.html#FT_UInt
FT_UInt
glyph_index,
ft2-basic_types.html#FT_Bool
FT_Bool
vertical,
FT_Incremental_MetricsRec  *ametrics );
A function used to retrieve the basic metrics of a given glyph index before accessing its data. This is necessary because, in certain formats like TrueType, the metrics are stored in a different place from the glyph images proper.
input
incremental
A handle to an opaque
ft2-raster.html#FT_Incremental
FT_Incremental
handle provided by the client application.
glyph_index
Index of relevant glyph.
vertical
If true, return vertical metrics.
ametrics
This parameter is used for both input and output. The original glyph metrics, if any, in font units. If metrics are not available all the values must be set to zero.
output
ametrics
The replacement glyph metrics in font units.
FT_Incremental_FuncsRec
typedef
struct
FT_Incremental_FuncsRec_
{
ft2-raster.html#FT_Incremental_GetGlyphDataFunc
FT_Incremental_GetGlyphDataFunc
get_glyph_data;
ft2-raster.html#FT_Incremental_FreeGlyphDataFunc
FT_Incremental_FreeGlyphDataFunc
free_glyph_data;
ft2-raster.html#FT_Incremental_GetGlyphMetricsFunc
FT_Incremental_GetGlyphMetricsFunc
get_glyph_metrics;
}
FT_Incremental_FuncsRec
;
A table of functions for accessing fonts that load data incrementally. Used in
ft2-raster.html#FT_Incremental_InterfaceRec
FT_Incremental_InterfaceRec
.
fields
get_glyph_data
The function to get glyph data. Must not be null.
free_glyph_data
The function to release glyph data. Must not be null.
get_glyph_metrics
The function to get glyph metrics. May be null if the font does not provide overriding glyph metrics.
FT_Incremental_InterfaceRec
typedef
struct
FT_Incremental_InterfaceRec_
{
const
ft2-raster.html#FT_Incremental_FuncsRec
FT_Incremental_FuncsRec
*  funcs;
ft2-raster.html#FT_Incremental
FT_Incremental
object;
}
FT_Incremental_InterfaceRec
;
A structure to be used with
ft2-base_interface.html#FT_Open_Face
FT_Open_Face
to indicate that the user wants to support incremental glyph loading. You should use it with
ft2-raster.html#FT_PARAM_TAG_INCREMENTAL
FT_PARAM_TAG_INCREMENTAL
as in the following example:
FT_Incremental_InterfaceRec  inc_int;
FT_Parameter                 parameter;
FT_Open_Args                 open_args;
// set up incremental descriptor
inc_int.funcs  = my_funcs;
inc_int.object = my_object;
// set up optional parameter
parameter.tag  = FT_PARAM_TAG_INCREMENTAL;
parameter.data = &inc_int;
// set up FT_Open_Args structure
open_args.flags      = FT_OPEN_PATHNAME | FT_OPEN_PARAMS;
open_args.pathname   = my_font_pathname;
open_args.num_params = 1;
open_args.params     = &parameter; // we use one optional argument
// open the font
error = FT_Open_Face( library, &open_args, index, &face );
...
FT_PARAM_TAG_INCREMENTAL
#define
FT_PARAM_TAG_INCREMENTAL
ft2-basic_types.html#FT_MAKE_TAG
FT_MAKE_TAG
( 'i', 'n', 'c', 'r' )
A constant used as the tag of
ft2-base_interface.html#FT_Parameter
FT_Parameter
structures to indicate an incremental loading object to be used by FreeType.
