PlatformContext Struct

struct Qul::Platform::PlatformContext

This class provides an abstract interface to implement platform context. More...

Header: #include <platform/platform.h>
Since: Qt Quick Ultralite (Platform) 2.0

Public Functions

virtual PlatformInterface::Rect adjustedPartialUpdateRect(const PlatformInterface::LayerEngine::ItemLayer *layer, const PlatformInterface::Rect &rect) const
virtual PlatformInterface::Screen *availableScreens(size_t *screenCount) const
virtual PlatformInterface::DrawingDevice *beginFrame(const PlatformInterface::LayerEngine::ItemLayer *layer, const PlatformInterface::Rect &rect, int refreshInterval = 1)
virtual Qul::Platform::Config config() const
virtual void consoleWrite(char character)
virtual uint64_t currentTimestamp() = 0
virtual void endFrame(const PlatformInterface::LayerEngine::ItemLayer *layer)
virtual void exec()
virtual void flushCachesForAsyncRead(const void *address, size_t length)
virtual Qul::Platform::FrameBufferingType frameBufferingType(const PlatformInterface::LayerEngine::ItemLayer *layer) const
virtual void initializeDisplay(const PlatformInterface::Screen *screen)
virtual void initializeHardware()
virtual void initializePlatform() = 0
virtual PlatformInterface::LayerEngine *layerEngine()
virtual PlatformInterface::MemoryAllocator *memoryAllocator(PlatformInterface::MemoryAllocator::AllocationType type)
virtual size_t partialBufferPixelCount(const PlatformInterface::LayerEngine::ItemLayer *layer) const
virtual Qul::Platform::FrameStatistics presentFrame(const PlatformInterface::Screen *screen, const PlatformInterface::Rect &rect)
virtual double rand() = 0
virtual void scheduleEngineUpdate(uint64_t timestamp) = 0
virtual uint64_t update() = 0
virtual void waitUntilAsyncReadFinished(const void *begin, const void *end)

Detailed Description

Methods of this class are platform APIs for hardware initialisation, execution loop and platform level graphics implementation. When porting to a new platform, a class derived from this class has to be implemented and the virtual methods are being overridden to get platform specific implementation. Qt Quick Ultralite core use an instance of this class to communicate with the hardware. See Qt Quick Ultralite Platform Porting Guide for more information.

Member Function Documentation

[virtual] PlatformInterface::Rect PlatformContext::adjustedPartialUpdateRect(const PlatformInterface::LayerEngine::ItemLayer *layer, const PlatformInterface::Rect &rect) const

Returns a platform-specific adjusted rect for a given layer when partial buffering is used.

The Qt Quick Ultralite core library uses this information to adjust the size of the dirty area when partial buffering is used.

The adjusted rect will later be passed to beginFrame() to draw the area corresponding to the partial update.

Some platforms might have certain alignment requirements or a minimum size for the update rectangle.

Note: Default implementation returns rect.

See also Qul::Platform::PlatformContext::beginFrame() and PartialBuffering.

[virtual] PlatformInterface::Screen *PlatformContext::availableScreens(size_t *screenCount) const

Returns array of the available screens. If there is no screen available function returns nullptr. Number of the items in the array is returned in screenCount output pointer.

The screen objects returned provide information about the screen dimensions as well as a swap chain used to draw to and present buffers for a particular display. First item in the returned array is treated as a default, primary screen.

Note: The memory allocated for the return value is owned by the platform. There is no transfer of ownership. Default implementation returns nullptr .

[virtual] PlatformInterface::DrawingDevice *PlatformContext::beginFrame(const PlatformInterface::LayerEngine::ItemLayer *layer, const PlatformInterface::Rect &rect, int refreshInterval = 1)

Begins Qt Quick Ultralite frame rendering.

Marks the beginning of Qt Quick Ultralite frame rendering for a given layer, and returns a DrawingDevice for it. The rect value specifies the dirty area that will be drawn to. The refreshInterval value specifies when to show the new frame, relative to when the last frame was shown. A refreshInterval of -1 indicates that the new frame should be shown immediately.

Note: Default implementation does nothing.

See also endFrame(), presentFrame(), Qul::PlatformInterface::DrawingDevice, and Qul::PlatformInterface::Rect.

