cohtml::View

The View represents a UI page with its DOM, styles and JavaScript context. Think of the View as a whole UI or UI element. The View for instance could be the whole HUD of a game. All View APIs, unless explicitly stated otherwise, can be called on any thread, but should not be used on multiple threads simultaneously.

#include <View.h>

Public Types

	Name
typedef void(COHERENT_STDCALL *)(cohtml::Binder *binder, void *model)	CoherentInternalBindGenericFunc

Public Functions

	Name
template <typename T > RegisterModelStatus	CreateModel(const char * name, T * model) Creates a model for binding.
template <typename T > UpdateModelStatus	UpdateWholeModel(T * model) Marks a model as dirty. Properties will be synchronized using the View::SynchronizeModels call.
virtual SynchronizeModelsStatus	SynchronizeModels() =0 Applies the changes accumulated by View::UpdateWholeModel to the corresponding JavaScript objects.
template <typename T > RegisterModelStatus	RegisterModel(const char * name, T * model, CoherentInternalBindGenericFunc func) Registers a model with a given name.
template <typename T > UpdateModelStatus	UnregisterModel(T * model) Unregisters a model.
virtual void	DestroyExposedInstanceOfType(void * object, cohtml::TypeInfo * typeInfo) =0 In order to identify different models internally we use a combination between a pointer to the object and a pointer to the type of the object. If you have an object where the type cannot be deduced statically during compile time, you need to provide it in a parameter to the function during runtime.
virtual UpdateModelStatus	UpdateWholeModelOfType(void * model, cohtml::TypeInfo * typeInfo) =0 Marks a model as dirty. Properties will be synchronized using the View::SynchronizeModels call.
virtual UpdateModelStatus	UnregisterModelOfType(void * model, cohtml::TypeInfo * typeInfo) =0 Unregisters a model.
virtual RegisterModelStatus	RegisterModelOfType(const char * name, void * model, cohtml::TypeInfo * typeInfo, CoherentInternalBindGenericFunc func) =0 Registers a model with a given name.
virtual void *	ReservedMethod(void * command, void * data) =0 Reserved method for internal usage. Do not use.
virtual void	TriggerEvent(const char * name) =0 Triggers a UI event.
template <typename T1 > void	TriggerEvent(const char * name, const T1 & argument1) Triggers a UI event.
template <typename T1 ,typename T2 > void	TriggerEvent(const char * name, const T1 & argument1, const T2 & argument2) Triggers a UI event.
template <typename T1 ,typename T2 ,typename T3 > void	TriggerEvent(const char * name, const T1 & argument1, const T2 & argument2, const T3 & argument3) Triggers a UI event.
template <typename T1 ,typename T2 ,typename T3 ,typename T4 > void	TriggerEvent(const char * name, const T1 & argument1, const T2 & argument2, const T3 & argument3, const T4 & argument4) Triggers a UI event.
template <typename T1 ,typename T2 ,typename T3 ,typename T4 ,typename T5 > void	TriggerEvent(const char * name, const T1 & argument1, const T2 & argument2, const T3 & argument3, const T4 & argument4, const T5 & argument5) Triggers a UI event.
virtual	~View()
virtual void	Destroy() =0 Destroys the View. Should be called before the destruction of the System and Library.
virtual void	LoadURL(const char * url) =0 Loads a page in the View.
virtual void	Reload() =0 Reloads the current page in the view.
virtual void	UnloadDocument() =0 Unloads the HTML document. This will remove the entire DOM tree, so nothing will rendered but the view object will still be usable and another document might be loaded using View::LoadURL.
virtual void	ClearNavigationHistory() =0 Clears the navigation history accessed from JavaScript History object Use that method after View::LoadURL to reset the navigation history in case the view is reused to display unrelated page.
virtual unsigned	Advance(TimePoint timeMilliseconds) =0 Advances the internal timer of the View and runs all animations. If changes have happened in the page, this call will also trigger a new layout and render on the other threads.
virtual unsigned	GetId() const =0 Returns the unique ID of the View.
virtual TaskFamilyId	GetTaskFamilyId() const =0 Returns the Task Family Id that can be used to schedule Layout work in an auxiliary thread.
virtual void	Resize(unsigned width, unsigned height) =0 Resizes the View contents.
virtual void	SetUserBackground(void * userTexture, const renoir::Texture2D & description) =0 The background where the UI scene will be drawn.
virtual void	SetGlobalBackdropFilterMask(void * userTexture, const renoir::Texture2D & description) =0 A texture to a mask that Cohtml will generate during ViewRenderer::Paint.
virtual void	SetUserBackgroundOffset(float x, float y) =0 Set the user background offset. This has to be the location of the upper left corner of the UI texture relative to the upper left corner of the user background texture.
virtual unsigned	GetWidth() const =0 Gets the View width.
virtual unsigned	GetHeight() const =0 Gets the View height.
virtual void	OnListenerLost() =0 Informs the View that its listener has been lost.
virtual void	EnableRendering(bool value) =0 Enables or disables the recording of rendering commands for the view. Enabled by default.
virtual void	EnableImmediateLayout(bool isEnabled) =0 Enables or disables immediate layout. Disabled by default.
virtual bool	IsImmediateLayoutEnabled() const =0 Returns whether or not immediate layout is enabled.
virtual void	ContinuousRepaint(bool enable) =0 Debugging flag. This will cause the View to re-draw itself each frame.
virtual void	EnableUISurfacePartitioning(bool enable) =0 Enable/Disable the UI partitioning mode. In this mode coh-partitioned elements will be rendered in persistent scratch textures.
virtual void	ShowPaintRectangles(bool show) =0 Debugging flag. This will cause the View show which parts of the texture are re-drawn each frame.
virtual void	ShowElementAABBs(bool show) =0 Debugging flag. This will cause the View to draw the bounding-boxes of all elements.
virtual void	EmitRenderingMetadata(bool emit) =0 Debugging flag. Enabling this will request the library to attach and emit metadata for every rendering command in the rendering backend. The metadata will contain the ID, CLASS and Node type of the Element that caused the drawing command. As multiple elements can be batched in the same command, the metadata will be a concatenated list of all Elements that have contributed to the batch. The user can emit the metadata in rendering & GPU debugging tools like PIX, RenderDoc, Razor etc. in order to gain better insight on the rendering operations & performance.
virtual bool	SetAdditionalFontFallbacks(const char * fontFamilies) =0 Sets fallback font families that will be used by all elements. Additional font families do not affect computed styles of an element.
virtual DebugDump *	DebugDumpDOMTree(unsigned flags) =0 Debugging helper. Collects a comprehensive DOM structure dump.
virtual DebugDump *	DebugDumpStackingContextTree() =0 Debugging helper. Collects data about stacking context subtrees of the DOM tree.
virtual bool	IsPointToPickEnabled() =0 Returns whether the “Select an element in the page to inspect it” feature is currently enabled in the inspector/dev tools.
virtual void	TouchEvent(const cohtml::TouchEventData * events, unsigned count, bool * handled, void * userData, const char * compositionId =nullptr) =0 Sends a touch input event to the View.
virtual void	GestureEvent(const cohtml::GestureEventData & event, bool * handled, void * userData, const char * compositionId =nullptr) =0 Sends a gesture input event to the View.
virtual void	MouseEvent(const cohtml::MouseEventData & event, bool * handled, void * userData, const char * compositionId =nullptr) =0 Sends a mouse input event to the View.
virtual void	KeyEvent(const cohtml::KeyEventData & event, bool * handled, void * userData, const char * compositionId =nullptr) =0 Sends a keyboard input event to the View.
virtual bool	IMESetComposition(const char * composition, unsigned targetStart, unsigned targetEnd) =0 Updates the internal state of the IME composition in the View.
virtual bool	IMEConfirmComposition(const char * composition) =0 Confirms the current IME composition.
virtual bool	IMECancelComposition() =0 Cancels the current IME composition.
virtual float	GetStartPanThreshold() const =0 Returns the minimum length of pans to be performed.
virtual void	SetStartPanThreshold(float value) =0 Sets the minimum length of pans to be performed.
virtual void	SetUserAgent(const char * userAgent) =0 Sets the User Agent string.
virtual ImagesList *	GetUsedImagesList(ImagesListExtract::Options options) const =0 Return a list of images currently in use by the View The list can be used to decide which images to pre-load or use for JS-based loading screens. The list is a current snapshot of the state of the View. Once built it will not change even if the View does. The user has to call the method again if she wants such changes applied.
virtual void	BeginCaptureDebugFrame(void * userData, FrameCaptureCallback callback, CaptureMode mode =CM_PreserveAll) =0 Will begin serializing every rendered frame to a memory blob which will be passed in the callback. The saved frames can be inspected for debug purposes.
virtual void	EndCaptureDebugFrame() =0 Ends serializing rendered frames.
virtual void	CaptureSingleDebugFrame(void * userData, FrameCaptureCallback callback, CaptureMode mode =CM_PreserveAll) =0 Will serialize next rendered frame to a memory blob which will be passed in the callback. The saved frames can be inspected for debug purposes.
virtual void	BeginCaptureBackendDebugFrame(void * userData, FrameCaptureCallback callback) =0 Will begin serializing the backend command for each frame to a memory blob which will be passed in the callback. The saved frames can be inspected for debug purposes.
virtual void	EndCaptureBackendDebugFrame() =0 Ends serializing backend commands.
virtual void	SetupPageCapture() =0 Puts the View and the corresponding system in a state where every resource is serialized to memory so that later you can create a full page capture containing everything needed to replay the currently loaded page.
virtual PageCapture *	DoPageCapture() =0 Generates a binary blob with the full page capture started through View::SetupPageCapture.
virtual void	LoadPageCapture(const char * data, size_t size, bool useOriginalHTML) =0 Loads a captured page that has been generated through View::DoPageCapture.
virtual void	CaptureSingleBackendDebugFrame(void * userData, FrameCaptureCallback callback) =0 Will serialize the backend commands for the next frame to a memory blob which will be passes in the callback.
virtual void	GetCacheCountStats(InternalCaches cache, unsigned & filled, unsigned & capacity) =0 Get info about the number of objects statistic of a particular internal cache.
virtual void	GetCacheBytesStats(InternalCaches cache, unsigned & filled, unsigned & capacity) =0 Get info about the bytes statistic of a particular internal cache.
virtual void	QueueSetCacheCountSize(InternalCaches cache, unsigned capacity) =0 Queue task to set the maximum number of objects in internal cache.
virtual void	QueueSetCacheBytesSize(InternalCaches cache, unsigned capacity) =0 Queue task to set the maximum bytes allowed for internal cache.
virtual void	QueueClearCaches(unsigned caches) =0 Queue a task to clear an internal caches list.
virtual BoundEventHandle	RegisterForEvent(const char * name, IEventHandler * handler) =0 Expose C++ handler to be called when a specific event occurs.
virtual void	UnregisterFromEvent(BoundEventHandle handle) =0 Remove a registered C++ handler.
virtual BoundEventHandle	BindCall(const char * name, IEventHandler * handler) =0 Expose C++ handler to be called from UI.
virtual void	UnbindCall(BoundEventHandle handle) =0 Remove a bound C++ handler.
virtual void	UnbindObject(const void * object) =0 Remove all handlers bound to a specific object.
template <typename T > void	ExposeAsGlobal(const char * name, T * object) Expose object as global variable.
template <typename T > void	DestroyExposedObject(T * object) Remove exposed object from JavaScript.
virtual void	DestroyExposedArray(void * array) =0 Remove exposed array from JavaScript.
virtual bool	IsReadyForBindings() const =0 Checks whether the cohtml.js bindings are initialized and ready to use.
virtual const char *	GetCurrentScriptStackTrace(int frameLimit =100) =0 Get the current script stack trace. Can be called in the debugger or in any code that is invoked from the script, for example event callbacks, model methods, etc…
virtual void	ExecuteScript(const char * script) =0 Execute arbitrary JavaScript code. This should be called only with a valid script context created.
virtual void	AddInitialScript(const char * script) =0 Schedules execution of JavaScript code on every page load. Can be called at any time. The scripts will be executed on the next page load in the same order they were added.
virtual void	ResetInitialScripts() =0 Resets the list of initial scripts executed on every page load.
virtual void	TerminateScriptExecution() =0 Forcefully terminates the current script execution. A script execution is any callback in the scripting or script tag evaluation. Therefore in order to terminate a very long running View method you may need to call TerminateScriptExecution more than once. It may be called on a different thread, but you must ensure that the View is still alive.
virtual void	SetCustomSceneCompositor(renoir::ISubLayerCompositor * compositor, void * viewMetadata) =0 Set a custom scene compositor whose callbacks will be invoked when the Renoir library processes the frontend graphics commands.
virtual void	SetSceneCustomEffectRenderer(renoir::ICustomEffectRenderer * renderer, void * customEffectRendererMetadata) =0 Set a custom effect renderer for the View. Callbacks of the interface will be invoked for elements that have the ‘coh-custom-effect-name’ property when the graphics library prepares the command buffer for execution. In the default rendering mode, this happens on the render thread and the same information will be handed when processing the BC_DrawCustomEffect command in the backend, which makes the use of this interface in this case redundant. If, however, you are processing the rendering commands on the UI thread, callbacks will be invoked on the UI thread as well. This allows clients to set parameters to custom materials in systems that require this to be done on the main/game thread.
virtual Binder *	GetBinder() =0 Returns a pointer to the internal binder.
virtual bool	SetCustomMediaFeature(const char * name, const char * value) =0 Enables a media feature with the given name and value.
virtual void	ResetCustomMediaFeatures() =0 Disables all currently enabled custom media features.

