C

<platform/platform.h> - Platform abstraction functionality

Provides abstraction functionality for the platform. More...

Header: #include <platform/platform.h>

Types

enum FrameBufferingType { SingleBuffering, FlippedDoubleBuffering, CopyingDoubleBuffering, OtherBuffering }

Functions

PlatformInterface::Screen *availableScreens(size_t *screenCount)
PlatformInterface::DrawingDevice *beginFrame(const PlatformInterface::Screen *screen, int layer, const PlatformInterface::Rect &rect, int refreshInterval = 1)
uint64_t currentTimestamp()
void endFrame(const PlatformInterface::Screen *screen)
void exec()
void flushCachesForAsyncRead(const void *address, size_t length)
Qul::Platform::FrameBufferingType frameBufferingType(const PlatformInterface::Screen *screen)
void initializeDisplay(const PlatformInterface::Screen *screen)
void initializeHardware()
Qul::Platform::FrameStatistics presentFrame(const PlatformInterface::Screen *screen, const PlatformInterface::Rect &rect)
double rand()
void scheduleEngineUpdate(uint64_t timestamp)
void waitUntilAsyncReadFinished(const void *begin, const void *end)

Detailed Description

This namespace contains all functions of the platform abstraction that are used by the Qt Quick Ultralite core library. The header files for this namespace are located in include/platform/

Classes or structs

Qul::Platform::FrameStatistics

Provides frame rendering statistics

Type Documentation

enum FrameBufferingType

Defines the different buffering mechanisms that are supported.

ConstantValueDescription
SingleBuffering0There is only single buffer used for rendering. All rendering must happen within timing budget allowed by the display refresh rate.
FlippedDoubleBuffering1Two buffers are used and both can be displayed. One is used for displaying while the other is used for rendering and then flipped.
CopyingDoubleBuffering2There is one buffer for rendering and one for displaying. When rendering is finished the content from rendering buffer is copied to the display buffer.
OtherBuffering3Other platform specific buffering type.

This enum was introduced or modified in Qt 1.5.

Function Documentation

PlatformInterface::Screen *availableScreens(size_t *screenCount)

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.

This function was introduced in Qt 1.5.

PlatformInterface::DrawingDevice *beginFrame(const PlatformInterface::Screen *screen, int layer, const PlatformInterface::Rect &rect, int refreshInterval = 1)

Begins Qt Quick Ultralite frame rendering.

Marks the beginning of Qt Quick Ultralite frame rendering and returns a DrawingDevice for the given region rect of a given screen. The refreshInterval specifies when to show the new frame, relative to when the last frame was shown. The layer specifies the layer index of the frame.

This function was introduced in Qt 1.5.

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

uint64_t currentTimestamp()

Returns the currently elapsed system time, in milliseconds.

This function was introduced in Qt Quick Ultralite 1.0.

void endFrame(const PlatformInterface::Screen *screen)

Ends Qt Quick Ultralite frame rendering.

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

This function was introduced in Qt 1.5.

See also beginFrame(), presentFrame(), and Qul::PlatformInterface::Screen.

void 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 enter a sleep state if possible.

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

static uint64_t nextUpdate = 0;

void scheduleEngineUpdate(uint64_t timestamp)
{
    nextUpdate = timestamp;
}
...
void exec()
{
    while (true) {
        const uint64_t timestamp = currentTimestamp();

        if (timestamp >= nextUpdate) {
            // Handle deadline or pending events
            Qul::PlatformInterface::updateEngine(timestamp);
        } else {
            // The core library has no pending actions.
            // The device may go to a sleep mode.

            // wait_for_interrupt(nextUpdate - timestamp);
        }
    }
}

This function was introduced in Qt 1.0.

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

void 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.

This function was introduced in Qt Quick Ultralite 1.2.

Qul::Platform::FrameBufferingType frameBufferingType(const PlatformInterface::Screen *screen)

Returns screen's buffering type.

Returns FrameBufferingType for the given screen.

This function was introduced in Qt 1.5.

See also FrameBufferingType.

void 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.

This function was introduced in Qt 1.1.

void initializeHardware()

Initializes the platform hardware.

Performs basic hardware initialization, such as interrupts, timers, MPU. Called before initializeDisplay.

This function was introduced in Qt 1.1.

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

Swaps framebuffers and returns statistics.

Swaps the given region rect of the framebuffer to be shown on the given screen and returns FrameStatistics.

This function was introduced in Qt 1.5.

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

double 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 standard library rand() or a custom software RNG can be used.

This function was introduced in Qt Quick Ultralite 1.1.

void 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.

This function was introduced in Qt 1.3.

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

void 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.

This function was introduced in Qt Quick Ultralite 1.2.

Available under certain Qt licenses.
Find out more.