Index: include/freetype/freetype.h |
diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h |
index 63c291af1270c8a1c4ba40388b000f0710ea38c6..0d5680bdba651b6d0c3b7dcf404abc9001826c88 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 |
/*************************************************************************/ |