VTextVirtenceGmbHAltenburgerStr.1304275Leipzig

VText 2.0 Unity Package

info@virtence.com

Februar15,2017

VText 3

2 Details

1 Quickstart VText is Unity package to generate dynamic 3D–Text geometry directly from truetypefonts(.ttf or.otf).

Themainfeaturesare

• DifferentMaterialsfor

– Frontface– Bevel– Sides

• Kerning

• TexturelayoutsuitableforLightmapping

• Availablebuildtargets

– Android(Arm32–bit)– Linux(32/64–bit)– Windows(32/64–bit)– OSX(32/64–bit)– iOS(Arm32/64–bit)

• LayoutalongAnimationCurve• Circularbendingwithanimatableradius• AutomaticgenerationofCollidersandorRigidBodies.• Experimental: Adding arbitrary components to each letter (like AudioSources,Animations,Scripts,etc)

VText 4

2 Details

1.1 Install AfterimportingtheVTextpackage,selectthemenuWindows/Virtence/Setup VText...Thiswillshowupadialoglikeinfigure1.

Figure1–Setup

Justfollowallinstallationsteps.Youcangotothenextstepbyclickingthe“Next”buttoninthelowerright.1.2 Demo scenes Important!Beforeopeningthetestscenes,ensureyousetupVTextlikeinsection1.1.Tomakethedemoscenesworkyoumustinstallthedemofontsweprovide.YoucandothatinStep 4 (Install fonts).YouwillfindtheVTextdemoscenesintheVirtence/VText-folder.VTextcomeswiththefollowingdemoscenes:

VText 5

2 Details

1.2.1StartScene

StartSceneisasimpleanimatedVTextscenewithagraphicaluserinterface.InplaymodeUnitywillshowsomethinglikefigure2.Itsintentionistoshowsomecommonsettingsforthe3Dandlayoutparameters.

Figure2-StartScene

1.2.2 TextureLayoutScene

Figure3showstheUnityviewsforTextureLayoutScene.ThisshowstheusedUV-Layoutwhich has light baking, etc. in mind. See section 3.2 for detailed information abouttexturelayout.

Figure3-TextureLayoutScene

VText 6

2 Details

1.2.3 AdditionalMonobehaviours

Figure4showsasmallscenewithself-writtenscriptsattachedtoeachletterofthetext.

Figure4-AdditionalMonobehaviours

Inthisscene,youcanseehowtorotatethesinglelettersaroundtheirowncenterandchangetheirmaterials.Furthermore,youcanhighlightanyletterof thebottomtextwith themouse.Thisdemonstrates theusageofaddingownscriptsautomaticallytoeachletter.1.2.4 Physics

This scene showsyouhow touseColliders andRigidbodies for youVTextobjects.Itlookslikefigure5.

Figure5-Physics

HereyoucanthrowsmallballstothelettersoftheVText.ThisdemonstratetheautomaticgenerationofCollidersandRigidbodiestotheletters.

VText 7

2 Details

1.2.5 Equalizer

HereweshowhowyoucanmodifythebendingcurvesofaVTextobjectatruntime.Thescenewilllooklikeinfigure6.

Figure6–Equalizer

Thetextinthisscenewillwiggletothesoundbychangingitsbendingcurvestogetanequalizereffect.1.3 Adding VText objects to your scene ClickingontheGameObject/Virtence/VText menuitemwilladdanemptychildtoyourhierarchy,whichcontainstheVTextInterfacecomponent.TheInspectoreditorpaneshowninFigure7willallowyoutoadjustthesettings.

Figure7-Inspector

WedescribetheUserInterfaceandtheparametersinthenextchapters.

VText 8

2 Details

To work properly you should have at least one font installed in theAssets/StreamingAssets/Fontsfolderbecausefornewtextswechoosethefirstfontwefindthereandifthereisn’tanywecan’tgeneratethetext.

Note:AllFontsinthatfolderwillbedistributedwhenbuildingformobiledevices!So,keeponlyfontswhicharerequiredinyourprojecttoreducethememoryfootprint.Alsobeawareofcopyrights!

VText 9

2 Details

2 User Interface Inthischapter,wewilldescribethedifferentpanesoftheUserInterface.2.1 Common Therearethreecomponentswhicharevisibleallthetime(excepttheVText-LogoofcauseJ).Thefirstcomponentisthetextinputfieldwhichlookslikeinfigure8.

Figure8-Textinputfield

Thisallowsyoutoenterthetextwhichwillbegenerated.KeepinmindthatthisinputfieldhasnowordwrappingonpurposebecauseyoucancreatemultilinetextwithVText.Todosoyouneedtopressthereturnkeyexplicitelytostartanewline.Thesecondcomponentwhichisalwaysvisibleisthetoolbar(seefigure9).

