CAPI_Surface.h File Reference

Go to the source code of this file.

Data Structures
struct	ULSurfaceDefinition

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.