Public Types Documentation

typedef CoherentInternalBindGenericFunc

typedef void(COHERENT_STDCALL* cohtml::View::CoherentInternalBindGenericFunc) (cohtml::Binder *binder, void *model);

Public Functions Documentation

function CreateModel

template <typename T >
inline RegisterModelStatus CreateModel(
    const char * name,
    T * model
)

Creates a model for binding.

Parameters:

• name the name for the model
• model pointer to the object used as model (must be even aligned)

Return: Returns RegisterModelStatus::RMS_Success or reason why the operation was not successful

Warning: The model pointer must remain valid until cohtml::IViewListener::OnBindingsReleased is called or unregistered with cohtml::View::UnregisterModel

function UpdateWholeModel

template <typename T >
inline UpdateModelStatus UpdateWholeModel(
    T * model
)

Marks a model as dirty. Properties will be synchronized using the View::SynchronizeModels call.

Parameters:

• model the model to be marked as dirty

Return: Returns UpdateModelStatus::UMS_Success or reason why the operation was not successful

function SynchronizeModels

virtual SynchronizeModelsStatus SynchronizeModels() =0

Applies the changes accumulated by View::UpdateWholeModel to the corresponding JavaScript objects.

Return: Returns SynchronizeModelsStatus::SMS_Success or reason why the operation was not successful

