The face requester should not perform funny
things on the returned face object, like creating
a new
FT_Size
for it, or setting a transformation through
FT_Set_Transform
!
Retrieves the
FT_Face
object that corresponds to a given face ID
through a cache manager.
input
manager
A handle to the cache manager.
face_id
The ID of the face object.
output
aface
A handle to the face object.
return
FreeType error code. 0 means success.
note
The returned
FT_Face
object is always owned by the manager. You should
never try to discard it yourself.
The
FT_Face
object doesn't necessarily have a current size
object (i.e., face->size can be 0). If you need a
specific `font size', use
FTC_Manager_Lookup_Size
instead.
Never change the face's transformation matrix
(i.e., never call the
FT_Set_Transform
function) on a returned face! If you need to
transform glyphs, do it yourself after glyph
loading.
Retrieves the
FT_Face
and
FT_Size
objects that correspond to a given ?FTC_SizeID.
input
manager
A handle to the cache manager.
size_id
The ID of the `font size' to use.
output
aface
A pointer to the handle of the face object. Set
it to zero if you don't need it.
asize
A pointer to the handle of the size object. Set
it to zero if you don't need it.
return
FreeType error code. 0 means success.
note
The returned
FT_Face
object is always owned by the manager. You should
never try to discard it yourself.
Never change the face's transformation matrix
(i.e., never call the
FT_Set_Transform
function) on a returned face! If you need to
transform glyphs, do it yourself after glyph
loading.
Similarly, the returned
FT_Size
object is always owned by the manager. You should
never try to discard it, and never change its
settings with
FT_Set_Pixel_Sizes
or
FT_Set_Char_Size
!
The returned size object is the face's current
size, which means that you can call
FT_Load_Glyph
with the face if you need to.
An opaque handle to a cache node object. Each
cache node is reference-counted. A node with a
count of 0 might be flushed out of a full cache
whenever a lookup request is performed.
If you lookup nodes, you have the ability to
"acquire" them, i.e., to increment their
reference count. This will prevent the node from
being flushed out of the cache until you
explicitly "release" it (see ?FTC_Node_Release).
Retrieves a given glyph image from a glyph image
cache.
input
cache
A handle to the source glyph image cache.
desc
A pointer to a glyph image descriptor.
gindex
The glyph index to retrieve.
output
aglyph
The corresponding
FT_Glyph
object. 0 in case of failure.
anode
Used to return the address of of the
corresponding cache node after incrementing its
reference count (see note below).
return
FreeType error code. 0 means success.
note
The returned glyph is owned and managed by the
glyph image cache. Never try to transform or
discard it manually! You can however create a
copy with
FT_Glyph_Copy
and modify the new one.
If "anode" is _not_ NULL, it receives the address
of the cache node containing the glyph image,
after increasing its reference count. This
ensures that the node (as well as the FT_Glyph)
will always be kept in the cache until you call
FTC_Node_Unref
to "release" it.
If "anode" is NULL, the cache node is left
unchanged, which means that the FT_Glyph could be
flushed out of the cache on the next call to one
of the caching sub-system APIs. Don't assume that
it is persistent!
A handle to a small bitmap cache. These are
special cache objects used to store small glyph
bitmaps (and anti-aliased pixmaps) in a much more
efficient way than the traditional glyph image
cache implemented by
FTC_ImageCache
.
Looks up a given small glyph bitmap in a given
sbit cache and "lock" it to prevent its flushing
from the cache until needed
input
cache
A handle to the source sbit cache.
desc
A pointer to the glyph image descriptor.
gindex
The glyph index.
output
sbit
A handle to a small bitmap descriptor.
anode
Used to return the address of of the
corresponding cache node after incrementing its
reference count (see note below).
return
FreeType error code. 0 means success.
note
The small bitmap descriptor and its bit buffer
are owned by the cache and should never be freed
by the application. They might as well disappear
from memory on the next cache lookup, so don't
treat them as persistent data.
The descriptor's `buffer' field is set to 0 to
indicate a missing glyph bitmap.
If "anode" is _not_ NULL, it receives the address
of the cache node containing the bitmap, after
increasing its reference count. This ensures that
the node (as well as the image) will always be
kept in the cache until you call
FTC_Node_Unref
to "release" it.
If "anode" is NULL, the cache node is left
unchanged, which means that the bitmap could be
flushed out of the cache on the next call to one
of the caching sub-system APIs. Don't assume that
it is persistent!
The corresponding
FT_Glyph
object. 0 in case of failure.
return
FreeType error code. 0 means success.
note
The returned glyph is owned and managed by the
glyph image cache. Never try to transform or
discard it manually! You can however create a
copy with
FT_Glyph_Copy
and modify the new one.
Because the glyph image cache limits the total
amount of memory taken by the glyphs it holds,
the returned glyph might disappear on a later
invocation of this function! It is a cache after
all...
Use this function to "lock" the glyph as long as
it is needed.
Looks up a given small glyph bitmap in a given
sbit cache.
input
cache
A handle to the source sbit cache.
desc
A pointer to the glyph image descriptor.
gindex
The glyph index.
output
sbit
A handle to a small bitmap descriptor.
return
FreeType error code. 0 means success.
note
The small bitmap descriptor and its bit buffer
are owned by the cache and should never be freed
by the application. They might as well disappear
from memory on the next cache lookup, so don't
treat them as persistent data.
The descriptor's `buffer' field is set to 0 to
indicate a missing glyph bitmap.
A simple structure used to describe a given
`font' to the cache manager. Note that a `font'
is the combination of a given face with a given
character size.
This function is used to check the state of the
cache manager if its `num_bytes' field is greater
than its `max_bytes' field. It will flush as many
old cache nodes as possible (ignoring cache nodes
with a non-zero reference count).
inout
manager
A handle to the cache manager.
note
Client applications should not call this function
directly. It is normally invoked by specific
cache implementations.
The reason this function is exported is to allow
client-specific cache classes.
A very compact structure used to describe a small
glyph bitmap.
fields
width
The bitmap width in pixels.
height
The bitmap height in pixels.
left
The horizontal distance from the pen position to
the left bitmap border (a.k.a. `left side
bearing', or `lsb').
top
The vertical distance from the pen position (on
the baseline) to the upper bitmap border (a.k.a.
`top side bearing'). The distance is positive for
upwards Y coordinates.
format
The format of the glyph bitmap (monochrome or
gray).
num_grays
The number of gray levels.
pitch
The number of bytes per bitmap line. May be
positive or negative.