kc3-lang/ftgl/src/FTGL/FTFont.h

• Show log

  Commit

• Hash : e9260bbf
  Author :
  Date : 2008-05-08T22:35:57
  

  * Implement C bindings for FTGlyph and FTFont subclassing. * Add subclassing to the simple C demo to show how to do similar stuff as in the C++ demo.

Download

• src/FTGL/FTFont.h

• /*
   * FTGL - OpenGL font library
   *
   * Copyright (c) 2001-2004 Henry Maddocks <ftgl@opengl.geek.nz>
   * Copyright (c) 2008 Sam Hocevar <sam@zoy.org>
   * Copyright (c) 2008 Sean Morrison <learner@brlcad.org>
   *
   * Permission is hereby granted, free of charge, to any person obtaining
   * a copy of this software and associated documentation files (the
   * "Software"), to deal in the Software without restriction, including
   * without limitation the rights to use, copy, modify, merge, publish,
   * distribute, sublicense, and/or sell copies of the Software, and to
   * permit persons to whom the Software is furnished to do so, subject to
   * the following conditions:
   *
   * The above copyright notice and this permission notice shall be
   * included in all copies or substantial portions of the Software.
   *
   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
   * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
   * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
   * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
   * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
   * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
   */
  
  #ifndef __ftgl__
  #   warning This header is deprecated. Please use <FTGL/ftgl.h> from now.
  #   include <FTGL/ftgl.h>
  #endif
  
  #ifndef __FTFont__
  #define __FTFont__
  
  #ifdef __cplusplus
  
  class FTFontImpl;
  
  /**
   * FTFont is the public interface for the FTGL library.
   *
   * Specific font classes are derived from this class. It uses the helper
   * classes FTFace and FTSize to access the Freetype library. This class
   * is abstract and deriving classes must implement the protected
   * <code>MakeGlyph</code> function to create glyphs of the
   * appropriate type.
   *
   * It is good practice after using these functions to test the error
   * code returned. <code>FT_Error Error()</code>. Check the freetype file
   * fterrdef.h for error definitions.
   *
   * @see     FTFace
   * @see     FTSize
   */
  class FTGL_EXPORT FTFont
  {
      protected:
          /**
           * Open and read a font file. Sets Error flag.
           *
           * @param fontFilePath  font file path.
           */
          FTFont(char const *fontFilePath);
  
          /**
           * Open and read a font from a buffer in memory. Sets Error flag.
           * The buffer is owned by the client and is NOT copied by FTGL. The
           * pointer must be valid while using FTGL.
           *
           * @param pBufferBytes  the in-memory buffer
           * @param bufferSizeInBytes  the length of the buffer in bytes
           */
          FTFont(const unsigned char *pBufferBytes, size_t bufferSizeInBytes);
  
      private:
          /* Allow our internal subclasses to access the private constructor */
          friend class FTBitmapFont;
          friend class FTExtrudeFont;
          friend class FTOutlineFont;
          friend class FTPixmapFont;
          friend class FTPolygonFont;
          friend class FTTextureFont;
  
          /**
           * Internal FTGL FTFont constructor. For private use only.
           *
           * @param pImpl  Internal implementation object. Will be destroyed
           *               upon FTFont deletion.
           */
          FTFont(FTFontImpl *pImpl);
  
      public:
          virtual ~FTFont();
  
          /**
           * Attach auxilliary file to font e.g font metrics.
           *
           * Note: not all font formats implement this function.
           *
           * @param fontFilePath  auxilliary font file path.
           * @return          <code>true</code> if file has been attached
           *                  successfully.
           */
          virtual bool Attach(const char* fontFilePath);
  
          /**
           * 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.
           * @return          <code>true</code> if file has been attached
           *                  successfully.
           */
          virtual bool Attach(const unsigned char *pBufferBytes,
                              size_t bufferSizeInBytes);
  
          /**
           * Set the character map for the face.
           *
           * @param encoding      Freetype enumerate for char map code.
           * @return              <code>true</code> if charmap was valid and
           *                      set correctly.
           */
          virtual bool CharMap(FT_Encoding encoding);
  
          /**
           * Get the number of character maps in this face.
           *
           * @return character map count.
           */
          virtual unsigned int CharMapCount() const;
  
          /**
           * Get a list of character maps in this face.
           *
           * @return pointer to the first encoding.
           */
          virtual FT_Encoding* CharMapList();
  
          /**
           * Set the char size for the current face.
           *
           * @param size      the face size in points (1/72 inch)
           * @param res       the resolution of the target device.
           * @return          <code>true</code> if size was set correctly
           */
          virtual bool FaceSize(const unsigned int size,
                                const unsigned int res = 72);
  
          /**
           * Get the current face size in points (1/72 inch).
           *
           * @return face size
           */
          virtual unsigned int FaceSize() const;
  
          /**
           * Set the extrusion distance for the font. Only implemented by
           * FTExtrudeFont
           *
           * @param depth  The extrusion distance.
           */
          virtual void Depth(float depth);
  
          /**
           * Set the outset distance for the font. Only implemented by
           * FTOutlineFont, FTPolygonFont and FTExtrudeFont
           *
           * @param outset  The outset distance.
           */
          virtual void Outset(float outset);
  
          /**
           * Set the front and back outset distances for the font. Only
           * implemented by FTExtrudeFont
           *
           * @param front  The front outset distance.
           * @param back   The back outset distance.
           */
          virtual void Outset(float front, float back);
  
          /**
           * Enable or disable the use of Display Lists inside FTGL
           *
           * @param  useList <code>true</code> turns ON display lists.
           *                 <code>false</code> turns OFF display lists.
           */
          virtual void UseDisplayList(bool useList);
  
          /**
           * Get the global ascender height for the face.
           *
           * @return  Ascender height
           */
          virtual float Ascender() const;
  
          /**
           * Gets the global descender height for the face.
           *
           * @return  Descender height
           */
          virtual float Descender() const;
  
          /**
           * Gets the line spacing for the font.
           *
           * @return  Line height
           */
          virtual float LineHeight() const;
  
          /**
           * Get the bounding box for a string.
           *
           * @param string  A char buffer.
           * @return  The corresponding bounding box.
           */
          virtual FTBBox BBox(const char *string);
  
          /**
           * Get the bounding box for a string.
           *
           * @param string  A wchar_t buffer.
           * @return  The corresponding bounding box.
           */
          virtual FTBBox BBox(const wchar_t *string);
  
          /**
           * Get the bounding box for a string.
           *
           * @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.
           * @return  The corresponding bounding box.
           */
          virtual FTBBox BBox(const char *string,
                              const int start, const int end);
  
          /**
           * Get the bounding box for a string.
           *
           * @param string  A wchar_t 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.
           * @return  The corresponding bounding box.
           */
          virtual FTBBox BBox(const wchar_t *string,
                              const int start, const int end);
  
          /**
           * Get the advance width for a string.
           *
           * @param string    a wchar_t string
           * @return      advance width
           */
          virtual float Advance(const wchar_t* string);
  
          /**
           * Get the advance width for a string.
           *
           * @param string    a char string
           * @return      advance width
           */
          virtual float Advance(const char* string);
  
          /**
           * Render a string of characters
           *
           * @param string    'C' style string to be output.
           */
          virtual void Render(const char* string);
  
          /**
           * Render a string of characters
           *
           * @param string    'C' style string to be output.
           * @param renderMode    Render mode to display
           */
          virtual void Render(const char* string, int renderMode);
  
          /**
           * Render a string of characters
           *
           * @param string    wchar_t string to be output.
           */
          virtual void Render(const wchar_t* string);
  
          /**
           * Render a string of characters
           *
           * @param string    wchar_t string to be output.
           * @param renderMode    Render mode to display
           */
          virtual void Render(const wchar_t *string, int renderMode);
  
          /**
           * Queries the Font for errors.
           *
           * @return  The current error code.
           */
          virtual FT_Error Error() const;
  
      protected:
          /* Allow impl to access MakeGlyph */
          friend class FTFontImpl;
  
          /**
           * Construct a glyph of the correct type.
           *
           * Clients must override the function and return their specialised
           * FTGlyph.
           *
           * @param slot  A FreeType glyph slot.
           * @return  An FT****Glyph or <code>null</code> on failure.
           */
          virtual FTGlyph* MakeGlyph(FT_GlyphSlot slot) = 0;
  
      private:
          /* Allow FTLayout classes to access this->impl. */
          friend class FTLayoutImpl;
  
          /**
           * Internal FTGL FTFont implementation object. For private use only.
           */
          FTFontImpl *impl;
  };
  
  #endif //__cplusplus
  
  FTGL_BEGIN_C_DECLS
  
  /**
   * FTGLfont is the public interface for the FTGL library.
   *
   * It is good practice after using these functions to test the error
   * code returned. <code>FT_Error Error()</code>. Check the freetype file
   * fterrdef.h for error definitions.
   */
  struct _FTGLFont;
  typedef struct _FTGLfont FTGLfont;
  
  /**
   * Create a custom FTGL font object.
   *
   * @param fontFilePath  The font file name.
   * @param data  A pointer to private data that will be passed to callbacks.
   * @param makeglyphCallback  A glyph-making callback function.
   * @return  An FTGLfont* object.
   */
  FTGL_EXPORT FTGLfont *ftglCreateCustomFont(char const *fontFilePath,
                                             void *data,
                     FTGLglyph * (*makeglyphCallback) (FT_GlyphSlot, void *));
  
  /**
   * 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);
  
  /**
   * Set the extrusion distance for the font. Only implemented by
   * FTExtrudeFont.
   *
   * @param font  An FTGLfont* object.
   * @param depth  The extrusion distance.
   */
  FTGL_EXPORT void ftglSetFontDepth(FTGLfont* font, float depth);
  
  /**
   * 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);
  
  /**
   * 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 ftglSetFontDisplayList(FTGLfont* font, int useList);
  
  /**
   * Get the global ascender height for the face.
   *
   * @param font  An FTGLfont* object.
   * @return  Ascender height
   */
  FTGL_EXPORT float ftglGetFontAscender(FTGLfont* font);
  
  /**
   * Gets the global descender height for the face.
   *
   * @param font  An FTGLfont* object.
   * @return  Descender height
   */
  FTGL_EXPORT float ftglGetFontDescender(FTGLfont* font);
  
  /**
   * 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);
  
  /**
   * Query a font for errors.
   *
   * @param font  An FTGLfont* object.
   * @return  The current error code.
   */
  FTGL_EXPORT FT_Error ftglGetFontError(FTGLfont* font);
  
  FTGL_END_C_DECLS
  
  #endif  //  __FTFont__
  
  

Download