Note: Waits for style solving generated from previous Advance. Avoid calling it too early.

function RegisterModel

template <typename T >
inline RegisterModelStatus RegisterModel(
    const char * name,
    T * model,
    CoherentInternalBindGenericFunc func
)

Registers a model with a given name.

Parameters:

• name the name of the model
• model the model pointer (must be even aligned)
• func overload of CoherentBindInternal for the custom type

Return: Returns RegisterModelStatus::RMS_Success or reason why the operation was not successful

Warning: For internal use only. Use View::CreateModel to create a model, which wraps the usage of this internal method.

function UnregisterModel

template <typename T >
inline UpdateModelStatus UnregisterModel(
    T * model
)

Unregisters a model.

Parameters:

• model the model to be unregistered.

Return: Returns UpdateModelStatus::UMS_Success or reason why the operation was not successful

Note: The global variable for the model in JavaScript will be deleted as well

function DestroyExposedInstanceOfType

virtual void DestroyExposedInstanceOfType(
    void * object,
    cohtml::TypeInfo * typeInfo
) =0

In order to identify different models internally we use a combination between a pointer to the object and a pointer to the type of the object. If you have an object where the type cannot be deduced statically during compile time, you need to provide it in a parameter to the function during runtime.

Parameters:

• object the C++ object to be removed from JavaScript
• typeInfo used to identify exactly which object on this address you want to destroy.

If you know the type of the object during compilation you can use template API CreateModel, UnregisterModel etc. If your object has a dynamic type (for example it may come from other VM) you must use their counterpart with the OfType suffix, listed below. The following code is an example on how you can get TypeInfo from the Binder:

