diff options
Diffstat (limited to 'include/freetype/freetype.h')
| -rw-r--r-- | include/freetype/freetype.h | 124 |
1 files changed, 91 insertions, 33 deletions
diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h index 63c291a..0d5680b 100644 --- a/include/freetype/freetype.h +++ b/include/freetype/freetype.h @@ -4,7 +4,7 @@ /* */ /* FreeType high-level API and common types (specification only). */ /* */ -/* Copyright 1996-2012 by */ +/* Copyright 1996-2013 by */ /* David Turner, Robert Wilhelm, and Werner Lemberg. */ /* */ /* This file is part of the FreeType project, and may only be used, */ @@ -16,6 +16,10 @@ /***************************************************************************/ +#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." @@ -25,14 +29,10 @@ #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 @@ -237,6 +237,10 @@ FT_BEGIN_HEADER /* 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; @@ -844,8 +848,8 @@ FT_BEGIN_HEADER /* 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. */ /* */ @@ -871,19 +875,22 @@ FT_BEGIN_HEADER /* 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 */ @@ -1105,8 +1112,8 @@ FT_BEGIN_HEADER * 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 ) \ @@ -1338,7 +1345,7 @@ FT_BEGIN_HEADER /* 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> */ @@ -2227,6 +2234,12 @@ FT_BEGIN_HEADER /* 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' */ + /* */ FT_EXPORT( FT_Error ) FT_Request_Size( FT_Face face, FT_Size_Request req ); @@ -2296,6 +2309,11 @@ FT_BEGIN_HEADER /* <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. */ + /* */ FT_EXPORT( FT_Error ) FT_Set_Pixel_Sizes( FT_Face face, FT_UInt pixel_width, @@ -2409,14 +2427,20 @@ FT_BEGIN_HEADER * 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. @@ -2435,8 +2459,14 @@ FT_BEGIN_HEADER * @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 @@ -2493,6 +2523,14 @@ FT_BEGIN_HEADER * 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. + * * @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 @@ -2507,6 +2545,13 @@ FT_BEGIN_HEADER * 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 ) @@ -2523,6 +2568,8 @@ FT_BEGIN_HEADER #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 ) /* */ @@ -2580,7 +2627,8 @@ FT_BEGIN_HEADER * * 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. + * 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' @@ -2922,7 +2970,7 @@ FT_BEGIN_HEADER /* */ /* 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> */ @@ -3081,9 +3129,15 @@ FT_BEGIN_HEADER /* <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, @@ -3383,9 +3437,13 @@ FT_BEGIN_HEADER /* 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 2012), the character with the most variants is */ + /* U+9089, having 31 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 */ @@ -3614,7 +3672,7 @@ FT_BEGIN_HEADER /* */ /* <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 */ @@ -3649,8 +3707,8 @@ FT_BEGIN_HEADER /* */ /* <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. */ @@ -3694,8 +3752,8 @@ FT_BEGIN_HEADER /* */ /* <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. */ @@ -3834,7 +3892,7 @@ FT_BEGIN_HEADER */ #define FREETYPE_MAJOR 2 #define FREETYPE_MINOR 4 -#define FREETYPE_PATCH 9 +#define FREETYPE_PATCH 12 /*************************************************************************/ |