2.9.16
Coherent GT
A modern user interface library for games
Coherent::UIGT::UISystem Class Referenceabstract

Encapsulates basic UI system functionality. More...

#include <Coherent/Coherent/UIGT/UISystem.h>

Public Member Functions

virtual ViewCreateView (const ViewInfo &info, const char *url, ViewLoadPolicy policy=VLP_UseCacheOrLoad)=0
 Creates a new UI View. More...
 
virtual ViewCreateView (const ViewInfo &info, const char *url, const char *scriptToExecute, ViewLoadPolicy policy=VLP_UseCacheOrLoad)=0
 Creates a new UI View. More...
 
virtual UISystemRendererCreateRenderer (renoir::RendererBackend *backend, renoir::ClickThroughProvider *clickThrough)=0
 Creates the UI System renderer. All ViewRenderers are created through it so this is mandatory for drawing the Views. More...
 
virtual UISystemRendererCreateRenderer (renoir::ClickThroughProvider *clickThrough)=0
 Creates the UI System renderer. All ViewRenderers are created through it so this is mandatory for drawing the Views. This variant must be used when the UISystem is initialized with an external rendering library. More...
 
virtual void InspectorJSMemoryStatsEnabled (bool enabled)=0
 Enables/disables JS memory statistics in the inspector Memory stats are disabled by default to save computational resources. More...
 
virtual bool AreInspectorJSMemoryStatsEnabled () const =0
 Returns if the JS memory stats are enabled during inspector debugging. More...
 
virtual void Uninitialize (bool terminateUIThread=true)=0
 Destroys the UI system. More...
 
virtual void Advance ()=0
 Advances the timers of the UI. Should be called each frame.
 
virtual bool HasLastAdvanceCompleted ()=0
 Checks whether the last issued Advance has completed. More...
 
virtual void SetInMemoryResourceCacheSize (unsigned int bytes)=0
 Sets the in-memory cache capacity for loaded resources, such as decoded images, fonts, styles, etc. More...
 
virtual void GetInMemoryResourceCacheUsage (unsigned *usedBytes, unsigned *capacity) const =0
 Gets the in-memory cache currently used bytes and total capacity. The returned values will only be updated if you have called RequestInMemoryResourceCacheUsage and Advance prior to the call. More...
 
virtual void RequestInMemoryResourceCacheUsage ()=0
 Requests an update of the in-memory cache size and capacity which can then be read using GetInMemoryResourceCacheUsage.
 
virtual unsigned Fence ()=0
 Puts a fence in the underlying task queue and returns its id. Does nothing if the system is synchronous. More...
 
virtual void WaitFor (unsigned fence)=0
 Blocks the current thread until the specified fence has finished. Does nothing if the system is synchronous. More...
 
virtual void EraseAllCookies ()=0
 Deletes all cookies, both session-only and permanent. The in-memory cookies are purged and the disk file is removed.
 
virtual void IgnoreSSLCertificateErrors (bool ignore)=0
 Sets whether new SSL connections should ignore SSL connection errors. More...
 
virtual bool IsIgnoringSSLCertificateErrors () const =0
 Gets whether new SSL connections should ignore SSL connection errors. More...
 
virtual void EnableVerboseNetworkLogging (bool enable)=0
 Changes the connection setting for verbose network logging. More...
 
virtual bool IsVerboseNetworkLoggingEnabled () const =0
 Returns true if new connections are set to use verbose network logging. More...
 
virtual void RegisterGamepad (unsigned id, const char *info, unsigned axesCount, unsigned buttonsCount)=0
 Registers a new gamepad. All created views will receive the gamepadconnected event. More...
 
virtual void UnregisterGamepad (unsigned id)=0
 Unregisters a gamepad. All created views will receive the gamepaddisconnected event. More...
 
virtual void UpdateGamepadState (const Coherent::UIGT::GamepadState &state)=0
 Updates the state of a single gamepad. More...
 
