1.17.0.1
Prysm
cohtml::System Class Referenceabstract

A System owns multiple Views. These Views share resources among them. It is usually enough to have just one System per application run. More...

Public Member Functions

virtual unsigned GetId ()=0
 
virtual void SetId (unsigned id)=0
 
virtual ~System ()
 
virtual ViewCreateView (const ViewSettings &settings)=0
 Creates a new View with the specified options. More...
 
virtual SystemCacheStatsGetSystemCacheStats () const =0
 Returns an objects that holds the current statistics of the system-wide caches. Remember to Release when done. More...
 
virtual void ClearCachedUnusedImages ()=0
 Removes all unused images (raster and svg) from internal caches. More...
 
virtual SystemRendererCreateSystemRenderer (const SystemRendererSettings &settings)=0
 Creates a new SystemRenderer. The SystemRenderer will hold rendering resources shared by all view renderers. More...
 
virtual SystemRendererCreateSystemRendererWithExternalRenderingLibrary (const SystemRendererSettingsWithExternalRenderingLibrary &settings)=0
 Creates a new SystemRenderer. The SystemRenderer will hold rendering resources shared by all view renderers. More...
 
virtual void AddFontsFromFolder_DEPRECATED (const char *path)=0
 Loads all fonts from the specified folder. The fonts can later be used in the Views Prefer using the RegisterFont API for better control over the loaded fonts. More...
 
virtual void RegisterFont (const char *url, const FontDescription &desc=FontDescription(), Fonts::FontSDF useSDF=Fonts::SDF_Auto)=0
 Registers a font that can be later used in the Views. This API is similar to a font-face rule and allows you to prepare font stream readers in advance, so that text can render without delays. Unlike the font-face rule, this API also allows you to load the font with its original description (using 'Auto' for weight or/and style with or without specifying specific family name for it). This API will load all available fonts from font collections (ttc, otc) when a specific font description isn't provided (use 'Auto' without family name). If any description is specified for a font collection, only the first font will be loaded under that description (same behavior as a font-face rule with font collection). More...
 
virtual void AddUserFont (const char **imagesData, unsigned *imagesDataSize, unsigned imagesCount, const UserFontDescription &description)=0
 Load the user font using image files. More...
 
virtual void AddUserFont (const IAsyncResourceResponse::UserImageData *userImages, unsigned imagesCount, const UserFontDescription &description)=0
 Load the user font using preloaded images. More...
 
virtual void SetDefaultFallbackFontName_DEPRECATED (const char *name)=0
 Loads font with given name from folders specified by AddFontsFromFolder. This font will be used when the another fond cannot be loaded or found as a default one. This font is a fallback if the font name used in a Style property is not found. If you want to change the default font that will be applied to all elements, you should change the value in LibraryParams::DefaultStyleFontFamily. More...
 
virtual void Destroy ()=0
 Destroys the System. More...
 
virtual void Advance (TimePoint timeMilliseconds)=0
 Advances the internal timers and inspector when available. More...
 
virtual void RegisterGamepad (unsigned id, const char *info, unsigned axesCount, unsigned buttonsCount, void *reserved=nullptr)=0
 Registers a new gamepad. All views will receive the gamepadconnected event. You can provide any number of axes and buttons though the standard mapping according to the HTML spec has 4 axes and 17 buttons which can be found here https://w3c.github.io/gamepad/#remapping. More...
 
virtual void UnregisterGamepad (unsigned id)=0
 Unregisters a gamepad. All views will receive the gamepaddisconnected event. More...
 
virtual void UpdateGamepadState (const cohtml::GamepadState &state)=0
 Updates the state of a single gamepad. More...
 
virtual void UpdateGamepadStateExtended (const cohtml::GamepadStateExtended &state)=0
 Updates the state of a single gamepad with motion tracking information. 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 PreloadAndCacheStylesheet (const char *url)=0
 Schedules a preload task for a given stylesheet and caches it upon successful parsing. More...
 
virtual bool RemoveStylesheetCacheEntry (const char *url)=0
 Clears data for a given stylesheet from the cache. More...
 
virtual void ClearStylesheetCache ()=0
 Clears all preloaded stylesheet data from the cache. More...
 
virtual void PreloadAndCacheHTML (const char *url)=0
 Schedules a preload task for a given HTML, parses it, and caches it. More...
 
virtual bool RemoveHTMLCacheEntry (const char *url)=0
 Clears data for a given HTML from the cache. More...
 
virtual void ClearHTMLCache ()=0
 Clears all preloaded HTML data from the cache. More...
 

Detailed Description

