CAPI_Surface.h File Reference

Overview

User-defined pixel buffer surface.

#include <Ultralight/CAPI/CAPI_Surface.h>

The library uses this to store pixel data when rendering Views on the CPU (see ulViewIsAccelerated()).

You can provide the library with your own Surface implementation to reduce the latency of displaying pixels in your application (Views will be drawn directly to a block of memory controlled by you).

When a View is rendered on the CPU, you can retrieve the backing Surface via ulViewGetSurface().

Precondition

This is automatically managed for you when using ulCreateApp(), if you want to override ULSurfaceDefinition, you'll need to use ulCreateRenderer() instead.

Default Implementation

A default Surface implementation, BitmapSurface, is automatically provided by the library when you call ulCreateRenderer() without defining a custom ULSurfaceDefinition.

You should cast the ULSurface to a ULBitmapSurface and call ulBitmapSurfaceGetBitmap() to access the underlying Bitmap.

Setting the Surface Implementation

To define your own implementation, you should implement the ULSurfaceDefinition callbacks, and then pass an instance of ULSurfaceDefinition containing your callbacks to ulPlatformSetSurfaceDefinition() before calling ulCreateRenderer().

Classes
struct	ULSurfaceDefinition
	User-defined surface interface. More...

Functions
ULExport unsigned int	ulSurfaceGetWidth (ULSurface surface)
	Width (in pixels).
ULExport unsigned int	ulSurfaceGetHeight (ULSurface surface)
	Height (in pixels).
ULExport unsigned int	ulSurfaceGetRowBytes (ULSurface surface)
	Number of bytes between rows (usually width * 4)
ULExport size_t	ulSurfaceGetSize (ULSurface surface)
	Size in bytes.
ULExport void *	ulSurfaceLockPixels (ULSurface surface)
	Lock the pixel buffer and get a pointer to the beginning of the data for reading/writing.
ULExport void	ulSurfaceUnlockPixels (ULSurface surface)
	Unlock the pixel buffer.
ULExport void	ulSurfaceResize (ULSurface surface, unsigned int width, unsigned int height)
	Resize the pixel buffer to a certain width and height (both in pixels).
ULExport void	ulSurfaceSetDirtyBounds (ULSurface surface, ULIntRect bounds)
	Set the dirty bounds to a certain value.
ULExport ULIntRect	ulSurfaceGetDirtyBounds (ULSurface surface)
	Get the dirty bounds.
ULExport void	ulSurfaceClearDirtyBounds (ULSurface surface)
	Clear the dirty bounds.
ULExport void *	ulSurfaceGetUserData (ULSurface surface)
	Get the underlying user data pointer (this is only valid if you have set a custom surface implementation via ulPlatformSetSurfaceDefinition).
ULExport ULBitmap	ulBitmapSurfaceGetBitmap (ULBitmapSurface surface)
	Get the underlying Bitmap from the default Surface.

Typedefs
typedef void *(*	ULSurfaceDefinitionCreateCallback) (unsigned int width, unsigned int height)
	The callback invoked when a Surface is created.
typedef void(*	ULSurfaceDefinitionDestroyCallback) (void *user_data)
	The callback invoked when a Surface is destroyed.
typedef unsigned int(*	ULSurfaceDefinitionGetWidthCallback) (void *user_data)
	The callback invoked when a Surface's width (in pixels) is requested.
typedef unsigned int(*	ULSurfaceDefinitionGetHeightCallback) (void *user_data)
	The callback invoked when a Surface's height (in pixels) is requested.
typedef unsigned int(*	ULSurfaceDefinitionGetRowBytesCallback) (void *user_data)
	The callback invoked when a Surface's row bytes is requested.
typedef size_t(*	ULSurfaceDefinitionGetSizeCallback) (void *user_data)
	The callback invoked when a Surface's size (in bytes) is requested.
typedef void *(*	ULSurfaceDefinitionLockPixelsCallback) (void *user_data)
	The callback invoked when a Surface's pixel buffer is requested to be locked for reading/writing (should return a pointer to locked bytes).
typedef void(*	ULSurfaceDefinitionUnlockPixelsCallback) (void *user_data)
	The callback invoked when a Surface's pixel buffer is requested to be unlocked after previously being locked.
typedef void(*	ULSurfaceDefinitionResizeCallback) (void *user_data, unsigned int width, unsigned int height)
	The callback invoked when a Surface is requested to be resized to a certain width/height.

Function Documentation

ulBitmapSurfaceGetBitmap()

ULExport ULBitmap ulBitmapSurfaceGetBitmap

(

ULBitmapSurface

surface

)

Get the underlying Bitmap from the default Surface.

Note

Do not call ulDestroyBitmap() on the returned value, it is owned by the surface.

ulSurfaceClearDirtyBounds()

ULExport void ulSurfaceClearDirtyBounds

(

ULSurface

surface

)

Clear the dirty bounds.

You should call this after you're done displaying the Surface.

ulSurfaceGetDirtyBounds()

ULExport ULIntRect ulSurfaceGetDirtyBounds

(

ULSurface

surface

)

Get the dirty bounds.

This value can be used to determine which portion of the pixel buffer has been updated since the last call to ulSurfaceClearDirtyBounds().

