- FT_Library library; /* handle to library */
- FT_Face face; /* handle to face object */
-
- error = FT_Init_FreeType( &library );
- if (error) { ..... }
-
- error = FT_New_Memory_Face( library,
- buffer, /* first byte in memory */
- size, /* size in bytes */
- 0, /* face_index */
- &face );
- if (error) { ... }
+ FT_Library library; /* handle to library */
+ FT_Face face; /* handle to face object */
+
+ error = FT_Init_FreeType( &library );
+ if (error) { ..... }
+
+ error = FT_New_Memory_Face( library,
+ buffer, /* first byte in memory */
+ size, /* size in bytes */
+ 0, /* face_index */
+ &face );
+ if (error) { ... }
As you can see, FT_New_Memory_Face simply takes a pointer to
@@ -185,38 +185,17 @@ FreeType 2.0 Tutorial
-
c. From other sources:
+
c. From other sources: (compressed files, network, etc..)
There are cases where using a filepathname or preloading the file in
memory is simply not enough. With FreeType 2, it is possible to provide
- your own implementation of i/o routines through the FT_Stream
- type.
+ your own implementation of i/o routines.
- Basically, one has to set up a FT_Stream object, according to
- the rules defined in the document named
- FreeType 2 System Interface, then pass it to the function
- FT_Open_Face as in:
-
-
-
- FT_Library library; /* handle to library */
- FT_Face face; /* handle to face object */
-
- error = FT_Init_FreeType( &library );
- if (error) { ..... }
-
- ... set up stream object, with handle "stream" ...
-
- error = FT_Open_Face( library,
- stream, /* handle to stream objects */
- 0, /* face_index */
- &face );
- if (error) { ... }
-
-
- custom implementations of FT_Stream are great to provide advanced
- features like automatic support of compressed files, network transparency,
- using UTF-16 file pathnames, etc..
+ This is done through the FT_Open_Face function, which can be
+ used to open a new font face with a custom input stream, select a specific
+ driver for opening, or even pass extra parameters to the font driver
+ when creating the object. We advise you to refer to the FreeType 2
+ Reference in order to learn how to use it.
@@ -396,7 +375,7 @@ FreeType 2.0 Tutorial
The glyph image is always stored in a special object called a
glyph slot. As it names suggests, a glyph slot is simply a
container that is able to hold one glyph image at a time, be it a bitmap,
- an outline, or something else. Each face object has a single glyph
+ an outline, or something else. Each face object has a single glyph slot
object that can be accessed as face−>glyph.
Loading a glyph image into the slot is performed by calling
@@ -440,14 +419,16 @@ FreeType 2.0 Tutorial
As said before, when a new face object is created, it will look for
a Unicode, Latin-1 or ASCII charmap and select it. The currently
selected charmap is accessed via face−>charmap. This
- field is NULL when no charmap is selected.
+ field is NULL when no charmap is selected, which typically happen when you
+ create a new FT_Face object from a font file that doesn't contain
+ an ASCII, Latin-1 or Unicode charmap (rare stuff).
- The field face−>num_charmaps and
+ The fields face−>num_charmaps and
face−>charmaps (notice the 's') can be used by
client applications to look at what charmaps are available in a given
face.
- face−charmaps is an array of pointers
+ face−>charmaps is an array of pointers
to the face−>num_charmaps charmaps contained in the
font face.
@@ -493,23 +474,31 @@ FreeType 2.0 Tutorial
7. Accessing glyph image data:
- Glyph image data is accessible through face−glyph.
- See the definition of the FT_GlyphSlot type on more details. You
- can perfectly create a shortcut to the glyph slot as in:
+ Glyph image data is accessible through face−>glyph.
+ See the definition of the FT_GlyphSlot type for more details. As
+ stated previously, each face has a single glyph slot, where one glyph
+ image at a time can be loaded. Each time you call
+ FT_Load_Glyph, you erase the content of the glyph slot with a new
+ glyph image.
+
+ Note however that the glyph slot object itself doesn't change, only its
+ content, which means that you can perfectly create a "shortcut" to access
+ it as in:
{
- FT_GlyphSlot glyph;
+ FT_GlyphSlot glyph = face->glyph; /* shortcut to glyph slot */
- .... load glyph ...
-
- glyph = face->glyph; /* shortcut to glyph data */
-
- .... access glyph data as glyph->xxxx
+ for ( n = 0; n < face->num_glyphs; n++ )
+ {
+ .... load glyph n...
+ .... access glyph data as glyph->xxxx
+ }
}
-
- For example, one can access the following fields:
+
+ The glyph variable will be valid until its parent face
+ is destroyed. Here are a few important fields of the glyph slot:
@@ -521,30 +510,41 @@ FreeType 2.0 Tutorial
glyph−>metrics
A simple structure used to hold the glyph image's metrics. Note
- that all distances are expressed in 1/64th of pixels !
+ that most distances are expressed in 1/64th of pixels !
See the API reference or User Guide for a description of the
FT_Glyph_Metrics structure.
-
+
glyph−>bitmap
When the glyph slot contains a bitmap, a simple FT_Bitmap
that describes it. See the API reference or user guide for a
description of the FT_Bitmap structure.
-
+
glyph−>outline
When the glyph slot contains a scalable outline, this structure
describes it. See the definition of the FT_Outline
structure.
-
+
8. Rendering glyph outlines into bitmaps:
- When the glyph image loaded in a glyph slot is a bitmap, you can use
- your favorite graphics library to blit it to your own surfaces.
+ You can easily test the format of the glyph image by inspecting the
+ face->glyph->format variable. If its value is
+ ft_glyph_format_bitmap, the glyph image that was loaded is
+ a bitmap that can be directly blit to your own surfaces through your
+ favorite graphics library (FreeType 2 doesn't provide bitmap blitting
+ routines, as you may imagine :-)
+ On the other hand, when the format if ft_glyph_format_outline
+ or something else, the library provides a means to convert such glyph
+ images to bitmaps through what are called rasters.
+
+
+
+
On the other hand, when the image is a scalable outline, or something else,
FreeType provides a function to convert the glyph image into a
pre-existing bitmap that you'll handle to it, named
diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index ae87c5106..3ebff27c0 100644
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -1378,24 +1378,51 @@
/*************************************************************************/
/* */
/* */
- /* FT_Stream_Type */
+ /* FT_Open_Flags */
/* */
/* */
- /* An enumeration used to list the possible ways to open a new */
- /* input stream. It is used by the FT_Open_Args structure.. */
+ /* An enumeration used to list the bit flags used within FT_Open_Args */
/* */
/* */
- /* ft_stream_memory :: this is a memory-based stream */
- /* ft_stream_copy :: copy the stream from the "stream" field */
- /* ft_stream_pathname :: create a new input stream from a C pathname */
+ /* ft_open_memory :: this is a memory-based stream */
+ /* ft_open_stream :: copy the stream from the "stream" field */
+ /* ft_open_pathname :: create a new input stream from a C pathname */
+ /* ft_open_driver :: use the "driver" field */
+ /* ft_open_params :: use the "num_params" & "params" field */
/* */
typedef enum {
- ft_stream_memory = 1,
- ft_stream_copy = 2,
- ft_stream_pathname = 3
+ ft_open_memory = 1,
+ ft_open_stream = 2,
+ ft_open_pathname = 4,
+ ft_open_driver = 8,
+ ft_open_params = 16
- } FT_Stream_Type;
+ } FT_Open_Flags;
+
+
+ /*************************************************************************/
+ /* */
+ /* */
+ /* FT_Parameter */
+ /* */
+ /* */
+ /* A simple structure used to pass more or less generic parameters */
+ /* to FT_Open_Face.. */
+ /* */
+ /* */
+ /* tag :: 4-byte identification tag */
+ /* data :: pointer to parameter data */
+ /* */
+ /* */
+ /* the id and role of parameters is driver-specific */
+ /* */
+ typedef struct FT_Parameter_
+ {
+ FT_ULong tag;
+ FT_Pointer data;
+
+ } FT_Parameter;
/*************************************************************************
*
@@ -1408,7 +1435,7 @@
* function FT_Open_Face & FT_Attach_Stream.
*
*
- * stream_type :: type of input stream
+ * flags :: set of bit flags indicating how to use the structure
*
* memory_base :: first byte of file in memory
* memory_size :: size in bytes of file in memory
@@ -1422,6 +1449,10 @@
* the face. If set to 0, FreeType will try to load
* the face with each one of the drivers in its list.
*
+ * num_params :: number of parameters
+ * params :: extra parameters passed to the font driver when
+ * opening a new face
+ *
*
* The stream_type determines which fields are used to create a new
* input stream.
@@ -1441,12 +1472,14 @@
typedef struct FT_Open_Args_
{
- FT_Stream_Type stream_type;
- FT_Byte* memory_base;
- FT_Long memory_size;
- FT_String* pathname;
- FT_Stream stream;
- FT_Driver driver;
+ FT_Open_Flags flags;
+ FT_Byte* memory_base;
+ FT_Long memory_size;
+ FT_String* pathname;
+ FT_Stream stream;
+ FT_Driver driver;
+ FT_Int num_params;
+ FT_Parameter* params;
} FT_Open_Args;
@@ -1493,6 +1526,52 @@
FT_Face* face );
+ /*************************************************************************/
+ /* */
+ /* */
+ /* FT_New_Memory_Face */
+ /* */
+ /* */
+ /* Creates a new face object from a given resource and typeface index */
+ /* using a font file already loaded into memory. */
+ /* */
+ /* */
+ /* library :: A handle to the library resource. */
+ /* */
+ /* */
+ /* file_base :: A pointer to the beginning of the font data. */
+ /* file_size :: The size of the memory chunk used by the font data. */
+ /* face_index :: The index of the face within the resource. The */
+ /* first face has index 0. */
+ /*