/* */
/* FreeType high-level API and common types (specification only). */
/* */
-/* Copyright 1996-2012 by */
+/* Copyright 1996-2014 by */
/* David Turner, Robert Wilhelm, and Werner Lemberg. */
/* */
/* This file is part of the FreeType project, and may only be used, */
/***************************************************************************/
+#ifndef __FREETYPE_H__
+#define __FREETYPE_H__
+
+
#ifndef FT_FREETYPE_H
#error "`ft2build.h' hasn't been included yet!"
#error "Please always use macros to include FreeType header files."
#endif
-#ifndef __FREETYPE_H__
-#define __FREETYPE_H__
-
-
#include <ft2build.h>
#include FT_CONFIG_CONFIG_H
-#include FT_ERRORS_H
#include FT_TYPES_H
+#include FT_ERRORS_H
FT_BEGIN_HEADER
/*************************************************************************/
/* */
/* <Section> */
+ /* header_inclusion */
+ /* */
+ /* <Title> */
+ /* FreeType's header inclusion scheme */
+ /* */
+ /* <Abstract> */
+ /* How client applications should include FreeType header files. */
+ /* */
+ /* <Description> */
+ /* To be as flexible as possible (and for historical reasons), */
+ /* FreeType uses a very special inclusion scheme to load header */
+ /* files, for example */
+ /* */
+ /* { */
+ /* #include <ft2build.h> */
+ /* */
+ /* #include FT_FREETYPE_H */
+ /* #include FT_OUTLINE_H */
+ /* } */
+ /* */
+ /* A compiler and its preprocessor only needs an include path to find */
+ /* the file `ft2build.h'; the exact locations and names of the other */
+ /* FreeType header files are hidden by preprocessor macro names, */
+ /* loaded by `ft2build.h'. The API documentation always gives the */
+ /* header macro name needed for a particular function. */
+ /* */
+ /*************************************************************************/
+
+
+ /*************************************************************************/
+ /* */
+ /* <Section> */
/* user_allocation */
/* */
/* <Title> */
/* The FreeType~2 base font interface. */
/* */
/* <Description> */
- /* This section describes the public high-level API of FreeType~2. */
+ /* This section describes the most important public high-level API */
+ /* functions of FreeType~2. */
/* */
/* <Order> */
/* FT_Library */
/* FT_GlyphSlot */
/* FT_CharMap */
/* FT_Encoding */
+ /* FT_ENC_TAG */
/* */
/* FT_FaceRec */
/* */
/* FT_FACE_FLAG_FIXED_WIDTH */
/* FT_FACE_FLAG_HORIZONTAL */
/* FT_FACE_FLAG_VERTICAL */
+ /* FT_FACE_FLAG_COLOR */
/* FT_FACE_FLAG_SFNT */
+ /* FT_FACE_FLAG_CID_KEYED */
+ /* FT_FACE_FLAG_TRICKY */
/* FT_FACE_FLAG_KERNING */
/* FT_FACE_FLAG_MULTIPLE_MASTERS */
/* FT_FACE_FLAG_GLYPH_NAMES */
/* FT_FACE_FLAG_EXTERNAL_STREAM */
- /* FT_FACE_FLAG_FAST_GLYPHS */
/* FT_FACE_FLAG_HINTER */
+ /* FT_FACE_FLAG_TRICKY */
+ /* */
+ /* FT_HAS_HORIZONTAL */
+ /* FT_HAS_VERTICAL */
+ /* FT_HAS_KERNING */
+ /* FT_HAS_FIXED_SIZES */
+ /* FT_HAS_GLYPH_NAMES */
+ /* FT_HAS_MULTIPLE_MASTERS */
+ /* FT_HAS_COLOR */
+ /* */
+ /* FT_IS_SFNT */
+ /* FT_IS_SCALABLE */
+ /* FT_IS_FIXED_WIDTH */
+ /* FT_IS_CID_KEYED */
+ /* FT_IS_TRICKY */
/* */
/* FT_STYLE_FLAG_BOLD */
/* FT_STYLE_FLAG_ITALIC */
/* */
/* FT_New_Face */
/* FT_Done_Face */
+ /* FT_Reference_Face */
/* FT_New_Memory_Face */
/* FT_Open_Face */
/* FT_Open_Args */
/* FT_Request_Size */
/* FT_Select_Size */
/* FT_Size_Request_Type */
+ /* FT_Size_RequestRec */
/* FT_Size_Request */
/* FT_Set_Transform */
/* FT_Load_Glyph */
/* FT_Get_Char_Index */
+ /* FT_Get_First_Char */
+ /* FT_Get_Next_Char */
/* FT_Get_Name_Index */
/* FT_Load_Char */
/* */
/* FT_LOAD_NO_SCALE */
/* FT_LOAD_NO_HINTING */
/* FT_LOAD_NO_BITMAP */
- /* FT_LOAD_CROP_BITMAP */
+ /* FT_LOAD_NO_AUTOHINT */
+ /* FT_LOAD_COLOR */
/* */
/* FT_LOAD_VERTICAL_LAYOUT */
/* FT_LOAD_IGNORE_TRANSFORM */
- /* FT_LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH */
/* FT_LOAD_FORCE_AUTOHINT */
/* FT_LOAD_NO_RECURSE */
/* FT_LOAD_PEDANTIC */
/* FT_LOAD_TARGET_LCD */
/* FT_LOAD_TARGET_LCD_V */
/* */
+ /* FT_LOAD_TARGET_MODE */
+ /* */
/* FT_Render_Glyph */
/* FT_Render_Mode */
/* FT_Get_Kerning */
/* FT_Set_Charmap */
/* FT_Get_Charmap_Index */
/* */
- /* FT_FSTYPE_INSTALLABLE_EMBEDDING */
- /* FT_FSTYPE_RESTRICTED_LICENSE_EMBEDDING */
- /* FT_FSTYPE_PREVIEW_AND_PRINT_EMBEDDING */
- /* FT_FSTYPE_EDITABLE_EMBEDDING */
- /* FT_FSTYPE_NO_SUBSETTING */
- /* FT_FSTYPE_BITMAP_EMBEDDING_ONLY */
- /* */
/* FT_Get_FSType_Flags */
+ /* FT_Get_SubGlyph_Info */
+ /* */
+ /* FT_Face_Internal */
+ /* FT_Size_Internal */
+ /* FT_Slot_Internal */
+ /* */
+ /* FT_FACE_FLAG_XXX */
+ /* FT_STYLE_FLAG_XXX */
+ /* FT_OPEN_XXX */
+ /* FT_LOAD_XXX */
+ /* FT_LOAD_TARGET_XXX */
+ /* FT_SUBGLYPH_FLAG_XXX */
+ /* FT_FSTYPE_XXX */
+ /* */
+ /* FT_HAS_FAST_GLYPHS */
/* */
/*************************************************************************/
/* If not disabled with @FT_LOAD_NO_HINTING, the values represent */
/* dimensions of the hinted glyph (in case hinting is applicable). */
/* */
+ /* Stroking a glyph with an outside border does not increase */
+ /* `horiAdvance' or `vertAdvance'; you have to manually adjust these */
+ /* values to account for the added width and height. */
+ /* */
typedef struct FT_Glyph_Metrics_
{
FT_Pos width;
/* It also embeds a memory manager (see @FT_Memory), as well as a */
/* scan-line converter object (see @FT_Raster). */
/* */
- /* For multi-threading applications each thread should have its own */
- /* FT_Library object. */
+ /* In multi-threaded applications, make sure that the same FT_Library */
+ /* object or any of its children doesn't get accessed in parallel. */
/* */
/* <Note> */
/* Library objects are normally created by @FT_Init_FreeType, and */
- /* destroyed with @FT_Done_FreeType. */
+ /* destroyed with @FT_Done_FreeType. If you need reference-counting */
+ /* (cf. @FT_Reference_Library), use @FT_New_Library and */
+ /* @FT_Done_Library. */
/* */
typedef struct FT_LibraryRec_ *FT_Library;
/*************************************************************************/
/* */
+ /* <Section> */
+ /* module_management */
+ /* */
+ /*************************************************************************/
+
+ /*************************************************************************/
+ /* */
/* <Type> */
/* FT_Module */
/* */
/*************************************************************************/
/* */
+ /* <Section> */
+ /* base_interface */
+ /* */
+ /*************************************************************************/
+
+ /*************************************************************************/
+ /* */
/* <Type> */
/* FT_Face */
/* */
/* <Note> */
/* Each @FT_Face has an _active_ @FT_Size object that is used by */
/* functions like @FT_Load_Glyph to determine the scaling */
- /* transformation which is used to load and hint glyphs and metrics. */
+ /* transformation that in turn is used to load and hint glyphs and */
+ /* metrics. */
/* */
/* You can use @FT_Set_Char_Size, @FT_Set_Pixel_Sizes, */
/* @FT_Request_Size or even @FT_Select_Size to change the content */
/* FT_ENCODING_MS_SYMBOL :: */
/* Corresponds to the Microsoft Symbol encoding, used to encode */
/* mathematical symbols in the 32..255 character code range. For */
- /* more information, see `http://www.ceviz.net/symbol.htm'. */
+ /* more information, see */
+ /* `http://www.kostis.net/charsets/symbol.htm'. */
/* */
/* FT_ENCODING_SJIS :: */
/* Corresponds to Japanese SJIS encoding. More info at */
- /* at `http://langsupport.japanreference.com/encoding.shtml'. */
+ /* at `http://en.wikipedia.org/wiki/Shift_JIS'. */
/* See note on multi-byte encodings below. */
/* */
/* FT_ENCODING_GB2312 :: */
/* FT_ENCODING_WANSUNG :: */
/* Corresponds to the Korean encoding system known as Wansung. */
/* For more information see */
- /* `http://www.microsoft.com/typography/unicode/949.txt'. */
+ /* `http://msdn.microsoft.com/en-US/goglobal/cc305154'. */
/* */
/* FT_ENCODING_JOHAB :: */
/* The Korean standard character set (KS~C 5601-1992), which */
/* FT_ENCODING_APPLE_ROMAN). */
/* */
/* If `platform_id' is @TT_PLATFORM_MACINTOSH, use the function */
- /* @FT_Get_CMap_Language_ID to query the Mac language ID which may */
+ /* @FT_Get_CMap_Language_ID to query the Mac language ID that may */
/* be needed to be able to distinguish Apple encoding variants. See */
/* */
- /* http://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/README.TXT */
+ /* http://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/Readme.txt */
/* */
/* to get an idea how to do that. Basically, if the language ID */
/* is~0, don't use it, otherwise subtract 1 from the language ID. */
} FT_Encoding;
- /*************************************************************************/
- /* */
- /* <Enum> */
- /* ft_encoding_xxx */
- /* */
- /* <Description> */
- /* These constants are deprecated; use the corresponding @FT_Encoding */
- /* values instead. */
- /* */
+ /* these constants are deprecated; use the corresponding `FT_Encoding' */
+ /* values instead */
#define ft_encoding_none FT_ENCODING_NONE
#define ft_encoding_unicode FT_ENCODING_UNICODE
#define ft_encoding_symbol FT_ENCODING_MS_SYMBOL
/* highest CID used in the font. */
/* */
/* family_name :: The face's family name. This is an ASCII */
- /* string, usually in English, which describes */
+ /* string, usually in English, that describes */
/* the typeface's family (like `Times New */
/* Roman', `Bodoni', `Garamond', etc). This */
/* is a least common denominator used to list */
/* PDF file). */
/* */
/* style_name :: The face's style name. This is an ASCII */
- /* string, usually in English, which describes */
+ /* string, usually in English, that describes */
/* the typeface's style (like `Italic', */
/* `Bold', `Condensed', etc). Not all font */
/* formats provide a style name, so this field */
/* expressed in font units (see */
/* `units_per_EM'). The box is large enough */
/* to contain any glyph from the font. Thus, */
- /* `bbox.yMax' can be seen as the `maximal */
- /* ascender', and `bbox.yMin' as the `minimal */
+ /* `bbox.yMax' can be seen as the `maximum */
+ /* ascender', and `bbox.yMin' as the `minimum */
/* descender'. Only relevant for scalable */
/* formats. */
/* */
/* usually negative. Only relevant for */
/* scalable formats. */
/* */
- /* height :: The height is the vertical distance */
+ /* height :: This value is the vertical distance */
/* between two consecutive baselines, */
/* expressed in font units. It is always */
/* positive. Only relevant for scalable */
/* formats. */
/* */
- /* max_advance_width :: The maximal advance width, in font units, */
+ /* If you want the global glyph height, use */
+ /* `ascender - descender'. */
+ /* */
+ /* max_advance_width :: The maximum advance width, in font units, */
/* for all glyphs in this face. This can be */
/* used to make word wrapping computations */
/* faster. Only relevant for scalable */
/* formats. */
/* */
- /* max_advance_height :: The maximal advance height, in font units, */
+ /* max_advance_height :: The maximum advance height, in font units, */
/* for all glyphs in this face. This is only */
/* relevant for vertical layouts, and is set */
/* to `height' for fonts that do not provide */
/* exist make FT_Load_Glyph return successfully; in all other cases */
/* you get an `FT_Err_Invalid_Argument' error. */
/* */
- /* Note that CID-keyed fonts which are in an SFNT wrapper don't */
+ /* Note that CID-keyed fonts that are in an SFNT wrapper don't */
/* have this flag set since the glyphs are accessed in the normal */
/* way (using contiguous indices); the `CID-ness' isn't visible to */
/* the application. */
/* FT_FACE_FLAG_TRICKY :: */
/* Set if the font is `tricky', this is, it always needs the */
/* font format's native hinting engine to get a reasonable result. */
- /* A typical example is the Chinese font `mingli.ttf' which uses */
+ /* A typical example is the Chinese font `mingli.ttf' that uses */
/* TrueType bytecode instructions to move and scale all of its */
/* subglyphs. */
/* */
/* Currently, there are about a dozen TrueType fonts in the list of */
/* tricky fonts; they are hard-coded in file `ttobjs.c'. */
/* */
+ /* FT_FACE_FLAG_COLOR :: */
+ /* Set if the font has color glyph tables. To access color glyphs */
+ /* use @FT_LOAD_COLOR. */
+ /* */
#define FT_FACE_FLAG_SCALABLE ( 1L << 0 )
#define FT_FACE_FLAG_FIXED_SIZES ( 1L << 1 )
#define FT_FACE_FLAG_FIXED_WIDTH ( 1L << 2 )
#define FT_FACE_FLAG_HINTER ( 1L << 11 )
#define FT_FACE_FLAG_CID_KEYED ( 1L << 12 )
#define FT_FACE_FLAG_TRICKY ( 1L << 13 )
+#define FT_FACE_FLAG_COLOR ( 1L << 14 )
/*************************************************************************
* FT_HAS_VERTICAL( face )
*
* @description:
- * A macro that returns true whenever a face object contains vertical
- * metrics.
+ * A macro that returns true whenever a face object contains real
+ * vertical metrics (and not only synthesized ones).
*
*/
#define FT_HAS_VERTICAL( face ) \
( face->face_flags & FT_FACE_FLAG_TRICKY )
+ /*************************************************************************
+ *
+ * @macro:
+ * FT_HAS_COLOR( face )
+ *
+ * @description:
+ * A macro that returns true whenever a face object contains
+ * tables for color glyphs.
+ *
+ */
+#define FT_HAS_COLOR( face ) \
+ ( face->face_flags & FT_FACE_FLAG_COLOR )
+
+
/*************************************************************************/
/* */
/* <Const> */
/* height :: The height in 26.6 fractional pixels. See */
/* @FT_FaceRec for the details. */
/* */
- /* max_advance :: The maximal advance width in 26.6 fractional */
+ /* max_advance :: The maximum advance width in 26.6 fractional */
/* pixels. See @FT_FaceRec for the details. */
/* */
/* <Note> */
/* <Fields> */
/* face :: Handle to the parent face object. */
/* */
- /* generic :: A typeless pointer, which is unused by the FreeType */
- /* library or any of its drivers. It can be used by */
- /* client applications to link their own data to each size */
+ /* generic :: A typeless pointer, unused by the FreeType library or */
+ /* any of its drivers. It can be used by client */
+ /* applications to link their own data to each size */
/* object. */
/* */
/* metrics :: Metrics for this size object. This field is read-only. */
/* listed through a direct, single-linked list */
/* using its `next' field. */
/* */
- /* generic :: A typeless pointer which is unused by the */
- /* FreeType library or any of its drivers. It */
- /* can be used by client applications to link */
- /* their own data to each glyph slot object. */
+ /* generic :: A typeless pointer unused by the FreeType */
+ /* library or any of its drivers. It can be */
+ /* used by client applications to link their own */
+ /* data to each glyph slot object. */
/* */
/* metrics :: The metrics of the last loaded glyph in the */
/* slot. The returned values depend on the last */
/* */
/* advance :: This shorthand is, depending on */
/* @FT_LOAD_IGNORE_TRANSFORM, the transformed */
- /* advance width for the glyph (in 26.6 */
- /* fractional pixel format). As specified with */
+ /* (hinted) advance width for the glyph, in 26.6 */
+ /* fractional pixel format. As specified with */
/* @FT_LOAD_VERTICAL_LAYOUT, it uses either the */
/* `horiAdvance' or the `vertAdvance' value of */
/* `metrics' field. */
/* change between calls of @FT_Load_Glyph and a */
/* few other functions. */
/* */
- /* bitmap_left :: This is the bitmap's left bearing expressed */
- /* in integer pixels. Of course, this is only */
- /* valid if the format is */
- /* @FT_GLYPH_FORMAT_BITMAP. */
+ /* bitmap_left :: The bitmap's left bearing expressed in */
+ /* integer pixels. Only valid if the format is */
+ /* @FT_GLYPH_FORMAT_BITMAP, this is, if the */
+ /* glyph slot contains a bitmap. */
/* */
- /* bitmap_top :: This is the bitmap's top bearing expressed in */
- /* integer pixels. Remember that this is the */
- /* distance from the baseline to the top-most */
- /* glyph scanline, upwards y~coordinates being */
+ /* bitmap_top :: The bitmap's top bearing expressed in integer */
+ /* pixels. Remember that this is the distance */
+ /* from the baseline to the top-most glyph */
+ /* scanline, upwards y~coordinates being */
/* *positive*. */
/* */
/* outline :: The outline descriptor for the current glyph */
/* This field is only valid for the composite */
/* glyph format that should normally only be */
/* loaded with the @FT_LOAD_NO_RECURSE flag. */
- /* For now this is internal to FreeType. */
/* */
/* subglyphs :: An array of subglyph descriptors for */
/* composite glyphs. There are `num_subglyphs' */
/* `slot->format' is also changed to @FT_GLYPH_FORMAT_BITMAP. */
/* */
/* <Note> */
- /* Here a small pseudo code fragment which shows how to use */
+ /* Here a small pseudo code fragment that shows how to use */
/* `lsb_delta' and `rsb_delta': */
/* */
/* { */
/* For multi-threading applications each thread should have its own */
/* FT_Library object. */
/* */
+ /* If you need reference-counting (cf. @FT_Reference_Library), use */
+ /* @FT_New_Library and @FT_Done_Library. */
+ /* */
FT_EXPORT( FT_Error )
FT_Init_FreeType( FT_Library *alibrary );
/* */
/* FT_OPEN_PARAMS :: Use the `num_params' and `params' fields. */
/* */
- /* ft_open_memory :: Deprecated; use @FT_OPEN_MEMORY instead. */
- /* */
- /* ft_open_stream :: Deprecated; use @FT_OPEN_STREAM instead. */
- /* */
- /* ft_open_pathname :: Deprecated; use @FT_OPEN_PATHNAME instead. */
- /* */
- /* ft_open_driver :: Deprecated; use @FT_OPEN_DRIVER instead. */
- /* */
- /* ft_open_params :: Deprecated; use @FT_OPEN_PARAMS instead. */
- /* */
/* <Note> */
/* The `FT_OPEN_MEMORY', `FT_OPEN_STREAM', and `FT_OPEN_PATHNAME' */
/* flags are mutually exclusive. */
#define FT_OPEN_DRIVER 0x8
#define FT_OPEN_PARAMS 0x10
-#define ft_open_memory FT_OPEN_MEMORY /* deprecated */
-#define ft_open_stream FT_OPEN_STREAM /* deprecated */
-#define ft_open_pathname FT_OPEN_PATHNAME /* deprecated */
-#define ft_open_driver FT_OPEN_DRIVER /* deprecated */
-#define ft_open_params FT_OPEN_PARAMS /* deprecated */
+
+ /* these constants are deprecated; use the corresponding `FT_OPEN_XXX' */
+ /* values instead */
+#define ft_open_memory FT_OPEN_MEMORY
+#define ft_open_stream FT_OPEN_STREAM
+#define ft_open_pathname FT_OPEN_PATHNAME
+#define ft_open_driver FT_OPEN_DRIVER
+#define ft_open_params FT_OPEN_PARAMS
/*************************************************************************/
/* opening a new face. */
/* */
/* <Note> */
- /* The stream type is determined by the contents of `flags' which */
+ /* The stream type is determined by the contents of `flags' that */
/* are tested in the following order by @FT_Open_Face: */
/* */
- /* If the `FT_OPEN_MEMORY' bit is set, assume that this is a */
+ /* If the @FT_OPEN_MEMORY bit is set, assume that this is a */
/* memory file of `memory_size' bytes, located at `memory_address'. */
/* The data are are not copied, and the client is responsible for */
/* releasing and destroying them _after_ the corresponding call to */
/* @FT_Done_Face. */
/* */
- /* Otherwise, if the `FT_OPEN_STREAM' bit is set, assume that a */
+ /* Otherwise, if the @FT_OPEN_STREAM bit is set, assume that a */
/* custom input stream `stream' is used. */
/* */
- /* Otherwise, if the `FT_OPEN_PATHNAME' bit is set, assume that this */
+ /* Otherwise, if the @FT_OPEN_PATHNAME bit is set, assume that this */
/* is a normal file and use `pathname' to open it. */
/* */
- /* If the `FT_OPEN_DRIVER' bit is set, @FT_Open_Face only tries to */
+ /* If the @FT_OPEN_DRIVER bit is set, @FT_Open_Face only tries to */
/* open the file with the driver whose handler is in `driver'. */
/* */
- /* If the `FT_OPEN_PARAMS' bit is set, the parameters given by */
+ /* If the @FT_OPEN_PARAMS bit is set, the parameters given by */
/* `num_params' and `params' is used. They are ignored otherwise. */
/* */
/* Ideally, both the `pathname' and `params' fields should be tagged */
/* <Return> */
/* FreeType error code. 0~means success. */
/* */
+ /* <Note> */
+ /* Use @FT_Done_Face to destroy the created @FT_Face object (along */
+ /* with its slot and sizes). */
+ /* */
FT_EXPORT( FT_Error )
FT_New_Face( FT_Library library,
const char* filepathname,
/* FT_New_Memory_Face */
/* */
/* <Description> */
- /* This function calls @FT_Open_Face to open a font which has been */
+ /* This function calls @FT_Open_Face to open a font that has been */
/* loaded into memory. */
/* */
/* <InOut> */
/* library :: A handle to the library resource. */
/* */
/* <Input> */
- /* args :: A pointer to an `FT_Open_Args' structure which must */
+ /* args :: A pointer to an `FT_Open_Args' structure that must */
/* be filled by the caller. */
/* */
/* face_index :: The index of the face within the font. The first */
/* */
/* <Note> */
/* Unlike FreeType 1.x, this function automatically creates a glyph */
- /* slot for the face object which can be accessed directly through */
+ /* slot for the face object that can be accessed directly through */
/* `face->glyph'. */
/* */
/* FT_Open_Face can be used to quickly check whether the font */
/* if the font format is recognized, or non-zero otherwise; */
/* the function returns a more or less empty face handle in `*aface' */
/* (if `aface' isn't NULL). The only useful field in this special */
- /* case is `face->num_faces' which gives the number of faces within */
+ /* case is `face->num_faces' that gives the number of faces within */
/* the font file. After examination, the returned @FT_Face structure */
/* should be deallocated with a call to @FT_Done_Face. */
/* */
/* face :: The target face object. */
/* */
/* <Input> */
- /* parameters :: A pointer to @FT_Open_Args which must be filled by */
+ /* parameters :: A pointer to @FT_Open_Args that must be filled by */
/* the caller. */
/* */
/* <Return> */
/* then only destroys a face if the counter is~1, otherwise it simply */
/* decrements the counter. */
/* */
- /* This function helps in managing life-cycles of structures which */
+ /* This function helps in managing life-cycles of structures that */
/* reference @FT_Face objects. */
/* */
/* <Input> */
/* particular bitmap strike. Use @FT_Select_Size instead in that */
/* case. */
/* */
+ /* The relation between the requested size and the resulting glyph */
+ /* size is dependent entirely on how the size is defined in the */
+ /* source face. The font designer chooses the final size of each */
+ /* glyph relative to this size. For more information refer to */
+ /* `http://www.freetype.org/freetype2/docs/glyphs/glyphs-2.html' */
+ /* */
+ /* Don't use this function if you are using the FreeType cache API. */
+ /* */
FT_EXPORT( FT_Error )
FT_Request_Size( FT_Face face,
FT_Size_Request req );
/* <Return> */
/* FreeType error code. 0~means success. */
/* */
+ /* <Note> */
+ /* You should not rely on the resulting glyphs matching, or being */
+ /* constrained, to this pixel size. Refer to @FT_Request_Size to */
+ /* understand how requested sizes relate to actual sizes. */
+ /* */
+ /* Don't use this function if you are using the FreeType cache API. */
+ /* */
FT_EXPORT( FT_Error )
FT_Set_Pixel_Sizes( FT_Face face,
FT_UInt pixel_width,
/* the details. */
/* */
/* For subsetted CID-keyed fonts, `FT_Err_Invalid_Argument' is */
- /* returned for invalid CID values (this is, for CID values which */
+ /* returned for invalid CID values (this is, for CID values that */
/* don't have a corresponding glyph in the font). See the discussion */
/* of the @FT_FACE_FLAG_CID_KEYED flag for more details. */
/* */
* behaviour to more specific and useful cases.
*
* FT_LOAD_NO_SCALE ::
- * Don't scale the outline glyph loaded, but keep it in font units.
+ * Don't scale the loaded outline glyph but keep it in font units.
*
* This flag implies @FT_LOAD_NO_HINTING and @FT_LOAD_NO_BITMAP, and
* unsets @FT_LOAD_RENDER.
*
+ * If the font is `tricky' (see @FT_FACE_FLAG_TRICKY for more), using
+ * FT_LOAD_NO_SCALE usually yields meaningless outlines because the
+ * subglyphs must be scaled and positioned with hinting instructions.
+ * This can be solved by loading the font without FT_LOAD_NO_SCALE and
+ * setting the character size to `font->units_per_EM'.
+ *
* FT_LOAD_NO_HINTING ::
- * Disable hinting. This generally generates `blurrier' bitmap glyph
- * when the glyph is rendered in any of the anti-aliased modes. See
+ * Disable hinting. This generally generates `blurrier' bitmap glyphs
+ * when the glyph are rendered in any of the anti-aliased modes. See
* also the note below.
*
* This flag is implied by @FT_LOAD_NO_SCALE.
* @FT_LOAD_NO_SCALE always sets this flag.
*
* FT_LOAD_VERTICAL_LAYOUT ::
- * Load the glyph for vertical text layout. _Don't_ use it as it is
- * problematic currently.
+ * Load the glyph for vertical text layout. In particular, the
+ * `advance' value in the @FT_GlyphSlotRec structure is set to the
+ * `vertAdvance' value of the `metrics' field.
+ *
+ * In case @FT_HAS_VERTICAL doesn't return true, you shouldn't use
+ * this flag currently. Reason is that in this case vertical metrics
+ * get synthesized, and those values are not always consistent across
+ * various font formats.
*
* FT_LOAD_FORCE_AUTOHINT ::
* Indicates that the auto-hinter is preferred over the font's native
* hinter. See also the note below.
*
- * FT_LOAD_CROP_BITMAP ::
- * Indicates that the font driver should crop the loaded bitmap glyph
- * (i.e., remove all space around its black bits). Not all drivers
- * implement this.
- *
* FT_LOAD_PEDANTIC ::
* Indicates that the font driver should perform pedantic verifications
* during glyph loading. This is mostly used to detect broken glyphs
* result in partially hinted or distorted glyphs in case a glyph's
* bytecode is buggy.
*
- * FT_LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH ::
- * Ignored. Deprecated.
- *
* FT_LOAD_NO_RECURSE ::
- * This flag is only used internally. It merely indicates that the
- * font driver should not load composite glyphs recursively. Instead,
- * it should set the `num_subglyph' and `subglyphs' values of the
- * glyph slot accordingly, and set `glyph->format' to
- * @FT_GLYPH_FORMAT_COMPOSITE.
- *
- * The description of sub-glyphs is not available to client
- * applications for now.
+ * Indicate that the font driver should not load composite glyphs
+ * recursively. Instead, it should set the `num_subglyph' and
+ * `subglyphs' values of the glyph slot accordingly, and set
+ * `glyph->format' to @FT_GLYPH_FORMAT_COMPOSITE. The description of
+ * subglyphs can then be accessed with @FT_Get_SubGlyph_Info.
*
* This flag implies @FT_LOAD_NO_SCALE and @FT_LOAD_IGNORE_TRANSFORM.
*
* FT_LOAD_NO_AUTOHINT ::
* Disable auto-hinter. See also the note below.
*
+ * FT_LOAD_COLOR ::
+ * This flag is used to request loading of color embedded-bitmap
+ * images. The resulting color bitmaps, if available, will have the
+ * @FT_PIXEL_MODE_BGRA format. When the flag is not used and color
+ * bitmaps are found, they will be converted to 256-level gray
+ * bitmaps transparently. Those bitmaps will be in the
+ * @FT_PIXEL_MODE_GRAY format.
+ *
+ * FT_LOAD_CROP_BITMAP ::
+ * Ignored. Deprecated.
+ *
+ * FT_LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH ::
+ * Ignored. Deprecated.
+ *
* @note:
* By default, hinting is enabled and the font's native hinter (see
* @FT_FACE_FLAG_HINTER) is preferred over the auto-hinter. You can
* Besides deciding which hinter to use, you can also decide which
* hinting algorithm to use. See @FT_LOAD_TARGET_XXX for details.
*
+ * Note that the auto-hinter needs a valid Unicode cmap (either a native
+ * one or synthesized by FreeType) for producing correct results. If a
+ * font provides an incorrect mapping (for example, assigning the
+ * character code U+005A, LATIN CAPITAL LETTER Z, to a glyph depicting a
+ * mathematical integral sign), the auto-hinter might produce useless
+ * results.
+ *
*/
#define FT_LOAD_DEFAULT 0x0
#define FT_LOAD_NO_SCALE ( 1L << 0 )
#define FT_LOAD_MONOCHROME ( 1L << 12 )
#define FT_LOAD_LINEAR_DESIGN ( 1L << 13 )
#define FT_LOAD_NO_AUTOHINT ( 1L << 15 )
+ /* Bits 16..19 are used by `FT_LOAD_TARGET_' */
+#define FT_LOAD_COLOR ( 1L << 20 )
/* */
* `load_flags'. They can't be ORed.
*
* If @FT_LOAD_RENDER is also set, the glyph is rendered in the
- * corresponding mode (i.e., the mode which matches the used algorithm
- * best) unless @FT_LOAD_MONOCHROME is set.
+ * corresponding mode (i.e., the mode that matches the used algorithm
+ * best). An exeption is FT_LOAD_TARGET_MONO since it implies
+ * @FT_LOAD_MONOCHROME.
*
* You can use a hinting algorithm that doesn't correspond to the same
* rendering mode. As an example, it is possible to use the `light'
} FT_Render_Mode;
- /*************************************************************************/
- /* */
- /* <Enum> */
- /* ft_render_mode_xxx */
- /* */
- /* <Description> */
- /* These constants are deprecated. Use the corresponding */
- /* @FT_Render_Mode values instead. */
- /* */
- /* <Values> */
- /* ft_render_mode_normal :: see @FT_RENDER_MODE_NORMAL */
- /* ft_render_mode_mono :: see @FT_RENDER_MODE_MONO */
- /* */
+ /* these constants are deprecated; use the corresponding */
+ /* `FT_Render_Mode' values instead */
#define ft_render_mode_normal FT_RENDER_MODE_NORMAL
#define ft_render_mode_mono FT_RENDER_MODE_MONO
/* <Return> */
/* FreeType error code. 0~means success. */
/* */
+ /* <Note> */
+ /* To get meaningful results, font scaling values must be set with */
+ /* functions like @FT_Set_Char_Size before calling FT_Render_Glyph. */
+ /* */
FT_EXPORT( FT_Error )
FT_Render_Glyph( FT_GlyphSlot slot,
FT_Render_Mode render_mode );
} FT_Kerning_Mode;
- /*************************************************************************/
- /* */
- /* <Const> */
- /* ft_kerning_default */
- /* */
- /* <Description> */
- /* This constant is deprecated. Please use @FT_KERNING_DEFAULT */
- /* instead. */
- /* */
+ /* these constants are deprecated; use the corresponding */
+ /* `FT_Kerning_Mode' values instead */
#define ft_kerning_default FT_KERNING_DEFAULT
-
-
- /*************************************************************************/
- /* */
- /* <Const> */
- /* ft_kerning_unfitted */
- /* */
- /* <Description> */
- /* This constant is deprecated. Please use @FT_KERNING_UNFITTED */
- /* instead. */
- /* */
#define ft_kerning_unfitted FT_KERNING_UNFITTED
-
-
- /*************************************************************************/
- /* */
- /* <Const> */
- /* ft_kerning_unscaled */
- /* */
- /* <Description> */
- /* This constant is deprecated. Please use @FT_KERNING_UNSCALED */
- /* instead. */
- /* */
#define ft_kerning_unscaled FT_KERNING_UNSCALED
/* */
/* glyph_index :: The glyph index. */
/* */
- /* buffer_max :: The maximal number of bytes available in the */
+ /* buffer_max :: The maximum number of bytes available in the */
/* buffer. */
/* */
/* <Output> */
/* glyph index~0 always corresponds to the `missing glyph' (called */
/* `.notdef'). */
/* */
- /* This function is not compiled within the library if the config */
- /* macro `FT_CONFIG_OPTION_NO_GLYPH_NAMES' is defined in */
- /* `include/freetype/config/ftoptions.h'. */
+ /* This function always returns an error if the config macro */
+ /* `FT_CONFIG_OPTION_NO_GLYPH_NAMES' is not defined in `ftoptions.h'. */
/* */
FT_EXPORT( FT_Error )
FT_Get_Glyph_Name( FT_Face face,
/* */
/* Because many fonts contain more than a single cmap for Unicode */
/* encoding, this function has some special code to select the one */
- /* which covers Unicode best (`best' in the sense that a UCS-4 cmap */
- /* is preferred to a UCS-2 cmap). It is thus preferable to */
+ /* that covers Unicode best (`best' in the sense that a UCS-4 cmap is */
+ /* preferred to a UCS-2 cmap). It is thus preferable to */
/* @FT_Set_Charmap in this case. */
/* */
FT_EXPORT( FT_Error )
/* <Note> */
/* If you use FreeType to manipulate the contents of font files */
/* directly, be aware that the glyph index returned by this function */
- /* doesn't always correspond to the internal indices used within */
- /* the file. This is done to ensure that value~0 always corresponds */
- /* to the `missing glyph'. */
+ /* doesn't always correspond to the internal indices used within the */
+ /* file. This is done to ensure that value~0 always corresponds to */
+ /* the `missing glyph'. If the first glyph is not named `.notdef', */
+ /* then for Type~1 and Type~42 fonts, `.notdef' will be moved into */
+ /* the glyph ID~0 position, and whatever was there will be moved to */
+ /* the position `.notdef' had. For Type~1 fonts, if there is no */
+ /* `.notdef' glyph at all, then one will be created at index~0 and */
+ /* whatever was there will be moved to the last index -- Type~42 */
+ /* fonts are considered invalid under this condition. */
/* */
FT_EXPORT( FT_UInt )
FT_Get_Char_Index( FT_Face face,
/* */
/* <Note> */
/* Use this function rather than directly reading the `fs_type' field */
- /* in the @PS_FontInfoRec structure which is only guaranteed to */
+ /* in the @PS_FontInfoRec structure, which is only guaranteed to */
/* return the correct results for Type~1 fonts. */
/* */
/* <Since> */
/* code range for CJK characters. */
/* */
/* An IVS is registered and unique; for further details please refer */
- /* to Unicode Technical Report #37, the Ideographic Variation */
- /* Database. To date (October 2007), the character with the most */
- /* variants is U+908A, having 8~such IVS. */
+ /* to Unicode Technical Standard #37, the Ideographic Variation */
+ /* Database: */
+ /* */
+ /* http://www.unicode.org/reports/tr37/ */
+ /* */
+ /* To date (November 2014), the character with the most variants is */
+ /* U+9089, having 32 such IVS. */
/* */
/* Adobe and MS decided to support IVS with a new cmap subtable */
/* (format~14). It is an odd subtable because it is not a mapping of */
/* The character codepoint in Unicode. */
/* */
/* <Return> */
- /* A pointer to an array of variant selector code points which are */
+ /* A pointer to an array of variant selector code points that are */
/* active for the given character, or NULL if the corresponding list */
/* is empty. */
/* */
/* The variant selector code point in Unicode. */
/* */
/* <Return> */
- /* A list of all the code points which are specified by this selector */
+ /* A list of all the code points that are specified by this selector */
/* (both default and non-default codes are returned) or NULL if there */
/* is no valid cmap or the variant selector is invalid. */
/* */
/* */
/* <Description> */
/* A very simple function used to perform the computation `(a*b)/c' */
- /* with maximal accuracy (it uses a 64-bit intermediate integer */
+ /* with maximum accuracy (it uses a 64-bit intermediate integer */
/* whenever necessary). */
/* */
/* This function isn't necessarily as fast as some processor specific */
FT_Long c );
- /* */
-
- /* The following #if 0 ... #endif is for the documentation formatter, */
- /* hiding the internal `FT_MULFIX_INLINED' macro. */
-
-#if 0
/*************************************************************************/
/* */
/* <Function> */
/* */
/* <Description> */
/* A very simple function used to perform the computation */
- /* `(a*b)/0x10000' with maximal accuracy. Most of the time this is */
- /* used to multiply a given value by a 16.16 fixed float factor. */
+ /* `(a*b)/0x10000' with maximum accuracy. Most of the time this is */
+ /* used to multiply a given value by a 16.16 fixed-point factor. */
/* */
/* <Input> */
/* a :: The first multiplier. */
FT_MulFix( FT_Long a,
FT_Long b );
- /* */
-#endif
-
-#ifdef FT_MULFIX_INLINED
-#define FT_MulFix( a, b ) FT_MULFIX_INLINED( a, b )
-#else
- FT_EXPORT( FT_Long )
- FT_MulFix( FT_Long a,
- FT_Long b );
-#endif
-
/*************************************************************************/
/* */
/* */
/* <Description> */
/* A very simple function used to perform the computation */
- /* `(a*0x10000)/b' with maximal accuracy. Most of the time, this is */
- /* used to divide a given value by a 16.16 fixed float factor. */
+ /* `(a*0x10000)/b' with maximum accuracy. Most of the time, this is */
+ /* used to divide a given value by a 16.16 fixed-point factor. */
/* */
/* <Input> */
- /* a :: The first multiplier. */
- /* b :: The second multiplier. Use a 16.16 factor here whenever */
- /* possible (see note below). */
+ /* a :: The numerator. */
+ /* b :: The denominator. Use a 16.16 factor here. */
/* */
/* <Return> */
/* The result of `(a*0x10000)/b'. */
/* */
- /* <Note> */
- /* The optimization for FT_DivFix() is simple: If (a~<<~16) fits in */
- /* 32~bits, then the division is computed directly. Otherwise, we */
- /* use a specialized version of @FT_MulDiv. */
- /* */
FT_EXPORT( FT_Long )
FT_DivFix( FT_Long a,
FT_Long b );
/* even a new release of FreeType with only documentation changes */
/* increases the version number. */
/* */
+ /* <Order> */
+ /* FT_Library_Version */
+ /* */
+ /* FREETYPE_MAJOR */
+ /* FREETYPE_MINOR */
+ /* FREETYPE_PATCH */
+ /* */
+ /* FT_Face_CheckTrueTypePatents */
+ /* FT_Face_SetUnpatentedHinting */
+ /* */
+ /* FREETYPE_XXX */
+ /* */
/*************************************************************************/
*
*/
#define FREETYPE_MAJOR 2
-#define FREETYPE_MINOR 4
-#define FREETYPE_PATCH 9
+#define FREETYPE_MINOR 5
+#define FREETYPE_PATCH 5
/*************************************************************************/
projects / framework / graphics / freetype.git / blobdiff