CeresEngine::UIWindowDevice Class Reference

The UIWindow::Device is the backing device for one or multiple windows. More...

#include <CeresEngine/UI/UIWindowDevice.hpp>

Inheritance diagram for CeresEngine::UIWindowDevice:

Public Member Functions
	UIWindowDevice () noexcept=default
virtual	~UIWindowDevice () noexcept=default
virtual void	draw (UIBackingStore &backingStore, UIDrawCommandBuffer &commandBuffer)
	Draws the UI command buffer into the backing store.
virtual void	flush (UIWindow &window, UIBackingStore &backingStore)
	Flushes the contents of the window to the backing device.
virtual UIBackingStorePtr	createBackingStore (UIWindow &window)=0
	Creates a new backing store for the window or a view that belongs to the window.
virtual double	getBackingScaleFactor (const UIWindow &window) const
	The backing scale factor.
virtual UIBackingStorePtr	registerWindow (UIWindow &window)
	Registers a window with this device.
virtual void	unregisterWindow (UIWindow &window)
	Unregisters the window from this device.
Public Member Functions inherited from CeresEngine::RefCounted< UIWindowDevice >
	RefCounted (Args &&... args)
	Creates a new RefCounted object and constructs a new Deleter by forwarding Args to it.
void	retain () noexcept
	Retains the object by increment it's reference count by one.
bool	release () noexcept
	Relases the object by decrementing it's reference count by one.

Protected Member Functions
void	notifyFrameChanged (UIWindow &window, const UIRect &newFrame)
	Utility method that must be called by device implementations when the window frame changes.
void	notifyBackingScaleFactorChange (UIWindow &window, double newBackingScalingFactor)
	Utility method that must be called by device implementations when the window scaling factor changes.

Friends
class	UIWindow

Detailed Description

The UIWindow::Device is the backing device for one or multiple windows.

The device is responsible for providing rendering infrastructure and event handling for a window. Multiple implementations of a device are possible, while the most common implementation is Surface, other implementations are possible like handling window docking or rendering for UI testing.

Devices are also responsible for keeping track of dirty windows that require flushing. The device is not required to immediately flush a window upon request, but it is expected that contents should eventually become available in some way that makes sense for the implementation.

Constructor & Destructor Documentation

UIWindowDevice()

CeresEngine::UIWindowDevice::UIWindowDevice ( )

explicitdefaultnoexcept

~UIWindowDevice()

virtual CeresEngine::UIWindowDevice::~UIWindowDevice ( )

virtualdefaultnoexcept

Member Function Documentation

createBackingStore()

virtual UIBackingStorePtr CeresEngine::UIWindowDevice::createBackingStore ( UIWindow &  window )

pure virtual

Creates a new backing store for the window or a view that belongs to the window.

The backing store is used to store the contents of a view, window or layer and acts as render target when doing draw calls.

The most common implementation is to return a framebuffer that accepts GPU drawing commands.

Implemented in CeresEngine::UIWindowFramebufferDevice, and CeresEngine::UIWindowSurfaceDevice.

draw()

virtual void CeresEngine::UIWindowDevice::draw ( UIBackingStore &  backingStore, UIDrawCommandBuffer &  commandBuffer  )

virtual

Draws the UI command buffer into the backing store.

This method is usually called from the UIWindow display method or from a UILayer when filling the contents.

The default implementation is a no-op.

Reimplemented in CeresEngine::UIWindowFramebufferDevice.

flush()

virtual void CeresEngine::UIWindowDevice::flush ( UIWindow &  window, UIBackingStore &  backingStore  )

virtual

Flushes the contents of the window to the backing device.

If this is a window that is backed by a physical operating-system provided window, it means presenting the contents of backingStore to the window swapchain.

The backingStore instance must be the same instance as returned from Other devices may choose to implement this differently. The default implementation is a no-op.

Reimplemented in CeresEngine::UIWindowFramebufferDevice, and CeresEngine::UIWindowSurfaceDevice.

getBackingScaleFactor()

virtual double CeresEngine::UIWindowDevice::getBackingScaleFactor ( const UIWindow &  window ) const

inlinevirtual

The backing scale factor.

The value of this property is 2.0 for high-resolution scaled display modes, and 1.0 for all other cases.

There are some scenarios where an application that is resolution-aware may want to reason on its own about the display environment it is running in. It is important to note that the value of this property does not represent anything concrete, such as pixel density or physical size, because it can vary based on the configured display mode. For example, the display may be in a mirrored configuration that is still high-resolution scaled, resulting in pixel geometry that may not match the native resolution of the display device.

Note

For almost all common cases, developers should avoid using the value of getBackingScaleFactor() as an input to layout or drawing calculations. Developers should instead use the backing coordinate space conversion methods, because the resulting code will more likely work consistently and correctly under both standard and high-resolution operation.

Reimplemented in CeresEngine::UIWindowSurfaceDevice.

notifyBackingScaleFactorChange()

void CeresEngine::UIWindowDevice::notifyBackingScaleFactorChange ( UIWindow &  window, double  newBackingScalingFactor  )

protected

Utility method that must be called by device implementations when the window scaling factor changes.

For an OS-provided window device, this represents the event when the window has it's device pixel ratio changed, usually by dragging it into a separate display, but could also be triggered by changes in OS-level configuration.

notifyFrameChanged()

void CeresEngine::UIWindowDevice::notifyFrameChanged ( UIWindow &  window, const UIRect &  newFrame  )

protected

Utility method that must be called by device implementations when the window frame changes.

For an OS-provided window device, this represents the event when the user resizes the window.

registerWindow()

virtual UIBackingStorePtr CeresEngine::UIWindowDevice::registerWindow ( UIWindow &  window )

virtual

Registers a window with this device.

The registration can return a valid UIBackingStore that the window can use as a rendering target for it's contents. If no backing store is returned, drawing the UIWindow is unavailable.

Reimplemented in CeresEngine::UIWindowSurfaceDevice.

unregisterWindow()

virtual void CeresEngine::UIWindowDevice::unregisterWindow ( UIWindow &  window )

virtual

Unregisters the window from this device.

Reimplemented in CeresEngine::UIWindowSurfaceDevice.

Friends And Related Symbol Documentation

UIWindow

friend class UIWindow

friend

---

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

• /Users/Rogiel/Developer/CeresEngine/Engine/Sources/CeresEngine/UI/UIWindowDevice.hpp