virtual void ClearFontCache ()=0
 Clears the internal fonts cache.
 
virtual void ClearFontCache (bool clearRenderingTextures)=0
 Clears the internal fonts cache. Use this when using an external rendering library. More...
 
virtual bool AddFont (const void *fontData, size_t dataSize)=0
 Load the font data in memory in advance. More...
 
virtual void AddBitmapFont (const char **imagesData, unsigned *imagesDataSize, unsigned imagesCount, const BitmapFontDescription &description)=0
 Load the bitmap font using image files. More...
 
virtual void AddBitmapFont (const ResourceResponseUIGT::UserImageData *userImages, unsigned imagesCount, const BitmapFontDescription &description)=0
 Load the bitmap font using user images. More...
 
virtual bool AddFontsFolder (const char *folder)=0
 Add folder with fonts for lazy loading of font data. More...
 
virtual void UserImagesChanged (const unsigned *images, unsigned count)=0
 Trigger repaint of a user provided texture. Call this whenever the image is changed by logic external to the library. Make sure to have ImageHandle set for such images. More...
 
virtual void ReplaceUserImage (const ResourceResponseUIGT::UserImageData &userImage)=0
 Replace an already loaded user image. More...
 
virtual void RunGarbageCollection (GarbageCollectMode mode)=0
 Run garbage collection to free up CPU memory. More...
 
virtual void LogMemoryUsage (LogMemoryUsageFlags flags=LMU_Short)=0
 Logs the current memory usage of components known to hold big chunks of memory. JS heap - responsible for the lifetime of JS objects and exectution of scripts. Resource cache - most of the webpage resources are stored in memory to accelerate reading and avoid frequent disk operations. More...
 
virtual void AddHyphenationDictionary (const char *locale, const char *dictData, size_t dataSize)=0
 Load hyphenation dictionary for a given locale. More...
 
virtual void RemoveHyphenationDictionary (const char *locale)=0
 Unload hyphenation dictionary for a given locale. More...
 

Detailed Description

Encapsulates basic UI system functionality.

Note
all methods of the System except CreateRenderer MUST be called in the UI thread

Member Function Documentation

◆ AddBitmapFont() [1/2]

virtual void Coherent::UIGT::UISystem::AddBitmapFont ( const char **  imagesData,
unsigned *  imagesDataSize,
unsigned  imagesCount,
const BitmapFontDescription description 
)
pure virtual

Load the bitmap font using image files.

Note
Images must be 1 channel alpha texture.
The memory can be freed immediately after the call
Warning
This methods will synchronously decode the image files from the memory blobs pointed by imagesData.
Parameters
imagesDatapointer to image files data.
imagesDataSizepointer to size of the image files.
imagesCountnumber of images
descriptionDescription of the bitmap font.

◆ AddBitmapFont() [2/2]

virtual void Coherent::UIGT::UISystem::AddBitmapFont ( const ResourceResponseUIGT::UserImageData *  userImages,
unsigned  imagesCount,
const BitmapFontDescription description 
)
pure virtual

Load the bitmap font using user images.

Note
Images must be 1 channel alpha texture.
The memory can be freed immediately after the call
Parameters
userImagespointer to UserImageData structs describing the images.
imagesCountnumber of images
descriptionDescription of the bitmap font.

◆ AddFont()

virtual bool Coherent::UIGT::UISystem::AddFont ( const void *  fontData,
size_t  dataSize 
)
pure virtual

Load the font data in memory in advance.

Warning
this is copy free implementation and the font data must not be deleted until the font is in use
Parameters
fontDatacontains pointer to the font data loaded into memory
dataSizecontains the size of the read font data
Returns
true if adding the font succeeded; false if fontData wasn't in a format understandable by Freetype.

◆ AddFontsFolder()

virtual bool Coherent::UIGT::UISystem::AddFontsFolder ( const char *  folder)
pure virtual

Add folder with fonts for lazy loading of font data.

