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.

#include <View.h>

Public Types

Name
typedef void(*)(cohtml::Binder *, void *)CoherentInternalBindGenericFunc

Public Functions

Name
template <typename T >
void
CreateModel(const char * name, T * model)
Creates a model for binding.
template <typename T >
void
UpdateWholeModel(T * model)
Marks a model as dirty. Properties will be synchronized using the View::SynchronizeModels call.
virtual voidSynchronizeModels() =0
Applies the changes accumulated by View::UpdateWholeModel to the corresponding JavaScript objects.
template <typename T >
void
RegisterModel(const char * name, T * model, CoherentInternalBindGenericFunc func)
Registers a model with a given name.
template <typename T >
void
UnregisterModel(T * model)
Unregisters a model.
virtual voidDestroyExposedInstanceOfType(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 voidUpdateWholeModelOfType(void * model, cohtml::TypeInfo * typeInfo) =0
Marks a model as dirty. Properties will be synchronized using the View::SynchronizeModels call.
virtual voidUnregisterModelOfType(void * model, cohtml::TypeInfo * typeInfo) =0
Unregisters a model.
virtual voidRegisterModelOfType(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 voidTriggerEvent(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 voidDestroy() =0
Destroys the View. Should be called before the destruction of the System and Library.
virtual voidLoadURL(const char * url) =0
Loads a page in the View.
virtual voidReload() =0
Reloads the current page in the view.
virtual voidUnloadDocument() =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 voidClearNavigationHistory() =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 unsignedAdvance(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 unsignedGetId() const =0
Returns the unique ID of the View.
virtual TaskFamilyIdGetTaskFamilyId() const =0
Returns the Task Family Id that can be used to schedule Layout work in an auxiliary thread.
virtual voidResize(unsigned width, unsigned height) =0
Resizes the View contents.
virtual voidSetUserBackground(void * userTexture, const renoir::Texture2D & description) =0
The background where the UI scene will be drawn.
virtual voidSetUserBackgroundOffset(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 voidSetResolutionForRendering(unsigned width, unsigned height) =0
Sets a resolution for rendering. This allows setting one size for the HTML (via the Resize method) and authoring the UI for that resolution, while here you can tell the SDK that it should render the UI into a different-sized texture. The ViewRenderer’s render target could be of a different size, although usually you’d want to have the resolution for rendering and ViewRenderer RT size to be the same.
virtual unsignedGetWidth() const =0
Gets the View width.
virtual unsignedGetHeight() const =0
Gets the View height.
virtual voidOnListenerLost() =0
Informs the View that its listener has been lost.
virtual voidEnableRendering(bool value) =0
Enables or disables the recording of rendering commands for the view. Enabled by default.
virtual voidEnableImmediateLayout(bool isEnabled) =0
Enables or disables immediate layout. Disabled by default.
virtual boolIsImmediateLayoutEnabled() const =0
Returns whether or not immediate layout is enabled.
virtual voidContinuousRepaint(bool enable) =0
Debugging flag. This will cause the View to re-draw itself each frame.
virtual voidEnableUISurfacePartitioning(bool enable) =0
Enable/Disable the UI partitioning mode. In this mode coh-partitioned elements wiil be rendered in persistent scratch textures.
virtual voidShowPaintRectangles(bool show) =0
Debugging flag. This will cause the View show which parts of the texture are re-drawn each frame.
virtual voidShowElementAABBs(bool show) =0
Debugging flag. This will cause the View to draw the bounding-boxes of all elements.
virtual voidEmitRenderingMetadata(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 boolSetAdditionalFontFallbacks(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 voidTouchEvent(const cohtml::TouchEventData * events, unsigned count, bool * handled, void * userData, const char * compositionId =nullptr) =0
Sends a touch input event to the View.
virtual voidGestureEvent(const cohtml::GestureEventData & event, bool * handled, void * userData, const char * compositionId =nullptr) =0
Sends a gesture input event to the View.
virtual voidMouseEvent(const cohtml::MouseEventData & event, bool * handled, void * userData, const char * compositionId =nullptr) =0
Sends a mouse input event to the View.
virtual voidKeyEvent(const cohtml::KeyEventData & event, bool * handled, void * userData, const char * compositionId =nullptr) =0
Sends a keyboard input event to the View.
virtual boolIMESetComposition(const char * composition, unsigned targetStart, unsigned targetEnd) =0
Updates the internal state of the IME composition in the View.
virtual boolIMEConfirmComposition(const char * composition) =0
Confirms the current IME composition.
virtual boolIMECancelComposition() =0
Cancels the current IME composition.
virtual floatGetStartPanThreshold() const =0
Returns the minimum length of pans to be performed.
virtual voidSetStartPanThreshold(float value) =0
Sets the minimum length of pans to be performed.
virtual voidSetUserAgent(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 renoir::GPUMemoryInfo *GetGPUMemoryStats() const =0
Get a struct with the GPU memory information of the scene.
virtual voidResetGPUMemoryTrackerPeaks() =0
Resets all peaks tracked in the GPU memory tracker to the current state.
virtual voidBeginCaptureDebugFrame(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 voidEndCaptureDebugFrame() =0
Ends serializing rendered frames.
virtual voidCaptureSingleDebugFrame(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 voidBeginCaptureBackendDebugFrame(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 voidEndCaptureBackendDebugFrame() =0
Ends serializing backend commands.
virtual voidSetupPageCapture() =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 cotaining everythin 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 voidLoadPageCapture(const char * data, size_t size, bool useOriginalHTML) =0
Loads a captured page that has been generated through View::DoPageCapture.
virtual voidCaptureSingleBackendDebugFrame(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 voidGetCacheCountStats(InternalCaches cache, unsigned & filled, unsigned & capacity) =0
Get info about the number of objects statistic of a particular internal cache.
virtual voidGetCacheBytesStats(InternalCaches cache, unsigned & filled, unsigned & capacity) =0
Get info about the bytes statistic of a particular internal cache.
virtual voidQueueSetCacheCountSize(InternalCaches cache, unsigned capacity) =0
Queue task to set the maximum number of objects in internal cache.
virtual voidQueueSetCacheBytesSize(InternalCaches cache, unsigned capacity) =0
Queue task to set the maximum bytes allowed for internal cache.
virtual voidQueueClearCaches(unsigned caches) =0
Queue a task to clear an internal caches list.
virtual BoundEventHandleRegisterForEvent(const char * name, IEventHandler * handler) =0
Expose C++ handler to be called when a specific event occurs.
virtual voidUnregisterFromEvent(BoundEventHandle handle) =0
Remove a registered C++ handler.
virtual BoundEventHandleBindCall(const char * name, IEventHandler * handler) =0
Expose C++ handler to be called from UI.
virtual voidUnbindCall(BoundEventHandle handle) =0
Remove a bound C++ handler.
virtual voidUnbindObject(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 voidDestroyExposedArray(void * array) =0
Remove exposed array from JavaScript.
virtual boolIsReadyForBindings() const =0
Checks whether the cohtml.js bindings are initialized and ready to use.
virtual voidExecuteScript(const char * script) =0
Execute arbitrary JavaScript code. This should be called only with a valid script context created.
virtual voidAddInitialScript(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 voidResetInitialScripts() =0
Resets the list of initial scripts executed on every page load.
virtual voidTerminateScriptExecution() =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 voidSetCustomSceneCompositor(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 voidSetSceneCustomEffectRenderer(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 game thread, callbacks will be invoked on the game thread as well. This allows clients to set parameters to custom materials in systems that require this to be done on the game thread.
virtual Binder *GetBinder() =0
Returns a pointer to the internal binder.

Public Types Documentation

typedef CoherentInternalBindGenericFunc

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

Public Functions Documentation

function CreateModel

template <typename T >
inline void 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)

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 void 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

function SynchronizeModels

virtual void SynchronizeModels() =0

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

function RegisterModel

template <typename T >
inline void 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

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 void UnregisterModel(
    T * model
)

Unregisters a model.

Parameters:

  • model the model to be unregistered.

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 void 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.

function UnregisterModelOfType

virtual void 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.

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

function RegisterModelOfType

virtual void 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

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.

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 thats undesired, call View::ClearNavigationHistory next.

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.

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 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 SetResolutionForRendering

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

Sets a resolution for rendering. This allows setting one size for the HTML (via the Resize method) and authoring the UI for that resolution, while here you can tell the SDK that it should render the UI into a different-sized texture. The ViewRenderer’s render target could be of a different size, although usually you’d want to have the resolution for rendering and ViewRenderer RT size to be the same.

Parameters:

  • width the width component of the resolution to render to
  • height the height component of the resolution to render to

Note: This API is useful for implementing a LOD system

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 wiil 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 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

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 passed to the ViewListener::OnNodeGestureEvent method. Can be 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

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.

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.

function GetGPUMemoryStats

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

Get a struct with the GPU memory information of the scene.

Note: Call the Release() method on the returned renoir::GPUMemoryInfo 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 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 Main 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 Main 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 Main 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 Main 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 Main 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 Main 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 cotaining everythin 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

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 Main thread.

Note:

  • Call Release() on the FrameCapture object to release the memory allocated for the data.
  • callback will be called on the Main 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.

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.

Warning: only the ICACHE_Textures and the ICACHE_ScratchLayerTextures have 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_Textures and the ICACHE_ScratchLayerTextures have 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:

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 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

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 game thread, callbacks will be invoked on the game thread as well. This allows clients to set parameters to custom materials in systems that require this to be done on the 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.