[virtual] Qul::Platform::Config PlatformContext::config() const

Provides instance of Qul::Platform::Config.

It's main purpose is to provide platform configuration to Qt Quick Ultralite core library.

Note: Default implementation is delivered with platform/common/platform.cpp, which must be linked with the custom platform implementation.

[virtual] void PlatformContext::consoleWrite(char character)

Writes one character to the console.

Used by the Qt Quick Ultralite core library to print log data.

Note: Default implementation does nothing.

See also Qul::PlatformInterface::log() and qul_printf().

[pure virtual] uint64_t PlatformContext::currentTimestamp()

Returns the currently elapsed system time, in milliseconds.

[virtual] void PlatformContext::endFrame(const PlatformInterface::LayerEngine::ItemLayer *layer)

Ends Qt Quick Ultralite frame rendering.

Marks the end of Qt Quick Ultralite frame rendering for the given layer.

Note: Default implementation does nothing.

See also beginFrame() and presentFrame().

[virtual] void PlatformContext::exec()

Runs the main exec loop provided by the platform.

The exec loop will run forever, or at least for as long as the application is running, and is responsible for calling Qul::PlatformInterface::updateEngine at appropriate times. When no updates need to performed, it should yield or enter a sleep state if possible.

Here's an example showing how the exec() function might look:

void ExamplePlatform::scheduleEngineUpdate(uint64_t timestamp)
    nextUpdate = timestamp;
