Surface

#include <Ultralight/platform/Surface.h>

Overview

User-defined pixel buffer surface.

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

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 View::surface().

Precondition

This is automatically managed for you when using App::Create(), if you want to override Surface or SurfaceFactory, you'll need to use Renderer::Create() instead.

Default Implementation

A default Surface implementation, BitmapSurface, is automatically provided by the library when you call Renderer::Create() without defining a custom SurfaceFactory.

You should cast the Surface to a BitmapSurface to access the underlying Bitmap.

Setting the Surface Implementation

To define your own implementation, you should inherit from this class, handle the virtual member functions, and then define a custom SurfaceFactory that creates/destroys an instance of your class.

After that, you should pass an instance of your custom SurfaceFactory class to Platform::set_surface_factory() before calling Renderer::Create().

Inheritance diagram for Surface:

Public Member Functions
virtual	~Surface ()
virtual uint32_t	width () const =0
	Width (in pixels).
virtual uint32_t	height () const =0
	Height (in pixels).
virtual uint32_t	row_bytes () const =0
	Number of bytes between rows (usually width * 4)
virtual size_t	size () const =0
	Size in bytes.
virtual void *	LockPixels ()=0
	Lock the pixel buffer and get a pointer to the beginning of the data for reading/writing.
virtual void	UnlockPixels ()=0
	Unlock the pixel buffer.
virtual void	Resize (uint32_t width, uint32_t height)=0
	Resize the pixel buffer to a certain width and height (both in pixels).
virtual void	set_dirty_bounds (const IntRect &bounds)
	Set the dirty bounds to a certain value.
virtual IntRect	dirty_bounds () const
	Get the dirty bounds.
virtual void	ClearDirtyBounds ()
	Clear the dirty bounds.

Protected Member Functions
	Surface ()

Protected Attributes
IntRect	dirty_bounds_

Constructor & Destructor Documentation

~Surface()

virtual ~Surface ( )

virtual

Surface()

Surface ( )

protected

Member Function Documentation

ClearDirtyBounds()

virtual void ClearDirtyBounds ( )

virtual

Clear the dirty bounds.

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

dirty_bounds()

virtual IntRect dirty_bounds ( ) const

virtual

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

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

  if (!surface.dirty_bounds().IsEmpty()) {
      // 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:
      surface.ClearDirtyBounds();
 }
 

height()

virtual uint32_t height ( ) const

pure virtual

Height (in pixels).

Implemented in BitmapSurface.

LockPixels()

virtual void * LockPixels ( )

pure virtual

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

Note

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

Implemented in BitmapSurface.

Resize()

virtual void Resize ( uint32_t width, uint32_t height )

pure virtual

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

This should never be called while pixels are locked.

Implemented in BitmapSurface.

row_bytes()

virtual uint32_t row_bytes ( ) const

pure virtual

Number of bytes between rows (usually width * 4)

Implemented in BitmapSurface.

set_dirty_bounds()

virtual void set_dirty_bounds ( const IntRect & bounds )

virtual

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

size()

virtual size_t size ( ) const

pure virtual

Size in bytes.

Implemented in BitmapSurface.

UnlockPixels()

virtual void UnlockPixels ( )

pure virtual

Unlock the pixel buffer.

Implemented in BitmapSurface.

width()

virtual uint32_t width ( ) const

pure virtual

Width (in pixels).

Implemented in BitmapSurface.

Member Data Documentation

dirty_bounds_

IntRect dirty_bounds_

protected

---

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

• Ultralight/platform/Surface.h