The general algorithm to determine if a Surface needs display is:

  if (!ulIntRectIsEmpty(ulSurfaceGetDirtyBounds(surface))) {
      // Surface pixels are dirty and needs display.
      // Cast Surface to native Surface and use it here (pseudo code)
      DisplaySurface(surface);

      // Once you're done, clear the dirty bounds:
      ulSurfaceClearDirtyBounds(surface);
 }
 

ulSurfaceGetHeight()

ULExport unsigned int ulSurfaceGetHeight

(

ULSurface

surface

)

Height (in pixels).

ulSurfaceGetRowBytes()

ULExport unsigned int ulSurfaceGetRowBytes

(

ULSurface

surface

)

Number of bytes between rows (usually width * 4)

ulSurfaceGetSize()

ULExport size_t ulSurfaceGetSize

(

ULSurface

surface

)

Size in bytes.

ulSurfaceGetUserData()

ULExport void * ulSurfaceGetUserData

(

ULSurface

surface

)

Get the underlying user data pointer (this is only valid if you have set a custom surface implementation via ulPlatformSetSurfaceDefinition).

This will return nullptr if this surface is the default ULBitmapSurface.

ulSurfaceGetWidth()

ULExport unsigned int ulSurfaceGetWidth

(

ULSurface

surface

)

Width (in pixels).

ulSurfaceLockPixels()

ULExport void * ulSurfaceLockPixels

(

ULSurface

surface

)

Lock the pixel buffer and get a pointer to the beginning of the data for reading/writing.

Native pixel format is premultiplied BGRA 32-bit (8 bits per channel).

ulSurfaceResize()

ULExport void ulSurfaceResize	(	ULSurface	surface,
		unsigned int	width,
		unsigned int	height )

Resize the pixel buffer to a certain width and height (both in pixels).

This should never be called while pixels are locked.

ulSurfaceSetDirtyBounds()

ULExport void ulSurfaceSetDirtyBounds	(	ULSurface	surface,
		ULIntRect	bounds )

Set the dirty bounds to a certain value.

This is called after the Renderer paints to an area of the pixel buffer. (The new value will be joined with the existing dirty_bounds())

ulSurfaceUnlockPixels()

ULExport void ulSurfaceUnlockPixels

(

ULSurface

surface

)

Unlock the pixel buffer.

Typedef Documentation

ULSurfaceDefinitionCreateCallback

typedef void *(* ULSurfaceDefinitionCreateCallback) (unsigned int width, unsigned int height)

The callback invoked when a Surface is created.

Parameters

width	The width in pixels.
height	The height in pixels.

Returns

This callback should return a pointer to user-defined data for the instance. This user data pointer will be passed to all other callbacks when operating on the instance.

ULSurfaceDefinitionDestroyCallback

typedef void(* ULSurfaceDefinitionDestroyCallback) (void *user_data)

The callback invoked when a Surface is destroyed.

Parameters

user_data

User data pointer uniquely identifying the surface.

ULSurfaceDefinitionGetHeightCallback

typedef unsigned int(* ULSurfaceDefinitionGetHeightCallback) (void *user_data)

The callback invoked when a Surface's height (in pixels) is requested.

Parameters

user_data

User data pointer uniquely identifying the surface.

ULSurfaceDefinitionGetRowBytesCallback

typedef unsigned int(* ULSurfaceDefinitionGetRowBytesCallback) (void *user_data)

The callback invoked when a Surface's row bytes is requested.

Note

This value is also known as "stride". Usually width * 4.

Parameters

user_data

User data pointer uniquely identifying the surface.

ULSurfaceDefinitionGetSizeCallback

typedef size_t(* ULSurfaceDefinitionGetSizeCallback) (void *user_data)

The callback invoked when a Surface's size (in bytes) is requested.

Parameters

user_data

User data pointer uniquely identifying the surface.

ULSurfaceDefinitionGetWidthCallback

typedef unsigned int(* ULSurfaceDefinitionGetWidthCallback) (void *user_data)

The callback invoked when a Surface's width (in pixels) is requested.

Parameters

user_data

User data pointer uniquely identifying the surface.

ULSurfaceDefinitionLockPixelsCallback

typedef void *(* ULSurfaceDefinitionLockPixelsCallback) (void *user_data)

The callback invoked when a Surface's pixel buffer is requested to be locked for reading/writing (should return a pointer to locked bytes).

Parameters

user_data

User data pointer uniquely identifying the surface.

ULSurfaceDefinitionResizeCallback

typedef void(* ULSurfaceDefinitionResizeCallback) (void *user_data, unsigned int width, unsigned int height)

The callback invoked when a Surface is requested to be resized to a certain width/height.

Parameters

user_data	User data pointer uniquely identifying the surface.
width	Width in pixels.
height	Height in pixels.

ULSurfaceDefinitionUnlockPixelsCallback

typedef void(* ULSurfaceDefinitionUnlockPixelsCallback) (void *user_data)

The callback invoked when a Surface's pixel buffer is requested to be unlocked after previously being locked.

Parameters

user_data

User data pointer uniquely identifying the surface.

Go to the source code of this file.