Extending TEXDraw

Here we explain about extending TEXDraw functionalities in depth.

API

Core components

The core components has similar properties.

Property Explanation
text Text to display in $\LaTeX$
size Initial text size in pixels, or world unit
alignment Initial alignment to set, in code the value is in Vector2
scrollArea Display offset in pixels, or world unit
padding Inset padding in pixels, or world unit
color Initial font color in RGBA Color
material Custom material to be rendered with
overflow Overflow method to use, see enum values below
raycastTarget TEXDraw UI only, is it able to receive input events?
pixelsPerUnit TEXDraw 3D only, for how much pixels ratio? 2 is double font resolution.
setTextDirty() A C# code function to force draw update.

Overflow modes

Value Explanation
Hidden Hide text which excess RectTransform boundary (default).
Visible Allow text that excess RectTransform boundary
DownScale Scale down the rendering output.
BestFit Recursively set the size down until no text excess RectTransform boundary

The different between DownScale and BestFit can be noticeable. DownScale is much quicker to render than BestFit but DownScale will simply scale down the resulting text so it will not respect available width.

If you want to constraint based on fixed height and width, BestFit is better. To automatically adjust height based on width, leave it as Hidden and set ContentSizeFitter’s height fit to Preferred Size. To automatically adjust width based on height, set it as DownScale and set ContentSizeFitter’s width fit to Preferred Size.

Editable Input

Use TexInput to make TEXDraw receives input as a WYSIWYG editor.

As of v6.1.0 it supports “escape input” mode so users can type “safely” without triggering any $\TeX$ commands. You can use this to make a $\TeX$ editor with aid of additional buttons to provide $\TeX$ expressions.

TexInput only support TEXDraw UI. It’s not supported in TEXDraw 3D. It only support limited syntax including but not limited to symbols, fractions, roots, and scripts. It also doesn’t have a good experience in mobile devices.

TexInput API

These API is available in TexInput component as a scripting aid. The first five is editable in inspector.

Property Explanation
text Text to display in $\LaTeX$
interactable Allow interaction like selecting text
readOnly Disallow editing text
escapeInput Escape all input to prevent directly typing $\LaTeX$
onChange Manage event listener when text has changed
hasFocus (Read only) check if currently has keyboard focus
selectionBegin Get or set Selection start index
selectionEnd Get or set Selection end index
selectedText Get or set selected text
SetSelection() Set currently selected text and emit events
RecordUndo() Records current text to undo log

TexLogger API

TexLogger aids in managing TexInput internal state. It’s the component that injects \link commands to all pieces of text so each of them can be clicked and selected.

Property Explanation
emptyPlaceholder Empty placeholder of {} so it’s editable inside
templateInput Inject expression between the generated expression that marked as ...
ReplaceString() Replace and record regular LaTeX string to injected LaTeX strings

TexCursor API

TexCursor aids in managing TexInput internal state. It’s the component that renders the cursor position and selection.

Property Explanation
activeColor Highlight color when selected
groupColor Highlight color when editing inside an expression
idleCoor Highlight color when selected but has no keyboard focus
cursorWidth Width of cursor
cursorBlink Cursor blink duration
selectionDilate When selection expressions, expand the highlight by this amount

Additional Components

These are smaller components that you can use to extend TEXDraw functionalities.

Scroll Container (TexScroll)

Use this to make TEXDraw scrollable.

While you can also use ScrollRect, TexScroll has a performance benefit of only rendering what’s on the screen (using Hidden overflow mode). You can’t do that with ScrollRect. TexScroll is suitable for rendering a very long $\TeX$ documents.

Use this to make TEXDraw links clickable and send unity code events.

To create a link you can use \link[href]{text}. The href is the link target, and text is the text to display. The link target string is sent together as the parameter of the firing OnLinkClick event in TexLink.

Internally you can get the resulting link rectangle area using tex.orchestrator.rendererState.vertexLinks. Use this to code your own special behavior along with the link command. It really can do much more than just clicking links.

Embedded RectTransform (TexEmbed)

One of other implementation usage for links is you can embed it within a RectTransform. You can use TexEmbed to achieve this.

Extensions

Open Sans

TEXDraw included Open Sans by default as \opens. You can set it as default text mode in TEXDraw preference.

The Open Sans is different than usual $\TeX$ fonts and will have fewer features. Because of that, Unicode conversion is turned off in that font.

TextMeshPro Support

TextMeshPro has crisp text rendering mode and it’s already built in Unity. TEXDraw can make use of TextMeshPro rendering capability so it’s looking crisp too.

TEXDraw can do this automatically for you, just find it in Menubar Tools > TEXDraw > Enable TMP Integration. You may see a rendering progress bar if you enable this for the first time.

If you see “You need to Extract TMP Essentials Asset First Before Activating TMP Integration” error, go to Window > TextMeshPro > Import TMP Essential Resources .

If you found “Requested build target group….” errors popped up, is a harmless error. You can safely ignore it.

You can disable TextMeshPro integration by go to the same menu when you enabled it before.

As for v5.7 there’s option to choose between dynamic and static mode. Dynamic mode is the preferred way as it may support more than just ASCII characters set for custom fonts. The old static mode is kept if for backward compatibility.

UI Elements

A limited support for providing UI Elements support is provided. When using UI Elements, you must change the default material’s shader to GUI/TEXDraw-UIE. Currently it doesn’t support TextMeshPro integration.

Hyphenation

An opt-in hyphenation engine is available. A hyphenation engine let’s paragraphs add hyphens to break very long texts automatically. This varies between many languages so you need a definition file to make it works, and LaTeX has them.