binder->SetMode(Binder::BM_GetTypeInfo); binder->BeginType(); Add the properties and methods for your type, using RegisterType, AddProperty, etc. binder->EndType(model); auto typeInfo = binder->GetTypeInfo(); Remove exposed object from JavaScript

function UpdateWholeModelOfType

virtual UpdateModelStatus UpdateWholeModelOfType(
    void * model,
    cohtml::TypeInfo * typeInfo
) =0

Marks a model as dirty. Properties will be synchronized using the View::SynchronizeModels call.

Parameters:

• model the model to be marked as dirty
• typeInfo used to identify exactly which object on this address you want to update.

Return: Returns UpdateModelStatus::UMS_Success or reason why the operation was not successful

Note: Waits for style solving generated from previous Advance. Avoid calling it too early.

function UnregisterModelOfType

virtual UpdateModelStatus UnregisterModelOfType(
    void * model,
    cohtml::TypeInfo * typeInfo
) =0

Unregisters a model.

Parameters:

• model the model to be unregistered.
• typeInfo used to identify exactly which object on this address you want to unregister.

Return: Returns UpdateModelStatus::UMS_Success or reason why the operation was not successful

Note: The global variable for the model in JavaScript will be deleted as well

function RegisterModelOfType

virtual RegisterModelStatus RegisterModelOfType(
    const char * name,
    void * model,
    cohtml::TypeInfo * typeInfo,
    CoherentInternalBindGenericFunc func
) =0

Registers a model with a given name.

Parameters:

• name the name of the model
• model the model pointer (must be even aligned)
• typeInfo used to identify exactly which object on this address you want to register.
• func function that will be used to bind instances of this type

Return: Returns RegisterModelStatus::RMS_Success or reason why the operation was not successful

Note: Waits for style solving generated from previous Advance. Avoid calling it too early.

function ReservedMethod

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

Reserved method for internal usage. Do not use.

function TriggerEvent

virtual void TriggerEvent(
    const char * name
) =0

Triggers a UI event.

Note: Waits for style solving generated from previous Advance. Avoid calling it too early.

function TriggerEvent

template <typename T1 >
inline void TriggerEvent(
    const char * name,
    const T1 & argument1
)

Triggers a UI event.

function TriggerEvent

template <typename T1 ,
typename T2 >
inline void TriggerEvent(
    const char * name,
    const T1 & argument1,
    const T2 & argument2
)

Triggers a UI event.

function TriggerEvent

template <typename T1 ,
typename T2 ,
typename T3 >
inline void TriggerEvent(
    const char * name,
    const T1 & argument1,
    const T2 & argument2,
    const T3 & argument3
)

Triggers a UI event.

function TriggerEvent

template <typename T1 ,
typename T2 ,
typename T3 ,
typename T4 >
inline void TriggerEvent(
    const char * name,
    const T1 & argument1,
    const T2 & argument2,
    const T3 & argument3,
    const T4 & argument4
)

Triggers a UI event.

function TriggerEvent

template <typename T1 ,
typename T2 ,
typename T3 ,
typename T4 ,
typename T5 >
inline void TriggerEvent(
    const char * name,
    const T1 & argument1,
    const T2 & argument2,
    const T3 & argument3,
    const T4 & argument4,
    const T5 & argument5
)

Triggers a UI event.

function ~View

virtual ~View()

function Destroy

virtual void Destroy() =0

Destroys the View. Should be called before the destruction of the System and Library.

function LoadURL

virtual void LoadURL(
    const char * url
) =0

Loads a page in the View.

Parameters:

• url A URL for the page to be loaded. Must be a valid URL. Spaces aren’t allowed.

Note:

• Calling View::LoadURL pushes states in the navigation history. If that’s undesired, call View::ClearNavigationHistory next.
• Waits for style solving generated from previous Advance. Avoid calling it too early.
• Calling View::LoadURL() with a non-empty URL and without a SystemSettings::ResourceHandler provided to the System will load a default fallback page instead. This lets you focus on other parts of the integration before setting up resource handling.

function Reload

virtual void Reload() =0

Reloads the current page in the view.

function UnloadDocument

virtual void UnloadDocument() =0

Unloads the HTML document. This will remove the entire DOM tree, so nothing will rendered but the view object will still be usable and another document might be loaded using View::LoadURL.

Note: Waits for style solving generated from previous Advance. Avoid calling it too early.

function ClearNavigationHistory

virtual void ClearNavigationHistory() =0

Clears the navigation history accessed from JavaScript History object Use that method after View::LoadURL to reset the navigation history in case the view is reused to display unrelated page.

function Advance

virtual unsigned Advance(
    TimePoint timeMilliseconds
) =0

Advances the internal timer of the View and runs all animations. If changes have happened in the page, this call will also trigger a new layout and render on the other threads.

Parameters:

• timeMilliseconds the time in milliseconds since arbitrary point in time. The time must be monotonically increasing

function GetId

virtual unsigned GetId() const =0

Returns the unique ID of the View.

function GetTaskFamilyId

virtual TaskFamilyId GetTaskFamilyId() const =0

Returns the Task Family Id that can be used to schedule Layout work in an auxiliary thread.

function Resize

virtual void Resize(
    unsigned width,
    unsigned height
) =0

Resizes the View contents.

Parameters:

• width the new width of the View
• height the new height of the View

Note: You must also update the texture for the ViewRenderer with the SetRenderTarget method

function SetUserBackground

virtual void SetUserBackground(
    void * userTexture,
    const renoir::Texture2D & description
) =0

The background where the UI scene will be drawn.

