0031458: Visualization - refine classes across Prs3d and StdPrs packages
[occt.git] / src / StdPrs / StdPrs_BRepFont.hxx
1 // Created on: 2013-09-16
2 // Copyright (c) 2013-2014 OPEN CASCADE SAS
3 //
4 // This file is part of Open CASCADE Technology software library.
5 //
6 // This library is free software; you can redistribute it and/or modify it under
7 // the terms of the GNU Lesser General Public License version 2.1 as published
8 // by the Free Software Foundation, with special exception defined in the file
9 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
10 // distribution for complete text of the license and disclaimer of any warranty.
11 //
12 // Alternatively, this file may be used under the terms of Open CASCADE
13 // commercial license or contractual agreement.
14
15 #ifndef _StdPrs_BRepFont_H__
16 #define _StdPrs_BRepFont_H__
17
18 #include <Adaptor3d_CurveOnSurface.hxx>
19 #include <BRep_Builder.hxx>
20 #include <Font_FTFont.hxx>
21 #include <Font_TextFormatter.hxx>
22 #include <Geom2dAdaptor_HCurve.hxx>
23 #include <Geom2dConvert_CompCurveToBSplineCurve.hxx>
24 #include <gp_Ax3.hxx>
25 #include <gp_XY.hxx>
26 #include <gp_XYZ.hxx>
27 #include <NCollection_DataMap.hxx>
28 #include <NCollection_String.hxx>
29 #include <Standard_Mutex.hxx>
30 #include <TColgp_Array1OfPnt2d.hxx>
31 #include <TopoDS_Shape.hxx>
32 #include <TopoDS_Face.hxx>
33 #include <TopTools_SequenceOfShape.hxx>
34
35 DEFINE_STANDARD_HANDLE(StdPrs_BRepFont, Font_FTFont)
36
37 //! This tool provides basic services for rendering of vectorized text glyphs as BRep shapes.
38 //! Single instance initialize single font for sequential glyphs rendering with implicit caching of already rendered glyphs.
39 //! Thus position of each glyph in the text is specified by shape location.
40 //!
41 //! Please notice that this implementation uses mutex for thread-safety access,
42 //! thus may lead to performance penalties in case of concurrent access.
43 //! Although caching should eliminate this issue after rendering of sufficient number of glyphs.
44 class StdPrs_BRepFont : protected Font_FTFont
45 {
46   DEFINE_STANDARD_RTTIEXT(StdPrs_BRepFont, Font_FTFont)
47 public:
48
49   //! Empty constructor
50   Standard_EXPORT StdPrs_BRepFont();
51
52   //! Constructor with initialization.
53   //! @param theFontPath FULL path to the font
54   //! @param theSize     the face size in model units
55   //! @param theFaceId   face id within the file (0 by default)
56   Standard_EXPORT StdPrs_BRepFont (const NCollection_String& theFontPath,
57                                    const Standard_Real       theSize,
58                                    const Standard_Integer    theFaceId = 0);
59
60   //! Constructor with initialization.
61   //! @param theFontName    the font name
62   //! @param theFontAspect  the font style
63   //! @param theSize        the face size in model units
64   //! @param theStrictLevel search strict level for using aliases and fallback
65   Standard_EXPORT StdPrs_BRepFont (const NCollection_String& theFontName,
66                                    const Font_FontAspect     theFontAspect,
67                                    const Standard_Real       theSize,
68                                    const Font_StrictLevel    theStrictLevel = Font_StrictLevel_Any);
69
70   //! Release currently loaded font.
71   Standard_EXPORT virtual void Release() Standard_OVERRIDE;
72
73   //! Initialize the font.
74   //! @param theFontPath FULL path to the font
75   //! @param theSize     the face size in model units
76   //! @param theFaceId   face id within the file (0 by default)
77   //! @return true on success
78   Standard_EXPORT bool Init (const NCollection_String& theFontPath,
79                              const Standard_Real       theSize,
80                              const Standard_Integer    theFaceId);
81
82   //! Find (using Font_FontMgr) and initialize the font from the given name.
83   //! Please take into account that size is specified NOT in typography points (pt.).
84   //! If you need to specify size in points, value should be converted.
85   //! Formula for pt. -> m conversion:
86   //!   aSizeMeters = 0.0254 * theSizePt / 72.0
87   //! @param theFontName   the font name
88   //! @param theFontAspect the font style
89   //! @param theSize       the face size in model units
90   //! @param theStrictLevel search strict level for using aliases and fallback
91   //! @return true on success
92   Standard_EXPORT bool FindAndInit (const TCollection_AsciiString& theFontName,
93                                     const Font_FontAspect  theFontAspect,
94                                     const Standard_Real    theSize,
95                                     const Font_StrictLevel theStrictLevel = Font_StrictLevel_Any);
96
97   //! Render single glyph as TopoDS_Shape.
98   //! @param theChar glyph identifier
99   //! @return rendered glyph within cache, might be NULL shape
100   Standard_EXPORT TopoDS_Shape RenderGlyph (const Standard_Utf32Char& theChar);
101
102   //! Setup glyph geometry construction mode.
103   //! By default algorithm creates independent TopoDS_Edge
104   //! for each original curve in the glyph (line segment or Bezie curve).
105   //! Algorithm might optionally create composite BSpline curve for each contour
106   //! which reduces memory footprint but limits curve class to C0.
107   //! Notice that altering this flag clears currently accumulated cache!
108   Standard_EXPORT void SetCompositeCurveMode (const Standard_Boolean theToConcatenate);
109
110   //! Setup glyph scaling along X-axis.
111   //! By default glyphs are not scaled (scaling factor = 1.0)
112   void SetWidthScaling (const float theScaleFactor)
113   {
114     myWidthScaling = theScaleFactor;
115   }
116
117 public:
118
119   //! @return vertical distance from the horizontal baseline to the highest character coordinate.
120   Standard_Real Ascender() const
121   {
122     return myScaleUnits * Standard_Real(Font_FTFont::Ascender());
123   }
124
125   //! @return vertical distance from the horizontal baseline to the lowest character coordinate.
126   Standard_Real Descender() const
127   {
128     return myScaleUnits * Standard_Real(Font_FTFont::Descender());
129   }
130
131   //! @return default line spacing (the baseline-to-baseline distance).
132   Standard_Real LineSpacing() const
133   {
134     return myScaleUnits * Standard_Real(Font_FTFont::LineSpacing());
135   }
136
137   //! Configured point size
138   Standard_Real PointSize() const
139   {
140     return myScaleUnits * Standard_Real(Font_FTFont::PointSize());
141   }
142
143   //! Compute advance to the next character with kerning applied when applicable.
144   //! Assuming text rendered horizontally.
145   Standard_Real AdvanceX (const Standard_Utf32Char theUCharNext)
146   {
147     return myScaleUnits * Standard_Real(Font_FTFont::AdvanceX (theUCharNext));
148   }
149
150   //! Compute advance to the next character with kerning applied when applicable.
151   //! Assuming text rendered horizontally.
152   Standard_Real AdvanceX (const Standard_Utf32Char theUChar,
153                           const Standard_Utf32Char theUCharNext)
154   {
155     return myScaleUnits * Standard_Real(Font_FTFont::AdvanceX (theUChar, theUCharNext));
156   }
157
158   //! Compute advance to the next character with kerning applied when applicable.
159   //! Assuming text rendered vertically.
160   Standard_Real AdvanceY (const Standard_Utf32Char theUCharNext)
161   {
162     return myScaleUnits * Standard_Real(Font_FTFont::AdvanceY (theUCharNext));
163   }
164
165   //! Compute advance to the next character with kerning applied when applicable.
166   //! Assuming text rendered vertically.
167   Standard_Real AdvanceY (const Standard_Utf32Char theUChar,
168                           const Standard_Utf32Char theUCharNext)
169   {
170     return myScaleUnits * Standard_Real(Font_FTFont::AdvanceY (theUChar, theUCharNext));
171   }
172
173   //! Returns scaling factor for current font size.
174   Standard_Real Scale() const
175   {
176     return myScaleUnits;
177   }
178
179   //! Returns mutex.
180   Standard_Mutex& Mutex()
181   {
182     return myMutex;
183   }
184
185 public:
186
187   //! Find (using Font_FontMgr) and initialize the font from the given name.
188   //! Alias for FindAndInit() for backward compatibility.
189   bool Init (const NCollection_String& theFontName,
190              const Font_FontAspect     theFontAspect,
191              const Standard_Real       theSize)
192   {
193     return FindAndInit (theFontName.ToCString(), theFontAspect, theSize, Font_StrictLevel_Any);
194   }
195
196 protected:
197
198   //! Render single glyph as TopoDS_Shape. This method does not lock the mutex.
199   //! @param theChar  glyph identifier
200   //! @param theShape rendered glyph within cache, might be NULL shape
201   //! @return true if glyph's geometry is available
202   Standard_EXPORT Standard_Boolean renderGlyph (const Standard_Utf32Char theChar,
203                                                 TopoDS_Shape&            theShape);
204
205 private:
206
207   //! Initialize class fields
208   void init();
209
210   //! Auxiliary method to create 3D curve
211   bool to3d (const Handle(Geom2d_Curve)& theCurve2d,
212              const GeomAbs_Shape        theContinuity,
213              Handle(Geom_Curve)&        theCurve3d);
214
215   //! Auxiliary method for creation faces from sequence of wires.
216   //! Splits to few faces (if it is needed) and updates orientation of wires.
217   Standard_Boolean buildFaces (const NCollection_Sequence<TopoDS_Wire>& theWires,
218                                TopoDS_Shape& theRes);
219
220   //! Hide visibility.
221   using Font_FTFont::FindAndCreate;
222
223 protected: //! @name Protected fields
224
225   NCollection_DataMap<Standard_Utf32Char, TopoDS_Shape>
226                        myCache;            //!< glyphs cache
227   Standard_Mutex       myMutex;            //!< lock for thread-safety
228   Handle(Geom_Surface) mySurface;          //!< surface to place glyphs on to
229   Standard_Real        myPrecision;        //!< algorithm precision
230   Standard_Real        myScaleUnits;       //!< scale font rendering units into model units
231   Standard_Boolean     myIsCompositeCurve; //!< flag to merge C1 curves of each contour into single C0 curve, OFF by default
232
233 protected: //! @name Shared temporary variables for glyph construction
234
235   Adaptor3d_CurveOnSurface myCurvOnSurf;
236   Handle(Geom2dAdaptor_HCurve) myCurve2dAdaptor;
237   Geom2dConvert_CompCurveToBSplineCurve myConcatMaker;
238   TColgp_Array1OfPnt2d     my3Poles;
239   TColgp_Array1OfPnt2d     my4Poles;
240   BRep_Builder             myBuilder;
241
242 };
243
244 #endif // _StdPrs_BRepFont_H__