kc3-lang/ftgl

diff --git a/docs/Makefile.am b/docs/Makefile.am
index fb5358e..d999833 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -59,6 +59,9 @@ EXTRA_DIST = \
 	FTGL_1_3.gif \
 	doxygen.cfg.in \
 	ftgl.dox \
+	tutorial.dox \
+	projects_using_ftgl.txt \
+	faq.dox \
 	images/metrics.svg \
 	$(NULL)
 
diff --git a/docs/doxygen.cfg.in b/docs/doxygen.cfg.in
index 65c3fdd..4346eed 100644
--- a/docs/doxygen.cfg.in
+++ b/docs/doxygen.cfg.in
@@ -533,7 +533,8 @@ INPUT_ENCODING         = UTF-8
 
 FILE_PATTERNS          = *.cpp \
                          *.h \
-                         *.dox
+                         *.dox \
+                         *.txt
 
 # The RECURSIVE tag can be used to turn specify whether or not subdirectories 
 # should be searched for input files as well. Possible values are YES and NO. 
diff --git a/docs/faq.dox b/docs/faq.dox
new file mode 100644
index 0000000..f61975f
--- /dev/null
+++ b/docs/faq.dox
@@ -0,0 +1,55 @@
+/** \page ftgl-faq Frequently Asked Questions
+
+ \section faq FAQ
+
+ \subsection faq1 When I try to compile FTGL it complains about a missing file from the include: #include <ft2build.h>
+
+ %FTGL relies on FreeType 2 for opening and decoding font files. This include
+ is the main include for FreeType. You will need to download Freetype 2 and
+ install it. Then make sure that the %FTGL project that you are using points to
+ your FreeType installation.
+
+ \subsection faq2 Is it possible to map a font to a "unit" size? My application relies on the fonts being a certain "physical" height (in OpenGL coordinate space) rather than a point size in display space. Any thoughts/suggestions?
+
+ We can do anything:) It would be easy to allow you to set the size in pixels,
+ though I'm not sure this is what you want. Setting the size to 'OpenGL units'
+ may be a bit harder. What does 1.0 in opengl space mean and how does that
+ relate to point size? For one person it might mean scaling the font up, for
+ someone else it may mean scaling down. Plus bitmaps and pixmaps have a pixel
+ to pixel relationship that you can't change.
+
+ Here's some guidelines for vector and texture fonts. Take note that I say
+ 'should' a lot :)
+
+ - One point in pixel space maps to 1 unit in OpenGL space, so a glyph that is
+ 18 points high should be 18.0 units high.
+
+ - If you set an ortho projection to the window size and draw a glyph it's
+ screen size should be the correct physical size ie a 72 point glyph on a 72dpi
+ screen will be 1 inch high. Also if you set a perspective projection that maps
+ 0.0 in the z axis to screen size you will get the same eg.
+ \code
+gluPerspective(90, window_height / 2 , small_number, large_number);
+ \endcode
+ So basically it all depends on your projection matrix. Obviously you can use
+ glScale but I understand if you don't want to.
+
+ Couple of extra things to note:
+
+ - The quality of vector glyphs will not change when you change the size, ie.
+ a really small polygon glyph up close will look exactly the same as a big one
+ from far away. They both contain the same amount of data. This doesn't apply
+ to texture fonts.
+
+ - Secondly, there is a bug in the advance/kerning code that will cause
+ ugliness at really small point sizes. This is because the advance and kerning
+ use ints so an advance of 0.4 will become zero. If this is going to be a
+ probelm, I can fix this.
+
+ Early on I did a lot of head scratching over the OpenGL unit to font size
+ thing because when I was first integrating %FTGL into my engine the fonts
+ weren't the size I was expecting. I was tempted to build in some scaling but I
+ decided doing nothing was the best approach because you can't please everyone.
+ Plus it's 'correct' as it is.
+
+*/
diff --git a/docs/ftgl.dox b/docs/ftgl.dox
index fe57107..29810a2 100644
--- a/docs/ftgl.dox
+++ b/docs/ftgl.dox
@@ -15,323 +15,31 @@
  - http://www.opengl.org/resources/features/fontsurvey/
 
  Most of these systems require a pre-processing stage to take the native fonts