Parameters:

• userTexture Pointer to a user-defined representation of the texture. Will be passed as-is to the graphics backend.
• description Description of the provided texture. The most relevant fields are Width, Height, ContentRectX, ContentRectY, ContentRectWidth, and ContentRectHeight

Note: With the ContentRectX and ContentRectY fields you can pass offset of the user background relative to the UI texture for this view. That is, where exactly will the top left corner of the UI texture end up in the user background

function SetGlobalBackdropFilterMask

virtual void SetGlobalBackdropFilterMask(
    void * userTexture,
    const renoir::Texture2D & description
) =0

A texture to a mask that Cohtml will generate during ViewRenderer::Paint.

Parameters:

• userTexture Pointer to a user-defined representation of the texture. Will be passed as-is to the graphics backend.
• description Description of the provided texture. The most relevant fields are Width and Height. Those should match the size of the render target passed to ViewRenderer::SetRenderTarget

function SetUserBackgroundOffset

virtual void SetUserBackgroundOffset(
    float x,
    float y
) =0

Set the user background offset. This has to be the location of the upper left corner of the UI texture relative to the upper left corner of the user background texture.

Parameters:

• x The x coordinate of the upper left corner where the UI texture will be drawn
• y The y coordinate of the upper left corner where the UI texture will be drawn

function GetWidth

virtual unsigned GetWidth() const =0

Gets the View width.

function GetHeight

virtual unsigned GetHeight() const =0

Gets the View height.

function OnListenerLost

virtual void OnListenerLost() =0

Informs the View that its listener has been lost.

function EnableRendering

virtual void EnableRendering(
    bool value
) =0

Enables or disables the recording of rendering commands for the view. Enabled by default.

Parameters:

• value whether to enable the recording of rendering commands

Note: You must still call Paint for resource management on the GPU.

function EnableImmediateLayout

virtual void EnableImmediateLayout(
    bool isEnabled
) =0

Enables or disables immediate layout. Disabled by default.

Parameters:

• isEnabled whether to enable immediate layout

function IsImmediateLayoutEnabled

virtual bool IsImmediateLayoutEnabled() const =0

Returns whether or not immediate layout is enabled.

function ContinuousRepaint

virtual void ContinuousRepaint(
    bool enable
) =0

Debugging flag. This will cause the View to re-draw itself each frame.

Parameters:

• enable whether to enable the continuous repaint mode

Note: this flag will have a significant impact on performance. Use for debugging purposes ONLY.

function EnableUISurfacePartitioning

virtual void EnableUISurfacePartitioning(
    bool enable
) =0

Enable/Disable the UI partitioning mode. In this mode coh-partitioned elements will be rendered in persistent scratch textures.

Parameters:

• enable whether to enable the UI partitioning mode

function ShowPaintRectangles

virtual void ShowPaintRectangles(
    bool show
) =0

Debugging flag. This will cause the View show which parts of the texture are re-drawn each frame.

Parameters:

• show whether to show the paint rectangles

function ShowElementAABBs

virtual void ShowElementAABBs(
    bool show
) =0

Debugging flag. This will cause the View to draw the bounding-boxes of all elements.

Parameters:

• show whether to show the bounding-boxes of elements

function EmitRenderingMetadata

virtual void EmitRenderingMetadata(
    bool emit
) =0

Debugging flag. Enabling this will request the library to attach and emit metadata for every rendering command in the rendering backend. The metadata will contain the ID, CLASS and Node type of the Element that caused the drawing command. As multiple elements can be batched in the same command, the metadata will be a concatenated list of all Elements that have contributed to the batch. The user can emit the metadata in rendering & GPU debugging tools like PIX, RenderDoc, Razor etc. in order to gain better insight on the rendering operations & performance.

Parameters:

• emit whether to emit or not the metadata - disabled by default

Note: The option should only be used during development as it has a perceivable CPU cost associated.

function SetAdditionalFontFallbacks

virtual bool SetAdditionalFontFallbacks(
    const char * fontFamilies
) =0

Sets fallback font families that will be used by all elements. Additional font families do not affect computed styles of an element.

Parameters:

• fontFamilies font families to be applied (use CSS font-family property format: “Arial, Roboto”)

Return: if font families were parsed or cleared successfully. The value was not changed if return value is false

Note: pass nullptr or empty string to clear additional fallbacks.

function DebugDumpDOMTree

virtual DebugDump * DebugDumpDOMTree(
    unsigned flags
) =0

Debugging helper. Collects a comprehensive DOM structure dump.

function DebugDumpStackingContextTree

virtual DebugDump * DebugDumpStackingContextTree() =0

Debugging helper. Collects data about stacking context subtrees of the DOM tree.

function IsPointToPickEnabled

virtual bool IsPointToPickEnabled() =0

Returns whether the “Select an element in the page to inspect it” feature is currently enabled in the inspector/dev tools.

function TouchEvent

virtual void TouchEvent(
    const cohtml::TouchEventData * events,
    unsigned count,
    bool * handled,
    void * userData,
    const char * compositionId =nullptr
) =0

Sends a touch input event to the View.

Parameters:

• events an array of ‘count’ events
• count the count of events passed
• handled a deprecated parameter, you should pass nullptr.
• userData an opaque pointer passed to the ViewListener::OnNodeTouched method. Can be nullptr.
• compositionId is used for sending a TouchEvent only for the specified composition subtree. when hitting a composited element coordinates should be passed as if the composition resides in Untransformed2DTargetRect

Note: Waits for style solving generated from previous Advance. Avoid calling it too early.

function GestureEvent

