Commit d2b1f357 authored by David Turner's avatar David Turner
Browse files

Initial revision

parents
This file summarizes the changes that occured since the last "beta" of FreeType 2.
Because the list is important, it has been divided into separate sections:
-----------------------------------------------------------------------------------------
High-Level Interface :
The high-level API has been considerably simplified. Here is how :
- resource objects have disappeared. this means that face objects can now
be created with a single function call (see FT_New_Face and
FT_Open_Face)
- when calling either FT_New_Face & FT_Open_Face, a size object and a
glyph slot object are automatically created for the face, and can be
accessed through "face->glyph" and "face->size" if one really needs to.
In most cases, there's no need to call FT_New_Size or FT_New_Glyph.
- similarly, FT_Load_Glyph now only takes a "face" argument (instead of
a glyph slot and a size). Also, it's "result" parameter is gone, as
the glyph image type is returned in the field "face->glyph.format"
- the list of available charmaps is directly accessible through
"face->charmaps", counting "face->num_charmaps" elements. Each
charmap has an 'encoding' field which specifies which known encoding
it deals with. Valid values are, for example :
ft_encoding_unicode (for ASCII, Latin-1 and Unicode)
ft_encoding_apple_roman
ft_encoding_sjis
ft_encoding_adobe_standard
other values may be added in the future. Each charmap still holds its
"platform_id" and "encoding_id" values in case the encoding is too
exotic for the current library
-----------------------------------------------------------------------------------------
Directory Structure:
Should seem obvious to most of you:
freetype/
config/ -- configuration sub-makefiles
ansi/
unix/
win32/
os2/
msdos/
include/ -- public header files, those to be included directly
by client apps
src/ -- sources of the library
base/ -- the base layer
sfnt/ -- the sfnt "driver" (see the drivers section below)
truetype/ -- the truetype driver
type1/ -- the type1 driver
shared/ -- some header files shared between drivers
demos/ -- demos/tools
docs/ -- documentation (a bit empty for now)
-----------------------------------------------------------------------------------------
Glyph Image Formats :
Drivers are now able to register new glyph image formats within the library.
For now, the base layer supports of course bitmaps and vector outlines, but
one could imagine something different like colored bitmaps, bi-color
vectors or wathever else (Metafonts anyone ??).
See the file `include/ftimage.h'. Note also that the type FT_Raster_Map is
gone, and is now replaced by FT_Bitmap, which should encompass all known
bitmap types.
Each new image format must provide at least one "raster", i.e. a module
capable of transforming the glyph image into a bitmap. It is also possible
to change the default raster used for a given glyph image format.
The default outline scan-converter now uses 128 levels of grays by default,
which tends to smooth many things. Note that the demo programs have been
updated significantly to be able to display these..
-----------------------------------------------------------------------------------------
Build system :
You still need GNU Make to build the library. The build system has been
very seriously re-vamped in order to provide things like :
- automatic host platform detection (reverting to 'config/ansi'
if it is not detected, with pseudo-standard compilation flags)
- the ability to compile from the Makefiles with very different and
exotic compilers. Note that linking the library can be difficult for
some platforms.
For example, the file `config/win32/lcclib.bat' is invoked by the
build system to create the ".lib" file with LCC-Win32 because its
librarian has too many flaws to be invoked directly from the Makefile.
Here's how it works :
- the first time you type `make', the build system runs a series of
sub-makefiles in order to detect your host platform. It then dumps
what it found, and creates a file called `config.mk' in the current
directory. This is a sub-Makefile used to define many important Make
variables used to build the library.
- the second time, the build system detects the `config.mk' then use it
to build the library. All object files go into 'obj' by default, as
well as the library file, but this can easily be changed.
Note that you can run "make setup" to force another host platform detection
even if a `config.mk' is present in the current directory. Another solution
is simply to delete the file, then re-run make.
Finally, the default compiler for all platforms is gcc (for now, this will
hopefully changed in the future). You can however specify a different
compiler by specifying it after the 'setup' target as in :
gnumake setup lcc on Win32 to use the LCC compiler
gnumake setup visualc on Win32 to use Visual C++
See the file `config/<system>/detect.mk' for a list of supported compilers
for your platforms.
It should be relatively easy to write new detection rules files and
config.mk..
Finally, to build the demo programs, go to `demos' and launch GNU Make,
it will use the `config.mk' in the top directory to build the test
programs..
-----------------------------------------------------------------------------------------
Portability :
In the previous beta, a single FT_System object was used to encompass
all low-level operations like thread synchronisation, memory management
and i/o access. This has been greatly simplified :
- thread synchronisation has been dropped, for the simple reason that
the library is already re-entrant, and that if you really need two
threads accessing the same FT_Library, you should really synchronize
access to it yourself with a simple mutex.
- memory management is performed through a very simple object called
"FT_Memory", which really is a table containing a table of pointers
to functions like malloc, realloc and free as well as some user data
(closure).
- resources have disappeared (they created more problems than they
solved), and i/o management have been simplified greatly as a
result. Streams are defined through FT_Stream objects, which can
be either memory-based or disk-based.
Note that each face has its own stream, which is closed only when
the face object is destroyed. Hence, a function like TT_Flush_Face
in 1.x cannot be directly supported. However, if you really need
something like this, you can easily tailor your own streams to achieve
the same feature at a lower level (and use FT_Open_Face instead of
FT_New_Face to create the face).
See the file "include/ftsystem.h" for more details, as well as the
implementations found in "config/unix" and "config/ansi".
-----------------------------------------------------------------------------------------
Drivers Interface :
(To be written)
-----------------------------------------------------------------------------------------
Extensions support :
(To be defined)
#******************************************************************************
#*
#* FreeType build system - top-level Makefile
#*
#* This file is designed for GNU Make, do not use it with another Make tool.
#* It works as follows :
#*
#* - when invoked for the first time, this Makefile will include
#* the rules found in `freetype/config/detect.mk'. They are in charge
#* of detecting the current platform.
#*
#* A summary of the detection will be displayed, and the file `config.mk'
#* will be created in the current directory
#*
#*
#* - when invoked later, this Makefile will include the rules found in
#* `config.mk'. This sub-Makefile will define some system-specific
#* variables (like compiler, compilation flags, object suffix, etc..),
#* then include the rules found in `freetype/config/freetype.mk',
#* used to build the library.
#*
#* See the comments in `config/detect.mk' and `config/freetype.mk' for
#* more details on host platform detection and library builds..
#*
#******************************************************************************
.PHONY: setup
#
# The variable TOP holds the path to the topmost directory in the FreeType
# engine source hierarchy. If it is not defined, default it to '.'
#
ifndef TOP
TOP := .
endif
CONFIG_MK := config.mk
#############################################################################
#
# If no configuration sub-makefile is present, or if "setup" is the target
# to be built, run the auto-detection rules to figure out which configuration
# rules file to use..
#
# Note that the configuration file is put in the current directory, which is
# not necessarily TOP.
#
# if `config.mk' is not present, set "check_platform" and "first_time"
#
ifeq ($(wildcard $(CONFIG_MK)),)
check_platform := 1
first_time := 1
endif
# if `setup' is one of the targets requested, set "check_platform"
#
ifneq ($(findstring setup,$(MAKECMDGOALS)),)
check_platform := 1
endif
#########################################################################
#
# include the automatic host platform detection rules when we need to
# check the platform.
#
#
ifdef check_platform
all: setup
include $(TOP)/config/detect.mk
# "setup" must be defined by the host platform detection rules
else
########################################################################
#
# A configuration sub-Makefile is present, simply run it..
#
#
all: build_freetype
BUILD_FREETYPE := yes
include $(CONFIG_MK)
endif #test check_platform
#*******************************************************************
#*
#* FreeType 2 Configuration rules for a `normal' ANSI compiler
#*
#* Copyright 1996-1999 by
#* David Turner, Robert Wilhelm, and Werner Lemberg.
#*
#* This file is part of the FreeType project, and may only be used
#* modified and distributed under the terms of the FreeType project
#* license, LICENSE.TXT. By continuing to use, modify, or distribute
#* this file you indicate that you have read the license and
#* understand and accept it fully.
#*
#*
#* The purpose of this sub-Makefile is to define various build and
#* platform specific variables before including the sub-Makefile
#* containing the FreeType library rules, found in
#*
#* $(TOP)/config/freetype.mk
#*
#* The following variables must be defined before including this
#* file :
#*
#* TOP Pathname to the top of the FreeType sources
#* hierarchy
#*
#* This file should define the following variables before including
#* the FreeType library rules file :
#*
#* BUILD Pathname to the platform-specific files used
#* for the build. Usually `$(TOP)/config/<system>'
#*
#* SEP Directory separator for the current platform.
#* Either / or \ (maybe : on Macs)
#*
#* DELETE The forced remove/delete command to erase one or more
#* files
#*
#* INCLUDE The location of all public header files. e.g.
#* `$(TOP)/include'include' *
#*
#* SRC The directory containing all sources. e.g.
#* '$(TOP)/src'
#*
#* OBJ_DIR The location where compiled object files will be
#* placed, e.g. '$(TOP)/obj'
#*
#* LIB_DIR The location where the resulting library file will be
#* placed, e.g. '$(TOP)/obj'
#*
#* LIBRARY The filename of the resulting library file, without
#* its extension.. e.g. 'libfreetype' or 'freetype'
#*
#* O The object file suffix. Can be '.o', '.obj,' '.lo,'
#* ';coff,' etc.
#*
#* A The library file suffix. Can be '.a' '.so,' '.lib'
#* '.dll,' etc.
#*
#* I The path inclusion flag. Some compilers use a
#* different flag than '-I' to specify an additional
#* include path. Examples are '/i=' or '-J ', etc.
#*
#* D The macro definition flag. I haven't met compilers
#* which don't use the '-D' switch to define a macro, but
#* who knows...
#*
#* T The compilation flag used to identify the target. Some
#* compilers use a different flag than '-o ' to specify
#* the name of the target object file.
#*
#* CFLAGS The set of flags used to compile object files.
#* (usually contains the flag '-c').
#*
#*
#*
#*******************************************************************
ifndef TOP
TOP := .
endif
DELETE := rm -f
SEP := /
BUILD := $(TOP)/config/ansi
PLATFORM := ansi
# the directory where all object files are placed
#
OBJ_DIR := $(TOP)/obj
# the directory where all library files are placed
#
# by default, this is the same as OBJ_DIR, however, this can be
# changed to suit particular needs..
#
LIB_DIR := $(OBJ_DIR)
# the object file extension, this can be .o, .tco, .obj, etc..
# depending on the platform
#
O := o
# the library file extension, this can be .a, .lib, etc..
# depending on the platform
#
A := a
# The name of the final library file.
# Note that the DOS-specific Makefile uses a shorter (8.3) name
#
LIBRARY := libfreetype
# path inclusion flag.
#
# Some compilers use a different flag than '-I' to specify an
# additional include path. Examples are "/i=" or "-J", etc...
#
I := -I
# C flag used to define a macro before the compilation of a given
# source object. Usually is '-D' like in "-DDEBUG"
#
D := -D
# Target flag - beware, there is a space after the 'o' !!
#
#
T := -o
# The link flag used to specify a given library file on link.
# Note that this is only used to compile the demo programs, not
# the library itself.
#
L := -l
# C flags
#
# These should concern :
#
# - debug output
# - optimization
# - warnings
# - ansi compliance..
#
ifndef CFLAGS
CFLAGS := -c
endif
# Now include the main sub-makefile. It contains all the rules used
# to build the library with the previous variables defined
#
include $(TOP)/config/freetype.mk
# Librarian to use to build the static library
#
FT_LIBRARIAN := $(AR) -r
# This final rule is used to link all object files into a single
# library. It is part of the system-specific sub-Makefile because not
# all librarians accept a simple syntax like :
#
# librarian library_file {list of object files}
#
$(FT_LIBRARY): $(OBJECTS_LIST)
-$(DELETE) $@
$(FT_LIBRARIAN) $@ $(OBJECTS_LIST)
/***************************************************************************/
/* */
/* ftconfig.h */
/* */
/* ANSI-specific configuration file (specification only). */
/* */
/* Copyright 1996-1999 by */
/* David Turner, Robert Wilhelm, and Werner Lemberg. */
/* */
/* This file is part of the FreeType project, and may only be used */
/* modified and distributed under the terms of the FreeType project */
/* license, LICENSE.TXT. By continuing to use, modify, or distribute */
/* this file you indicate that you have read the license and */
/* understand and accept it fully. */
/* */
/***************************************************************************/
/*************************************************************************/
/* */
/* This header file contains a number of macro definitions that are used */
/* by the rest of the engine. Porters are free to copy this file and */
/* adapt it to suit their own system. */
/* */
/* IMPORTANT NOTE: */
/* */
/* Porters, read carefully the comments in `ftsys.h' before trying to */
/* port this file to your system. It contains many essential */
/* remarks, and will ease your work greatly. */
/* */
/*************************************************************************/
#ifndef FTCONFIG_H
#define FTCONFIG_H
/* Include the header file containing all developer build options */
#include <ftoption.h>
/*************************************************************************/
/* */
/* PLATFORM-SPECIFIC CONFIGURATION MACROS */
/* */
/* These macros can be toggled to suit a specific system. The current */
/* ones are defaults used to compile FreeType in an ANSI C environment */
/* (16bit compilers are also supported). Copy this file to your own */
/* `freetype/arch/<system>' directory, and edit it to port the engine. */
/* */
/*************************************************************************/
/* Define to empty if the keyword does not work. */
/* #undef const */
/* Define if you have the ANSI C header files. */
#define STDC_HEADERS 1
/* We use <limits.h> values to know the sizes of the types. */
#include <limits.h>
/* The number of bytes in an `int' type. */
#if UINT_MAX == 0xFFFFFFFF
#define SIZEOF_INT 4
#elif UINT_MAX == 0xFFFF
#define SIZEOF_INT 2
#elif UINT_MAX > 0xFFFFFFFF && UINT_MAX == 0xFFFFFFFFFFFFFFFF
#define SIZEOF_INT 8
#else
#error "Unsupported number of bytes in `int' type!"
#endif
/* The number of bytes in a `long' type. */
#if ULONG_MAX == 0xFFFFFFFF
#define SIZEOF_LONG 4
#elif ULONG_MAX > 0xFFFFFFFF && ULONG_MAX == 0xFFFFFFFFFFFFFFFF
#define SIZEOF_LONG 8
#else
#error "Unsupported number of bytes in `long' type!"
#endif
/* Define if you have the memcpy function. */
#define HAVE_MEMCPY 1
/* Define if you have the <fcntl.h> header file. */
#define HAVE_FCNTL_H 0
/* Define if you have the <unistd.h> header file. */
#define HAVE_UNISTD_H 0
/* Preferred alignment of data */
#define FT_ALIGNMENT 8
/*************************************************************************/
/* */
/* AUTOMATIC CONFIGURATION MACROS */
/* */
/* These macros are computed from the ones defined above. Don't touch */
/* their definition, unless you know precisely what you're doing. No */
/* porter should need to mess with them. */
/* */
/*************************************************************************/
/*************************************************************************/
/* */
/* IntN types */
/* */
/* Used to guarantee the size of some specific integers. */
/* */
typedef signed short FT_Int16;
typedef unsigned short FT_Word16;
#if SIZEOF_INT == 4
typedef signed int FT_Int32;
typedef unsigned int FT_Word32;
#elif SIZEOF_LONG == 4
typedef signed long FT_Int32;
typedef unsigned long FT_Word32;
#else
#error "no 32bit type found - please check your configuration files"
#endif
#if SIZEOF_LONG == 8
/* LONG64 must be defined when a 64-bit type is available */
#define LONG64
#define INT64 long
#else
/*************************************************************************/
/* */
/* GCC provides the non-ANSI 'long long' 64-bit type. You can activate */
/* it by defining the FTCALC_USE_LONG_LONG macro in `ftconfig.h'. Note */
/* that this will produce many -ansi warnings during library */
/* compilation. */
/* */
#ifdef FTCALC_USE_LONG_LONG
#define LONG64
#define INT64 long long
#endif /* FTCALC_USE_LONG_LONG */
#endif
#ifdef FT_MAKE_OPTION_SINGLE_OBJECT
#define LOCAL_DEF static
#define LOCAL_FUNC static
#else
#define LOCAL_DEF extern
#define LOCAL_FUNC /* nothing */
#endif
#ifdef FT_MAKE_OPTION_SINGLE_LIBRARY_OBJECT
#define BASE_DEF LOCAL_DEF
#define BASE_FUNC LOCAL_FUNC
#else
#define BASE_DEF extern
#define BASE_FUNC /* nothing */
#endif
#ifndef EXPORT_DEF
#define EXPORT_DEF extern
#endif
#ifndef EXPORT_FUNC
#define EXPORT_FUNC /* nothing */
#endif
#endif /* FTCONFIG_H */
/* END */
#ifndef FTOPTION_H
#define FTOPTION_H
/*************************************************************************/
/* */
/* USER-SELECTABLE CONFIGURATION MACROS */
/* */
/* These macros can be toggled by developers to enable or disable */
/* certain aspects of FreeType. This file contains macros that apply to */
/* all of FreeType. Driver-specific configurations are placed in each */
/* driver directory (e.g. `freetype/drivers/ttlib/ttconfig.h'). */
/* */
/*************************************************************************/
/*************************************************************************/
/* */
/* Alternate Glyph Image Format support */
/* */
/* By default, the glyph images returned by the FreeType glyph loader */
/* can either be a pixmap or a vectorial outline defined through */
/* bezier control points. When defining the following configuration */