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