Parameters
folderpath to the folder with fonts
Returns
true if adding the folder succeeded; false if enumerating folder failed.

◆ AddHyphenationDictionary()

virtual void Coherent::UIGT::UISystem::AddHyphenationDictionary ( const char *  locale,
const char *  dictData,
size_t  dataSize 
)
pure virtual

Load hyphenation dictionary for a given locale.

Once the dictionary is added the client can release its content

Parameters
localepointer to the locale string which identifies the locale of the dictionary. Locale format must match the one used for the lang attribute
dictDatapointer to the memory buffer with the content of the hyphenation dictionary
dataSizethe size of the content memory buffer in bytes

◆ AreInspectorJSMemoryStatsEnabled()

virtual bool Coherent::UIGT::UISystem::AreInspectorJSMemoryStatsEnabled ( ) const
pure virtual

Returns if the JS memory stats are enabled during inspector debugging.

Returns
the state of the stats flag

◆ ClearFontCache()

virtual void Coherent::UIGT::UISystem::ClearFontCache ( bool  clearRenderingTextures)
pure virtual

Clears the internal fonts cache. Use this when using an external rendering library.

Parameters
clearRenderingTextureswhether the rendering textures should be cleared as well. This can affect other users of the rendering library.

◆ CreateRenderer() [1/2]

virtual UISystemRenderer* Coherent::UIGT::UISystem::CreateRenderer ( renoir::RendererBackend backend,
renoir::ClickThroughProvider *  clickThrough 
)
pure virtual

Creates the UI System renderer. All ViewRenderers are created through it so this is mandatory for drawing the Views.

Note
it is safe to call this method from a rendering thread
Parameters
backendthe backend to use when rendering
classto supply methods for UI graphical queries for click-through detection
Returns
the UI System renderer

◆ CreateRenderer() [2/2]

virtual UISystemRenderer* Coherent::UIGT::UISystem::CreateRenderer ( renoir::ClickThroughProvider *  clickThrough)
pure virtual

Creates the UI System renderer. All ViewRenderers are created through it so this is mandatory for drawing the Views. This variant must be used when the UISystem is initialized with an external rendering library.

See also
InitializeUIGTSystemWithRenderingLibrary
Note
it is safe to call this method from a rendering thread
Parameters
classto supply methods for UI graphical queries for click-through detection
Returns
the UI System renderer

◆ CreateView() [1/2]

virtual View* Coherent::UIGT::UISystem::CreateView ( const ViewInfo info,
const char *  url,
ViewLoadPolicy  policy = VLP_UseCacheOrLoad 
)
pure virtual

Creates a new UI View.

Parameters
infoan instance of the ViewInfo struct that describes all the parameters of the view
urlthe page to load when the view is created
policydefines if the View should use cached resources or reload everything from disk/server. The parameter is important during development with the 'coui' protocol. A resource might be modified but still available in the in-memory cache. In that case the View might use the cached version ignoring the cache. It's advisable to ignore the cache if loading a View that is being actively developed. In shipped builds always use the cache as it substantially improves load-speed and resources in shipped titles should be immutable.
Returns
the newly created view

◆ CreateView() [2/2]

virtual View* Coherent::UIGT::UISystem::CreateView ( const ViewInfo info,
const char *  url,
const char *  scriptToExecute,
ViewLoadPolicy  policy = VLP_UseCacheOrLoad 
)
pure virtual

Creates a new UI View.

Parameters
infoan instance of the ViewInfo struct that describes all the parameters of the view
urlthe page to load when the view is created
scriptToExecuteJavaScript code that will be executed on every new page at start
policydefines if the View should use cached resources or reload everything from disk/server. The parameter is important during development with the 'coui' protocol. A resource might be modified but still available in the in-memory cache. In that case the View might use the cached version ignoring the cache. It's advisable to ignore the cache if loading a View that is being actively developed. In shipped builds always use the cache as it substantially improves load-speed and resources in shipped titles should be immutable.
Returns
the newly created view

