Overview

SharedImages folder

Image preloading is a feature of Gameface that allows developers to use textures loaded on the GPU for their UI. Image preloading also allows to specify content rectangle where the actual image is. This can be used if the image has padding or is part of a texture atlas.

This lets you achieve the following use cases:

Improve the loading time of pages by preparing the textures in advance instead loading them on request.
Reduce memory footprint when the engine and the UI share textures, by having the texture stored in GPU memory only once, instead of twice (once for the engine and once for Gameface).
Use custom image formats.
Make use of Unity's texture compressing to save space and memory.

Note: Gameface expects all textures to have premultiplied alpha, keep that in mind when loading the images.

How To Use

All images that are going to be used as preloaded must be located at the root level of
```
Assets/Resources/Cohtml/SharedImages/
```
The Gameface resource handler will search this path first when an image is requested. Unity will ensure that any textures found in that folder are loaded and they will be shared for use with Gameface.
Proper URL format:
- coui://preloaded/ prefix
- without image extension.
- at the root of the folder Assets/Resources/Cohtml/SharedImages/.

Note: When the image doesn't have prefix coui://preloaded/ Gameface will trying to find the image by image extension only.

Preloaded Images HTML Example

<!DOCTYPE html>
<head>
</head>
<body>
    <img src="coui://preloaded/my_image_name">
</body>
</html>

Note: This example would only work if my_image_name.png exists inside the SharedImages folder.

Lifetime of preloaded resources

Note: References to the preloaded resources will be released after they are not referenced anymore by any HTML element or JS object. Removing an element which is using a preloaded resource from the DOM tree does not mean that the reference to the resource will be released immediately.

Reference flow when using preloaded resources as background-image:

Create an element with a style which has preloaded resource for a background-image.
When the element's style is evaluated, the style will add a reference to the resource.
The reference will be removed when:
- The background-image in the element's style is changed.
- The style of the element is removed or the whole element is removed from the DOM tree.

Note: Elements which are detached from the tree does not have styles.

Lifetime flow in <img>:

Create <img> element with a preloaded resource specified by the src attribute.
The element will add a reference to the resource.
The reference will be removed when:
- The src attribute is changed.
- The Garbage Collector destroys the element.

Note: Non-user images work the same way, but they are cached internally by our SDK. They are going to be freed when the cache reaches the configured thresholds.