- and convert them into a proprietry format.
+ and convert them into a proprietary format.
 
  %FTGL was born out of the need to treat fonts in OpenGL applications just like
  any other application. For example when using Adobe Photoshop or Microsoft
  Word you don't need an intermediate pre-processing step to use high quality
  scalable fonts.
 
- \section starting Starting to use FTGL
+ \section documentation Documentation
 
- Only one header is required to use %FTGL:
+ - \subpage ftgl-tutorial
 
-\code
-#include <FTGL/ftgl.h>
-\endcode
+ - C API reference:
+   - FTGlyph.h
+   - FTFont.h
+   - FTLayout.h
 
- \section type Choosing a font type
+ - C++ API reference:
+   - class FTGlyph
+   - class FTFont
+   - class FTLayout
 
- %FTGL supports 6 font output types among 3 groups: raster fonts, vector
- fonts, and texture fonts which are a mixture of both. Each font type has its
- advantages and disadvantages.
+ \section information Additional information
 
- \subsection raster Raster fonts
+ - \subpage ftgl-faq
 
- Raster fonts are made of pixels painted directly on the viewport's
- framebuffer. They cannot be directly rotated or scaled.
-
- - Bitmap fonts use 1-bit (2-colour) rasterised glyphs.
- - Pixmap fonts use 8-bit (256 levels) rasterised glyphs.
-
- \image html rasterfont.png
- \image latex rasterfont.eps "" width=0.7\textwidth
-
- \subsection vector Vector fonts
-
- Vector fonts are 3D objects that are rendered at the current matrix location.
- All position, scale, texture and material effects apply to vector fonts.
-
- - Polygon fonts use planar triangle meshes and can be texture-mapped.
- - Outline fonts use OpenGL lines.
- - Extruded fonts are extruded polygon fonts, with the front, back and side
-   meshes renderable separately to apply different effects and materials.
-
- \image html vectorfont.png
- \image latex vectorfont.eps "" width=0.7\textwidth
-
- \subsection texture Texture fonts
-
- Texture fonts are probably the most versatile type. They are fast,
- antialiased, and can be transformed just like any OpenGL primitive.
-
- \image html texturefont.png
- \image latex texturefont.eps "" width=0.7\textwidth
-
- \section creating Create font objects
-
- Creating a font and displaying some text is really straightforward, be it
- in C or in C++.
-
- \subsection c in C
-
- \code
-/* Create a pixmap font from a TrueType file. */
-FTGLfont *font = ftglCreatePixmapFont("/home/user/Arial.ttf");
-
-/* If something went wrong, bail out. */
-if(!font)
-    return -1;
-
-/* Set the font size and render a small text. */
-ftglSetFontFaceSize(font, 72, 72);
-ftglRenderFont(font, "Hello World!", FTGL_RENDER_ALL);
-
-/* Destroy the font object. */
-ftglDestroyFont(font);
- \endcode
-
- \subsection cxx in C++
-
- \code
-// Create a pixmap font from a TrueType file.
-FTGLPixmapFont font("/home/user/Arial.ttf");
-
-// If something went wrong, bail out.
-if(font.Error())
-    return -1;
-
-// Set the font size and render a small text.
-font.FaceSize(72);
-font.Render("Hello World!");
- \endcode
-
- The first 128 glyphs of the font (generally corresponding to the ASCII set)
- are preloaded. This means that usual text is rendered fast enough, but no
- memory is wasted loading glyphs that will not be used.
-
- \section commands More font commands
-
- \subsection metrics Font metrics
-
- \image html metrics.png
- \image latex metrics.eps "" width=0.5\textwidth
-
- If you ask a font to render at 0.0, 0.0 the bottom left most pixel or polygon
- may not be aligned to 0.0, 0.0. With FTFont::Ascender(), FTFont::Descender()
- and FTFont::Advance() an approximate bounding box can be calculated.
-
- For an exact bounding box, use the FTFont::BBox() function. This function
- returns the extent of the volume containing 'string'. 0.0 on the y axis will
- be aligned with the font baseline.
-
- \subsection charmap Specifying a character map encoding
-
- From the FreeType documentation:
-
- "By default, when a new face object is created, (FreeType) lists all the
- charmaps contained in the font face and selects the one that supports Unicode
- character codes if it finds one. Otherwise, it tries to find support for
- Latin-1, then ASCII."
-
- It then gives up. In this case %FTGL will set the charmap to the first it
- finds in the fonts charmap list. You can expilcitly set the char encoding with
- FTFont::CharMap().
-
- Valid encodings as of FreeType 2.0.4 are:
-
- - ft_encoding_none
- - ft_encoding_unicode
- - ft_encoding_symbol
- - ft_encoding_latin_1
- - ft_encoding_latin_2
- - ft_encoding_sjis
- - ft_encoding_gb2312
- - ft_encoding_big5
- - ft_encoding_wansung
- - ft_encoding_johab
- - ft_encoding_adobe_standard
- - ft_encoding_adobe_expert
- - ft_encoding_adobe_custom
- - ft_encoding_apple_roman
-
- For instance:
-
- \code
-font.CharMap(ft_encoding_apple_roman);
- \endcode
-
- This will return an error if the requested encoding can't be found in the
- font.
-
- If your application uses Latin-1 characters, you can preload this character
- set using the following code:
-
- \code
-// Create a pixmap font from a TrueType file.
-FTGLPixmapFont font("/home/user/Arial.ttf");
-
-// If something went wrong, bail out.
-if(font.Error())
-    return -1;
-
-// Set the face size and the character map. If something went wrong, bail out.
-font.FaceSize(72);
-if(!font.CharMap(ft_encoding_latin_1))
-    return -1;
-
-// Create a string containing all characters between 128 and 255
-// and preload the Latin-1 chars without rendering them.
-char buf[129];
-for(int i = 128; i < 256; i++)
-{
-    buf[i] = (char)(unsigned char)i;
-}
-buf[128] = '\0';
-
-font.Advance(buf);
-}
- \endcode
-
-
- \section faq FAQ
-
- \subsection faq1 When I try to compile FTGL it complains about a missing file from the include: #include <ft2build.h>
-
- %FTGL relies on FreeType 2 for opening and decoding font files. This include
- is the main include for FreeType. You will need to download Freetype 2 and
- install it. Then make sure that the %FTGL project that you are using points to
- your FreeType installation.
-
- \subsection faq2 Is it possible to map a font to a "unit" size? My application relies on the fonts being a certain "physical" height (in OpenGL coordinate space) rather than a point size in display space. Any thoughts/suggestions?
-
- We can do anything:) It would be easy to allow you to set the size in pixels,
- though I'm not sure this is what you want. Setting the size to 'OpenGL units'
- may be a bit harder. What does 1.0 in opengl space mean and how does that
- relate to point size? For one person it might mean scaling the font up, for
- someone else it may mean scaling down. Plus bitmaps and pixmaps have a pixel
- to pixel relationship that you can't change.
-
- Here's some guidelines for vector and texture fonts. Take note that I say
- 'should' a lot :)
-
- - One point in pixel space maps to 1 unit in OpenGL space, so a glyph that is
- 18 points high should be 18.0 units high.
-
- - If you set an ortho projection to the window size and draw a glyph it's
- screen size should be the correct physical size ie a 72 point glyph on a 72dpi
- screen will be 1 inch high. Also if you set a perspective projection that maps
- 0.0 in the z axis to screen size you will get the same eg.
- \code
-gluPerspective(90, window_height / 2 , small_number, large_number);
- \endcode
- So basically it all depends on your projection matrix. Obviously you can use
- glScale but I understand if you don't want to.
-
- Couple of extra things to note:
-
- - The quality of vector glyphs will not change when you change the size, ie.
- a really small polygon glyph up close will look exactly the same as a big one
- from far away. They both contain the same amount of data. This doesn't apply
- to texture fonts.
-
- - Secondly, there is a bug in the advance/kerning code that will cause
- ugliness at really small point sizes. This is because the advance and kerning
- use ints so an advance of 0.4 will become zero. If this is going to be a
- probelm, I can fix this.
-
- Early on I did a lot of head scratching over the OpenGL unit to font size
- thing because when I was first integrating %FTGL into my engine the fonts
- weren't the size I was expecting. I was tempted to build in some scaling but I
- decided doing nothing was the best approach because you can't please everyone.
- Plus it's 'correct' as it is.
-
-
- \section sample Sample font manager class
-
-\code
-FTTextureFont* myFont = FTGLFontManager::Instance().GetFont("arial.ttf", 72);
-
-#include <map>
-#include <string>
-#include <FTGL/ftgl.h>
-
-using namespace std;
-
-typedef map<string, FTFont*> FontList;
-typedef FontList::const_iterator FontIter;
-
-class FTGLFontManager
-{
-    public:
-        // NOTE
-        // This is shown here for brevity. The implementation should be in the source
-        // file otherwise your compiler may inline the function resulting in
-        // multiple instances of FTGLFontManager
-        static FTGLFontManager& Instance()
-        {
-            static FTGLFontManager tm;
-            return tm;
-        }
-
-        ~FTGLFontManager()
-        {
-            FontIter font;
-            for(font = fonts.begin(); font != fonts.end(); font++)
-            {
-                delete (*font).second;
-            }
-
-            fonts.clear();
-        }
-
-
-        FTFont* GetFont(const char *filename, int size)
-        {
-            char buf[256];
-            sprintf(buf, "%s%i", filename, size);
-            string fontKey = string(buf);
-
-            FontIter result = fonts.find(fontKey);
-            if(result != fonts.end())
-            {
-                LOGMSG("Found font %s in list", filename);
-                return result->second;
-            }
-
-            FTFont* font = new FTTextureFont;
-
-            string fullname = path + string(filename);
-
-            if(!font->Open(fullname.c_str()))
-            {
-                LOGERROR("Font %s failed to open", fullname.c_str());
-                delete font;
-                return NULL;
-            }
-
-            if(!font->FaceSize(size))
-            {
-                LOGERROR("Font %s failed to set size %i", filename, size);
-                delete font;
-                return NULL;
-            }
-
-            fonts[fontKey] = font;
-
-            return font;
-        }
-
-
-    private:
-        // Hide these 'cause this is a singleton.
-        FTGLFontManager(){}
-        FTGLFontManager(const FTGLFontManager&){};
-        FTGLFontManager& operator = (const FTGLFontManager&){ return *this; };
-
-        // container for fonts
-        FontList fonts;
-};
-\endcode
+ - \subpage ftgl-projects
 
 */