◆ EnableVerboseNetworkLogging()

virtual void Coherent::UIGT::UISystem::EnableVerboseNetworkLogging ( bool  enable)
pure virtual

Changes the connection setting for verbose network logging.

Parameters
enabletrue when new connections should use VerboseNetworkLogging to log debug netowking information, false otherwise.
Warning
Existing connections will not be affected by this setting.
See also
IsVerboseNetworkLoggingEnabled
Coherent::UIGT::SystemSettings::EnableVerboseNetworkLogging

◆ Fence()

virtual unsigned Coherent::UIGT::UISystem::Fence ( )
pure virtual

Puts a fence in the underlying task queue and returns its id. Does nothing if the system is synchronous.

Returns
the unique id of the fence that can be later passed to Coherent::UIGT::WaitFor.

◆ GetInMemoryResourceCacheUsage()

virtual void Coherent::UIGT::UISystem::GetInMemoryResourceCacheUsage ( unsigned *  usedBytes,
unsigned *  capacity 
) const
pure virtual

Gets the in-memory cache currently used bytes and total capacity. The returned values will only be updated if you have called RequestInMemoryResourceCacheUsage and Advance prior to the call.

Parameters
usedBytesvariable to output the current usage of the cache, in bytes
capacityvariable to output the current capacity of the cache, in bytes
Warning
The values returned are up-to-date only if you have called RequestInMemoryResourceCacheUsage and Advance prior to this call.

◆ HasLastAdvanceCompleted()

virtual bool Coherent::UIGT::UISystem::HasLastAdvanceCompleted ( )
pure virtual

Checks whether the last issued Advance has completed.

Returns
true for a synchronous UI System, or if the last Advance call has completed for an async UI System. Returns false if the last Advance is still being processed in an async UI System and a new call to Advance would block waiting for the last one to complete.

◆ IgnoreSSLCertificateErrors()

virtual void Coherent::UIGT::UISystem::IgnoreSSLCertificateErrors ( bool  ignore)
pure virtual

Sets whether new SSL connections should ignore SSL connection errors.

Parameters
ignoretrue when new connections should ignore SSL errors, false otherwise.
Warning
Existing connections will not be affected by this setting.
You must have already set the certificate authorities bundle when you require verification.
See also
IsIgnoringSSLCertificateErrors
Coherent::UIGT::SystemSettings::IgnoreSSLCertificateErrors

◆ InspectorJSMemoryStatsEnabled()

virtual void Coherent::UIGT::UISystem::InspectorJSMemoryStatsEnabled ( bool  enabled)
pure virtual

Enables/disables JS memory statistics in the inspector Memory stats are disabled by default to save computational resources.

Parameters
enabledsets the JS memory stats to enabled/disabled

◆ IsIgnoringSSLCertificateErrors()

virtual bool Coherent::UIGT::UISystem::IsIgnoringSSLCertificateErrors ( ) const
pure virtual

Gets whether new SSL connections should ignore SSL connection errors.

See also
IgnoreSSLCertificateErrors
Coherent::UIGT::SystemSettings::IgnoreSSLCertificateErrors
Returns
true if new connections will ignore SSL errors, false otherwise

◆ IsVerboseNetworkLoggingEnabled()

virtual bool Coherent::UIGT::UISystem::IsVerboseNetworkLoggingEnabled ( ) const
pure virtual

Returns true if new connections are set to use verbose network logging.

See also
EnableVerboseNetworkLogging
Coherent::UIGT::SystemSettings::EnableVerboseNetworkLogging
Returns
true if new connections will log debug netowking information, false otherwise

◆ LogMemoryUsage()

virtual void Coherent::UIGT::UISystem::LogMemoryUsage ( LogMemoryUsageFlags  flags = LMU_Short)
pure virtual

Logs the current memory usage of components known to hold big chunks of memory. JS heap - responsible for the lifetime of JS objects and exectution of scripts. Resource cache - most of the webpage resources are stored in memory to accelerate reading and avoid frequent disk operations.

