CAPI_ImageSource.h File Reference

Overview

User-defined image source to display custom images on a web-page.

#include <Ultralight/CAPI/CAPI_ImageSource.h>

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 ULGPUDriver::next_texture_id 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.

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 after creating the ImageSource, you should call ulImageSourceInvalidate() to notify the library that the image should be redrawn.

Functions
ULExport ULImageSource	ulCreateImageSourceFromTexture (unsigned int width, unsigned int height, unsigned int texture_id, ULRect texture_uv, ULBitmap bitmap)
	Create an image source from a GPU texture with optional backing bitmap.
ULExport ULImageSource	ulCreateImageSourceFromBitmap (ULBitmap bitmap)
	Create an image source from a bitmap.
ULExport void	ulDestroyImageSource (ULImageSource image_source)
	Destroy an image source.
ULExport void	ulImageSourceInvalidate (ULImageSource image_source)
	Invalidate the image source, notifying the library that the image has changed and should be redrawn.
ULExport void	ulImageSourceProviderAddImageSource (ULString id, ULImageSource image_source)
	Add an image source to the provider.
ULExport void	ulImageSourceProviderRemoveImageSource (ULString id)
	Remove an image source from the provider.

Function Documentation

ulCreateImageSourceFromBitmap()

ULExport ULImageSource ulCreateImageSourceFromBitmap

(

ULBitmap

bitmap

)

Create an image source from a bitmap.

Parameters

bitmap

The backing bitmap for this image source.

Returns

A new image source instance.

ulCreateImageSourceFromTexture()

ULExport ULImageSource ulCreateImageSourceFromTexture	(	unsigned int	width,
		unsigned int	height,
		unsigned int	texture_id,
		ULRect	texture_uv,
		ULBitmap	bitmap )

Create an image source 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 ULGPUDriver::next_texture_id.
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 image source instance.

ulDestroyImageSource()

ULExport void ulDestroyImageSource

(

ULImageSource

image_source

)

Destroy an image source.

Parameters

image_source

The image source to destroy.

ulImageSourceInvalidate()

ULExport void ulImageSourceInvalidate

(

ULImageSource

image_source

)

Invalidate the image source, notifying the library that the image has changed and should be redrawn.

ulImageSourceProviderAddImageSource()

ULExport void ulImageSourceProviderAddImageSource	(	ULString	id,
		ULImageSource	image_source )

Add an image source to the provider.

Parameters

id	The identifier of the image source.
image_source	The image source to add.

ulImageSourceProviderRemoveImageSource()

ULExport void ulImageSourceProviderRemoveImageSource

(

ULString

id

)

Remove an image source from the provider.

Parameters

id	The identifier of the image source.

Go to the source code of this file.