A System owns multiple Views. These Views share resources among them. It is usually enough to have just one System per application run.

Constructor & Destructor Documentation

◆ ~System()

virtual cohtml::System::~System ( )
virtual

Member Function Documentation

◆ AddFontsFromFolder_DEPRECATED()

virtual void cohtml::System::AddFontsFromFolder_DEPRECATED ( const char *  path)
pure virtual

Loads all fonts from the specified folder. The fonts can later be used in the Views Prefer using the RegisterFont API for better control over the loaded fonts.

Parameters
paththe name of the folder
Note
Requires a valid IFileSystemReader for enumerating the folder.
Warning
This API is deprecated. Use font-face rules or RegisterFont API to load/preload fonts

◆ AddUserFont() [1/2]

virtual void cohtml::System::AddUserFont ( const char **  imagesData,
unsigned *  imagesDataSize,
unsigned  imagesCount,
const UserFontDescription description 
)
pure virtual

Load the user font using image files.

Note
The memory can be freed immediately after the call
Images must have the appropriate number of channels Bitmap: 1-channel(A) texture MSDF: 3-channel(RGB) texture
Parameters
imagesDatapointer to image files data.
imagesDataSizepointer to size of the image files.
imagesCountnumber of images
descriptionDescription of the bitmap font.

◆ AddUserFont() [2/2]

virtual void cohtml::System::AddUserFont ( const IAsyncResourceResponse::UserImageData userImages,
unsigned  imagesCount,
const UserFontDescription description 
)
pure virtual

Load the user font using preloaded images.

Note
After freeing the rendering resources you can call this method again in order to provide new images for the same bitmap font description.
The memory can be freed immediately after the call
Images must have the appropriate number of channels Bitmap: 1-channel(A) texture MSDF: 3-channel(RGB) texture
Parameters
userImagespointer to UserImageData structs describing the images.
imagesCountnumber of images
descriptionDescription of the bitmap font.

◆ Advance()

virtual void cohtml::System::Advance ( TimePoint  timeMilliseconds)
pure virtual

Advances the internal timers and inspector when available.

◆ ClearCachedUnusedImages()

virtual void cohtml::System::ClearCachedUnusedImages ( )
pure virtual

Removes all unused images (raster and svg) from internal caches.

Note
Images must be unused (orphaned) for them to be cleared. If you want to force ALL images to be unloaded you need for first call View::UnloadDocument to remove any references the DOM might still hold to the images.

◆ ClearHTMLCache()

virtual void cohtml::System::ClearHTMLCache ( )
pure virtual

Clears all preloaded HTML data from the cache.

Note
Removing HTML from cache that is currently in use by a view won't free HTML data immediately,
data will be freed after the View finishes DOM building, even if the HTML is not loaded yet.

◆ ClearStylesheetCache()

virtual void cohtml::System::ClearStylesheetCache ( )
pure virtual

Clears all preloaded stylesheet data from the cache.

Note
If a stylesheet that is currently in use by a view is cleared, it won't affect the view
but a resource request will be fired the next time it is needed

◆ CreateSystemRenderer()

virtual SystemRenderer* cohtml::System::CreateSystemRenderer ( const SystemRendererSettings settings)
pure virtual

Creates a new SystemRenderer. The SystemRenderer will hold rendering resources shared by all view renderers.

◆ CreateSystemRendererWithExternalRenderingLibrary()

virtual SystemRenderer* cohtml::System::CreateSystemRendererWithExternalRenderingLibrary ( const SystemRendererSettingsWithExternalRenderingLibrary settings)
pure virtual

Creates a new SystemRenderer. The SystemRenderer will hold rendering resources shared by all view renderers.

Note
Use this version when the Library is initialized with an external rendering library.
See also
cohtml::Library::InitializeWithRenderingLibrary

◆ CreateView()

virtual View* cohtml::System::CreateView ( const ViewSettings settings)
pure virtual

Creates a new View with the specified options.

◆ Destroy()

virtual void cohtml::System::Destroy ( )
pure virtual

Destroys the System.

◆ GetId()

virtual unsigned cohtml::System::GetId ( )
pure virtual

◆ GetSystemCacheStats()

virtual SystemCacheStats* cohtml::System::GetSystemCacheStats ( ) const
pure virtual

Returns an objects that holds the current statistics of the system-wide caches. Remember to Release when done.

◆ PreloadAndCacheHTML()

virtual void cohtml::System::PreloadAndCacheHTML ( const char *  url)
pure virtual

Schedules a preload task for a given HTML, parses it, and caches it.

