ref: e6bb95336ac164d37a89d7c4bd77025d6964f003
parent: 53be6e9b1bca447fdb3d347ba3331eeaffe5aae1
author: David Turner <[email protected]>
date: Fri Dec 23 08:32:06 EST 2005
* Jamfile, docs/reference/README: fix it so that "jam refdoc" works correctly to generate the API reference in 'docs/reference' * src/tools/docmaker/tohtml.py: update to output nicer fields lists in the API reference * src/base/ftobjs.c (FT_Load_Glyph): FT_LOAD_TARGET_LIGHT now forces auto-hinting * freetype/freetype.h: updating the documentation for FT_LOAD_TARGET_XXX and FT_Render_Mode values
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2005-12-23 David Turner <[email protected]>
+
+ * Jamfile, docs/reference/README: fix it so that "jam refdoc" works
+ correctly to generate the API reference in 'docs/reference'
+
+ * src/tools/docmaker/tohtml.py: update to output nicer fields lists
+ in the API reference
+
+ * src/base/ftobjs.c (FT_Load_Glyph): FT_LOAD_TARGET_LIGHT now
+ forces auto-hinting
+
+ * freetype/freetype.h: updating the documentation for
+ FT_LOAD_TARGET_XXX and FT_Render_Mode values
+
+
2005-12-23 suzuki toshiya <[email protected]>
* src/base/ftmac.c (FT_New_Face_From_Suitcase): Counts scalable
--- a/Jamfile
+++ b/Jamfile
@@ -181,6 +181,13 @@
SubInclude FT2_TOP tests ;
}
+rule RefDoc
+{+ Depends $1 : all ;
+ NotFile $1 ;
+ Always $1 ;
+}
+
actions RefDoc
{python $(FT2_SRC)/tools/docmaker/docmaker.py --prefix=ft2 --title=FreeType-2.1.10 --output=$(DOC_DIR) $(FT2_INCLUDE)/freetype/*.h $(FT2_INCLUDE)/freetype/config/*.h $(FT2_INCLUDE)/freetype/cache/*.h
--- a/docs/CHANGES
+++ b/docs/CHANGES
@@ -14,6 +14,10 @@
II. IMPORTANT CHANGES
+ - the LIGHT hinting algorithm produces more pleasant results. Also,
+ using the FT_LOAD_TARGET_LIGHT flags within FT_Load_Glyph will always
+ force auto-hinting, as a special exception.
+
- Face metrics (face->size->metrics) and glyph metrics are no
longer rounded. If you do not round in your applications too,
you may find glyphs become blurry.
@@ -43,6 +47,11 @@
III. MISCELLANEOUS
+ - the documentation for FT_LOAD_TARGET_XXX and FT_RENDER_MODE_XXX
+ values have been updated to better reflect their uses and differences
+ (one set is used to specify hinting algorithm, the other to specify
+ pixel rendering mode).
+
- FT_New_Face() & FT_New_Face_From_FSSpec() in ftmac.c are changed
to count supported scalable faces (sfnt, LWFN) only, and returns
the number of available faces via face->num_faces. Unsupported
@@ -96,15 +105,15 @@
highly recommended to upgrade.
- FreeType didn't properly parse empty Type 1 glyphs.
-
+
- An unbound dynamic buffer growth was fixed in the PFR loader.
-
+
- Several bugs have been fixed in the cache sub-system.
- FreeType behaved incorrectly when resizing two distinct but very
close character pixel sizes through `FT_Set_Char_Size' (Savannah
bug #12263).
-
+
- The auto-hinter didn't work properly for fonts without a Unicode
charmap -- it even refused to load the glyphs.
@@ -184,7 +193,7 @@
PIC mode (i.e., when generating a Unix shared object/dll) put
the array into the non-shared writable section of the library
since absolute pointers are not relocatable by nature.
-
+
This reduces the memory consumption by approximately 16KByte per
process linked to FreeType. We now also store the array in a
compressed form (as a trie) which saves about 20KByte of code as
--- a/docs/reference/README
+++ b/docs/reference/README
@@ -1,2 +1,5 @@
After saying `make refdoc' this directory contains the FreeType API
reference. You need python to make this target.
+
+This also works with Jam, just type 'jam refdoc' in the main directory.
+
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -2356,7 +2356,7 @@
* FT_LOAD_IGNORE_TRANSFORM ::
* Indicates that the glyph loader should not try to transform the
* loaded glyph image. This doesn't prevent scaling, hinting, or
- * rendering.
+ * rendering. See @FT_Set_Transform
*
* FT_LOAD_MONOCHROME ::
* This flag is used with @FT_LOAD_RENDER to indicate that you want
@@ -2379,34 +2379,9 @@
* See also FT_FACE_FLAG_HINTER (@FT_FACE_FLAG_XXX), FT_LOAD_FORCE_AUTO,
* and FT_LOAD_NO_HINTING above.
*
- * FT_LOAD_TARGET_NORMAL ::
- * Use hinting for @FT_RENDER_MODE_NORMAL.
- *
- * FT_LOAD_TARGET_LIGHT ::
- * Use hinting for @FT_RENDER_MODE_LIGHT.
- *
- * FT_LOAD_TARGET_MONO ::
- * Use hinting for @FT_RENDER_MODE_MONO.
- *
- * FT_LOAD_TARGET_LCD ::
- * Use hinting for @FT_RENDER_MODE_LCD.
- *
- * FT_LOAD_TARGET_LCD_V ::
- * Use hinting for @FT_RENDER_MODE_LCD_V.
- *
* @note:
- * You should use only _one_ of the FT_LOAD_TARGET_XXX values; they
- * can't be ORed.
- *
- * However, FreeType makes a distinction between the hinting algorithm
- * being used, and the pixel mode of the target bitmaps. For example,
- * it is possible to use the `light' hinting algorithm and have the
- * results rendered in horizontal LCD pixel mode, with code like this:
- *
- * FT_Load_Glyph( face, glyph_index,
- * load_flags | FT_LOAD_TARGET_LIGHT );
- * FT_Render_Glyph( face->glyph, FT_RENDER_MODE_LCD );
- *
+ * see also @FT_LOAD_TARGET_XXX which relate to hinting algorithm
+ * selection.
*/
#define FT_LOAD_DEFAULT 0x0
#define FT_LOAD_NO_SCALE 0x1
@@ -2429,8 +2404,72 @@
/* */
+ /**************************************************************************
+ *
+ * @enum: FT_LOAD_TARGET_XXX
+ *
+ * @description:
+ * a list of values that are used to select a specific hinting
+ * algorithm to the glyph loader. You should OR one of these values
+ * to your 'load_flags' when calling @FT_Load_Glyph.
+ *
+ * note that these values are only used by the auto-hinter, and ignored
+ * by the native ones (e.g. the TrueType bytecode interpreter). You
+ * must use @FT_LOAD_FORCE_AUTOHINT to ensure that they're always used.
+ *
+ * @FT_LOAD_TARGET_LIGHT being an exception, that always forces the
+ * auto-hinter.
+ *
+ * @values:
+ * FT_LOAD_TARGET_NORMAL ::
+ * correspond to the default hinting algorithm, optimized for standard
+ * gray-level rendering. for monochrome output, use @FT_RENDER_MODE_MONO
+ * instead.
+ *
+ * FT_LOAD_TARGET_LIGHT ::
+ * correspond to a lighter hinting algorithm for non-monochrome modes.
+ * This will generate more glyphs that are more fuzzy but more faithful
+ * to their original shape. A bit like Mac OS X.
+ *
+ * As a special exception, this values *always* forces auto-hinting,
+ * whatever the native hinter is.
+ *
+ * FT_LOAD_TARGET_MONO ::
+ * strong hinting algorithm that should only be used for monochrome
+ * output. The result will probably be unpleasant for other rendering
+ * modes.
+ *
+ * FT_LOAD_TARGET_LCD ::
+ * a variant of @FT_LOAD_TARGET_NORMAL optimized for horizontally
+ * decimated LCD displays.
+ *
+ * FT_LOAD_TARGET_LCD_V ::
+ * a variant of @FT_LOAD_TARGET_NORMAL optimized for vertically decimated
+ * LCD displays.
+ *
+ * @note:
+ * You should use only _one_ of the FT_LOAD_TARGET_XXX values in your
+ * 'load_flags'. They can't be ORed.
+ *
+ * If you also use the @FT_LOAD_RENDER flag, then the output will be
+ * determined by the corresponding @FT_Render_Mode value. E.g.
+ * @FT_LOAD_TARGET_NORMAL will generate a gray-level pixmap
+ * (see @FT_RENDER_MODE_NORMAL)
+ *
+ * You can use a hinting algorithm that doesn't correspond to the same
+ * rendering mode. For example, it is possible to use the `light' hinting
+ * algorithm and have the results rendered in horizontal LCD pixel mode,
+ * with code like this:
+ *
+ * {+ * FT_Load_Glyph( face, glyph_index,
+ * load_flags | FT_LOAD_TARGET_LIGHT );
+ *
+ * FT_Render_Glyph( face->glyph, FT_RENDER_MODE_LCD );
+ * }
+ */
+
#define FT_LOAD_TARGET_( x ) ( (FT_Int32)( (x) & 15 ) << 16 )
-#define FT_LOAD_TARGET_MODE( x ) ( (FT_Render_Mode)( ( (x) >> 16 ) & 15 ) )
#define FT_LOAD_TARGET_NORMAL FT_LOAD_TARGET_( FT_RENDER_MODE_NORMAL )
#define FT_LOAD_TARGET_LIGHT FT_LOAD_TARGET_( FT_RENDER_MODE_LIGHT )
@@ -2438,6 +2477,15 @@
#define FT_LOAD_TARGET_LCD FT_LOAD_TARGET_( FT_RENDER_MODE_LCD )
#define FT_LOAD_TARGET_LCD_V FT_LOAD_TARGET_( FT_RENDER_MODE_LCD_V )
+/**
+ * @macro: FT_LOAD_TARGET_MODE
+ *
+ * @description:
+ * return the @FT_Render_Mode corresponding to a given @FT_LOAD_TARGET_XXX
+ * value.
+ */
+#define FT_LOAD_TARGET_MODE( x ) ( (FT_Render_Mode)( ( (x) >> 16 ) & 15 ) )
+
/* */
@@ -2480,8 +2528,7 @@
/* <Description> */
/* An enumeration type that lists the render modes supported by */
/* FreeType 2. Each mode corresponds to a specific type of scanline */
- /* conversion performed on the outline, as well as specific */
- /* hinting optimizations. */
+ /* conversion performed on the outline. */
/* */
/* For bitmap fonts the `bitmap->pixel_mode' field in the */
/* @FT_GlyphSlotRec structure gives the format of the returned */
@@ -2493,15 +2540,11 @@
/* anti-aliased bitmaps, using 256 levels of opacity. */
/* */
/* FT_RENDER_MODE_LIGHT :: */
- /* This is similar to @FT_RENDER_MODE_NORMAL -- you have to use */
- /* @FT_LOAD_TARGET_LIGHT in calls to @FT_Load_Glyph to get any */
- /* effect since the rendering process no longer influences the */
- /* positioning of glyph outlines. */
+ /* This is equivalent to @FT_RENDER_MODE_NORMAL. It is only defined */
+ /* as a separate value because render modes are also used */
+ /* indirectly to define hinting algorithm selectors. See */
+ /* @FT_LOAD_TARGET_XXX for details. */
/* */
- /* The resulting glyph shapes are more similar to the original, */
- /* while being a bit more fuzzy (`better shapes' instead of `better */
- /* contrast', so to say. */
- /* */
/* FT_RENDER_MODE_MONO :: */
/* This mode corresponds to 1-bit bitmaps. */
/* */
@@ -2691,7 +2734,8 @@
/* */
/* <Description> */
/* Retrieves the ASCII name of a given glyph in a face. This only */
- /* works for those faces where FT_HAS_GLYPH_NAME(face) returns true. */
+ /* works for those faces where @FT_HAS_GLYPH_NAMES(face) returns */
+ /* TRUE. */
/* */
/* <Input> */
/* face :: A handle to a source face object. */
--- a/src/base/ftobjs.c
+++ b/src/base/ftobjs.c
@@ -523,6 +523,11 @@
FT_LOAD_NO_AUTOHINT ) ) &&
FT_DRIVER_IS_SCALABLE( driver ) &&
FT_DRIVER_USES_OUTLINES( driver ) );
+
+ /* force auto-hinting for the LIGHT hinting mode */
+ if ( autohint && FT_LOAD_TARGET_MODE(load_flags) == FT_RENDER_MODE_LIGHT )
+ load_flags |= FT_LOAD_FORCE_AUTOHINT;
+
if ( autohint )
{if ( FT_DRIVER_HAS_HINTER( driver ) &&
--- a/src/tools/docmaker/tohtml.py
+++ b/src/tools/docmaker/tohtml.py
@@ -192,6 +192,7 @@
url = self.make_block_url( block )
return '<a href="' + url + '">' + name + '</a>' + rest
except:
+ # we detected a cross-reference to an unknown item
return '?' + name + '?' + rest
# look for italics and bolds
@@ -246,7 +247,7 @@
def print_html_field( self, field ):
if field.name:
- print "<table><tr valign=top><td><b>"+field.name+"</b></td><td>"
+ print "<table><tr valign=top><td><p><b>"+field.name+"</b></p></td><td>"
print self.make_html_items( field.items )
@@ -288,9 +289,14 @@
def print_html_field_list( self, fields ):
- print "<table cellpadding=3>"
+ print "<table cellpadding=3 border=0>"
for field in fields:
- print "<tr valign=top><td><b>" + field.name + "</b></td><td>"
+ if len(field.name) > 22:
+ print "<tr valign=top><td colspan=0><b>"+field.name+"</b></td></tr>"
+ print "<tr valign=top><td></td><td>"
+ else:
+ print "<tr valign=top><td><b>" + field.name + "</b></td><td>"
+
self.print_html_items( field.items )
print "</td></tr>"
print "</table>"
@@ -488,4 +494,4 @@
def section_dump_all( self ):
for section in self.sections:
self.section_dump( section, self.file_prefix + section.name + '.html' )
-
+