kc3-lang/ftgl

diff --git a/src/FTFont/FTFontGlue.cpp b/src/FTFont/FTFontGlue.cpp
index ace0bdb..3ae8189 100644
--- a/src/FTFont/FTFontGlue.cpp
+++ b/src/FTFont/FTFontGlue.cpp
@@ -138,67 +138,63 @@ C_FUN(int, ftglAttachData, (FTGLfont *f, const unsigned char *p, size_t s),
       return 0, Attach, (p, s));
 
 // bool FTFont::CharMap(FT_Encoding encoding);
-C_FUN(int, ftglCharMap, (FTGLfont *f, FT_Encoding enc),
+C_FUN(int, ftglSetFontCharMap, (FTGLfont *f, FT_Encoding enc),
       return 0, CharMap, (enc));
 
 // unsigned int FTFont::CharMapCount();
-C_FUN(unsigned int, ftglCharMapCount, (FTGLfont *f),
+C_FUN(unsigned int, ftglGetFontCharMapCount, (FTGLfont *f),
       return 0, CharMapCount, ());
 
 // FT_Encoding* FTFont::CharMapList();
-C_FUN(FT_Encoding *, ftglCharMapList, (FTGLfont* f),
+C_FUN(FT_Encoding *, ftglGetFontCharMapList, (FTGLfont* f),
       return NULL, CharMapList, ());
 
 // virtual bool FTFont::FaceSize(const unsigned int size,
 //                               const unsigned int res = 72);
-C_FUN(int, ftglSetFaceSize, (FTGLfont *f, unsigned int s),
-      return 0, FaceSize, (s));
-C_FUN(int, ftglSetFaceSizeRes, (FTGLfont *f, unsigned int s, unsigned int r),
-      return 0, FaceSize, (s, r));
+C_FUN(int, ftglSetFontFaceSize, (FTGLfont *f, unsigned int s, unsigned int r),
+      return 0, FaceSize, (s, r > 0 ? r : 72));
 
 // unsigned int FTFont::FaceSize() const;
 // XXX: need to call FaceSize() as FTFont::FaceSize() because of FTGLTexture
-C_FUN(unsigned int, ftglGetFaceSize, (FTGLfont *f),
+C_FUN(unsigned int, ftglGetFontFaceSize, (FTGLfont *f),
       return 0, FTFont::FaceSize, ());
 
 // virtual void FTFont::Depth(float depth);
-C_FUN(void, ftglSetDepth, (FTGLfont *f, float d), return, Depth, (d));
+C_FUN(void, ftglSetFontDepth, (FTGLfont *f, float d), return, Depth, (d));
 
 // virtual void FTFont::Outset(float front, float back);
-C_FUN(void, ftglSetOutset, (FTGLfont *f, float front, float back),
+C_FUN(void, ftglSetFontOutset, (FTGLfont *f, float front, float back),
       return, FTFont::Outset, (front, back));
 
 // void FTFont::UseDisplayList(bool useList);
-C_FUN(void, ftglUseDisplayList, (FTGLfont *f, int l),
+C_FUN(void, ftglFontUseDisplayList, (FTGLfont *f, int l),
       return, UseDisplayList, (l));
 
 // float FTFont::Ascender() const;
-C_FUN(float, ftglAscender, (FTGLfont *f), return 0.f, Ascender, ());
+C_FUN(float, ftglGetFontAscender, (FTGLfont *f), return 0.f, Ascender, ());
 
 // float FTFont::Descender() const;
-C_FUN(float, ftglDescender, (FTGLfont *f), return 0.f, Descender, ());
+C_FUN(float, ftglGetFontDescender, (FTGLfont *f), return 0.f, Descender, ());
 
 // float FTFont::LineHeight() const;
-C_FUN(float, ftglLineHeight, (FTGLfont *f), return 0.f, LineHeight, ());
+C_FUN(float, ftglGetFontLineHeight, (FTGLfont *f), return 0.f, LineHeight, ());
 
 // void FTFont::BBox(const char* string, float& llx, float& lly, float& llz,
 //                   float& urx, float& ury, float& urz);
-C_FUN(void, ftglBBox, (FTGLfont *f, const char* s, float c[6]),
-      return, BBox, (s, c[0], c[1], c[2], c[3], c[4], c[5]));
+C_FUN(void, ftglGetFontBBox, (FTGLfont *f, const char* s, int start, int end,
+                              float c[6]),
+      return, BBox, (s, start, end, c[0], c[1], c[2], c[3], c[4], c[5]));
 
 // float FTFont::Advance(const char* string);
-C_FUN(float, ftglAdvance, (FTGLfont *f, const char* s),
+C_FUN(float, ftglGetFontAdvance, (FTGLfont *f, const char* s),
       return 0.f, Advance, (s));
 
-// virtual void FTFont::Render(const char* string);
-C_FUN(void, ftglRender, (FTGLfont *f, const char * s), return, Render, (s));
-
 // virtual void Render(const char* string, int renderMode);
-C_FUN(void, ftglRenderMode, (FTGLfont *f, const char *s, int r),
+C_FUN(void, ftglRenderFont, (FTGLfont *f, const char *s, int r),
       return, Render, (s, r));
 
 // FT_Error FTFont::Error() const;
-C_FUN(FT_Error, ftglError, (FTGLfont *f), return -1, Error, ());
+C_FUN(FT_Error, ftglGetFontError, (FTGLfont *f), return -1, Error, ());
 
 FTGL_END_C_DECLS
 
diff --git a/src/FTGL/FTFont.h b/src/FTGL/FTFont.h
index b610d2a..fdc8dfd 100644
--- a/src/FTGL/FTFont.h
+++ b/src/FTGL/FTFont.h
@@ -74,12 +74,12 @@ class FTGL_EXPORT FTFont
         bool Attach(const char* fontFilePath);
 
         /**
-         * Attach auxilliary data to font e.g font metrics, from memory
+         * Attach auxilliary data to font e.g font metrics, from memory.
          *
          * Note: not all font formats implement this function.
          *
-         * @param pBufferBytes  the in-memory buffer
-         * @param bufferSizeInBytes  the length of the buffer in bytes
+         * @param pBufferBytes  the in-memory buffer.
+         * @param bufferSizeInBytes  the length of the buffer in bytes.
          * @return          <code>true</code> if file has been attached
          *                  successfully.
          */
@@ -91,7 +91,7 @@ class FTGL_EXPORT FTFont
          *
          * @param encoding      Freetype enumerate for char map code.
          * @return              <code>true</code> if charmap was valid and
-         *                      set correctly
+         *                      set correctly.
          */
         bool CharMap(FT_Encoding encoding);
 
@@ -119,7 +119,7 @@ class FTGL_EXPORT FTFont
         bool FaceSize(const unsigned int size, const unsigned int res = 72);
 
         /**
-         * Get the current face size in points.
+         * Get the current face size in points (1/72 inch).
          *
          * @return face size
          */
@@ -308,40 +308,173 @@ class FTGL_EXPORT FTFont
 
 FTGL_BEGIN_C_DECLS
 
-FTGL_EXPORT FTGLfont *ftglCreateBitmapFont(const char *fontname);
-FTGL_EXPORT FTGLfont *ftglCreateExtrudeFont(const char *fontname);
-FTGL_EXPORT FTGLfont *ftglCreateOutlineFont(const char *fontname);
-FTGL_EXPORT FTGLfont *ftglCreatePixmapFont(const char *fontname);
-FTGL_EXPORT FTGLfont *ftglCreatePolygonFont(const char *fontname);
-FTGL_EXPORT FTGLfont *ftglCreateTextureFont(const char *fontname);
+/**
+ * Destroy an FTGL font object.
+ *
+ * @param font  An FTGLfont* object.
+ */
+FTGL_EXPORT void ftglDestroyFont(FTGLfont* font);
+
+/**
+ * Attach auxilliary file to font e.g. font metrics.
+ *
+ * Note: not all font formats implement this function.
+ *
+ * @param font  An FTGLfont* object.
+ * @param path  Auxilliary font file path.
+ * @return  1 if file has been attached successfully.
+ */
+FTGL_EXPORT int ftglAttachFile(FTGLfont* font, const char* path);
+
+/**
+ * Attach auxilliary data to font, e.g. font metrics, from memory.
+ *
+ * Note: not all font formats implement this function.
+ *
+ * @param font  An FTGLfont* object.
+ * @param data  The in-memory buffer.
+ * @param size  The length of the buffer in bytes.
+ * @return  1 if file has been attached successfully.
+ */
+FTGL_EXPORT int ftglAttachData(FTGLfont* font, const unsigned char * data,
+                               size_t size);
+
+/**
+ * Set the character map for the face.
+ *
+ * @param font  An FTGLfont* object.
+ * @param encoding  Freetype enumerate for char map code.
+ * @return  1 if charmap was valid and set correctly.
+ */
+FTGL_EXPORT int ftglSetFontCharMap(FTGLfont* font, FT_Encoding encoding);
+
+/**
+ * Get the number of character maps in this face.
+ *
+ * @param font  An FTGLfont* object.
+ * @return character map count.
+ */
+FTGL_EXPORT unsigned int ftglGetFontCharMapCount(FTGLfont* font);
+
+/**
+ * Get a list of character maps in this face.
+ *
+ * @param font  An FTGLfont* object.
+ * @return pointer to the first encoding.
+ */
+FTGL_EXPORT FT_Encoding* ftglGetFontCharMapList(FTGLfont* font);
+
+/**
+ * Set the char size for the current face.
+ *
+ * @param font  An FTGLfont* object.
+ * @param size  The face size in points (1/72 inch).
+ * @param res  The resolution of the target device, or 0 to use the default
+ *             value of 72.
+ * @return  1 if size was set correctly.
+ */
+FTGL_EXPORT int ftglSetFontFaceSize(FTGLfont* font, unsigned int size,
+                                    unsigned int res);
+
+/**
+ * Get the current face size in points (1/72 inch).
+ *
+ * @param font  An FTGLfont* object.
+ * @return face size
+ */
+FTGL_EXPORT unsigned int ftglGetFontFaceSize(FTGLfont* font);
 
-FTGL_EXPORT void ftglDestroyFont(FTGLfont*);
+/**
+ * Set the extrusion distance for the font. Only implemented by
+ * FTExtrudeFont.
+ *
+ * @param font  An FTGLfont* object.
+ * @param depth  The extrusion distance.
+ */
+FTGL_EXPORT void ftglSetDepth(FTGLfont* font, float depth);
 
-FTGL_EXPORT int ftglAttachFile (FTGLfont*, const char*);
-FTGL_EXPORT int ftglAttachData (FTGLfont*, const unsigned char *, size_t);
+/**
+ * Set the outset distance for the font. Only FTOutlineFont, FTPolygonFont
+ * and FTExtrudeFont implement front outset. Only FTExtrudeFont implements
+ * back outset.
+ *
+ * @param font  An FTGLfont* object.
+ * @param front  The front outset distance.
+ * @param back  The back outset distance.
+ */
+FTGL_EXPORT void ftglSetFontOutset(FTGLfont* font, float front, float back);
 
-FTGL_EXPORT int          ftglCharMap      (FTGLfont*, FT_Encoding);
-FTGL_EXPORT unsigned int ftglCharMapCount (FTGLfont*);
-FTGL_EXPORT FT_Encoding* CharMapList      (FTGLfont*);
+/**
+ * Enable or disable the use of Display Lists inside FTGL
+ *
+ * @param font  An FTGLfont* object.
+ * @param useList  1 turns ON display lists.
+ *                 0 turns OFF display lists.
+ */
+FTGL_EXPORT void ftglFontUseDisplayList(FTGLfont* font, int useList);
 
-FTGL_EXPORT int          ftglSetFaceSize    (FTGLfont*, unsigned int);
-FTGL_EXPORT int          ftglSetFaceSizeRes (FTGLfont*,
-                                             unsigned int, unsigned int);
-FTGL_EXPORT unsigned int ftglGetFaceSize    (FTGLfont*);
-FTGL_EXPORT void         ftglSetDepth       (FTGLfont*, float);
-FTGL_EXPORT void         ftglSetOutset      (FTGLfont*, float, float);
+/**
+ * Get the global ascender height for the face.
+ *
+ * @param font  An FTGLfont* object.
+ * @return  Ascender height
+ */
+FTGL_EXPORT float ftglGetFontAscender(FTGLfont* font);
 
-FTGL_EXPORT void ftglUseDisplayList (FTGLfont*, int);
+/**
+ * Gets the global descender height for the face.
+ *
+ * @param font  An FTGLfont* object.
+ * @return  Descender height
+ */
+FTGL_EXPORT float ftglGetFontDescender(FTGLfont* font);
 
-FTGL_EXPORT float ftglAscender   (FTGLfont*);
-FTGL_EXPORT float ftglDescender  (FTGLfont*);
-FTGL_EXPORT float ftglLineHeight (FTGLfont*);
-FTGL_EXPORT void  ftglBBox       (FTGLfont*, const char *, float[]);
-FTGL_EXPORT float ftglAdvance    (FTGLfont*, const char *);
-FTGL_EXPORT void  ftglRender     (FTGLfont*, const char *);
-FTGL_EXPORT void  ftglRenderMode (FTGLfont*, const char *, int);
+/**
+ * Gets the line spacing for the font.
+ *
+ * @param font  An FTGLfont* object.
+ * @return  Line height
+ */
+FTGL_EXPORT float ftglGetFontLineHeight(FTGLfont* font);
+
+/**
+ * Get the bounding box for a string.
+ *
+ * @param font  An FTGLfont* object.
+ * @param string  A char buffer
+ * @param start  The index of the first character of string to check.
+ * @param end  The index of the last character of string to check.  If < 0
+               then characters will be parsed until a '@\0' is encountered.
+ * @param bounds  An array of 6 float values where the bounding box's lower
+ *                left near and upper right far 3D coordinates will be stored.
+ */
+FTGL_EXPORT void ftglGetFontBBox(FTGLfont* font, const char *string,
+                                 int start, int end, float bounds[6]);
+
+/**
+ * Get the advance width for a string.
+ *
+ * @param font  An FTGLfont* object.
+ * @param string  A char string.
+ * @return  Advance width
+ */
+FTGL_EXPORT float ftglGetFontAdvance(FTGLfont* font, const char *string);
+
+/**
+ * Render a string of characters.
+ *
+ * @param font  An FTGLfont* object.
+ * @param string  Char string to be output.
+ * @param mode  Render mode to display.
+ */
+FTGL_EXPORT void ftglRenderFont(FTGLfont* font, const char *string, int mode);
 
-FTGL_EXPORT FT_Error ftglError (FTGLfont*);
+/**
+ * Queries the Font for errors.
+ *
+ * @return  The current error code.
+ */
+FTGL_EXPORT FT_Error ftglGetFontError(FTGLfont* font);
 
 FTGL_END_C_DECLS
 
diff --git a/src/FTGL/FTGLBitmapFont.h b/src/FTGL/FTGLBitmapFont.h
index f91d658..58ad7e4 100644
--- a/src/FTGL/FTGLBitmapFont.h
+++ b/src/FTGL/FTGLBitmapFont.h
@@ -71,5 +71,19 @@ class FTGL_EXPORT FTBitmapFont : public FTFont
 
 #endif //__cplusplus
 
+FTGL_BEGIN_C_DECLS
+
+/**
+ * Create a specialised FTGLfont object for handling bitmap fonts.
+ *
+ * @param file  The font file name.
+ * @return  An FTGLfont* object.
+ *
+ * @see  FTGLfont
+ */
+FTGL_EXPORT FTGLfont *ftglCreateBitmapFont(const char *file);
+
+FTGL_END_C_DECLS
+
 #endif  //  __FTBitmapFont__
 
diff --git a/src/FTGL/FTGLExtrdFont.h b/src/FTGL/FTGLExtrdFont.h
index 05963cd..3404c7f 100644
--- a/src/FTGL/FTGLExtrdFont.h
+++ b/src/FTGL/FTGLExtrdFont.h
@@ -72,5 +72,20 @@ class FTGL_EXPORT FTExtrudeFont : public FTFont
 
 #endif //__cplusplus
 
+FTGL_BEGIN_C_DECLS
+
+/**
+ * Create a specialised FTGLfont object for handling extruded poygon fonts.
+ *
+ * @param file  The font file name.
+ * @return  An FTGLfont* object.
+ *
+ * @see  FTGLfont
+ * @see  ftglCreatePolygonFont
+ */
+FTGL_EXPORT FTGLfont *ftglCreateExtrudeFont(const char *file);
+
+FTGL_END_C_DECLS
+
 #endif // __FTExtrudeFont__
 
diff --git a/src/FTGL/FTGLOutlineFont.h b/src/FTGL/FTGLOutlineFont.h
index 510b0f4..5f8a2f3 100644
--- a/src/FTGL/FTGLOutlineFont.h
+++ b/src/FTGL/FTGLOutlineFont.h
@@ -71,4 +71,19 @@ class FTGL_EXPORT FTOutlineFont : public FTFont
 
 #endif //__cplusplus
 
+FTGL_BEGIN_C_DECLS
+
+/**
+ * Create a specialised FTGLfont object for handling vector outline fonts.
+ *
+ * @param file  The font file name.
+ * @return  An FTGLfont* object.
+ *
+ * @see  FTGLfont
+ */
+FTGL_EXPORT FTGLfont *ftglCreateOutlineFont(const char *file);
+
+FTGL_END_C_DECLS
+
 #endif // __FTOutlineFont__
+
diff --git a/src/FTGL/FTGLPixmapFont.h b/src/FTGL/FTGLPixmapFont.h
index 0b241cf..044674f 100644
--- a/src/FTGL/FTGLPixmapFont.h
+++ b/src/FTGL/FTGLPixmapFont.h
@@ -71,5 +71,19 @@ class FTGL_EXPORT FTPixmapFont : public FTFont
 
 #endif // __cplusplus
 
+FTGL_BEGIN_C_DECLS
+
+/**
+ * Create a specialised FTGLfont object for handling pixmap (grey scale) fonts.
+ *
+ * @param file  The font file name.
+ * @return  An FTGLfont* object.
+ *
+ * @see  FTGLfont
+ */
+FTGL_EXPORT FTGLfont *ftglCreatePixmapFont(const char *file);
+
+FTGL_END_C_DECLS
+
 #endif  //  __FTPixmapFont__
 
diff --git a/src/FTGL/FTGLPolygonFont.h b/src/FTGL/FTGLPolygonFont.h
index 9acff59..c2468d4 100644
--- a/src/FTGL/FTGLPolygonFont.h
+++ b/src/FTGL/FTGLPolygonFont.h
@@ -71,5 +71,20 @@ class FTGL_EXPORT FTPolygonFont : public FTFont
 
 #endif //__cplusplus
 
+FTGL_BEGIN_C_DECLS
+
+/**
+ * Create a specialised FTGLfont object for handling tesselated polygon
+ * mesh fonts.
+ *
+ * @param file  The font file name.
+ * @return  An FTGLfont* object.
+ *
+ * @see  FTGLfont
+ */
+FTGL_EXPORT FTGLfont *ftglCreatePolygonFont(const char *file);
+
+FTGL_END_C_DECLS
+
 #endif  //  __FTPolygonFont__
 
diff --git a/src/FTGL/FTGLTextureFont.h b/src/FTGL/FTGLTextureFont.h
index 02e3f8f..3982847 100644
--- a/src/FTGL/FTGLTextureFont.h
+++ b/src/FTGL/FTGLTextureFont.h
@@ -71,5 +71,19 @@ class  FTGL_EXPORT FTTextureFont : public FTFont
 
 #endif //__cplusplus
 
+FTGL_BEGIN_C_DECLS
+
+/**
+ * Create a specialised FTGLfont object for handling texture-mapped fonts.
+ *
+ * @param file  The font file name.
+ * @return  An FTGLfont* object.
+ *
+ * @see  FTGLfont
+ */
+FTGL_EXPORT FTGLfont *ftglCreateTextureFont(const char *file);
+
+FTGL_END_C_DECLS
+
 #endif // __FTTextureFont__
 
diff --git a/test/CTest.c b/test/CTest.c
index 883126e..3cddc27 100644
--- a/test/CTest.c
+++ b/test/CTest.c
@@ -40,13 +40,13 @@ int main(int argc, char *argv[])
     ALLOC(ftglCreateTextureFont, f[5], argv[1]);
 
     for(i = 0; i < 6; i++)
-        ftglRender(f[i], "Hello world");
+        ftglRenderFont(f[i], "Hello world", FTGL_RENDER_ALL);
 
     for(i = 0; i < 6; i++)
-        ftglSetFaceSize(f[i], 37);
+        ftglSetFontFaceSize(f[i], 37, 72);
 
     for(i = 0; i < 6; i++)
-        ftglRender(f[i], "Hello world");
+        ftglRenderFont(f[i], "Hello world", FTGL_RENDER_ALL);
 
     for(i = 0; i < 6; i++)
         ftglDestroyFont(f[i]);