cohtml::Library

This class encapsulates the global Cohtml library.

#include <Library.h>

Public Functions #

Public Functions Documentation #

function ~Library #

virtual ~Library()

function CreateSystem #

virtual System * CreateSystem(
    const SystemSettings & settings
) =0

Create a Cohtml System that can hold multiple Views.

Parameters:

• settings the system creation parameters

Return: a Cohtml system object

function StopWorkers #

virtual void StopWorkers() =0

Stops all work happening on auxiliary threads. The developer should call this to break the loops in ExecuteResourceWork and ExecuteLayoutWork and then eventually join the threads.

function Uninitialize #

virtual void Uninitialize(
    bool freeGlobalSdkMemory =false
) =0

Uninitializes the Cohtml library.

Parameters:

• freeGlobalSdkMemory frees any global SDK memory

Warning: The last time you call this function you must call it with freeGlobalSdkMemory = true. After freeing the global SDK memory, it won’t be possible to reinitialize the Library. Freeing the memory is usually done on application exit so all user allocations are cleared. This method must be called on the same thread, where Library::Initialize was called!

function GetFeatureInterface #

virtual void * GetFeatureInterface(
    unsigned featureID
) =0

Used for acquiring specific feature objects.

function ExecuteWork #

virtual void ExecuteWork(
    WorkType type,
    WorkExecutionMode mode,
    TaskFamilyId family =COHTML_ANY_TASK_FAMILY_ID
) =0

Executes Cohtml tasks. Some work in Cohtml has to happen asynchronously which improves performance and the scalability of the solution. The type of work is either Resources (loading, parsing, GC) or Layout. When new work is available, the user is notified through the OnWorkAvailable callback and should make sure that at some point that work is executed. The mode parameter is important to decide if you’ll only do some tasks (WEM_UntilQueueEmpty) or use it with a dedicated thread until the Library lives. Using a dedicated thread (WEM_UntilQuit) is simpler, but offers less control. This method can be called on any thread.

Parameters:

• type Sets the work type to schedule. Layout work shouldn’t be executed if the UseDedicatedLayoutThread parameter is false. In that case the Layout will happen in the View::Advance calls.
• mode Sets the mode to use in the Execution. Note that WEM_UntilQuit will not return until Cohtml itself is uninitialized.
• family Sets the task family Layout work to execute. Each View has a task family that can be retrieved through View::GetTaskFamilyId. The parameter allows executing work for a specific View, you can also pass COHTML_ANY_TASK_FAMILY_ID, which will execute any Layout work available for all Views.

function EnableProfiling #

virtual void EnableProfiling(
    bool enabled,
    const char * file,
    unsigned level
) =0

Start/Stop the emitting of internal profiling markers.

Parameters:

• enabled Whether the profiling should be stopped or started
• file If the profiling is done throught minitrace, the path for the JSON file where the profiling messages will be written to.
• level The profiling level – 1 or 2. 1 - enables only basic markers, 2 - enables all markers and can negatively impact performance but provides a lot of information

Note:

• The file will be opened throught the ‘SystemSettings::IFileSystemWriter’ object and the file path will be prepended with ‘LibraryParams::WritableDirectory’.
• The profiling can be enabled only in Development builds of Cohtml

function ReservedMethod #

virtual void * ReservedMethod(
    void * command,
    void * data
) =0

Reserved method for internal usage. Do not use.

function CreateScriptCompiler #

virtual ScriptCompiler * CreateScriptCompiler() =0

Creates new ScriptCompiler. Can be used to compile Script files and produce compiled data.

Note: Remember to Destroy the compiler instance when you no longer need it.

Warning: Can return nullptr if not supported by the current scripting engine.

function GetGPUMemoryStats #

virtual GPUMemoryInfo * GetGPUMemoryStats() const =0

Get a struct with the GPU memory information for Cohtml resources.

Note:

• This is available only in a Developer configuration, and will return nullptr otherwise
• Call the Release() method on the returned GPUMemoryInfo to release the memory allocated for the data

function GetUserGPUMemoryStats #

virtual UserGPUMemoryInfo * GetUserGPUMemoryStats() const =0

Get a struct with the GPU memory information for user resources.

Note:

• This is available only in a Developer configuration, and will return nullptr otherwise
• Call the Release() method on the returned UserGPUMemoryInfo to release the memory allocated for the data

function ResetGPUMemoryTrackerPeaks #

virtual void ResetGPUMemoryTrackerPeaks() =0

Resets all peaks tracked in the GPU memory tracker to the current state.

function Initialize #

static Library * Initialize(
    const char * licenseKey,
    const LibraryParams & params
)

Initializes the library.

Parameters:

• licenseKey license key provided by Coherent Labs
• params the initialization parameters of the library.

Return: A library object

Note: you can have only one library active at a time

function InitializeWithRenderingLibrary #

static Library * InitializeWithRenderingLibrary(
    const char * licenseKey,
    const LibraryParamsWithExternalRenderingLibrary & params,
    renoir::IRenderingLibrary * renderingLibrary
)

Initializes the library with an externally initialized rendering library.

Parameters:

• licenseKey license key provided by Coherent Labs
• params the initialization parameters of the library.
• renderingLibrary initialized Rendering library to use.

Return: A library object

Note:

• you can have only one library active at a time
• use this only when you need to reuse the rendering library.

function GetDefaultUserAgent #

static const char * GetDefaultUserAgent()

Get default User Agent string which can be used to reset view UA.

function HintThreadUsage #

static void HintThreadUsage(
    WorkType type
)

This hints Cohtml that the calling thread will be used for certain work. The call is optional and used for profiling purposes only. It is not necessary to call it in a final shipping environment.

Parameters:

• type Sets the work type of this thread.

function DecodeURLString #

static void DecodeURLString(
    const char * url,
    unsigned urlLen,
    char * decoded,
    unsigned * decodedSize
)

Decodes a URL string substituting any URL-encoded characters (%20, %21 etc.) with their ASCII counterparts i.e. ‘my%20url.html’ -> ‘my url.html’.

Parameters:

• url the url string to decode
• urlLen the number of characters in the url
• decoded pointer to the buffer where to copy the decoded string. Can be nullptr in order to query the size of the output
• decodedSize the length of the decoded string, including the terminating null

function GetBuildSDKVersion #

static const char * GetBuildSDKVersion()

Get a string with the version of the SDK that has been used to build Cohtml library.

Return: String with the version of the platform SDK

function GetLibraryVersion #

static const char * GetLibraryVersion()

Get a string with the version of the Cohtml library.

Return: String with the version of the Cohtml library

function SetScriptEngineAllocator #

static void SetScriptEngineAllocator(
    IAllocator * allocator
)

Set a global allocator to handle virtual machine allocations. It must be called once per process - before the first initialization of the library. VM memory tracking is implemented only for platforms where COHTML uses V8.

Parameters:

• allocator to handle VM allocations

Warning: V8 uses lazy-created global objects that will leak between library initializations and after the library is no longer used

function EnableCSSParserErrorLocations #

static void EnableCSSParserErrorLocations(
    bool enable
)

When enabled, adds line, column and file to CSS parser errors at the cost of reduced CSS parsing performance. Enabled by default for Debug builds, disabled by default for Release builds.