diff --git a/docs/projects_using_ftgl.txt b/docs/projects_using_ftgl.txt
index c12d992..8b16558 100644
--- a/docs/projects_using_ftgl.txt
+++ b/docs/projects_using_ftgl.txt
@@ -1,35 +1,27 @@
+/** \page ftgl-projects Projects using FTGL
 
-To add your name to this list, please contact one of the FTGL
+To add your project to this list, please contact one of the %FTGL
 developers at http://sf.net/projects/ftgl
 
 Projects are listed in alphabetical order.
 
-Projects currently using FTGL
------------------------------
+\section current Projects currently using FTGL
 
-Blender
-http://blender.org/
+ - Blender (http://blender.org/)
 
-BZFlag
-http://BZFlag.org/
-as of version 2.99
+ - BZFlag (http://BZFlag.org/), as of version 2.99
 
-Duel
-http://www.personal.rdg.ac.uk/~sir03me/play/code.html
+ - Duel (http://www.personal.rdg.ac.uk/~sir03me/play/code.html)
 
-FTGL#
-http://www.paskaluk.com/projects.php
+ - %FTGL# (http://www.paskaluk.com/projects.php)
 
-Ruby FTGL
-http://rubyforge.org/projects/ruby-ftgl/
+ - Ruby %FTGL (http://rubyforge.org/projects/ruby-ftgl/)
 
-VTK
-http://www.vtk.org/
+ - VTK (http://www.vtk.org/)
 
 
-Projects that used to use FTGL
-------------------------------
+\section old Projects that used to use FTGL
 
-GNU Backgammon 
-http://www.gnubg.org/
-until version 0.14.3+20060520-1
+ - GNU Backgammon (http://www.gnubg.org/), until version 0.14.3+20060520-1
+
+*/
diff --git a/docs/tutorial.dox b/docs/tutorial.dox
new file mode 100644
index 0000000..dae3062
--- /dev/null
+++ b/docs/tutorial.dox
@@ -0,0 +1,262 @@
+/** \page ftgl-tutorial FTGL tutorial
+
+ \section starting Starting to use FTGL
+
+ Only one header is required to use %FTGL:
+
+\code
+#include <FTGL/ftgl.h>
+\endcode
+
+ \section type Choosing a font type
+
+ %FTGL supports 6 font output types among 3 groups: raster fonts, vector
+ fonts, and texture fonts which are a mixture of both. Each font type has its
+ advantages and disadvantages.
+
+ \subsection raster Raster fonts
+
+ Raster fonts are made of pixels painted directly on the viewport's
+ framebuffer. They cannot be directly rotated or scaled.
+
+ - Bitmap fonts use 1-bit (2-colour) rasterised glyphs.
+ - Pixmap fonts use 8-bit (256 levels) rasterised glyphs.
+
+ \image html rasterfont.png
+ \image latex rasterfont.eps "" width=0.7\textwidth
+
+ \subsection vector Vector fonts
+
+ Vector fonts are 3D objects that are rendered at the current matrix location.
+ All position, scale, texture and material effects apply to vector fonts.
+
+ - Polygon fonts use planar triangle meshes and can be texture-mapped.
+ - Outline fonts use OpenGL lines.
+ - Extruded fonts are extruded polygon fonts, with the front, back and side
+   meshes renderable separately to apply different effects and materials.
+
+ \image html vectorfont.png
+ \image latex vectorfont.eps "" width=0.7\textwidth
+
+ \subsection texture Texture fonts
+
+ Texture fonts are probably the most versatile type. They are fast,
+ antialiased, and can be transformed just like any OpenGL primitive.
+
+ \image html texturefont.png
+ \image latex texturefont.eps "" width=0.7\textwidth
+
+ \section creating Create font objects
+
+ Creating a font and displaying some text is really straightforward, be it
+ in C or in C++.
+
+ \subsection c in C
+
+ \code
+/* Create a pixmap font from a TrueType file. */
+FTGLfont *font = ftglCreatePixmapFont("/home/user/Arial.ttf");
+
+/* If something went wrong, bail out. */
+if(!font)
+    return -1;
+
+/* Set the font size and render a small text. */
+ftglSetFontFaceSize(font, 72, 72);
+ftglRenderFont(font, "Hello World!", FTGL_RENDER_ALL);
+
+/* Destroy the font object. */
+ftglDestroyFont(font);
+ \endcode
+
+ \subsection cxx in C++
+
+ \code
+// Create a pixmap font from a TrueType file.
+FTGLPixmapFont font("/home/user/Arial.ttf");
+
+// If something went wrong, bail out.
+if(font.Error())
+    return -1;
+
+// Set the font size and render a small text.
+font.FaceSize(72);
+font.Render("Hello World!");
+ \endcode
+
+ The first 128 glyphs of the font (generally corresponding to the ASCII set)
+ are preloaded. This means that usual text is rendered fast enough, but no
+ memory is wasted loading glyphs that will not be used.
+
+ \section commands More font commands
+
+ \subsection metrics Font metrics
+
+ \image html metrics.png
+ \image latex metrics.eps "" width=0.5\textwidth
+
+ If you ask a font to render at 0.0, 0.0 the bottom left most pixel or polygon
+ may not be aligned to 0.0, 0.0. With FTFont::Ascender(), FTFont::Descender()
+ and FTFont::Advance() an approximate bounding box can be calculated.
+
+ For an exact bounding box, use the FTFont::BBox() function. This function
+ returns the extent of the volume containing 'string'. 0.0 on the y axis will
+ be aligned with the font baseline.
+
+ \subsection charmap Specifying a character map encoding
+
+ From the FreeType documentation:
+
+ "By default, when a new face object is created, (FreeType) lists all the
+ charmaps contained in the font face and selects the one that supports Unicode
+ character codes if it finds one. Otherwise, it tries to find support for
+ Latin-1, then ASCII."
+
+ It then gives up. In this case %FTGL will set the charmap to the first it
+ finds in the fonts charmap list. You can expilcitly set the char encoding with
+ FTFont::CharMap().
+
+ Valid encodings as of FreeType 2.0.4 are:
+
+ - ft_encoding_none
+ - ft_encoding_unicode
+ - ft_encoding_symbol
+ - ft_encoding_latin_1
+ - ft_encoding_latin_2
+ - ft_encoding_sjis
+ - ft_encoding_gb2312
+ - ft_encoding_big5
+ - ft_encoding_wansung
+ - ft_encoding_johab
+ - ft_encoding_adobe_standard
+ - ft_encoding_adobe_expert
+ - ft_encoding_adobe_custom
+ - ft_encoding_apple_roman
+
+ For instance:
+
+ \code
+font.CharMap(ft_encoding_apple_roman);
+ \endcode
+
+ This will return an error if the requested encoding can't be found in the
+ font.
+
+ If your application uses Latin-1 characters, you can preload this character
+ set using the following code:
+
+ \code
+// Create a pixmap font from a TrueType file.
+FTGLPixmapFont font("/home/user/Arial.ttf");
+
+// If something went wrong, bail out.
+if(font.Error())
+    return -1;
+
+// Set the face size and the character map. If something went wrong, bail out.
+font.FaceSize(72);
+if(!font.CharMap(ft_encoding_latin_1))
+    return -1;
+
+// Create a string containing all characters between 128 and 255
+// and preload the Latin-1 chars without rendering them.
+char buf[129];
+for(int i = 128; i < 256; i++)
+{
+    buf[i] = (char)(unsigned char)i;
+}
+buf[128] = '\0';
+
+font.Advance(buf);
+}
+ \endcode
+
+
+ \section sample Sample font manager class
+
+\code
+FTTextureFont* myFont = FTGLFontManager::Instance().GetFont("arial.ttf", 72);
+
+#include <map>
+#include <string>
+#include <FTGL/ftgl.h>
+
+using namespace std;
+
+typedef map<string, FTFont*> FontList;
+typedef FontList::const_iterator FontIter;
+
+class FTGLFontManager
+{
+    public:
+        // NOTE
+        // This is shown here for brevity. The implementation should be in the source
+        // file otherwise your compiler may inline the function resulting in
+        // multiple instances of FTGLFontManager
+        static FTGLFontManager& Instance()
+        {
+            static FTGLFontManager tm;
+            return tm;
+        }
+
+        ~FTGLFontManager()
+        {
+            FontIter font;
+            for(font = fonts.begin(); font != fonts.end(); font++)
+            {
+                delete (*font).second;
+            }
+
+            fonts.clear();
+        }
+
+
+        FTFont* GetFont(const char *filename, int size)
+        {
+            char buf[256];
+            sprintf(buf, "%s%i", filename, size);
+            string fontKey = string(buf);
+
+            FontIter result = fonts.find(fontKey);
+            if(result != fonts.end())
+            {
+                LOGMSG("Found font %s in list", filename);
+                return result->second;
+            }
+
+            FTFont* font = new FTTextureFont;
+
+            string fullname = path + string(filename);
+
+            if(!font->Open(fullname.c_str()))
+            {
+                LOGERROR("Font %s failed to open", fullname.c_str());
+                delete font;
+                return NULL;
+            }
+
+            if(!font->FaceSize(size))
+            {
+                LOGERROR("Font %s failed to set size %i", filename, size);
+                delete font;
+                return NULL;
+            }
+
+            fonts[fontKey] = font;
+
+            return font;
+        }
+
+
+    private:
+        // Hide these 'cause this is a singleton.
+        FTGLFontManager(){}
+        FTGLFontManager(const FTGLFontManager&){};
+        FTGLFontManager& operator = (const FTGLFontManager&){ return *this; };
+
+        // container for fonts
+        FontList fonts;
+};
+\endcode
+
+*/