Loading...
Searching...
No Matches
ImageSourceabstract
#include <Ultralight/ImageSource.h>
Overview
User-defined image source to display custom images on a web-page.
This API allows you to composite your own images into a web-page. This is useful for displaying in-game textures, external image assets, or other custom content.
ImageSource File Format
To use an ImageSource, you must first create an .imgsrc file containing a string identifying the image source. This string will be used to lookup the ImageSource from ImageSourceProvider when it is loaded on a web-page.
The file format is as follows:
IMGSRC-V1
<identifier>
You can use the .imgsrc file anywhere in your web-page that typically accepts an image URL. For example:
<img src="my_custom_image.imgsrc" />
Creating from a GPU Texture
To composite your own GPU texture on a web-page, you should first reserve a texture ID from GPUDriver::NextTextureId() and then create an ImageSource from that texture ID. Next, you should register the ImageSource with ImageSourceProvider using the identifier from the .imgsrc file.
When the image element is drawn on the web-page, the library will draw geometry using the specified texture ID and UV coordinates. You should bind your own texture when the specified texture ID is used.
- Note
- If the GPU renderer is not enabled for the View or pixel data is needed for other purposes, the library will sample the backing bitmap instead.
Creating from a Bitmap
To composite your own bitmap on a web-page, you should create an ImageSource from a Bitmap. Next, you should register the ImageSource with ImageSourceProvider using the identifier from the .imgsrc file.
When the image element is drawn on the web-page, the library will sample this bitmap directly.
Invalidating Images
If you modify the texture or bitmap pixels after creating the ImageSource, you should call ImageSource::Invalidate() to notify the library that the image should be redrawn.
Inheritance diagram for ImageSource:
Static Public Member Functions | |
| static RefPtr< ImageSource > | CreateFromTexture (uint32_t width, uint32_t height, uint32_t texture_id, const Rect &texture_uv, RefPtr< Bitmap > bitmap=nullptr) |
| Create an ImageSource from a GPU texture with optional backing bitmap. | |
| static RefPtr< ImageSource > | CreateFromBitmap (RefPtr< Bitmap > bitmap) |
| Create an ImageSource from a Bitmap. | |
Public Member Functions | |
| virtual uint32_t | width () const =0 |
| Get the width of the image in pixels. | |
| virtual uint32_t | height () const =0 |
| Get the height of the image in pixels. | |
| virtual uint32_t | texture_id () const =0 |
| Get the GPU texture identifier to bind when drawing the quad for this image. | |
| virtual Rect | texture_uv () const =0 |
| Get the UV coordinates of the texture. | |
| virtual RefPtr< Bitmap > | bitmap ()=0 |
| Get the backing bitmap for this image source. | |
| virtual void | Invalidate ()=0 |
| Invalidate the image. | |
| virtual void | AddListener (ImageSourceListener *listener)=0 |
| Add a listener to the image source. | |
| virtual void | RemoveListener (ImageSourceListener *listener)=0 |
| Remove a listener from the image source. | |
| Public Member Functions inherited from RefCounted | |
| virtual void | AddRef () const =0 |
| Increment the reference count (thread-safe). | |
| virtual void | Release () const =0 |
| Decrement the reference count (thread-safe). | |
| virtual int | ref_count () const =0 |
| Get the current reference count. | |
| virtual WeakControlBlock * | weak_control_block () const |
| Get the control block used to track weak references to this object. | |
Protected Member Functions | |
| ImageSource ()=default | |
| virtual | ~ImageSource ()=default |
| ImageSource (const ImageSource &)=delete | |
| void | operator= (const ImageSource &)=delete |
| Protected Member Functions inherited from RefCounted | |
| virtual | ~RefCounted () |
Constructor & Destructor Documentation
◆ ImageSource() [1/2]
|
protecteddefault |
◆ ~ImageSource()
|
protectedvirtualdefault |
◆ ImageSource() [2/2]
|
protecteddelete |
Member Function Documentation
◆ AddListener()
|
pure virtual |
Add a listener to the image source.
- Parameters
-
listener The listener to add.
◆ bitmap()
◆ CreateFromBitmap()
|
static |
Create an ImageSource from a Bitmap.
- Parameters
-
bitmap The backing bitmap for this image source.
- Returns
- A new ImageSource instance.
◆ CreateFromTexture()
|
static |
Create an ImageSource from a GPU texture with optional backing bitmap.
- Parameters
-
width The width of the image in pixels (used for layout). height The height of the image in pixels (used for layout). texture_id The GPU texture identifier to bind when drawing the quad for this image. This should be non-zero and obtained from GPUDriver::NextTextureId(). texture_uv The UV coordinates of the texture. bitmap Optional backing bitmap for this image source. This is used when drawing the image using the CPU renderer or when pixel data is needed for other purposes. You should update this bitmap when the texture changes.
- Returns
- A new ImageSource instance.
◆ height()
|
pure virtual |
Get the height of the image in pixels.
◆ Invalidate()
|
pure virtual |
Invalidate the image.
This will notify the library that the image has changed and should be redrawn.
◆ operator=()
|
protecteddelete |
◆ RemoveListener()
|
pure virtual |
Remove a listener from the image source.
- Parameters
-
listener The listener to remove.
◆ texture_id()
|
pure virtual |
Get the GPU texture identifier to bind when drawing the quad for this image.
- Note
- This will be zero (0) if the image source was created from a bitmap.
◆ texture_uv()
|
pure virtual |
Get the UV coordinates of the texture.
◆ width()
|
pure virtual |
Get the width of the image in pixels.
The documentation for this class was generated from the following file:
- Ultralight/ImageSource.h