src/Font/Font_FTFont.hxx

   1 // Created on: 2013-01-28
   2 // Created by: Kirill GAVRILOV
   3 // Copyright (c) 2013-2014 OPEN CASCADE SAS
   4 //
   5 // This file is part of Open CASCADE Technology software library.
   6 //
   7 // This library is free software; you can redistribute it and/or modify it under
   8 // the terms of the GNU Lesser General Public License version 2.1 as published
   9 // by the Free Software Foundation, with special exception defined in the file
  10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  11 // distribution for complete text of the license and disclaimer of any warranty.
  12 //
  13 // Alternatively, this file may be used under the terms of Open CASCADE
  14 // commercial license or contractual agreement.
  15
  16 #ifndef _Font_FTFont_H__
  17 #define _Font_FTFont_H__
  18
  19 #include <Font_FontAspect.hxx>
  20 #include <Font_Rect.hxx>
  21 #include <Font_StrictLevel.hxx>
  22 #include <Graphic3d_HorizontalTextAlignment.hxx>
  23 #include <Graphic3d_VerticalTextAlignment.hxx>
  24 #include <Image_PixMap.hxx>
  25 #include <NCollection_String.hxx>
  26 #include <TCollection_AsciiString.hxx>
  27
  28 // forward declarations to avoid including of FreeType headers
  29 typedef struct FT_FaceRec_* FT_Face;
  30 typedef struct FT_Vector_   FT_Vector;
  31 class Font_FTLibrary;
  32
  33 //! Font initialization parameters.
  34 struct Font_FTFontParams
  35 {
  36   unsigned int PointSize;          //!< face size in points (1/72 inch)
  37   unsigned int Resolution;         //!< resolution of the target device in dpi for FT_Set_Char_Size()
  38   bool         ToSynthesizeItalic; //!< generate italic style (e.g. for font family having no italic style); FALSE by default
  39   bool         IsSingleStrokeFont; //!< single-stroke (one-line) font, FALSE by default
  40
  41   //! Empty constructor.
  42   Font_FTFontParams() : PointSize (0), Resolution (72u), ToSynthesizeItalic (false), IsSingleStrokeFont (false) {}
  43
  44   //! Constructor.
  45   Font_FTFontParams (unsigned int thePointSize,
  46                      unsigned int theResolution)
  47   : PointSize (thePointSize), Resolution (theResolution), ToSynthesizeItalic (false), IsSingleStrokeFont (false) {}
  48 };
  49
  50 DEFINE_STANDARD_HANDLE(Font_FTFont, Standard_Transient)
  51
  52 //! Wrapper over FreeType font.
  53 //! Notice that this class uses internal buffers for loaded glyphs
  54 //! and it is absolutely UNSAFE to load/read glyph from concurrent threads!
  55 class Font_FTFont : public Standard_Transient
  56 {
  57   DEFINE_STANDARD_RTTIEXT(Font_FTFont, Standard_Transient)
  58 public:
  59
  60   //! Find the font Initialize the font.
  61   //! @param theFontName    the font name
  62   //! @param theFontAspect  the font style
  63   //! @param theParams      initialization parameters
  64   //! @param theStrictLevel search strict level for using aliases and fallback
  65   //! @return true on success
  66   Standard_EXPORT static Handle(Font_FTFont) FindAndCreate (const TCollection_AsciiString& theFontName,
  67                                                             const Font_FontAspect     theFontAspect,
  68                                                             const Font_FTFontParams&  theParams,
  69                                                             const Font_StrictLevel    theStrictLevel = Font_StrictLevel_Any);
  70
  71 public:
  72
  73   //! Create uninitialized instance.
  74   Standard_EXPORT Font_FTFont (const Handle(Font_FTLibrary)& theFTLib = Handle(Font_FTLibrary)());
  75
  76   //! Destructor.
  77   Standard_EXPORT virtual ~Font_FTFont();
  78
  79   //! @return true if font is loaded
  80   inline bool IsValid() const
  81   {
  82     return myFTFace != NULL;
  83   }
  84
  85   //! @return image plane for currently rendered glyph
  86   inline const Image_PixMap& GlyphImage() const
  87   {
  88     return myGlyphImg;
  89   }
  90
  91   //! Initialize the font from the given file path.
  92   //! @param theFontPath path to the font
  93   //! @param theParams   initialization parameters
  94   //! @return true on success
  95   bool Init (const TCollection_AsciiString& theFontPath,
  96              const Font_FTFontParams& theParams)
  97   {
  98     return Init (Handle(NCollection_Buffer)(), theFontPath, theParams);
  99   }
 100
 101   //! Initialize the font from the given file path or memory buffer.
 102   //! @param theData     memory to read from, should NOT be freed after initialization!
 103   //!                    when NULL, function will attempt to open theFileName file
 104   //! @param theFileName optional path to the font
 105   //! @param theParams   initialization parameters
 106   //! @return true on success
 107   Standard_EXPORT bool Init (const Handle(NCollection_Buffer)& theData,
 108                              const TCollection_AsciiString& theFileName,
 109                              const Font_FTFontParams& theParams);
 110
 111   //! Find (using Font_FontMgr) and initialize the font from the given name.
 112   //! @param theFontName    the font name
 113   //! @param theFontAspect  the font style
 114   //! @param theParams      initialization parameters
 115   //! @param theStrictLevel search strict level for using aliases and fallback
 116   //! @return true on success
 117   Standard_EXPORT bool FindAndInit (const TCollection_AsciiString& theFontName,
 118                                     Font_FontAspect theFontAspect,
 119                                     const Font_FTFontParams& theParams,
 120                                     Font_StrictLevel theStrictLevel = Font_StrictLevel_Any);
 121
 122   //! Return TRUE if this is single-stroke (one-line) font, FALSE by default.
 123   //! Such fonts define single-line glyphs instead of closed contours, so that they are rendered incorrectly by normal software.
 124   bool IsSingleStrokeFont() const { return myFontParams.IsSingleStrokeFont; }
 125
 126   //! Set if this font should be rendered as single-stroke (one-line).
 127   void SetSingleStrokeFont (bool theIsSingleLine) { myFontParams.IsSingleStrokeFont = theIsSingleLine; }
 128
 129   //! Return TRUE if italic style should be synthesized; FALSE by default.
 130   bool ToSynthesizeItalic() const { return myFontParams.ToSynthesizeItalic; }
 131
 132   //! Release currently loaded font.
 133   Standard_EXPORT virtual void Release();
 134
 135   //! Render specified glyph into internal buffer (bitmap).
 136   Standard_EXPORT bool RenderGlyph (const Standard_Utf32Char theChar);
 137
 138   //! @return maximal glyph width in pixels (rendered to bitmap).
 139   Standard_EXPORT unsigned int GlyphMaxSizeX() const;
 140
 141   //! @return maximal glyph height in pixels (rendered to bitmap).
 142   Standard_EXPORT unsigned int GlyphMaxSizeY() const;
 143
 144   //! @return vertical distance from the horizontal baseline to the highest character coordinate.
 145   Standard_EXPORT float Ascender() const;
 146
 147   //! @return vertical distance from the horizontal baseline to the lowest character coordinate.
 148   Standard_EXPORT float Descender() const;
 149
 150   //! @return default line spacing (the baseline-to-baseline distance).
 151   Standard_EXPORT float LineSpacing() const;
 152
 153   //! Configured point size
 154   unsigned int PointSize() const
 155   {
 156     return myFontParams.PointSize;
 157   }
 158
 159   //! Setup glyph scaling along X-axis.
 160   //! By default glyphs are not scaled (scaling factor = 1.0)
 161   void SetWidthScaling (const float theScaleFactor)
 162   {
 163     myWidthScaling = theScaleFactor;
 164   }
 165
 166   //! Compute horizontal advance to the next character with kerning applied when applicable.
 167   //! Assuming text rendered horizontally.
 168   //! @param theUCharNext the next character to compute advance from current one
 169   Standard_EXPORT float AdvanceX (Standard_Utf32Char theUCharNext) const;
 170
 171   //! Compute horizontal advance to the next character with kerning applied when applicable.
 172   //! Assuming text rendered horizontally.
 173   //! @param theUChar     the character to be loaded as current one
 174   //! @param theUCharNext the next character to compute advance from current one
 175   Standard_EXPORT float AdvanceX (Standard_Utf32Char theUChar,
 176                                   Standard_Utf32Char theUCharNext);
 177
 178   //! Compute vertical advance to the next character with kerning applied when applicable.
 179   //! Assuming text rendered vertically.
 180   //! @param theUCharNext the next character to compute advance from current one
 181   Standard_EXPORT float AdvanceY (Standard_Utf32Char theUCharNext) const;
 182
 183   //! Compute vertical advance to the next character with kerning applied when applicable.
 184   //! Assuming text rendered vertically.
 185   //! @param theUChar     the character to be loaded as current one
 186   //! @param theUCharNext the next character to compute advance from current one
 187   Standard_EXPORT float AdvanceY (Standard_Utf32Char theUChar,
 188                                   Standard_Utf32Char theUCharNext);
 189
 190   //! @return glyphs number in this font.
 191   Standard_EXPORT Standard_Integer GlyphsNumber() const;
 192
 193   //! Retrieve glyph bitmap rectangle
 194   Standard_EXPORT void GlyphRect (Font_Rect& theRect) const;
 195
 196   //! Computes bounding box of the given text using plain-text formatter (Font_TextFormatter).
 197   //! Note that bounding box takes into account the text alignment options.
 198   //! Its corners are relative to the text alignment anchor point, their coordinates can be negative.
 199   Standard_EXPORT Font_Rect BoundingBox (const NCollection_String&               theString,
 200                                          const Graphic3d_HorizontalTextAlignment theAlignX,
 201                                          const Graphic3d_VerticalTextAlignment   theAlignY);
 202
 203 public:
 204
 205   //! Initialize the font.
 206   //! @param theFontPath   path to the font
 207   //! @param thePointSize  the face size in points (1/72 inch)
 208   //! @param theResolution the resolution of the target device in dpi
 209   //! @return true on success
 210   Standard_DEPRECATED ("Deprecated method, Font_FTFontParams should be used for passing parameters")
 211   bool Init (const NCollection_String& theFontPath,
 212              unsigned int thePointSize,
 213              unsigned int theResolution)
 214   {
 215     Font_FTFontParams aParams;
 216     aParams.PointSize  = thePointSize;
 217     aParams.Resolution = theResolution;
 218     return Init (theFontPath.ToCString(), aParams);
 219   }
 220
 221   //! Initialize the font.
 222   //! @param theFontName   the font name
 223   //! @param theFontAspect the font style
 224   //! @param thePointSize  the face size in points (1/72 inch)
 225   //! @param theResolution the resolution of the target device in dpi
 226   //! @return true on success
 227   Standard_DEPRECATED ("Deprecated method, Font_FTFontParams should be used for passing parameters")
 228   bool Init (const NCollection_String& theFontName,
 229              Font_FontAspect theFontAspect,
 230              unsigned int thePointSize,
 231              unsigned int theResolution)
 232   {
 233     Font_FTFontParams aParams;
 234     aParams.PointSize  = thePointSize;
 235     aParams.Resolution = theResolution;
 236     return FindAndInit (theFontName.ToCString(), theFontAspect, aParams);
 237   }
 238
 239 protected:
 240
 241   //! Convert value to 26.6 fixed-point format for FT library API.
 242   template <typename theInput_t>
 243   int32_t toFTPoints (const theInput_t thePointSize) const
 244   {
 245     return (int32_t)thePointSize * 64;
 246   }
 247
 248   //! Convert value from 26.6 fixed-point format for FT library API.
 249   template <typename theReturn_t, typename theFTUnits_t>
 250   inline theReturn_t fromFTPoints (const theFTUnits_t theFTUnits) const
 251   {
 252     return (theReturn_t)theFTUnits / 64.0f;
 253   }
 254
 255 protected:
 256
 257   //! Load glyph without rendering it.
 258   Standard_EXPORT bool loadGlyph (const Standard_Utf32Char theUChar);
 259
 260   //! Wrapper for FT_Get_Kerning - retrieve kerning values.
 261   Standard_EXPORT bool getKerning (FT_Vector& theKern,
 262                                    Standard_Utf32Char theUCharCurr,
 263                                    Standard_Utf32Char theUCharNext) const;
 264
 265 protected:
 266
 267   Handle(Font_FTLibrary)     myFTLib;        //!< handle to the FT library object
 268   Handle(NCollection_Buffer) myBuffer;       //!< memory buffer
 269   FT_Face                    myFTFace;       //!< FT face object
 270   TCollection_AsciiString    myFontPath;     //!< font path
 271   Font_FTFontParams          myFontParams;   //!< font initialization parameters
 272   float                      myWidthScaling; //!< scale glyphs along X-axis
 273   int32_t                    myLoadFlags;    //!< default load flags
 274
 275   Image_PixMap               myGlyphImg;     //!< cached glyph plane
 276   Standard_Utf32Char         myUChar;        //!< currently loaded unicode character
 277
 278 };
 279
 280 #endif // _Font_FTFont_H__