ref: c1205799f5bfab9e9b9187fdd8094dd347c65b13
dir: /src/shared/autohint.h/
/***************************************************************************/
/* */
/* autohint.h */
/* */
/* High-level `autohint" driver interface (specification) */
/* */
/* Copyright 1996-2000 by */
/* David Turner, Robert Wilhelm, and Werner Lemberg. */
/* */
/* This file is part of the FreeType project, and may only be used, */
/* modified, and distributed under the terms of the FreeType project */
/* license, LICENSE.TXT. By continuing to use, modify, or distribute */
/* this file you indicate that you have read the license and */
/* understand and accept it fully. */
/* */
/* */
/* The auto-hinter is used to load and automatically hint glyphs */
/* when a format-specific hinter isn't available.. */
/* */
/***************************************************************************/
#ifndef AUTOHINT_H
#define AUTOHINT_H
/***************************************************************************
*
* A small technical note regarding automatic hinting in order to clarify
* this module interface.
*
* An automatic hinter might compute two kinds of data for a given face:
*
* - global hints: usually some metrics that describe global properties
* of the face. It is computed by scanning more or less
* agressively the glyphs in the face, and thus can be
* very slow to compute (even if the size of global hints
* is really small)
*
* - glyph hints: these describe some important features of the glyph
* outline, as well as how to align them. They are generally
* much faster to compute than global hints.
*
* The current FreeType auto-hinter does a pretty good job while performing
* fast computations for both global and glyph hints. However, we might be
* interested in introducing more complex and powerful algorithms in the
* future, like the one described in the John D. Hobby paper, which
* unfortunately require a lot more horsepower.
*
* Because a sufficiently sophisticated font management system would
* typically implement a LRU cache of opened face objects to reduce memory
* usage, it is a good idea to be able to avoid recomputing global hints
* every time the same face is re-opened.
*
* We thus provide the ability to cache global hints outside of the face
* object, in order to speed up font re-opening time. Of course, this
* feature is purely optional, so most client programs won't even notice
* it :o)
*
* I initially though that it'd be a good idea to cache the glyph hints too,
* however, if my general idea now is that if you really need to cache these
* too, you're simply in need of a new font format, where all this information
* could be stored within the font file and decoded on the fly :-)
*
*/
#include <freetype.h>
typedef struct FT_AutoHinterRec_ *FT_AutoHinter;
/***********************************************************************
*
* <FuncType>
* FT_AutoHinter_Get_Global_Func
*
* <Description>
* Retrieve the global hints computed for a given face object
* the resulting data is dissociated from the face and will survive
* a call to FT_Done_Face. It must be discarded through the API
* FT_AutoHinter_Done_Global_Func.
*
* <Input>
* hinter :: handle to source auto-hinter
* face :: handle to source face object
*
* <Output>
* global_hints :: typeless pointer to the global hints
* global_len :: size in bytes of global hints
*
*/
typedef void (*FT_AutoHinter_Get_Global_Func)( FT_AutoHinter hinter,
FT_Face face,
void* *global_hints,
long *global_len );
/***********************************************************************
*
* <FuncType>
* FT_AutoHinter_Done_Global_Func
*
* <Description>
* Discards the global hints retrieved through
* FT_AutoHinter_Get_Global_Func. This is the only way these hints
* are freed from memory.
*
* <Input>
* hinter :: handle to auto-hinter module
* global :: pointer to retrieved global hints to discard
*/
typedef void (*FT_AutoHinter_Done_Global_Func)( FT_AutoHinter hinter,
void* global );
/***********************************************************************
*
* <FuncType>
* FT_AutoHinter_Init_Func
*
* <Description>
* Compute or set the global hints for a given face object.
*
* <Input>
* hinter :: handle to source auto-hinter module
* face :: handle to target face object.
* global_hints :: typeless pointer to global hints. If 0, the
* hints are computed for the face
*
* <Note>
* it is up to client applications to ensure that the global hints
* were retrieved for the same face object. Strange results may occur
* otherwise..
*
*/
typedef FT_Error (*FT_AutoHinter_Init_Func)( FT_AutoHinter hinter,
FT_Face face,
void* global_hints );
/***********************************************************************
*
* <FuncType>
* FT_AutoHinter_Done_Func
*
* <Description>
* Discards the global hints for a given face..
*
* <Input>
* hinter :: handle to source auto-hinter module
* face :: handle to target face object.
*
*/
typedef FT_Error (*FT_AutoHinter_Done_Func)( FT_AutoHinter hinter,
FT_Face face );
/***********************************************************************
*
* <FuncType>
* FT_AutoHinter_Load_Func
*
* <Description>
* This function is used to load, scale and automatically hint a glyph
* from a given face.
*
* <Input>
* face :: handle to the face.
* glyph_index :: glyph index
* load_flags :: load flags
*
* <Note>
* This function is capable of loading composite glyphs by hinting
* each sub-glyph independently (which improves quality).
*
* It will call the font driver with FT_Load_Glyph, with FT_LOAD_NO_SCALE
* set..
*
*/
typedef FT_Error (*FT_AutoHinter_Load_Func)( FT_Face face,
FT_UInt glyph_index,
FT_ULong load_flags );
/***********************************************************************
*
* <Struct>
* FT_AutoHinter_Interface
*
* <Description>
* The auto-hinter module's interface.
*
*/
typedef struct FT_AutoHinter_Interface
{
FT_AutoHinter_Init_Func init_autohinter;
FT_AutoHinter_Done_Func done_autohinter;
FT_AutoHinter_Load_Func load_glyph;
FT_AutoHinter_Get_Global_Func get_global_hints;
FT_AutoHinter_Done_Global_Func done_global_hints;
} FT_AutoHinter_Interface;
#endif /* AUTOHINT_H */