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被設(shè)計為一種占用空間小的、高效的、高度可定制的、并且可以產(chǎn)生可移植的高品質(zhì)輸出（符號圖像）?？梢员挥迷谥T如圖像庫、展出服務(wù)器、字體轉(zhuǎn)換工具、圖像文字產(chǎn)生工具等多種其它產(chǎn)品上。
注意FreeType 2是一種字體服務(wù)而沒有提供為實現(xiàn)文字布局或圖形化處理這樣高階的功能使用的API（比如帶色文字渲染之類的）。然而，它提供一個簡單的、易用的并且統(tǒng)一的接口實現(xiàn)對多種字體文件的訪問，從而大大簡化了這些高級的任務(wù)。
FreeType 2的發(fā)行遵循兩個開源許可：我們自己的BSD樣式的FreeType License和GPL（通用公共許可證）。它可以被用在任何程序中，無論是專有與否。
在常見的圖形庫中，如OpenSceneGraph, OpenCASCADE, HOOPS, Qt,等涉及到文字處理的，都會用到FreeType. 在一些游戲開發(fā)中，也會用到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的官網(wǎng)上有詳細的教程說明FreeType的用法，網(wǎng)址為：https://www.freetype.org/freetype2/docs/tutorial/index.html
主要的步驟如下：
v 包含頭文件 Header Files;
v 庫的初始化 Library Initialization;
v 加載字體 Loading a Font Face;
v 訪問字體數(shù)據(jù) Accessing the Face Data;
v 設(shè)置當前像素大小 Setting the Current Pixel Size;
v 加載文字 Loading a Glyph Image;
v 簡單的顯示 Simple Text Rendering；
下面代碼是上述過程的一個實現(xiàn)，忽略了錯誤處理：
#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;
}
調(diào)試程序可以看出Face中已經(jīng)有了一些數(shù)據(jù)。
3.FreeType Outlines
FreeType中的一個文字輪廓Outline是由二維空間閉合的線圍成。每一個輪廓線是由一系列的直線段和Bezier曲線組成。根據(jù)字體文件格式的不同，他們可能是二階或三階多項式。二階的通常稱為quadratic或conic弧，他們用于TrueType格式。三階的稱為cubic弧，通常用于PostScript Type1, CFF, 和CFF2格式中。詳細描述見：
https://www.freetype.org/freetype2/docs/glyphs/glyphs-6.html
Bezier曲線是B樣條曲線的一個特例，他的特點就是曲線的階數(shù)與控制點的個數(shù)相關(guān)，即給定控制頂點就可以確定Bezier曲線。所以O(shè)penCASCADE中對于Bezier曲線有這樣的構(gòu)造函數(shù)：
每一段曲線弧都由起點start，終點end和控制頂點control points來描述。描述輪廓線的每個點都有一個特定的標記Tag來區(qū)別是線段還是Bezier曲線。
兩個連續(xù)的on點確定了線段的兩個端點；
在兩個on點之間的一個conic off點組成了一個conic Bezier曲線；
在兩個on點之間的兩個cubic off點組成了一個cubic Bezier曲線；
理解了上述內(nèi)容就可以得到文字的輪廓線了。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的用法后，實現(xiàn)上述功能也是很簡單的。這里簡要說明實現(xiàn)步驟：
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如下圖所示：
如果要顯示出文字的填充效果，則需要有三角化工具將文字輪廓網(wǎng)格化。OpenCASCADE中將輪廓生成Wire->Face，即可以生成顯示數(shù)據(jù)了：
5.Conclusion
FreeType的文字處理功能很強大，幾乎所有的三維造型內(nèi)核中文字的處理都是使用的FreeType。
FreeType的文字輪廓使用了線段和Bezier曲線來表達，Bezier曲線是B樣條曲線的特例。理解Bezier曲線就可以自己繪制文字輪廓了。
FreeType使用簡單，可以方便得到文字的輪廓數(shù)據(jù)。將輪廓數(shù)據(jù)生成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