Parameters
urlA URL for the HTML to be preloaded and cached. Must be a valid absolute URL. Spaces aren't allowed.
Note
The HTML cache is shared among all views

◆ PreloadAndCacheStylesheet()

virtual void cohtml::System::PreloadAndCacheStylesheet ( const char *  url)
pure virtual

Schedules a preload task for a given stylesheet and caches it upon successful parsing.

Parameters
urlA URL for the stylesheet to be preloaded and cached. Must be a valid URL. Spaces aren't allowed.
Note
The stylesheet cache is shared among all views

◆ RegisterFont()

virtual void cohtml::System::RegisterFont ( const char *  url,
const FontDescription desc = FontDescription(),
Fonts::FontSDF  useSDF = Fonts::SDF_Auto 
)
pure virtual

Registers a font that can be later used in the Views. This API is similar to a font-face rule and allows you to prepare font stream readers in advance, so that text can render without delays. Unlike the font-face rule, this API also allows you to load the font with its original description (using 'Auto' for weight or/and style with or without specifying specific family name for it). This API will load all available fonts from font collections (ttc, otc) when a specific font description isn't provided (use 'Auto' without family name). If any description is specified for a font collection, only the first font will be loaded under that description (same behavior as a font-face rule with font collection).

Parameters
urlURL for the font to be loaded. Must be a valid URL. Spaces aren't allowed.
descThe description of the font to be loaded
useSDFControls the method used when rendering fonts, same as the coh-font-sdf font-face property SDF reduces memory consumption but finer font details are lost. If you experience a loss of detail in font rendering, try turning SDF off.

◆ RegisterGamepad()

virtual void cohtml::System::RegisterGamepad ( unsigned  id,
const char *  info,
unsigned  axesCount,
unsigned  buttonsCount,
void *  reserved = nullptr 
)
pure virtual

Registers a new gamepad. All views will receive the gamepadconnected event. You can provide any number of axes and buttons though the standard mapping according to the HTML spec has 4 axes and 17 buttons which can be found here https://w3c.github.io/gamepad/#remapping.

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
reservedreserved parameter. Set to nullptr

◆ RemoveHTMLCacheEntry()

virtual bool cohtml::System::RemoveHTMLCacheEntry ( const char *  url)
pure virtual

Clears data for a given HTML from the cache.

Parameters
urlThe URL for the HTML to be cleared from the cache. Must be the same URL used for its preloading.
Returns
true, if the cache entry corresponding to the given URL was found and cleared successfully
Note
Removing HTML from cache that is currently in use by a view won't free HTML data immediately,
data will be freed after the View finishes DOM building, even if the HTML is not loaded yet.

◆ RemoveStylesheetCacheEntry()

virtual bool cohtml::System::RemoveStylesheetCacheEntry ( const char *  url)
pure virtual

Clears data for a given stylesheet from the cache.

Parameters
urlThe URL for the stylesheet to be cleared from cache. Must be the same URL used for its preloading.
Returns
true, if the cache entry corresponding to the given URL was found and cleared successfully
Note
If a stylesheet that is currently in use by a view is cleared, it won't affect the view
but a resource request will be fired the next time it is needed

◆ SetDefaultFallbackFontName_DEPRECATED()

virtual void cohtml::System::SetDefaultFallbackFontName_DEPRECATED ( const char *  name)
pure virtual

Loads font with given name from folders specified by AddFontsFromFolder. This font will be used when the another fond cannot be loaded or found as a default one. This font is a fallback if the font name used in a Style property is not found. If you want to change the default font that will be applied to all elements, you should change the value in LibraryParams::DefaultStyleFontFamily.

Parameters
namename of the font to load as default fallback
Note
This should be called after AddFontsFromFolder
Warning
This function is deprecated and about to be removed. Cohtml now uses an embedded fallback font.

◆ SetId()

virtual void cohtml::System::SetId ( unsigned  id)
pure virtual

◆ UnregisterGamepad()

virtual void cohtml::System::UnregisterGamepad ( unsigned  id)
pure virtual

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

Parameters
idthe id of the gamepad to unregister

◆ UpdateGamepadState()

virtual void cohtml::System::UpdateGamepadState ( const cohtml::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.

◆ UpdateGamepadStateExtended()

virtual void cohtml::System::UpdateGamepadStateExtended ( const cohtml::GamepadStateExtended state)
pure virtual

Updates the state of a single gamepad with motion tracking information.

Parameters
statenew state of the gamepad
Note
All gamepad-related methods are system-wise. All views will get the new state.
If you do not require motion tracking, use System::UpdateGamepadState

◆ UserImagesChanged()

virtual void cohtml::System::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