+ + + +

FreeType » Docs » Support API » Quick retrieval of advance values

+

Quick retrieval of advance values¶

+

Synopsis¶

+

This section contains functions to quickly extract advance values without handling glyph outlines, if possible.

+

FT_Get_Advance¶

+

Defined in FT_ADVANCES_H (freetype/ftadvanc.h).

+

  FT_EXPORT( FT_Error )
+  FT_Get_Advance( FT_Face    face,
+                  FT_UInt    gindex,
+                  FT_Int32   load_flags,
+                  FT_Fixed  *padvance );
+

+ +

Retrieve the advance value of a given glyph outline in an FT_Face.

+

input

+ + + + +

face	+ The source `FT_Face` handle. +
gindex	+ The glyph index. +
load_flags	+ A set of bit flags similar to those used when calling `FT_Load_Glyph`, used to determine what kind of advances you need. +

+ +

output

+ + +

padvance

+

The advance value. If scaling is performed (based on the value of load_flags), the advance value is in 16.16 format. Otherwise, it is in font units.

+

If FT_LOAD_VERTICAL_LAYOUT is set, this is the vertical advance corresponding to a vertical layout. Otherwise, it is the horizontal advance in a horizontal layout.

+

+ +

return

+ +

FreeType error code. 0 means success.

+

note

+ +

This function may fail if you use FT_ADVANCE_FLAG_FAST_ONLY and if the corresponding font backend doesn't have a quick way to retrieve the advances.

+

A scaled advance is returned in 16.16 format but isn't transformed by the affine transformation specified by FT_Set_Transform.

+

+ +

FT_Get_Advances¶

+

Defined in FT_ADVANCES_H (freetype/ftadvanc.h).

+

  FT_EXPORT( FT_Error )
+  FT_Get_Advances( FT_Face    face,
+                   FT_UInt    start,
+                   FT_UInt    count,
+                   FT_Int32   load_flags,
+                   FT_Fixed  *padvances );
+

+ +

Retrieve the advance values of several glyph outlines in an FT_Face.

+

input

+ + + + + +

face	+ The source `FT_Face` handle. +
start	+ The first glyph index. +
count	+ The number of advance values you want to retrieve. +
load_flags	+ A set of bit flags similar to those used when calling `FT_Load_Glyph`. +

+ +

output

+ + +

padvance

+

The advance values. This array, to be provided by the caller, must contain at least count elements.

+

If scaling is performed (based on the value of load_flags), the advance values are in 16.16 format. Otherwise, they are in font units.

+

If FT_LOAD_VERTICAL_LAYOUT is set, these are the vertical advances corresponding to a vertical layout. Otherwise, they are the horizontal advances in a horizontal layout.

+

+ +

return

+ +

FreeType error code. 0 means success.

+

note

+ +

This function may fail if you use FT_ADVANCE_FLAG_FAST_ONLY and if the corresponding font backend doesn't have a quick way to retrieve the advances.

+

Scaled advances are returned in 16.16 format but aren't transformed by the affine transformation specified by FT_Set_Transform.

+

+ +

FT_ADVANCE_FLAG_FAST_ONLY¶

+

Defined in FT_ADVANCES_H (freetype/ftadvanc.h).

+

#define FT_ADVANCE_FLAG_FAST_ONLY  0x20000000L
+

+ +

A bit-flag to be OR-ed with the flags parameter of the FT_Get_Advance and FT_Get_Advances functions.

+

If set, it indicates that you want these functions to fail if the corresponding hinting mode or font driver doesn't allow for very quick advance computation.

+

Typically, glyphs that are either unscaled, unhinted, bitmapped, or light-hinted can have their advance width computed very quickly.

+

Normal and bytecode hinted modes that require loading, scaling, and hinting of the glyph outline, are extremely slow by comparison.

+

+ + + + + + + +