cohtml::Library

This class encapsulates the global Cohtml library.

#include <Library.h>

Public Functions

Name
virtual~Library()
virtual System *CreateSystem(const SystemSettings & settings) =0
Create a Cohtml System that can hold multiple Views.
virtual voidStopWorkers() =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.
virtual voidUninitialize(bool freeGlobalSdkMemory =false) =0
Uninitializes the Cohtml library.
virtual void *GetFeatureInterface(unsigned featureID) =0
Used for acquiring specific feature objects.
virtual voidExecuteWork(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.
virtual void *ReservedMethod(void * command, void * data) =0
Reserved method for internal usage. Do not use.
virtual ScriptCompiler *CreateScriptCompiler() =0
Creates new ScriptCompiler. Can be used to compile Script files and produce compiled data.
virtual renoir::GPUMemoryInfo *GetGPUMemoryStats() const =0
Get a struct with the GPU memory information.
virtual renoir::GPUMemoryInfo *GetTotalGPUMemoryStats() const =0
Get a struct with the merged GPU memory information of the library and all views together.
virtual renoir::UserGPUMemoryInfo *GetUserGPUMemoryStats() const =0
Get a struct with the user GPU memory information.
virtual voidResetGPUMemoryTrackerPeaks() =0
Resets all peaks tracked in the GPU memory tracker to the current state.
Library *Initialize(const char * licenseKey, const LibraryParams & params)
Initializes the library.
Library *InitializeWithRenderingLibrary(const char * licenseKey, const LibraryParamsWithExternalRenderingLibrary & params, renoir::IRenderingLibrary * renderingLibrary)
Initializes the library with an externally initialized rendering library.
const char *GetDefaultUserAgent()
Get default User Agent string which can be used to reset view UA.
voidHintThreadUsage(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.
voidDecodeURLString(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’.
const char *GetBuildSDKVersion()
Get a string with the version of the SDK that has been used to build Cohtml library.
const char *GetLibraryVersion()
Get a string with the version of the Cohtml library.
voidSetScriptEngineAllocator(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.
voidEnableCSSParserErrorLocations(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.

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.

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 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 renoir::GPUMemoryInfo * GetGPUMemoryStats() const =0

Get a struct with the GPU memory information.

Note: Call the Release() method on the returned renoir::GPUMemoryInfo to release the memory allocated for the data

function GetTotalGPUMemoryStats

virtual renoir::GPUMemoryInfo * GetTotalGPUMemoryStats() const =0

Get a struct with the merged GPU memory information of the library and all views together.

Note: Call the Release() method on the returned renoir::GPUMemoryInfo to release the memory allocated for the data

function GetUserGPUMemoryStats

virtual renoir::UserGPUMemoryInfo * GetUserGPUMemoryStats() const =0

Get a struct with the user GPU memory information.

Note: Call the Release() method on the returned renoir::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.