virtual void GestureEvent(
    const cohtml::GestureEventData & event,
    bool * handled,
    void * userData,
    const char * compositionId =nullptr
) =0

Sends a gesture input event to the View.

Parameters:

• event a gesture event
• handled a deprecated parameter, you should pass nullptr.
• userData an opaque pointer. Currently unused, you should pass nullptr.
• compositionId is used for sending a GestureEvent only to the specified composition subtree. when hitting a composited element coordinates should be passed as if the composition resides in Untransformed2DTargetRect

Note: Waits for style solving generated from previous Advance. Avoid calling it too early.

function MouseEvent

virtual void MouseEvent(
    const cohtml::MouseEventData & event,
    bool * handled,
    void * userData,
    const char * compositionId =nullptr
) =0

Sends a mouse input event to the View.

Parameters:

• event a mouse event
• handled a deprecated parameter, you should pass nullptr.
• userData an opaque pointer passed to the ViewListener::OnNodeMouseEvent method. Can be nullptr.
• compositionId is used for sending a MouseEvent only to the specified composition subtree. when hitting a composited element coordinates should be passed as if the composition resides in Untransformed2DTargetRect

function KeyEvent

virtual void KeyEvent(
    const cohtml::KeyEventData & event,
    bool * handled,
    void * userData,
    const char * compositionId =nullptr
) =0

Sends a keyboard input event to the View.

Parameters:

• event a keyboard event
• handled a deprecated parameter, you should pass nullptr.
• userData an opaque pointer passed to the ViewListener::OnNodeMouseEvent method. Can be nullptr.
• compositionId is used for sending a KeyEvent only to the specified composition subtree.

Note: Waits for style solving generated from previous Advance. Avoid calling it too early.

function IMESetComposition

virtual bool IMESetComposition(
    const char * composition,
    unsigned targetStart,
    unsigned targetEnd
) =0

Updates the internal state of the IME composition in the View.

Parameters:

• composition the composition string so far
• targetStart the index at the start of the selection
• targetEnd the index at the end of the selection

Return: the outcome of the operation (will fail if there isn’t a focused input field)

function IMEConfirmComposition

virtual bool IMEConfirmComposition(
    const char * composition
) =0

Confirms the current IME composition.

Parameters:

• composition the string to confirm

Return: the outcome of the operation (will fail if there isn’t a focused input field)

function IMECancelComposition

virtual bool IMECancelComposition() =0

Cancels the current IME composition.

Return: the outcome of the operation (will fail if there isn’t a focused input field)

function GetStartPanThreshold

virtual float GetStartPanThreshold() const =0

Returns the minimum length of pans to be performed.

function SetStartPanThreshold

virtual void SetStartPanThreshold(
    float value
) =0

Sets the minimum length of pans to be performed.

Parameters:

• value the minimum length in pixels

function SetUserAgent

virtual void SetUserAgent(
    const char * userAgent
) =0

Sets the User Agent string.

Parameters:

• userAgent the user agent string

function GetUsedImagesList

virtual ImagesList * GetUsedImagesList(
    ImagesListExtract::Options options
) const =0

Return a list of images currently in use by the View The list can be used to decide which images to pre-load or use for JS-based loading screens. The list is a current snapshot of the state of the View. Once built it will not change even if the View does. The user has to call the method again if she wants such changes applied.

Return: An object that represents an iterator over the list

Note:

• Call the Release method on the returned ImagesList to reclaim its memory.
• Waits for style solving generated from previous Advance. Avoid calling it too early.

function BeginCaptureDebugFrame

virtual void BeginCaptureDebugFrame(
    void * userData,
    FrameCaptureCallback callback,
    CaptureMode mode =CM_PreserveAll
) =0

Will begin serializing every rendered frame to a memory blob which will be passed in the callback. The saved frames can be inspected for debug purposes.

Parameters:

• userData opaque pointer which will be passed in the callback
• callback Pointer to function which will be called with the serialized data. The callback will be called on the UI thread.
• mode Obfuscation behaviour to use when capturing frames

Note:

• If you need to capture whole screen call ContinuousRepaint(true) to redraw the whole screen.
• Call Release() on the FrameCapture object to release the memory allocated for the data.
• callback will be called on the UI thread

Warning: the option must be used only for debug and performance measurements. It slows down the application significantly.

function EndCaptureDebugFrame

virtual void EndCaptureDebugFrame() =0

Ends serializing rendered frames.

function CaptureSingleDebugFrame

virtual void CaptureSingleDebugFrame(
    void * userData,
    FrameCaptureCallback callback,
    CaptureMode mode =CM_PreserveAll
) =0

Will serialize next rendered frame to a memory blob which will be passed in the callback. The saved frames can be inspected for debug purposes.

Parameters:

• userData opaque pointer which will be passed in the callback
• callback Pointer to function which will be called with the serialized data. The callback will be called on the UI thread.
• mode Obfuscation behaviour to use when capturing the frame

Note:

• If you need to capture whole screen call ContinuousRepaint(true) to redraw the whole screen.
• Call Release() on the FrameCapture object to release the memory allocated for the data.
• callback will be called on the UI thread

Warning: the option must be used only for debug and performance measurements. It slows down the application significantly.

function BeginCaptureBackendDebugFrame

virtual void BeginCaptureBackendDebugFrame(
    void * userData,
    FrameCaptureCallback callback
) =0

Will begin serializing the backend command for each frame to a memory blob which will be passed in the callback. The saved frames can be inspected for debug purposes.

Parameters:

• userData opaque pointer which will be passed in the callback
• callback Pointer to function which will be called with the serialized data. The callback will be called on the UI thread.