Parameters
flagsdetermines which components will be logged

◆ RegisterGamepad()

virtual void Coherent::UIGT::UISystem::RegisterGamepad ( unsigned  id,
const char *  info,
unsigned  axesCount,
unsigned  buttonsCount 
)
pure virtual

Registers a new gamepad. All created views will receive the gamepadconnected event.

Parameters
idthe unique identifier for the gamepad
infogeneral information for the gamepad such as producer and model
axesCountthe number of analog axes the gamepad has
buttonsCountthe number of buttons the gamepad has

◆ RemoveHyphenationDictionary()

virtual void Coherent::UIGT::UISystem::RemoveHyphenationDictionary ( const char *  locale)
pure virtual

Unload hyphenation dictionary for a given locale.

Parameters
localepointer to the locale string which identifies the locale of the dictionary.

◆ ReplaceUserImage()

virtual void Coherent::UIGT::UISystem::ReplaceUserImage ( const ResourceResponseUIGT::UserImageData &  userImage)
pure virtual

Replace an already loaded user image.

This method can be used when you need to replace userImage data, e.g. when you want to resize or replace the texture. The only thing you need to keep unchanged is the ImageHandle it was loaded with.

Parameters
userImageis UserImageData struct describing the image.

◆ RunGarbageCollection()

virtual void Coherent::UIGT::UISystem::RunGarbageCollection ( GarbageCollectMode  mode)
pure virtual

Run garbage collection to free up CPU memory.

This method will invoke a garbage collection run with the specified mode to release unused memory.

Warning
Garbage collection is relatively slow operation so use this method with care and only when you need the to free up CPU memory.
After calling this method, expect the next page load times to be similar to the initial "cold start" times.
Note
This function works best with disabled internal allocator as othewise the freed memory will end up being reused and not returned to the client
Parameters
modedetermines the mode in which the garbage collection runs

◆ SetInMemoryResourceCacheSize()

virtual void Coherent::UIGT::UISystem::SetInMemoryResourceCacheSize ( unsigned int  bytes)
pure virtual

Sets the in-memory cache capacity for loaded resources, such as decoded images, fonts, styles, etc.

Parameters
bytesthe new capacity of the cache, in bytes

◆ Uninitialize()

virtual void Coherent::UIGT::UISystem::Uninitialize ( bool  terminateUIThread = true)
pure virtual

Destroys the UI system.

Parameters
terminateUIThreadwhether to terminate the thread Coherent is running on in async mode. Set it to false if you need to initialize another system during the same application run. This flag is ignored if the system is synchronous.
Warning
the UISystem object is unusable after this call
This method is ALWAYS synchronous

◆ UnregisterGamepad()

virtual void Coherent::UIGT::UISystem::UnregisterGamepad ( unsigned  id)
pure virtual

Unregisters a gamepad. All created views will receive the gamepaddisconnected event.

Parameters
idthe id of the gamepad to unregister

◆ UpdateGamepadState()

virtual void Coherent::UIGT::UISystem::UpdateGamepadState ( const Coherent::UIGT::GamepadState state)
pure virtual

Updates the state of a single gamepad.

Parameters
statenew state of the gamepad
Note
All gamepad-related methods are system-wise. All views will get the new state.

◆ UserImagesChanged()

virtual void Coherent::UIGT::UISystem::UserImagesChanged ( const unsigned *  images,
unsigned  count 
)
pure virtual

Trigger repaint of a user provided texture. Call this whenever the image is changed by logic external to the library. Make sure to have ImageHandle set for such images.

Parameters
imagesarray of image handles - id-s of the user provided images that are changed
countthe number of changed images

◆ WaitFor()

virtual void Coherent::UIGT::UISystem::WaitFor ( unsigned  fence)
pure virtual

Blocks the current thread until the specified fence has finished. Does nothing if the system is synchronous.

Parameters
fencean unique fence id returned by an earlier call to Fence