ufmGetVectorOutline(3w)ufmGetVectorOutline(3w)NAMEufmGetVectorOutline - get vector outlines for specified characters
C SYNOPSIS
#include <ufm.h>
int ufmGetVectorOutline(unsigned int nTypefaceHandles,
unsigned int *typefaceHandles, int charCodeType,
unsigned int nCharCodes, void *charCodes, float tolerance,
unsigned int *nOutlines, ufmVectorOutline **outlines)
DESCRIPTIONufmGetVectorOutline gets vector 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, ufmGetVectorOutline will
look for vector 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
ufmGetVectorOutline 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 vector outlines for all characters in the
outline font for a specified typeface. If you want vector 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.
tolerance specifies how closely vector outlines should approximate the
exact outlines of a specified character. The unit of measure for
tolerance is an em.
Page 1
ufmGetVectorOutline(3w)ufmGetVectorOutline(3w)
ufmGetVectorOutlines 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.
When you are finished with the array (outlines), you can free it by
calling ufmFreeVectorOutline.
If you set the number of character codes nCharCodes to 0,
ufmGetVectorOutline will return all available character outlines for the
specified typeface, and ignore the value of charCodes. Getting all
character outlines for a large typeface, such as a Japanese, Chinese or
Korean font, may take a long time. You may want to get just the
character outlines you need for such fonts.
A character outline is specified by specifying 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 computers than exact
character paths. Use the function ufmGetVectorOutline to get vector
approximations of character paths, and use the function
ufmGetExactOutline to get exact character paths.
You can specify a tolerance for the approximations of character paths by
using the argument tolerance in a call to the function
ufmGetVectorOutline. That tolerance is specified as a floating-point
number. The unit of measure for that number is an em. A good value for
that tolerance is 0.004 em. That means that the difference between the
approximate paths and exact paths must not exceed 0.004 of an em. The
value of 0.0 indicates no tolerance, that is, the exact paths.
ufmGetVectorOutline does not accept tolerances which are less than or
equal to 0.0. When the tolerance value is greater than 0.0, character
paths are approximated by vectors.
The data structure type ufmVectorOutline is defined in the header file
<ufm.h>. The field nPaths in a data structure of type ufmVectorOutline
specifies the number of paths in an outline. A path is constructed by
connecting specified points by line segments. The x and y coordinate is
specified for each point. The unit of measure is an em. The last point
in a path must be connected to the first point in that path.
Page 2
ufmGetVectorOutline(3w)ufmGetVectorOutline(3w)
The field nPoints in a data structure of type ufmVectorOutline specifies
the number of points in the array points for each path. The array points
contains the x and y coordinates of points.
ufmGetVectorOutline returns unscaled vector character outlines.
Coordinates of vertices in character outlines are specified in ems.
Those coordinates 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
They can be scaled 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.
When your program is finished with the array outlines, it should call the
function ufmFreeVectorOutline with a pointer to that outline. UFM will
then free the memory it allocated for that outline.
SEE ALSOufmFreeExactOutline(3w), ufmFreeVectorOutline(3w),
ufmGetExactOutline(3w), ufmOpenTypeface(3w).
DIAGNOSTICS
If ufmGetVectorOutline 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, ufmGetVectorOutline 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
