next up previous contents index
Next: Character-Encoding Relation Up: Common Information on Fonts Previous: Information from FontInfo-Dictionary   Contents   Index


Metric Information on Glyphs

 int T1_GetCharWidth( int FontID, char char1)

to 0pt \fbox{$\mathcal{F}()\Rightarrow$} The character width according to the AFM information is returned in charspace units. If no AFM information is available, 0 is returned.

The width of a character is the amount of horizontal escapement that the next character is shifted to the right with respect to the current position. This information is not given in the character's bounding box. Also, the width corresponds to the entry characterWidth in the glyph-structure, as described in [*]. But since T1_GetCharWidth(), returns its result in charspace units, the accuracy is much higher than using the value of the glyph-structure which has only pixel-accuracy.

If there is an extension specified for the font in question, the characters width is corrected correspondingly.

 BBox T1_GetCharBBox( int FontID, char char1)

to 0pt \fbox{$\mathcal{F}()\Rightarrow$} The character's bounding box of char1 is returned with the elements to be interpreted in charspace units. The bounding box of a character is defined to be smallest rectangle aligned parallel to the $x$- and $y$-axis of the character coordinate system which encloses the painted area of the character completely. This rectangle is completely specified by specifying its lower left and its upper right corner. From a programmer's point of view, a characters bounding box is defined by the following struct of type BBox:
typedef struct
{ 
   int llx;     /* lower left x-position  */
   int lly;     /* lower left y-position  */
   int urx;     /* upper right x-position */
   int ury;     /* upper right y-position */
} BBox;
In case the character is not encoded or no AFM data is available, a box containing only zeros is returned.

The bounding box is corrected if an extension value has been applied to the font in question.

Since version 0.3-beta, slanted fonts are fully supported, meaning that for slanted fonts too a correct bounding box will be returned. This is however quite time expensive since the characters' real outline must be considered. See the discussion on slanting a font ([*]) for an explanation of this.

 int T1_GetStringWidth( int FontID, char *string,
                        int len, long spaceoff, int kerning)

to 0pt \fbox{$\mathcal{F}()\Rightarrow$}

 BBox T1_GetStringBBox( int FontID, char *string,
                        int len, long spaceoff, int kerning)

to 0pt \fbox{$\mathcal{F}()\Rightarrow$} These two functions represent the complement to the above functions on the level of strings. All parameters that take influence on the resulting width and bounding box must be given in the argument list. Their meaning is identical to the meaning they have when calling string rastering functions (see [*]).

 METRICSINFO T1_GetMetricsInfo( int FontID, char *string,
                                int len, long spaceoff, int kerning)

to 0pt \fbox{$\mathcal{F}()\Rightarrow$} In certain situations bounding box and width of a glyph are required both. In these cases it is more convenient to call T1_GetMetricsInfo() which returns a structure that contains all information. METRICSINFO is defined in t1lib.h as:
typedef struct
{
  int      width;
  BBox     bbox;
  int      numchars;
  int      *charpos;
} METRICSINFO;
All numbers are to be interpreted in character space units -- they are directly taken from AFM data. width is the glyph's width and bbox its bounding box which in turn is a struct as defined some paragraphs above.

numchars is assigned number of characters in string. If the argument len is different from 0, numchars is assigned that value.

charpos is a pointer to an integer array of size numchars allocated by T1_GetMetricsInfo(). During execution this array is filled step by step with the horizontal escapement in character space units of the respective character relative to the start point of the string glyph which corresponds to 0. charpos remains valid until T1_GetMetricsInfo() is called the next time. The user should not free this memory because this is handled automatically.

The terms concerning the bounding box of slanted fonts mentioned under the description of T1_GetCharBBox() apply here as well. The first and the last character of string have to be observed spending high effort. But nevertheless the correct bounding box is returned.

 int T1_GetKerning( int FontID, char char1, char char2)

to 0pt \fbox{$\mathcal{F}()\Rightarrow$} This function returns the amount of kerning for the specified character pair char1 and char2. If an extension has been specified for the font (see [*]), the amount of kerning is automatically corrected using the extension factor. The value returned has to be interpreted in charspace units.

If no AFM information is available for the font in question, simply 0 is returned. The same applies if the font is not loaded.

The implementation of this function requires that the kerning pairs in the AFM file are sorted in alphabetical order. I am not sure whether this condition is found in the specification of the AFM file format. If this function doesn't work although AFM kerning data is available, this might be the reason.

 int T1_QueryLigs( int FontID, char char1,
                   char **successors, char **ligatures)

to 0pt \fbox{$\mathcal{F}()\Rightarrow$} This function implements the interface to the ligature information in the AFM data. Ligatures are special character-symbols which are substituted if special pairs, triples or whatever groups of characters appear in a string. For example, ``fi'' is replaced with the ligature ``fi''. In this example, the ``i'' is called successor and the ``fi'' is the associated ligature.

char1 is the character which has to be checked for ligatures, i.e., the first character of a possible ligature group. successors and ligatures should be addresses of pointers to chars. These pointers are modified by the T1_QueryLigs().

First, T1_QueryLigs() checks how many ligatures are defined for the character given by char1. Assuming this number is $n$, it then defines memory for two arrays of type char with size $n$. These arrays are filled with the indices of the successor-characters and with the indices of the associated ligatures, respectively. The current encoding vector is used for this. The addresses of these two arrays are written to the addresses of the respective pointers successors and ligatures. They are thus later available to the user in order to access the memory where the successor-character and ligatures are specified. The value $n$ is returned in order to tell the user how many ligatures were found and to give the user information about the end of the two arrays.

If the font is not loaded or AFM data is not available, -1 is returned.

Since this may seem to be a little complicated, here is a programming example:

char *succ, *lig;
int n_lig, i;
char char1='f';

/* Get ligature information of character 'f' in font 0: */
n_lig=T1_QueryLig( 0, char1, &suc, &lig);

/* print out indices of characters and their ligatures */
for ( i=0; i<n_lig; i++;){
  printf("First char: %d, +  next char: %d --> ligatur: %d\n",
         char1,
         succ[i],
         lig[i]);

Notice that the arrays where the successor indices and the respective ligature indices are stored are static in T1_QueryLigs(). Thus, they may not be freed and moreover they are only valid until the next time T1_QueryLigs() is called.


next up previous contents index
Next: Character-Encoding Relation Up: Common Information on Fonts Previous: Information from FontInfo-Dictionary   Contents   Index
2004-10-04