Figure9–Toolbar

ThisallowsyoutoswitchthemaincategoriesofaVTextobject.

VText 10

2 Details

Wedistinguishbetweenthefollowingcategoriesfornow:

- Style(fontsandmaterials)- Mesh(everythingwhichaffectsthe3Dgeometrieslikethedepthof

the letters, the bevel, shadow-casting or –receiving, tessellation-quality,etc.)

- Layout(herewehandlelayoutparameterslikealignment,bending,sizeandspaces)

- Physics(addcollidersorrigidbodiestoyourletters)- Scripts(experimental!)(addanyUnitycomponentstoyourletters,

likescripts,animations,sound,etc.)

Weexplainthesectionsinthefollowingchapterindetail.ThethirdcomponentwhichisalwaysvisibleistheRebuild-buttonlikeshowninfigure10.

Figure10–Rebuild

Youcanseethisbuttonasafallback.ThiswillrebuildallaspectsmentionedaboveofyourVTextobject.2.2 Style Herewedefinethestyleparametersofthetext.Theinspectorviewforthestyleparameterslookslikefigure11.

Figure11-Style

VText 11

2 Details

2.2.1 Font

Hereyoucandefinethefontwhichisusedforthegeneratedgeometry.Keepin mind that only fonts are usable which are located at theAssets/StreamingAssets/Fonts folder. That’s becausewewant tomake surethat your fonts are distributed correctly if you build the application to anexecutableforanyprovidedsystem.2.2.2 Size

Thiswilldefinethesizeofthegeneratedgeometryinmeters.2.2.3 Materials

Tounderstand thematerials, it’sagoodstart to seehowVText-lettersareorganized.Figure12showsyouasingleletterwithitscomponents.

Figure12-Organizationofaletter

Thebluepartinfigure12showsthesocalledfacepart.Thegraypartiscalledbevelandisasmoothlycurvedsurfacebetweentheblueandtheredpart…whichiscalledside.Andthat’sexactlywhattheseveralmaterialsinthestylesectiondescribe.Youcandefineamaterialforeachofthoseparts.

VText 12

2 Details

2.3 Mesh The Mesh section allows you to adjust parameters which affects thegenerated3Dgeometry.Itwilllooklikefigure13.

Figure13-Mesh

Hereyoucanadjustthefollowingparameters:• Depth:thisdescribesthedepthofeachletter.Thismakesyourtext

three dimensional. You can set the material for these faces bychangingtheSidematerialintheStylesection.Settingthedepthto0createsa2Dtextwhichcanbeplacedinthe3Dworldandgivesusacoupleofperformancerele

• Bevel:thisisthesmoothlyroundedpartbetweenthefront-orback-facesandthesideofeach letter.That’swhyyoucansetthebevelsize only if you have defined a depth greater than 0. You canchangethebevelmaterialinthestylesection.

• Backface:oftenyouwillnotseethebackfacesofthetext.That’swhywedonotgeneratethemperdefault.Butifyoubendorrotateyourtext you maybe want to create the backfaces too. This parameterallowsyoutoswitchthemonoroff.Ifyouenablethebackfaceswecreatethegeometryforthebackpartsofthelettersandthebevelonthebacksideaswell.

• Quality:Thequalityparameterallowsyoutoadjust thenumberoftriangles generated for the 3D text. Of cause, less trianglesmeansbetter performance but less smoothness. When creating thegeometry,wemainlyadjustthecurvedpartsoftheletters.

VText 13

2 Details

• Castshadows:Thisallowsyoutospecifyif(andhow)thegeneratedtextshouldcastshadows.TheparametervaluesarethesameasthecastshadowparametersofUnity’sMeshRenderercomponent.

• Receiveshadows:hereyoucanspecifyifyourtextsshouldreceiveshadowsornot

• Use lightprobes: if your scene contains lightprobes then you candefinehereifyourtextshouldbeaffectedbythem.

• Create tangents: some shader (esp. normal or bumpmappingshader)requiretangentstoworkcorrectly.Ifyouusesuchshadersforyourtextyoushouldenablethis.Keepitoffifyoudon’tneedthem.

2.4 Layout Withinthissectionyoucanadjustallparameterswhichchangethelayoutorbendingofyourtexts.Thelayoutsectionwilllooklikefigure14.

Figure14-Layout

2.4.1 Common

Thefollowingparameterswillhelpyoutoadjust the layoutofyourtext toyourneeds:

• Horizontal:hereyoucanset themain layoutofyour text… ifyouwantitislayoutedhorizontallyorvertically.ThiswillalsoinfluencetheparametersMajorandMinor.

VText 14

2 Details

• Major:Thisdefinesthealignmentofyourtextdependingonitsmainlayout(horizontalorvertical).Ifitissettohorizontal,thentheMajoralignmentworksinx-directionofyoutext.Ifitissettovertical,thentheMajoralignmentworksiny-direction.Thefollowingvaluescanbeset:

o Base:Thisisonlyusedifyourtextissetuphorizontallyandonly used for theMajor alignment. Then the pivot point ofyourtextissettothebaselineofthefont.Inallothercases,itworksthesamewaylikeStart(seethenextvalue).

o Start:Thepivotpointofyourtextissettothetop-leftoftheentiretext.

o Center:Thepivotpointissettothecenteroftheentiretext.o End:Thepivotpoint issettothebottom-rightof theentire

text.o Block:ThisalignsthetextlikeyouareusingtheStartsetting

butitwillsetthespacebetweenwordsinawaythatalllineshaveequallength.(Note:ThisworksonlyifyousetitinMajormode (horizontal and vertical) andonly if youhavemultiplelines.ActuallywedoNOTtrimwhitespacesfromthebeginningor end of the line and they are taken into account for thecalculation…justbecausemaybeyouintendthis.Maybeweputinaparameterforthislaterorswitchovertotrimwhitespacesautomatically. So if your results looks wrong please doublecheckifyouhavewhitespacesatthebeginningorendofline.)

• Minor:ThisdescribesthealignmentinexactlytheoppositedirectionoftheMajoralignment.So,ifyourtextislayoutedhorizontallythenthis describes the alignment in y-direction. If your text is layoutedverticallythisdescribesthealignmentinx-direction.ThevaluesarethesamelikefortheMajoralignment(seeMajor).

• Linespace:Thisparameterdefinesthedistanceofthebaselineofonelinetothebaselinetexofthenextline.Thismeansthatalinespaceof0willputalllinesontopofeachother.Inthisway,youcancreate overlapping texts too. A value of 1means the “normal” linespaceastheyaredefinedbythefont.Avalueof2forinstancedoublesthedistancebetweentwolines.

• Letter space: Using this parameter you can adjust the distancebetweentwoletters.Avalueof0meansthatthereisnoextraspacebetweentheletters.Theyarerendered“normally”.

VText 15

2 Details

2.4.2 Bending

Inthebendingsectionofthelayoutyoucanbendyourtextinacoupleofways.Allmethodsdescribedherehavethefollowingincommon.TobendyourtextweuseUnityAnimationCurveswhichalsoallowsittoanimatethesecurvesand therefor animate the bending of the text. Furthermore, each bendingallows you to align the single letters to your defined curve (the CircularBendingwillalwaysalignyourlettersalongthecircle…butwewillcometoitlater).

• BendXZ:Thisallowsyoutobendyourtextinzdirection.Thismeansthatyourtextwillstayonthegroundbutyoucanchangeitsdirectionalongz.Theresultwillbesomethinglikeshowninfigure15.

Figure15-BendXZ

• BendXY:Thisallowsyoutobendyourtextinydirection.Thismeansthatyourtextwillmoveupanddown.Theresultwillbesomethinglikeshowninfigure16.

Figure16-BendXY

• Circularbending:Thecircularbendingallowsyoutobendyourtext

arounda(imaginary)circleorapartofit.Thisisoftenusedtorotateatextaroundasphereorcylinder.Webetyouknowthistextrotatingaroundtheearthlogolikeinfigure17?

VText 16

2 Details

Figure17-Circularbendingexample

Tosetupacircularbendingyoucanchangethefollowingparameters:o Startangle:thiswillsetthestartpositionofyourtext. It is

defined in degrees around the circle. Values lower than 0degreeandhigher than360degreewill result inamultiplebendingaroundthecircle.

o Endangle:thisdefinestheendpositionofyourtextonthecircle.Itisdefinedindegreetoo.Valueslowerthan0degreeandhigherthan360degreewillresultinamultiplebendingaroundthecircle.

o Radius:This defines the radius of the circle. Changing thisparametermovesyour text fartheraway fromthecenterofyourVTextobject.

IfyouenabletheAnimateradiusbuttonthenyouhavethechancetochangetheradiusalongyourtext.Thisisnotananimationperse(wewill come to it later) but it usesUnity’s animation curves again tomodifytheradiusalongyourtext.Thevaluesofthecurveshouldbedefinedinx-directionina0-1rangewhere0isthebeginningofyourtextand1istheend.They-valuesaremultipliedwiththeradiusyoudefinedabove.This allows you in a simpleway to bend your text like a spiral forinstance(seefigure18)

