ufmGetExactOutline(3w)ufmGetExactOutline(3w)NAMEufmGetExactOutline - get exact outlines for specified characters
C SYNOPSIS
#include <ufm.h>
int ufmGetExactOutline(unsigned int nTypefaceHandles,
unsigned int *typefaceHandles, int charCodeType,
unsigned int nCharCodes, void *charCodes,
unsigned int *nOutlines, ufmExactOutline **outlines)
DESCRIPTIONufmGetExactOutline gets exact outlines for specified characters. You can
get a character outline only for those typefaces which have the flag
scalableMetrics set to 1 in their ufmTypeface data structures, that is,
for those typefaces for which outline font files were found.
nTypefaceHandles specifies the number of entries (typeface handles) in
the array typefaceHandles.
typefaceHandles is an array of handles for open typefaces. That array
must have nTypefaceHandles entries. Use the function ufmOpenTypeface to
open a typeface, and get a handle for that typeface.
If you specify more than one typeface handle, ufmGetExactOutline will
look for exact character outlines in the outline font files for specified
typefaces. If it does not find a requested character outline in the
outline font file for the first specified typeface, it will look for that
outline in the next outline font file. It will stop looking as soon as
it finds the requested character outline. If it cannot find that
outline, it will return the outline for the default character. If
ufmGetExactOutline cannot find the outline even for the default
character, it will return an error code.
charCodeType specifies a 1-byte character code (UFM_BYTE1), a Unicode
UCS-2 code (UFM_UCS2), a Unicode UCS-4 code (UFM_UCS4), a 2-byte
character code (UFM_BYTE2), or a 4-byte character code (UFM_BYTE4).
nCharCodes specifies the number of elements in the array charCodes. Set
nCharCodes to 0 if you want exact outlines for all characters in the
outline font for a specified typeface. If you want exact outlines for
only some characters, use the array charCodes to specify the codes of
those characters.
Getting all character outlines from a large font, such as a Japanese,
Chinese or Korean font, may take a long time. You may want to get just
the character outlines you need from such fonts.
ufmGetExactOutlines returns the number of character outlines it finds
(nOutlines), and the address of the array in which it stores those
outlines (outlines). That array has nOutlines entries.
Page 1
ufmGetExactOutline(3w)ufmGetExactOutline(3w)
When you are finished with the array (outlines), you can free it by
calling ufmFreeExactOutline.
A character outline is specified by specifying zero or more paths. A
data structure of the type ufmExactOutline contains zero or more paths.
For example, you get zero paths for the space character, and you get two
paths for the character O in an outline Helvetica font. One path is for
the inner circle, and one for the outer circle. The character O is drawn
by filling with some color the area between those two paths. A path that
is to be filled must be specified in a counterclockwise direction. A
path that is to be left unfilled must be specified in a clockwise
direction.
Exact character paths consist of directed line segments (vectors) and
curve segments. Approximations of character paths consist of only
directed line segments. Vector approximations of character paths are
much easier and faster to draw on Silicon Graphics machines than exact
character paths, but exact paths usually look better. Use the function
ufmGetVectorOutline to get vector approximations of character paths, and
use the function ufmGetExactOutline to get exact character paths.
Notice that the function ufmGetVectorOutline has an argument called
tolerance, but the function ufmGetExactOutline does not have that
argument. That argument is used to specify how closely to approximate
the exact outlines of a specified character. The value of that argument
would always be 0.0 for exact outlines, so that argument is not needed
for the function ufmGetExactOutline. The function ufmGetVectorOutline
does not accept those tolerance values which are less than or equal to
zero. It accepts only tolerance values greater than zero.
The field nPaths in a data structure of type ufmExactOutline specifies
the number of paths in an outline. The field nPoints specifies the
number of elements in the array points for each path. The field points
contains the x and y coordinates of points. The field nOperators
specifies the number of elements in the array operators for each path.
The field operators contains integer codes for the following four
operators: 1 (MOVE), 2 (LINE), 3 (CURVE) and 4 (CLOSE).
The operator MOVE requires one operand of the type ufmPoint (the x and y
coordinates of the new current point). A new path will be started at the
new current point. This operator does not add any segments to a path.
The operator LINE also requires one operand of the type ufmPoint (the x
and y coordinate of a point). That operator appends a straight line
segment to the current path. That line segment extends from the current
point to a specified point. When the line segment is appended, the
specified point becomes the new current point.
The operator CURVE requires three operands of the type ufmPoint (the
coordinates x1, y1, x2, y2, x3 and y3 of three points). That operator
appends a Bezier cubic section to the current path between the current
Page 2
ufmGetExactOutline(3w)ufmGetExactOutline(3w)
point at the coordinates [x0, y0] and the point at the coordinates [x3,
y3], using the points at the coordinates [x1, y1] and [x2, y2] as the
Bezier cubic control points. When the curve segment is appended, the new
current point is at the coordinates [x3, y3].
The operator CLOSE does not require any operands. It appends a straight
line segment to the current path. That line segment extends from the
current point to the path's first point.
ufmGetExactOutline returns unscaled character paths. Values of operands
(x and y coordinates of points) are specified in ems. Those values can
then be scaled to an appropriate size in points by using the formula:
scaled-value = scalable-value x point-size x resolution / 72.0
or to an appropriate size in pixels by using the formula:
scaled-value = scalable-value x pixel-size
The value 72.0 is a frequently-used approximation for 72.27 in those
calculations which involve point sizes. A point is defined as 1/72.27 of
an inch, so it would be more precise to divide by 72.27 than by 72.0 in
the formula shown above.
SEE ALSOufmFreeExactOutline(3w), ufmFreeVectorOutline(3w),
ufmGetVectorOutline(3w), ufmOpenTypeface(3w).
DIAGNOSTICS
If ufmGetExactOutline is not able to allocate the memory it needs, it
will return the value UFM_OUT_OF_MEMORY. If the values of one or more
arguments are not valid, ufmGetExactOutline will return the value
UFM_INVALID_VALUE. Else, it will return the value UFM_NO_ERROR.
UFM_OUT_OF_MEMORY, UFM_INVALID_VALUE and UFM_NO_ERROR are defined in the
header file <ufm.h>.
Page 3