LaTeX engine has these definition in hyphenation.org adopted in many languages. For example here are direct links for certain languages:

You need to download one of them then assign it to TEXDraw Configuration -> Hyphenation Definition.

RTL Support

Back then when TEXDraw is in v4.x it has a robust RTL support to deal with arabic fonts. It’s dropped in 5.x so it’s not supported yet. You can ask me if you plan to use RTL in TEXDraw.

NGUI Support

I think not a lot of people using NGUI nowadays so it’s no longer supported. The last version TEXDraw support NGUI was v4.4.1.

Advanced Topics

How TEXDraw Works

TEXDraw split the rendering into three parts:

  • Parsing: This is the process where string is converted into tokens we called Atom. This atom itself doesn’t know any dimensions and only contain extracted data from text and the information about it’s current state it needed to render.
  • Boxing: This is the process where Atom is converted into smaller subset of rendering blocks we called Box. This Box defines each width and height dimension we know each box size up until the root box. Sometimes this process is repeated in order to satisfy layout requirements.
  • Rendering: This is the final process where all Box-es are baked into a mesh buffer. All positions for each box are known and directly baked there. The final result will be a list of mesh buffers where each of them is sent to available rendering GameObject pool (hidden from editor) each with their own font texture.

TEXDraw is smart enough to invoke rendering where they need to. For instance, if you only change the color property of TEXDraw or hovering a link with TEXLink, only re-rendering happens. If you resize the RectTransform, only re-boxing and re-rendering happens. Full rendering only happens if the text property has been changed.

Internal Orchestrator

Inside of any TEXDraw components, you can access a property called orchestrator. It’s the internal factory of TEXDraw rendering engine, and it’s publicly accessible so you can extend it’s functionalities. Here are some properties inside TexOrchestrator than you can use to extend TEXDraw functionalities:

Property Explanation
parser Internal text parsing engine. Note: This instance is shared across game lifetime.
parserState Intermediary context state for parsing. Nothing useful here.
boxingState Intermediary context state for boxing. Nothing useful here.
rendererState Last cache after rendering. Contains some useful data about last rendering call.
latestAtomCache Last cache after parsing. Contains tree-graph data about last parsing call.
latestBoxCache Last cache after boxing. Contains tree-graph data about last boxing call.
outputNativeCanvasSize WIdth and height of rendered text in local coordinate before getting modified by overflow policy.
Parse(string) C# code function for parsing. Output saved to latestAtomCache
Box() C# code function for boxing. Output saved to latestBoxCache
Render() C# code function for render. Output saved to rendererState
Trace() Debug resulted latestAtomCache and latestBoxCache. Returns string.

The rendererState also contains some useful data to manipulate with.

Property Explanation
vertexes An array to FillHelper, the underlying mesh buffer
vertexKeyFonts A dictionary map from font ID to vertexes index
vertexLinks An array of tuple containing a string key and a Rect area in local coordinate of the underlying TEXDraw transform.
vertexLinksOutput An array of tint color applied for each vertexLinks
clipRect Effective clipping area (if overflow set to Hidden)

Writing TeX in C#

Because TEXDraw often uses \, you might want to use literal syntax in strings like:

texdraw.text = @"$\theta=\alpha^2+\beta^2$";

However for a long $\LaTeX$ it’s often better to write it in separate .tex file in Resources and load it using \input syntax.

Enable Debugging Mode

You can define TEXDRAW_DEBUG in scripting definitions to enable debugging mode. Here are the things that you will unlock:

  • Debug View is visible in TexConfiguration and if it activated all TEXDraw in scene will have a yellow-ish rectangle blob to give hints of invisible white spaces and other box area.
  • TEXDraw child rendering components TEXDrawRenderer and TEXDraw3DRenderer will be visible in hierarchy.
  • A tool will be unlocked in menu Tools, TEXDraw, Pool Checks. This editor tool helps to inspect any instance of memory leak in TEXDraw’s internal memory class pool.

Extending Commands

Edit TexModuleInitiator.cs. Obviously you need a moderate experience in extending someone else’s code. I may or may not help you doing this.

Optimizing Performance

It’s already fast.

But for more reliable performance, you may want to put a dummy TEXDraw object in the first scene (even though it’s offscreen). This is because TEXDraw resouces is loaded “lazily”. If you enable/load TEXDraw in the middle of runtime for the first time, you probably will see a hiccup in a frame, albeit less than a second.

Also you may want to Enable TextMeshPro Support because it has better performance and more consistent rendering. The default dynamic font rendering Unity has a problem, that it’s generated runtime, so sometimes you’ll see a glitched display when using TEXDraw with it.

Optimizing Bundle Size

To reduce compile size generated from TEXDraw, you can remove unnecessary files from it. Here’s one of tips you can do:

  • Delete Samples folder.
  • Delete unused fonts. Notably from Sprites, User, Extras if you’re not using these fonts. (be cautions for wasy and stmary, as these are symbol files you probably not aware of using it already)
  • Delete unused font resources from TEXDraw/Resources/TexFontMetadata. They’re not cleaned up automatically.

Implementation Differences with TeX editor in the wild west

Due to technical challenges, there are few differences and limitations that need to be noted, especially if you already know to TeX works in different editor:

  • TEXDraw don’t throw errors because of incomplete syntax. This can be tricky if you notice something that doesn’t work as expected.
  • TEXDraw don’t support macro changes in runtime (for performance reason).
  • TEXDraw don’t support \usepackage. If you want a feature to be implemented please reach the developer or discuss it on forum.