VText 17

2 Details

Figure18-Changeradiusalongthetext

Tip:There is no need to use just one of the parametersmentioned above. Becreativeandcombinethem.ThiswayyoucancombinetheBendXYcurvetobeaslopeandadditionallyaddaCircularbindinglikedescribedbeforetogetatornado-bendinglikeinfigure19.

Figure19-Tornadoexample

2.4 Physics Inthephysicssection,youcanautomaticallyaddRigidBodiesandCollidertoeachofthegeneratedletters.Thisallowsyoutointeractwiththemlateroraddphysicbehaviourstoit.Thephysicssectionwilllooklikeinfigure20.

VText 18

2 Details

Figure20-Physics

Actually, we allow the generation of box- and mesh colliders with thecommonparametersliketheyaredefinedbyUnity.Also for rigidbodieswe provide youwith the commonparameters knownfromUnity.SeethePhysicsexamplesceneforaquickstart.2.4 Scripts Becareful,thissectionisexperimentalandcanleadtoUnitycrashes!Herewewanttogiveyouthepossibilitytoaddarbitrarycomponentstoeachof the generated letters automatically. This would allow you to addcomponents like Animators, AudioSources, your own scripts, etc to eachletterandthereforegivingyoumuchmore flexibility for laterusageof thetext.Thescriptssectionlookslikefigure21.

Figure21-Scripts

VText 19

2 Details

Thewaywehandle it isthatyoucreateareferencegameobject(simplyanemptygameobject)andaddallcomponentsyouwanttoit.Youcandisablethisgameobjectinyourscenesoitdoesnotaffectyourscene.Onthisreferencegameobjectyoucanadjustallsettingswhichyouwanttohaveoneachletter.NowdraganddropyourreferencegameobjectintotheReferenceobjectfield in the script section. If new letters are generated we take allcomponentsandtheirsettings fromthereferenceobjectandcopythemtothenewgeneratedletter.Some components (and their subtypes) will not be copied because wegenerate them in VText or Unity does not allow it at all. The followingcomponentswillnotbecopied:

• Transform• Renderer• MeshFilter• Rigidbody• Collider

WealsoknowthataddingscriptswhichhaveaVTextInterfaceasapublicvariable(whichisassignedintheInspector)canleadtodeadlockswhichwillresultinUnitycrashes.ThereisnoproblemifyougetaccesscomponentsinyourscriptsbyusingtheGetComponentmethods.

VText 20

2 Details

3 Programming Interface

All mentioned sections and parameters can be accessed by using theprogramminginterfacetoo.Thiswillallowyoutochangeorevenanimateeachparameteratruntime.Withtheexceptionofthechoosenfontandthesizeofthegeneratedtext,allparameters can be found in the VTextInterface programming sectioncorrespondingtothesectionsintheVTextUserInterface.Thechoosenfontcanbefoundintheparametersectionandthesizeofthegeneratedtextcanbefoundinthelayoutsection.Wemustkeepitthiswayforbackwardcompatibilityreasons.ToaccesstheVText interfaceyoucanusetheGetComponentmethodfromUnitylike:

VTextInterface vi = GetComponent<VTextInterface>(); OryoucancreateapublicvariableofthetypeVTextInterfaceanddraganddroptheVTextinterfaceofyourtextintoitintheInspector.3.1 Sections CorrespondingtotheVTextUserInterfacewesplitteduptheProgrammingInterfaceintothesamesections.3.1.1 VTextInterface parameter

ThefollowingaspectscanbechangedbyusingtheVTextInterfaceclass:

Table1:VTextInterface

Property Type DescriptionRenderText string TheTexttogenerate.parameter VTextParameter Meshconstructionparameter.layoutPhysicsAdditionalComponents

VTextLayoutVTextPhysics

VTextAdditionalComponents

Textlayoutparameter.ThephysicsparamterAdditionalcomponents

VText 21

2 Details

3.1.2 Mesh parameter

ThefollowingaspectscanbechangedbyusingthemeshparameterssectionoftheProgrammingInterface:

Table2:Meshparameter

Youcanaccessthembyusingsomethinglikethefollowing:

VTextInterface vi = GetComponent<VTextInterface>(); vi.RenderText = “My text”; // this must be in Assets/StreamingAssets/Fonts vi.parameter.FontName = “MyFont.ttf”; vi.parameter.Depth = 1.0f; vi.parameter.Bevel = 0.03f; vi.parameter.Backface = true;

3.1.2 Layout parameter