Note:

• If you need to capture whole screen call ContinuousRepaint(true) to redraw the whole screen.
• Call Release() on the FrameCapture object to release the memory allocated for the data.
• callback will be called on the UI thread

Warning: the option must be used only for debug and performance measurements. It slows down the application significantly.

function EndCaptureBackendDebugFrame

virtual void EndCaptureBackendDebugFrame() =0

Ends serializing backend commands.

function SetupPageCapture

virtual void SetupPageCapture() =0

Puts the View and the corresponding system in a state where every resource is serialized to memory so that later you can create a full page capture containing everything needed to replay the currently loaded page.

Note: Call this as soon as possible because cohtml has to capture every resource that a page might need

function DoPageCapture

virtual PageCapture * DoPageCapture() =0

Generates a binary blob with the full page capture started through View::SetupPageCapture.

Return: an object pointing to a byte data that should be saved to a file

Note: call View::SetupPageCapture before calling View::DoPageCapture

function LoadPageCapture

virtual void LoadPageCapture(
    const char * data,
    size_t size,
    bool useOriginalHTML
) =0

Loads a captured page that has been generated through View::DoPageCapture.

Parameters:

• data pointer to data previously captured through View::DoPageCapture
• size size of the data in bytes
• useOriginalHTML should the displayed HTML be the original HTML as given by the original link or the document.documentElement.InnerHTML at the time of the capture

Note: Waits for style solving generated from previous Advance. Avoid calling it too early.

function CaptureSingleBackendDebugFrame

virtual void CaptureSingleBackendDebugFrame(
    void * userData,
    FrameCaptureCallback callback
) =0

Will serialize the backend commands for the next frame to a memory blob which will be passes in the callback.

Parameters:

• userData opaque pointer which will be passed in the callback
• callback Pointer to function which will be called with the serialized data. The callback will be called on the UI thread.

Note:

• Call Release() on the FrameCapture object to release the memory allocated for the data.
• callback will be called on the UI thread

function GetCacheCountStats

virtual void GetCacheCountStats(
    InternalCaches cache,
    unsigned & filled,
    unsigned & capacity
) =0

Get info about the number of objects statistic of a particular internal cache.

Parameters:

• cache specifies for which cache to return the info about the count statistic
• filled number of existing objects in the cache
• capacity maximum number of objects that can coexist in the cache

Note:

• the filled count in cache can be higher than the capacity, because some caches are pruned at the end of the frame.
• Waits for style solving generated from previous Advance. Avoid calling it too early.

Warning: the ICACHE_ScratchLayerTextures doesn’t currently have the count statistic

function GetCacheBytesStats

virtual void GetCacheBytesStats(
    InternalCaches cache,
    unsigned & filled,
    unsigned & capacity
) =0

Get info about the bytes statistic of a particular internal cache.

Parameters:

• cache specifies for which cache to return the info about the bytes statistic
• filled bytes in the cache
• capacity maximum bytes that the cache can contain

Note:

• the filled bytes in cache can be higher than the capacity, because some caches are pruned at the end of the frame.
• Waits for style solving generated from previous Advance. Avoid calling it too early.

Warning: only the ICACHE_GPUResourcesPool has the bytes statistic

function QueueSetCacheCountSize

virtual void QueueSetCacheCountSize(
    InternalCaches cache,
    unsigned capacity
) =0

Queue task to set the maximum number of objects in internal cache.

Parameters:

• cache specifies for which cache to set the bytes size
• capacity maximum number of objects allowed in the cache

Note: This takes effect at the next Advance/Paint cycle

Warning: the ICACHE_ScratchLayerTextures doesn’t have this statistic

function QueueSetCacheBytesSize

virtual void QueueSetCacheBytesSize(
    InternalCaches cache,
    unsigned capacity
) =0

Queue task to set the maximum bytes allowed for internal cache.

Parameters:

• cache specifies for which cache to set the count size
• capacity maximum bytes allowed in the cache

Note: This takes effect at the next Advance/Paint cycle

Warning: only the ICACHE_GPUResourcesPool has the bytes statistic

function QueueClearCaches

virtual void QueueClearCaches(
    unsigned caches
) =0

Queue a task to clear an internal caches list.

Parameters:

• caches a bit field listing all caches to clear

Note: This takes effect at the next Advance/Paint cycle

function RegisterForEvent

virtual BoundEventHandle RegisterForEvent(
    const char * name,
    IEventHandler * handler
) =0

Expose C++ handler to be called when a specific event occurs.

Parameters:

• name name of the event
• handler handler to be executed

Return: bound handle so the handler can be unregistered

Note: RegisterForEvent takes ownership of the handler

Warning: Any object in the handler must be valid until cohtml::IViewListener::OnBindingsReleased is called or the handler is unregistered with cohtml::View::UnregisterFromEvent

function UnregisterFromEvent

virtual void UnregisterFromEvent(
    BoundEventHandle handle
) =0

Remove a registered C++ handler.

Parameters:

• handle the handle of the event handler to be unregistered

Warning: Unregistering a handler inside the handler callback is not supported and will result in undefined behavior

function BindCall

virtual BoundEventHandle BindCall(
    const char * name,
    IEventHandler * handler
) =0

Expose C++ handler to be called from UI.

Parameters:

• name name for the handler in the UI
• handler handler to be executed

Return: bound handle so the handler can be unbound later

Note: BindCall takes ownership of the handler

Warning: Any object in the handler must be valid until cohtml::IViewListener::OnBindingsReleased is called or the handler is unbound with cohtml::View::UnbindCall

function UnbindCall