void ExamplePlatform::exec()
    while (true) {
        logFlush(); // Flush partially filled log buffer
        const uint64_t timestamp = this->update();

        if (timestamp > Platform::getPlatformInstance()->currentTimestamp()) {
            // The device may yield or go into sleep mode

Note: The function body can be left empty if you are not going to use any demos, examples, tests, calling Application::exec() or app_common framework.

See also Qul::PlatformInterface::updateEngine().

[virtual] void PlatformContext::flushCachesForAsyncRead(const void *address, size_t length)

This function is called to synchronize a given area of memory before an asynchronous read.

For asynchronous transfers, such as blitting and blending using DMA2D (STM) or PXP (NXP), it might be necessary to invalidate some caches (like D-Cache on ARM based CPUs) so that any changes to memory are actually fully committed before the transfer begins.

Use this function to indicate that the memory range specified by address and length might have been modified, and that caches need to be flushed to ensure that asynchronous transfers read the correct up-to-date data.

Note: Default implementation does nothing.

[virtual] Qul::Platform::FrameBufferingType PlatformContext::frameBufferingType(const PlatformInterface::LayerEngine::ItemLayer *layer) const

Returns layer's buffering type.

Returns FrameBufferingType for the given layer.

Note: Default implementation returns FrameBufferingType::SingleBuffering.

See also FrameBufferingType.

[virtual] void PlatformContext::initializeDisplay(const PlatformInterface::Screen *screen)

Initializes the platform display.

Initializes the platform display, with the screen geometry provided by the screen parameter. Called some time after initializeHardware.

Note: Default implementation does nothing.

[virtual] void PlatformContext::initializeHardware()

Initializes hardware required by Qt Quick Ultralite.

This may include clocks, pins, peripherals, buses and memories.

Developer may also decide not to implement it and perform own hardware initialization.

Note: On static library configuration this function won't get called if qul_run() is called with initializeHardware set to false.

Called by Qul::initHardware().

[pure virtual] void PlatformContext::initializePlatform()

Initializes Qt Quick Ultralite platform specific components.

This may include resource preloading and initializing CPU-based fallback drawing engine in Qt Quick Ultralite core.

Called by Qul::initPlatform().

[virtual] PlatformInterface::LayerEngine *PlatformContext::layerEngine()

Returns the layer engine for the platform.

Returns the layer engine responsible for allocating, updating and deallocating hardware layers. If the platform doesn't support multiple layers, nullptr can be returned.

Note: Default implementation returns nullptr .

[virtual] PlatformInterface::MemoryAllocator *PlatformContext::memoryAllocator(PlatformInterface::MemoryAllocator::AllocationType type)

Provides a memory allocator

Returns a Qul::PlatformInterface::MemoryAllocator pointer to handle memory allocations of the given type.

Note: The returned pointer is owned by the platform and should not be freed. Default implementation returns pointer to static instance of Qul::PlatformInterface::MemoryAllocator .

See also Qul::PlatformInterface::MemoryAllocator.

[virtual] size_t PlatformContext::partialBufferPixelCount(const PlatformInterface::LayerEngine::ItemLayer *layer) const

Returns the pixel count of a single partial framebuffer for a given layer.

The Qt Quick Ultralite platform library uses this information to limit the size of the rect in beginFrame when partial buffering is used.

Minimum pixel count is the width of the layer. Bigger pixel count will reduce rendering overhead.

Note: Default implementation returns 0.

See also Qul::Platform::PlatformContext::beginFrame() and PartialBuffering.

[virtual] Qul::Platform::FrameStatistics PlatformContext::presentFrame(const PlatformInterface::Screen *screen, const PlatformInterface::Rect &rect)

Presents layer and frame updates to the screen and returns statistics.

Qt Quick Ultralite core calls presentFrame for a given screen after all its layer updates have been done using the Qul::Platform::PlatformContext::layerEngine, and all updated frame contents have been rendered using beginFrame and endFrame.

The rect parameter specifies the bounding rectangle of the areas of the screen that have changed relative to the last frame, assuming no layer positions have changed.

Platforms that support it should update the background color based on Qul::PlatformInterface::Screen::backgroundColor().

Note: presentFrame might get called without beginFrame or endFrame being called first, if layer properties such as position or opacity have changed, or if the screen's background color has changed. Default implementation does nothing.

See also beginFrame(), endFrame(), Qul::Platform::FrameStatistics, Qul::PlatformInterface::Rect, and Qul::PlatformInterface::Screen.

[pure virtual] double PlatformContext::rand()

Return a uniformly random value in the range [0, 1).

This function returns a random value in the range [0, 1), meaning 1 should not be inclusive. It might use a hardware random number generator if available. Otherwise, the C++11 std::minstd_rand or a custom software RNG can be used.

[pure virtual] void PlatformContext::scheduleEngineUpdate(uint64_t timestamp)

Requests the platform implementation to schedule a Qt Quick Ultralite engine update at timestamp.

This function is supposed to be only called from the Qt Quick Ultralite engine during execution of updateEngine(). It requests the platform implementation to schedule an update of the Qt Quick Ultralite engine at the given timestamp. The timestamp is calculated based on the Qt Quick Ultralite engine timers and running animations.

A timestamp lesser than the current timestamp, or even 0, should result in calling updateEngine as soon as possible. A greater timestamp value than the current timestamp means that the platform implementation should call updateEngine at that given time. Until the scheduled time, the device may enter a sleep mode. Qul::PlatformInterface::updateEngine should not be called earlier than required.

For an example usage see the exec() or updateEngine() documentation.

Note: The implementation of this function can get called from an interrupt and it must be safe for running within an interrupt context.

See also Qul::PlatformInterface::updateEngine() and Qul::Platform::PlatformContext::exec().

[pure virtual] uint64_t PlatformContext::update()

Performs a single update of the Qt Quick Ultralite core engine.

This function performs all actions to update the Qt Quick Ultralite core engine once. It calls Qul::PlatformInterface::updateEngine if the time is due.

Here's an example showing how the update() function might look:

uint64_t ExamplePlatform::update()
    const uint64_t timestamp = this->currentTimestamp();

    if (timestamp >= nextUpdate) {
        // Handle deadline or pending events

    return nextUpdate;

See also Qul::PlatformInterface::updateEngine and Qul::Platform::PlatformContext::exec.

[virtual] void PlatformContext::waitUntilAsyncReadFinished(const void *begin, const void *end)

Block until no asynchronous transfer is reading from the given memory range.

Some platforms support asynchronous transfers, like DMA2D (STM) or PXP (NXP), that are used for drawing and blending. If the CPU writes to memory that is currently being read from by some asynchronous blending operation, then that could cause unwanted graphical glitches.

Use this function to wait until all asynchronous reads from the memory area specified by begin and end have finished. The range is [begin, end), meaning end is not included but serves to indicate the end of the range.

Note: Default implementation does nothing.

Available under certain Qt licenses.
Find out more.