ufmGetVectorOutline(3w)
ufmGetVectorOutline - get vector outlines for specified characters
As shipped in IRIX 6.5.7. Unchanged since IRIX 6.5.
NAME ufmGetVectorOutline - 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) DESCRIPTION ufmGetVectorOutline 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. 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. 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 ALSO ufmFreeExactOutline(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>.