virtual void UnbindCall(
    BoundEventHandle handle
) =0

Remove a bound C++ handler.

Parameters:

• handle the handle of the handler to be unbound

Warning: Unbinding a handler inside the handler callback is not supported and will result in undefined behavior

function UnbindObject

virtual void UnbindObject(
    const void * object
) =0

Remove all handlers bound to a specific object.

Parameters:

• object the object whose handlers will be removed

Warning: Unbinding the object inside the handler callback is not supported and will result in undefined behavior

function ExposeAsGlobal

template <typename T >
inline void ExposeAsGlobal(
    const char * name,
    T * object
)

Expose object as global variable.

Parameters:

• name name of the global variable
• object the instance for the global variable

Warning: The object pointer must remain valid until cohtml::IViewListener::OnBindingsReleased is called or destroyed with cohtml::View::DestroyExposedObject

function DestroyExposedObject

template <typename T >
inline void DestroyExposedObject(
    T * object
)

Remove exposed object from JavaScript.

Parameters:

• object the C++ object that to be removed from JavaScript

function DestroyExposedArray

virtual void DestroyExposedArray(
    void * array
) =0

Remove exposed array from JavaScript.

Parameters:

• array - the array pointer provided when binding the array with Binder::TryBindArrayByRef

function IsReadyForBindings

virtual bool IsReadyForBindings() const =0

Checks whether the cohtml.js bindings are initialized and ready to use.

Return: true, if the view is ready to accept JavaScript bindings, false otherwise.

function GetCurrentScriptStackTrace

virtual const char * GetCurrentScriptStackTrace(
    int frameLimit =100
) =0

Get the current script stack trace. Can be called in the debugger or in any code that is invoked from the script, for example event callbacks, model methods, etc…

Parameters:

• frameLimit the maximum number of stack frames to capture

Return: the current script stack trace or an empty string if there is no script execution when the method is invoked.

Note: The returned pointer is valid until the next call to this method. To free the used memory call again with zero frameLimit

function ExecuteScript

virtual void ExecuteScript(
    const char * script
) =0

Execute arbitrary JavaScript code. This should be called only with a valid script context created.

Parameters:

• script code to be evaluated in the context of the main frame of the view

Note: Waits for style solving generated from previous Advance. Avoid calling it too early.

function AddInitialScript

virtual void AddInitialScript(
    const char * script
) =0

Schedules execution of JavaScript code on every page load. Can be called at any time. The scripts will be executed on the next page load in the same order they were added.

Parameters:

• script code to be evaluated in the context of the main frame of the view

function ResetInitialScripts

virtual void ResetInitialScripts() =0

Resets the list of initial scripts executed on every page load.

function TerminateScriptExecution

virtual void TerminateScriptExecution() =0

Forcefully terminates the current script execution. A script execution is any callback in the scripting or script tag evaluation. Therefore in order to terminate a very long running View method you may need to call TerminateScriptExecution more than once. It may be called on a different thread, but you must ensure that the View is still alive.

Note: This method works only on platforms with V8 as scripting engine

Warning: Termination will throw uncaught exception in the script

function SetCustomSceneCompositor

virtual void SetCustomSceneCompositor(
    renoir::ISubLayerCompositor * compositor,
    void * viewMetadata
) =0

Set a custom scene compositor whose callbacks will be invoked when the Renoir library processes the frontend graphics commands.

Parameters:

• compositor The compositor instance that the View will use to invoke callbacks
• viewMetadata Custom metadata passed to the renoir::ISubLayerCompositor::OnDrawSubLayer callback into the renoir::ISubLayerCompositor::DrawData::CustomSceneMetadata field

Note:

• The DOM tree can be divided into “sublayers” for rendering purposes. Each sublayer is drawn to an off-screen texture and then composed back to the original render target. Setting a custom compositor allows the user to do the composition themselves, and even use the data from the renoir::ISubLayerCompositor callbacks to draw the sublayer practically anywhere, on any render target (not necessarily the originally intended one).
• See the documentation for custom composition for more details.

Warning: The compositor instance passed must outlive the View.

function SetSceneCustomEffectRenderer

virtual void SetSceneCustomEffectRenderer(
    renoir::ICustomEffectRenderer * renderer,
    void * customEffectRendererMetadata
) =0

Set a custom effect renderer for the View. Callbacks of the interface will be invoked for elements that have the ‘coh-custom-effect-name’ property when the graphics library prepares the command buffer for execution. In the default rendering mode, this happens on the render thread and the same information will be handed when processing the BC_DrawCustomEffect command in the backend, which makes the use of this interface in this case redundant. If, however, you are processing the rendering commands on the UI thread, callbacks will be invoked on the UI thread as well. This allows clients to set parameters to custom materials in systems that require this to be done on the main/game thread.

Parameters:

• renderer The custom effect renderer instance that will receive callbacks.
• customEffectRendererMetadata Custom metadata passed as-is in the renoir::DrawCustomEffectCmd::UserData field within the structure passed to the backend

function GetBinder

virtual Binder * GetBinder() =0

Returns a pointer to the internal binder.

function SetCustomMediaFeature

virtual bool SetCustomMediaFeature(
    const char * name,
    const char * value
) =0

Enables a media feature with the given name and value.

Parameters:

• name of the feature
• value of the feature

Return: a flag to indicate the success of the operation

Note: Waits for style solving generated from previous Advance. Avoid calling it too early.

function ResetCustomMediaFeatures

virtual void ResetCustomMediaFeatures() =0

Disables all currently enabled custom media features.

Note: Waits for style solving generated from previous Advance. Avoid calling it too early.

---