ImageSource

#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
virtual void	Release () const =0
virtual int	ref_count () const =0

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]

ImageSource ( )

protecteddefault

~ImageSource()

virtual ~ImageSource ( )

protectedvirtualdefault

ImageSource() [2/2]

ImageSource ( const ImageSource & )

protecteddelete

Member Function Documentation

AddListener()

virtual void AddListener ( ImageSourceListener * listener )

pure virtual

Add a listener to the image source.

Parameters

listener

The listener to add.

bitmap()

virtual RefPtr< Bitmap > bitmap ( )

pure virtual

Get the backing bitmap for this image source.

CreateFromBitmap()

static RefPtr< ImageSource > CreateFromBitmap ( RefPtr< Bitmap > bitmap )

static

Create an ImageSource from a Bitmap.

Parameters

bitmap

The backing bitmap for this image source.

Returns

A new ImageSource instance.

CreateFromTexture()

static RefPtr< ImageSource > CreateFromTexture ( uint32_t width, uint32_t height, uint32_t texture_id, const Rect & texture_uv, RefPtr< Bitmap > bitmap = nullptr )

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

virtual uint32_t height ( ) const

pure virtual

Get the height of the image in pixels.

Invalidate()

virtual void Invalidate ( )

pure virtual

Invalidate the image.

This will notify the library that the image has changed and should be redrawn.

operator=()

void operator= ( const ImageSource & )

protecteddelete

RemoveListener()

virtual void RemoveListener ( ImageSourceListener * listener )

pure virtual

Remove a listener from the image source.

Parameters

listener

The listener to remove.

texture_id()

virtual uint32_t texture_id ( ) const

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

virtual Rect texture_uv ( ) const

pure virtual

Get the UV coordinates of the texture.

width()

virtual uint32_t width ( ) const

pure virtual

Get the width of the image in pixels.

---

The documentation for this class was generated from the following file:

• Ultralight/ImageSource.h