ufmGetCharMetricsByName(3w)ufmGetCharMetricsByName(3w)NAMEufmGetCharMetricsByName - get character metrics by name or CID code
C SYNOPSIS
#include <ufm.h>
int ufmGetCharMetricsByName(unsigned int nTypefaceHandles,
unsigned int *typefaceHandles, unsigned int nCharNames,
char **charNames, unsigned int *nCharMetrics,
ufmCharMetrics **charMetrics)
DESCRIPTIONufmGetCharMetricsByName gets the scalable metrics for specified character
names or CID codes (character id codes for CID-keyed fonts) from font
metric files. You can get scalable character metrics only for those
typefaces which have the flag scalableMetrics set to 1 in their
ufmTypeface data structures, that is, for those typefaces for which font
metric 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, ufmGetCharMetricsByName
will find the font metric files for specified typefaces. Then it will
look for the scalable metrics data for a specified character in the font
metric file for the first specified typeface. If it does not find that
data in that file, it will look for that data in the next font metrics
file. It will stop looking as soon as it finds the requested character
metrics data. If it cannot find that data for a specified character, it
will return the metrics data for the default character. If
ufmGetCharMetricsByName cannot find the metrics data 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 character metrics data for all characters in
a specified typeface. If you want character metrics data for only some
characters, use the array charNames to specify the names or CID codes of
those characters.
ufmGetCharMetricsByName stores the character metrics data it finds into
an array of data structures of the type (ufmCharMetrics). Then it
returns the number of entries (nCharMetrics) in that array and the
address of that array (charMetrics).
Page 1
ufmGetCharMetricsByName(3w)ufmGetCharMetricsByName(3w)
When you are finished with the array (charMetrics), you can free it by
calling ufmFreeCharMetrics with the argument values that were returned by
ufmGetCharMetricsByName.
All scalable metrics values provided by ufmGetCharMetricsByName are
specified in ems. You can scale such values to an appropriate point size
by using the formula:
scaled value = scalable-value x point-size x resolution / 72.0
You can scale such values to an appropriate pixel size by using the
formula:
scaled-value = scalable-value x pixel-size
The character advance width in pixels for a given resolution can be
calculated from the scalable character advance width in ems by using the
formula:
advance-width = scalable-advance-width x point-size x resolution / 72.0
The result is usually rounded to the nearest pixel.
SEE ALSOufmFreeCharMetrics(3w), ufmGetCharMetrics, ufmOpenTypeface(3w).
DIAGNOSTICS
If ufmGetCharMetricsByName 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, ufmGetCharMetricsByName will return the value
UFM_INVALID_VALUE. UFM_OUT_OF_MEMORY and UFM_INVALID_VALUE are defined
in the header file <ufm.h>.
Page 2
