FreeType in OpenCASCADE
eryar@163.com
Abstract. FreeType is required for text display in the 3D viewer. FreeType is a software font engine that is designed to be small, efficient, highly customizable, and portable while capable of producing high-quality output(glyph images). It can be used in graphics libraries, display servers, font conversion tools, text image generation tools, and many other products as well. The blog is focus on the FreeType usage in OpenCASCADE to convert text to BRep shape.
Key Words. FreeType, OpenCASCADE, Text, BRep
1.Introduction
FreeType 2被設計為一種占用空間小的、高效的、高度可定制的、并且可以產生可移植的高品質輸出（符號圖像）。可以被用在諸如圖像庫、展出服務器、字體轉換工具、圖像文字產生工具等多種其它產品上。
注意FreeType 2是一種字體服務而沒有提供為實現文字布局或圖形化處理這樣高階的功能使用的API（比如帶色文字渲染之類的）。然而，它提供一個簡單的、易用的并且統一的接口實現對多種字體文件的訪問，從而大大簡化了這些高級的任務。
FreeType 2的發行遵循兩個開源許可：我們自己的BSD樣式的FreeType License和GPL（通用公共許可證）。它可以被用在任何程序中，無論是專有與否。
在常見的圖形庫中，如OpenSceneGraph, OpenCASCADE, HOOPS, Qt,等涉及到文字處理的，都會用到FreeType. 在一些游戲開發中，也會用到FreeType.本文主要對FreeType的用法作簡單介紹，這樣對FreeType有個直觀認識。然后再介紹FreeType對文字輪廓的表示方法，及如何生成三維文字。
在OpenCASCADE中文字可以二維的方式顯示，也可以三維的方式顯示，三維方式可以有線框和渲染模式，如下圖所示：
Figure 1. 2D Text in Length Dimension
Figure 2. 3D Wireframe Text in Dimension
Figure 3. 3D Shading Text in Dimension
2.FreeType Usage
在FreeType的官網上有詳細的教程說明FreeType的用法，網址為：https://www.freetype.org/freetype2/docs/tutorial/index.html
主要的步驟如下：
v 包含頭文件 Header Files;
v 庫的初始化 Library Initialization;
v 加載字體 Loading a Font Face;
v 訪問字體數據 Accessing the Face Data;
v 設置當前像素大小 Setting the Current Pixel Size;
v 加載文字 Loading a Glyph Image;
v 簡單的顯示 Simple Text Rendering；
下面代碼是上述過程的一個實現，忽略了錯誤處理：
#include <ft2build.h>
#include FT_FREETYPE_H
#pragma comment(lib, "freetype.lib")
void test(void)
{
FT_Face aFace = NULL;
FT_Library aLibrary = NULL;
// Library Initialization.
FT_Init_FreeType(&aLibrary);
// Loading a Font Face.
FT_New_Face(aLibrary, "C:/Windows/Fonts/arial.ttf", 0, &aFace);
// Setting the Current Pixel Size.
FT_Set_Char_Size(
aFace, /* handle to face object */
0, /* char_width in 1/64th of points */
16*64, /* char_height in 1/64th of points */
300, /* horizontal device resolution */
300 ); /* vertical device resolution */
// Loading a Glyph Image
// a. Converting a Character Code Into a Glyph Index
FT_UInt aGlyphIndex = FT_Get_Char_Index( aFace, 'A' );
// b. Loading a Glyph From the Face
// Once you have a glyph index, you can load the corresponding glyph image.
FT_Load_Glyph(
aFace, /* handle to face object */
aGlyphIndex, /* glyph index */
FT_LOAD_DEFAULT); /* load flags */
// Simple Text Rendering
FT_GlyphSlot aGlyphSlot = aFace->glyph;
}
int main(int argc, char* argv[])
{
test();
return 0;
}
調試程序可以看出Face中已經有了一些數據。
3.FreeType Outlines
FreeType中的一個文字輪廓Outline是由二維空間閉合的線圍成。每一個輪廓線是由一系列的直線段和Bezier曲線組成。根據字體文件格式的不同，他們可能是二階或三階多項式。二階的通常稱為quadratic或conic弧，他們用于TrueType格式。三階的稱為cubic弧，通常用于PostScript Type1, CFF, 和CFF2格式中。詳細描述見：
https://www.freetype.org/freetype2/docs/glyphs/glyphs-6.html
Bezier曲線是B樣條曲線的一個特例，他的特點就是曲線的階數與控制點的個數相關，即給定控制頂點就可以確定Bezier曲線。所以OpenCASCADE中對于Bezier曲線有這樣的構造函數：
每一段曲線弧都由起點start，終點end和控制頂點control points來描述。描述輪廓線的每個點都有一個特定的標記Tag來區別是線段還是Bezier曲線。
兩個連續的on點確定了線段的兩個端點；
在兩個on點之間的一個conic off點組成了一個conic Bezier曲線；
在兩個on點之間的兩個cubic off點組成了一個cubic Bezier曲線；
理解了上述內容就可以得到文字的輪廓線了。OpenCASCADE中對輪廓線的處理代碼如下所示：
// =======================================================================
// function : renderGlyph
// purpose :
// =======================================================================
Standard_Boolean Font_BRepFont::renderGlyph (const Standard_Utf32Char theChar,
TopoDS_Shape& theShape)
{
theShape.Nullify();
if (!loadGlyph (theChar)
|| myFTFace->glyph->format != FT_GLYPH_FORMAT_OUTLINE)
{
return Standard_False;
}
else if (myCache.Find (theChar, theShape))
{
return !theShape.IsNull();
}
FT_Outline& anOutline = myFTFace->glyph->outline;
if (!anOutline.n_contours)
return Standard_False;
TopLoc_Location aLoc;
TopoDS_Face aFaceDraft;
myBuilder.MakeFace (aFaceDraft, mySurface, myPrecision);
// Get orientation is useless since it doesn't retrieve any in-font information and just computes orientation.
// Because it fails in some cases - leave this to ShapeFix.
//const FT_Orientation anOrient = FT_Outline_Get_Orientation (&anOutline);
for (short aContour = 0, aStartIndex = 0; aContour < anOutline.n_contours; ++aContour)
{
const FT_Vector* aPntList = &anOutline.points[aStartIndex];
const char* aTags = &anOutline.tags[aStartIndex];
const short anEndIndex = anOutline.contours[aContour];
const short aPntsNb = (anEndIndex - aStartIndex) + 1;
aStartIndex = anEndIndex + 1;
if (aPntsNb < 3)
{
// closed contour can not be constructed from < 3 points
continue;
}
BRepBuilderAPI_MakeWire aWireMaker;
gp_XY aPntPrev;
gp_XY aPntCurr = readFTVec (aPntList[aPntsNb - 1]);
gp_XY aPntNext = readFTVec (aPntList[0]);
Standard_Integer aLinePnts = (FT_CURVE_TAG(aTags[aPntsNb - 1]) == FT_Curve_Tag_On) ? 1 : 0;
gp_XY aPntLine1 = aPntCurr;
// see http://freetype.sourceforge.net/freetype2/docs/glyphs/glyphs-6.html
// for a full description of FreeType tags.
for (short aPntId = 0; aPntId < aPntsNb; ++aPntId)
{
aPntPrev = aPntCurr;
aPntCurr = aPntNext;
aPntNext = readFTVec (aPntList[(aPntId + 1) % aPntsNb]);
// process tags
if (FT_CURVE_TAG(aTags[aPntId]) == FT_Curve_Tag_On)
{
if (aLinePnts < 1)
{
aPntLine1 = aPntCurr;
aLinePnts = 1;
continue;
}
const gp_XY aDirVec = aPntCurr - aPntLine1;
const Standard_Real aLen = aDirVec.Modulus();
if (aLen <= myPrecision)
{
aPntLine1 = aPntCurr;
aLinePnts = 1;
continue;
}
if (myIsCompositeCurve)
{
Handle(Geom2d_TrimmedCurve) aLine = GCE2d_MakeSegment (gp_Pnt2d (aPntLine1), gp_Pnt2d (aPntCurr));
myConcatMaker.Add (aLine, myPrecision);
}
else
{
Handle(Geom_Curve) aCurve3d;
Handle(Geom2d_Line) aCurve2d = new Geom2d_Line (gp_Pnt2d (aPntLine1), gp_Dir2d (aDirVec));
if (to3d (aCurve2d, GeomAbs_C1, aCurve3d))
{
TopoDS_Edge anEdge = BRepLib_MakeEdge (aCurve3d, 0.0, aLen);
myBuilder.UpdateEdge (anEdge, aCurve2d, mySurface, aLoc, myPrecision);
aWireMaker.Add (anEdge);
}
}
aPntLine1 = aPntCurr;
}
else if (FT_CURVE_TAG(aTags[aPntId]) == FT_Curve_Tag_Conic)
{
aLinePnts = 0;
gp_XY aPntPrev2 = aPntPrev;
gp_XY aPntNext2 = aPntNext;
// previous point is either the real previous point (an "on" point),
// or the midpoint between the current one and the previous "conic off" point
if (FT_CURVE_TAG(aTags[(aPntId - 1 + aPntsNb) % aPntsNb]) == FT_Curve_Tag_Conic)
{
aPntPrev2 = (aPntCurr + aPntPrev) * 0.5;
}
// next point is either the real next point or the midpoint
if (FT_CURVE_TAG(aTags[(aPntId + 1) % aPntsNb]) == FT_Curve_Tag_Conic)
{
aPntNext2 = (aPntCurr + aPntNext) * 0.5;
}
my3Poles.SetValue (1, aPntPrev2);
my3Poles.SetValue (2, aPntCurr);
my3Poles.SetValue (3, aPntNext2);
Handle(Geom2d_BezierCurve) aBezierArc = new Geom2d_BezierCurve (my3Poles);
if (myIsCompositeCurve)
{
myConcatMaker.Add (aBezierArc, myPrecision);
}
else
{
Handle(Geom_Curve) aCurve3d;
if (to3d (aBezierArc, GeomAbs_C1, aCurve3d))
{
TopoDS_Edge anEdge = BRepLib_MakeEdge (aCurve3d);
myBuilder.UpdateEdge (anEdge, aBezierArc, mySurface, aLoc, myPrecision);
aWireMaker.Add (anEdge);
}
}
}
else if (FT_CURVE_TAG(aTags[aPntId]) == FT_Curve_Tag_Cubic
&& FT_CURVE_TAG(aTags[(aPntId + 1) % aPntsNb]) == FT_Curve_Tag_Cubic)
{
aLinePnts = 0;
my4Poles.SetValue (1, aPntPrev);
my4Poles.SetValue (2, aPntCurr);
my4Poles.SetValue (3, aPntNext);
my4Poles.SetValue (4, gp_Pnt2d(readFTVec (aPntList[(aPntId + 2) % aPntsNb])));
Handle(Geom2d_BezierCurve) aBezier = new Geom2d_BezierCurve (my4Poles);
if (myIsCompositeCurve)
{
myConcatMaker.Add (aBezier, myPrecision);
}
else
{
Handle(Geom_Curve) aCurve3d;
if (to3d (aBezier, GeomAbs_C1, aCurve3d))
{
TopoDS_Edge anEdge = BRepLib_MakeEdge (aCurve3d);
myBuilder.UpdateEdge (anEdge, aBezier, mySurface, aLoc, myPrecision);
aWireMaker.Add (anEdge);
}
}
}
}
if (myIsCompositeCurve)
{
Handle(Geom2d_BSplineCurve) aDraft2d = myConcatMaker.BSplineCurve();
if (aDraft2d.IsNull())
{
continue;
}
const gp_Pnt2d aFirstPnt = aDraft2d->StartPoint();
const gp_Pnt2d aLastPnt = aDraft2d->EndPoint();
if (!aFirstPnt.IsEqual (aLastPnt, myPrecision))
{
Handle(Geom2d_TrimmedCurve) aLine = GCE2d_MakeSegment (aLastPnt, aFirstPnt);
myConcatMaker.Add (aLine, myPrecision);
}
Handle(Geom2d_BSplineCurve) aCurve2d = myConcatMaker.BSplineCurve();
Handle(Geom_Curve) aCurve3d;
if (to3d (aCurve2d, GeomAbs_C0, aCurve3d))
{
TopoDS_Edge anEdge = BRepLib_MakeEdge (aCurve3d);
myBuilder.UpdateEdge (anEdge, aCurve2d, mySurface, aLoc, myPrecision);
aWireMaker.Add (anEdge);
}
myConcatMaker.Clear();
}
else
{
if (!aWireMaker.IsDone())
{
continue;
}
TopoDS_Vertex aFirstV, aLastV;
TopExp::Vertices (aWireMaker.Wire(), aFirstV, aLastV);
gp_Pnt aFirstPoint = BRep_Tool::Pnt (aFirstV);
gp_Pnt aLastPoint = BRep_Tool::Pnt (aLastV);
if (!aFirstPoint.IsEqual (aLastPoint, myPrecision))
{
aWireMaker.Add (BRepLib_MakeEdge (aFirstV, aLastV));
}
}
if (!aWireMaker.IsDone())
{
continue;
}
TopoDS_Wire aWireDraft = aWireMaker.Wire();
//if (anOrient == FT_ORIENTATION_FILL_LEFT)
//{
// According to the TrueType specification, clockwise contours must be filled
aWireDraft.Reverse();
//}
myBuilder.Add (aFaceDraft, aWireDraft);
}
myFixer.Init (aFaceDraft);
myFixer.Perform();
theShape = myFixer.Result();
if (!theShape.IsNull()
&& theShape.ShapeType() != TopAbs_FACE)
{
// shape fix can not fix orientation within the single call
TopoDS_Compound aComp;
myBuilder.MakeCompound (aComp);
for (TopExp_Explorer aFaceIter (theShape, TopAbs_FACE); aFaceIter.More(); aFaceIter.Next())
{
TopoDS_Face aFace = TopoDS::Face (aFaceIter.Current());
myFixer.Init (aFace);
myFixer.Perform();
myBuilder.Add (aComp, myFixer.Result());
}
theShape = aComp;
}
myCache.Bind (theChar, theShape);
return !theShape.IsNull();
}
4.Text 3D
在一些圖形庫中都可以生成三維文字，如下圖所示：
理解了FreeType的用法后，實現上述功能也是很簡單的。這里簡要說明實現步驟：
l 使用FreeType得到文字的輪廓線；
l 將閉合的輪廓線生成Wire->Face;
l 將輪廓線生成的Face進行拉伸得到Solid體。
在OpenCASCADE中得到文字輪廓線生成的Face的類是：Font_BRepFont。下面給出示例得到指定文字的面。
#include <BRepTools.hxx>
#include <Font_BRepFont.hxx>
#include <Font_BRepTextBuilder.hxx>
#pragma comment(lib, "TKernel.lib")
#pragma comment(lib, "TKMath.lib")
#pragma comment(lib, "TKG2d.lib")
#pragma comment(lib, "TKG3d.lib")
#pragma comment(lib, "TKGeomBase.lib")
#pragma comment(lib, "TKGeomAlgo.lib")
#pragma comment(lib, "TKBRep.lib")
#pragma comment(lib, "TKTopAlgo.lib")
#pragma comment(lib, "TKService.lib")
void text2brep()
{
Font_BRepFont aBrepFont("C:/Windows/Fonts/arial.ttf", 3.5);
Font_BRepTextBuilder aTextBuilder;
TopoDS_Shape aTextShape = aTextBuilder.Perform(aBrepFont, NCollection_String("eryar@163.com"));
BRepTools::Dump(aTextShape, std::cout);
BRepTools::Write(aTextShape, "d:/text.brep");
}
int main(int argc, char* argv[])
{
text2brep();
return 0;
}
在Draw Test Harness中顯示出文字的輪廓text.brep如下圖所示：
如果要顯示出文字的填充效果，則需要有三角化工具將文字輪廓網格化。OpenCASCADE中將輪廓生成Wire->Face，即可以生成顯示數據了：
5.Conclusion
FreeType的文字處理功能很強大，幾乎所有的三維造型內核中文字的處理都是使用的FreeType。
FreeType的文字輪廓使用了線段和Bezier曲線來表達，Bezier曲線是B樣條曲線的特例。理解Bezier曲線就可以自己繪制文字輪廓了。
FreeType使用簡單，可以方便得到文字的輪廓數據。將輪廓數據生成Face即可以拉伸出三維文字效果。
6.References
1. https://www.freetype.org/freetype2/docs/tutorial/index.html
2. http://www.shnenglu.com/eryar/archive/2014/08/17/OpenCascade_Text_Rendering.html
3. https://www.freetype.org/freetype2/docs/glyphs/glyphs-6.html