Library Configuration

Overview

The library creates Systems, initializes rendering, executes tasks, and manages memory and performance. There is only one instance for the Unity3D editor’s lifetime. It is recommended to leave the settings at their default values when using the plugin for the first time, then turn on the settings you need based on the features you use. The Library behavior can be configure from the Library configuration window.

How To Use

1. From Unity3D’s Context menu, click on the Gameface/Configure Library menu. The Library configuration window will appear.

   

2. Change the parameters with your preferences and click the Save button.
3. Restart the Unity3D Editor to apply your Library configuration.

Library Parameters

Logging Severity

cohtml.Net.LibraryParamsWithExternalRenderingLibrary.LoggingSeverity of the logging messages to show. Keep this to Info or higher in Shipping builds. Excessive logging can hurt performance.

Use C# Rendering Backend

When this option is enabled the plugin will use Unity’s C# rendering API, instead of the native rendering library provided by Gameface. It also ensures that rendering commands recording is on the Main thread. This option is not a Library setting, so you don’t have to restart the editor when you enable/disable it between play/stops. The two backends are supported on the following platforms:

Platform	Native rendering backend	C# Rendering backend
Windows	Yes	Yes
MacOS	Yes	Yes
iOS	Yes	No
Android	Yes	Partially (Vulkan only)
PS4	Yes	Yes
Xbox One	Yes	Yes
PS5	Yes	Yes
Xbox Series X/S	Yes	Yes
Switch	No	Yes

Note

Unity’s C# rendering API is mandatory for the Xbox Series X/S and Switch platforms and will have a slight performance impact in some cases compared to the native rendering backend.

Default Style Font Family

cohtml.Net.LibraryParamsWithExternalRenderingLibrary.DefaultStyleFontFamily sets the default font family that will be used by all Elements in the Views. The default font style is analogous to setting the CSS property “font-family” of all elements to the value of this field.

Path tessellation threshold ratio

cohtml.Net.CommonRenderingLibraryParams.PathTessellationThresholdRatio sets the threshold ratio, which is used for determining whether to reuse old tessellated paths or tessellate new ones when changing the display size of paths (e.g. SVGs). If the threshold ratio is lower, then more paths will be tessellated, which will lead to a higher path visual quality but also increased memory usage. On the other hand, setting the threshold ratio to a higher value will result in the reuse of more tessellated paths, which may cause lower path visual quality, because old tessellated paths are upscaled or downscaled to be reused. However, a higher threshold value will lead to a decrease in memory usage. Tessellation threshold ratio less than or equal to 1 will cause tessellation on every size change.

Note

The default tessellation threshold ratio is 2.5, which means that if we have previously tessellated a path with size X, then we will reuse it if the size of the new one is 250% larger or smaller. This is done by upscaling or downscaling the old tessellated path.

Allow Multiple Rendering Threads

Allows usage of Rendering Library calls from different threads. If not enabled, using rendering methods from different threads produces an error message.

Note

This option is useful when, for example, the client rendering backend records commands on different threads, that are later executed on a dedicated rendering thread. In the general use case where the rendering methods are called directly on the client’s rendering thread, this should be set to false, to warn when incorrect usage is detected.

Atlas text Dimension

Sets the width and height of the Text atlas in pixels. The default value is 1024. The values must be in the range from 64px to 8192px. If the given value is not a power of two it will be rounded up.

Memory tracking

Since memory tracking is a performance-heavy debugging tool, it is not enabled by default. When enabled from the Library configuration, Gameface will start tracking its memory allocations and provide you with the following APIs:

// Returns the current number of active allocations
GetAllocationCount();
// Returns the total size of allocated memory in bytes
GetAllocatedMemory();
// Returns the total number of allocations for a given memory type
GetTotalsByType(cohtml::MemTags::MemTagsType memtag);
// Returns the current number of allocated bytes for a given memory type
GetCurrentBytesByType(cohtml::MemTags::MemTagsType memtag);
// Returns the current number of allocations for a given memory type
GetCurrentCountsByType(cohtml::MemTags::MemTagsType memtag);

You can invoke the APIs by using the cohtml.Net.UnityPlugin.Instance().<API>; call where API is one of the above functions.

Note

Check out how to override components settings in the Extended setup guide page.