ToaccessthelayoutspecificparametersyoucanchangethefollowingpartsoftheVTextInterface.Youcanaccessitby:

VTextInterface vi = GetComponent<VTextInterface>(); vi.layout.Major = VTextLayout.align.Center;

for instance.

Property Type DescriptionDepth float TherelativedepthofextrudedglyphBevel float Outlinewidthanddepth–shiftBackface bool WillgeneratebacksideiftrueGenerateTangents bool Willgeneratetangentsoneachglyphif

trueFontname string Thefontfilename

VText 22

2 Details

Table3:Layoutparameter

3.1.3 Physics

Hereyoucanaccessthephysicparametersofyourtext.Tochangethemyoucandosomethinglike:

VTextInterface vi = GetComponent<VTextInterface>(); vi.Physics.Collider=VTextPhysics.ColliderType.Mesh;

3.1.4 Scripts

InthesamewayyoucanaccesstheScriptssectionoftheVTextinterface: VTextInterface vi = GetComponent<VTextInterface>(); vi.AdditionalComponents.AdditionalComponentsObject = myRefObj;

Property Type DescriptionHorizontal bool Majorlayoutdirection.Verticallayoutif

false.Major align Majorlayoutmode.Minor align Minorlayoutmode.Size float Localscalingfactorforeachglyph.Spacing float Localscalingfactorforminoradjustment.CurveXZ AnimationCurve Z–PositionAnimationCurve.OrientationXZ bool TextfacestangentinZiftrue.CurveXY AnimationCurve Y–PositionAnimationCurve.OrientationXY bool TextfacestangentinYiftrue.CastShadows bool Generatedglyphswillcastshadow.ReceiveShadows bool Generatedglyphswillreceiveshadow.UseLightProbes bool TextwilluseLightProbesifavailable.

VText 23

2 Details

3.2 Textures TheUV–Coordinatesofeachglyphareconstructedinalightmappingconformalway.

Figure22-Texturelayout

AsshowninFigure22,thefrontfaceconsumestheyellowUV–range(0,0)...(0.5,0.5).The

blueUV–range(0,0.5)...(0.5,1.0)coversthebackfacearea.EachcontoursidecoversanU–

rangeof(0.5,0.5+n∗0.1)wherenistheindexofactivecontour.Bevelrangeisdependanton its amount, andwhetherbackface rendering is enabled.TheV–range is normalizedfrom the lengthof the longest contour. Figure23 shows the resultingunlitmaterial inUnity.

Figure23-TexturedVText

Youmaywonderwhyfront-andback–facelayoutcoverssuchasmallareaintheUV–

range.It’sbecausethemaximumglyphsizeofDroidSans.ttf isthatmuchlargerthanthecommonusedglyphs.Otherfontsmayshowdifferentranges.

VText 24

2 Details

3.3 Performance Aslongasyouareusingonly2D–Text1allVTextobjectsreferencingthesamefontuseonlyonedictionaryforglyphlookup.SoUnityisabletobatchmostofyourtext,evenifsomeusedifferentsizes.3D–TextrequiresaseparateglyphdictionaryforeachVTextobject.Sobatchingisonly

possibleinVTextitself.Itisgenerallynogoodideatochangeparametersatruntime,whichrequireacomplete

rebuildoftheglyphs2!Especiallytextwithalotofdifferentglyphswillneedsometimetorebuild.Achangeof layoutparameterisnotthatcostly,becausenorebuildofglyphsisrequired.DependingonthesettingsofNeedTangents,extraattributesaregenerated.Thisisonly

requiredifoneofyourmaterialscontainsabumpmappingshader.Forbestperformanceturnitoffifnotrequired.IftheparameterBackfaceisturnedon,additionalfacesaregeneratedforeachglyph.If

you’llneverseethebackfacesinyourscene,turnitoff.

3.4 Build If you change or set the name of the font via script, you should be aware of the casesensitivityoffilenamesonnonWindowsbasedoperatingsystems!Ifyourtextwillnotshowupinyourbuild,firstchecktherightspelling(includingcase)ofthefontname.

1depthandbevelzero2suchaschangingDepthorBevel

2Details

25 VText

4 Legal This package is copyright© 2014 - 2017 by Virtence GmbH.

4.1 3rd party Thispackageusesthefollowing3rdpartyproducts:

freetype2

Portions of this software are copyright 2014 The FreeType Project (www.freetype.org). All rights reserved.

Fonts

This package contains the following fonts, which are licensed under the SIL Open Font License:

• CostaRica.otf• Dotrice-Bold-Condensed.otf• Lack.otf• Lobster.otf• Segment14.otf• Xolonium-Bold.otf• RacingSansOne-Regular.ttf