C

Platform Namespace

Qul::Platform

The namespace offers interfaces to port Qt Quick Ultralite to new platforms. More...

Header: #include <Platform>

Classes

Types

enum FrameBufferingType { SingleBuffering, FlippedDoubleBuffering, CopyingDoubleBuffering, OtherBuffering }
enum class MessageQueueStatus { Success, MessageDiscarded, MessageOverwritten, EmptyQueue, Timeout, …, OtherError }

Functions

Qul::PlatformInterface::Screen *availableScreens(size_t *screenCount)
Qul::PlatformInterface::DrawingDevice *beginFrame(const Qul::PlatformInterface::LayerEngine::ItemLayer *layer, const Qul::PlatformInterface::Rect &rect, int refreshInterval = 1)
void consoleWrite(char character)
uint64_t currentTimestamp()
void deleteQueue(Qul::Platform::MessageQueueInterface *queue)
void endFrame(const Qul::PlatformInterface::LayerEngine::ItemLayer *layer)
void exec()
void flushCachesForAsyncRead(const void *address, size_t length)
Qul::Platform::FrameBufferingType frameBufferingType(const Qul::PlatformInterface::LayerEngine::ItemLayer *layer)
void initializeDisplay(const Qul::PlatformInterface::Screen *screen)
void initializeHardware()
Qul::PlatformInterface::LayerEngine *layerEngine()
std::size_t maximumQueueMessageSize()
Qul::PlatformInterface::MemoryAllocator *memoryAllocator(Qul::PlatformInterface::MemoryAllocator::AllocationType type)
Qul::Platform::FrameStatistics presentFrame(const Qul::PlatformInterface::Screen *screen, const Qul::PlatformInterface::Rect &rect)
void printHeapStats()
void printStackStats()
void qul_free(void *ptr)
void *qul_malloc(std::size_t size)
void *qul_realloc(void *ptr, std::size_t new_size)
double rand()
Qul::Platform::MessageQueueInterface *requestQueue(std::size_t queueCapacity, std::size_t messageSize)
void scheduleEngineUpdate(uint64_t timestamp)
uint64_t update()
void waitUntilAsyncReadFinished(const void *begin, const void *end)

Detailed Description

Classes

class FrameStatistics

Provides frame rendering statistics. More...

class MessageQueue

A convenience class used to interface with the queue implementation. More...

class MessageQueueInterface

Interface class providing platform-specific queues to Qt Quick Ultralite. More...

class SinglePointTouchEvent

A struct containing information related to a single point touch event. More...

class SinglePointTouchEventDispatcher

A convenience class for handling single point touch from the platform. More...

class StackAllocator

Provides a simple memory allocator for functions that might temporarily require some extra memory for caching. More...

Type Documentation

[since Qt Quick Ultralite (Platform) 1.5] 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 Quick Ultralite (Platform) 1.5.

[since Qt Quick Ultralite (Platform) 1.9] enum class MessageQueueStatus

Status code returned by the MessageQueueInterface functions.

ConstantValueDescription
MessageQueueStatus::Success0Function was executed successfully.
MessageQueueStatus::MessageDiscarded1Message was discarded. This must be returned only when MessageQueueInterface::enqueueOrDiscard() and MessageQueueInterface::enqueueOrDiscardFromInterrupt() functions discard the given message.
MessageQueueStatus::MessageOverwritten2A message in a queue was overwritten with the given message. This must be returned only by the MessageQueueInterface::enqueueOrOverwrite() and MessageQueueInterface::enqueueOrOverwriteFromInterrupt() functions.
MessageQueueStatus::EmptyQueue3MessageQueueInterface::receive() or MessageQueueInterface::receiveFromInterrupt() could not get a message from the queue because it is empty.
MessageQueueStatus::Timeout4Could not get a message from the queue within timeout ms.
MessageQueueStatus::DiscardNotSupported5The queue implementation does not support discarding.
MessageQueueStatus::OverwriteNotSupported6The queue implementation does not support overwriting.
MessageQueueStatus::OtherError7None of the status codes fit the status of the function. EventQueue treats it as an error.

This enum was introduced or modified in Qt Quick Ultralite (Platform) 1.9.

Function Documentation

[since Qt Quick Ultralite (Platform) 1.5] Qul::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 Quick Ultralite (Platform) 1.5.

[since Qt Quick Ultralite (Platform) 1.7] Qul::PlatformInterface::DrawingDevice *beginFrame(const Qul::PlatformInterface::LayerEngine::ItemLayer *layer, const Qul::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.

This function was introduced in Qt Quick Ultralite (Platform) 1.7.

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

[since Qt Quick Ultralite 1.9] void consoleWrite(char character)

Output one character of log data.

character is the output character.

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

This function was introduced in Qt Quick Ultralite 1.9.

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

[since Qt Quick Ultralite 1.0] uint64_t currentTimestamp()

Returns the currently elapsed system time, in milliseconds.

This function was introduced in Qt Quick Ultralite 1.0.

[since Qt Quick Ultralite (Platform) 1.9] void deleteQueue(Qul::Platform::MessageQueueInterface *queue)

Deletes the queue.

This function is used by MessageQueue to delete a queue when it is not needed anymore.

Here is an example implementation of this function:

void deleteQueue(MessageQueueInterface *queue)
{
    MyMessageQueue *mq = static_cast<MyMessageQueue *>(queue);
    mq->~MyMessageQueue();
    qul_free(mq);
}

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

See also requestQueue(), maximumQueueMessageSize(), Qul::Platform::MessageQueue, and Qul::Platform::MessageQueueInterface.

[since Qt Quick Ultralite (Platform) 1.5] void endFrame(const Qul::PlatformInterface::LayerEngine::ItemLayer *layer)

Ends Qt Quick Ultralite frame rendering.

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

This function was introduced in Qt Quick Ultralite (Platform) 1.5.

See also beginFrame() and presentFrame().

[since Qt Quick Ultralite (Platform) 1.0] 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) {
        logFlush(); // Flush partially filled log buffer
        const uint64_t timestamp = Platform::update();

        if (timestamp > Platform::currentTimestamp()) {
            // The device may go to a sleep mode until timestamp or interrupt
        }
    }
}

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.

This function was introduced in Qt Quick Ultralite (Platform) 1.0.

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

[since Qt Quick Ultralite 1.2] 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.

[since Qt Quick Ultralite (Platform) 1.5] Qul::Platform::FrameBufferingType frameBufferingType(const Qul::PlatformInterface::LayerEngine::ItemLayer *layer)

Returns layer's buffering type.

Returns FrameBufferingType for the given layer.

This function was introduced in Qt Quick Ultralite (Platform) 1.5.

See also FrameBufferingType.

[since Qt Quick Ultralite (Platform) 1.1] void initializeDisplay(const Qul::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 Quick Ultralite (Platform) 1.1.

[since Qt Quick Ultralite (Platform) 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 Quick Ultralite (Platform) 1.1.

[since Qt Quick Ultralite (Platform) 1.7] Qul::PlatformInterface::LayerEngine *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.

This function was introduced in Qt Quick Ultralite (Platform) 1.7.

[since Qt Quick Ultralite (Platform) 1.9] std::size_t maximumQueueMessageSize()

Returns the maximum size of a message that a queue can hold. If the queue's maximum message size is not known or is arbitrary, SIZE_MAX must be returned.

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

See also requestQueue(), Qul::Platform::MessageQueue, and Qul::Platform::MessageQueueInterface.

[since Qt Quick Ultralite (Platform) 1.9] Qul::PlatformInterface::MemoryAllocator *memoryAllocator(Qul::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.

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

[since Qt Quick Ultralite (Platform) 1.5] Qul::Platform::FrameStatistics presentFrame(const Qul::PlatformInterface::Screen *screen, const Qul::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::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.

This function was introduced in Qt Quick Ultralite (Platform) 1.5.

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

[since Qt Quick Ultralite (Platform) 1.5] void printHeapStats()

Print heap usage statistics to stderr.

This function was introduced in Qt Quick Ultralite (Platform) 1.5.

[since Qt Quick Ultralite (Platform) 1.5] void printStackStats()

Print stack usage statistics to stderr.

This function was introduced in Qt Quick Ultralite (Platform) 1.5.

[since Qt Quick Ultralite (Platform) 1.5] void qul_free(void *ptr)

Frees a memory block allocated by qul_malloc.

ptr is the pointer to the memory block to be freed.

This function was introduced in Qt Quick Ultralite (Platform) 1.5.

See also Qul::Platform::qul_malloc(std::size_t size) and Qul::Platform::qul_realloc(void *ptr, std::size_t new_size).

[since Qt Quick Ultralite (Platform) 1.5] void *qul_malloc(std::size_t size)

Allocates memory in the way optimal for the platform.

size is the size of the requested block of memory, in bytes.

All of Qt Quick Ultralite performs dynamic memory allocation through this function.

Memory allocated using this function must be freed using qul_free. Resizing the memory block that was allocated can also be done using qul_realloc.

Might return NULL if there is not sufficient memory to satisfy the request.

This function was introduced in Qt Quick Ultralite (Platform) 1.5.

See also Qul::Platform::qul_free(void *ptr) and Qul::Platform::qul_realloc(void *ptr, std::size_t new_size).

[since Qt Quick Ultralite (Platform) 1.5] void *qul_realloc(void *ptr, std::size_t new_size)

Attempt to resize a memory block allocated with qul_malloc.

ptr is the pointer the the previously allocated memory block, and new_size is the new size for the memory block, in bytes.

Might return NULL if there is not sufficient memory to satisfy the request.

This function was introduced in Qt Quick Ultralite (Platform) 1.5.

See also Qul::Platform::qul_malloc(std::size_t size) and Qul::Platform::qul_free(void *ptr).

[since Qt Quick Ultralite 1.1] 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 C++11 std::minstd_rand or a custom software RNG can be used.

This function was introduced in Qt Quick Ultralite 1.1.

[since Qt Quick Ultralite (Platform) 1.9] Qul::Platform::MessageQueueInterface *requestQueue(std::size_t queueCapacity, std::size_t messageSize)

Returns an instance of the MessageQueueInterface implementation with queueCapacity capacity. The queue must accept messages that satisfies the messageSize requirement. If the implementation can't satisfy the queueCapacity or messageSize, the function must return a null pointer.

This function is used by MessageQueue to get an appropriate queue for its use.

Here is an example implementation of this function:

MessageQueueInterface *requestQueue(size_t queueCapacity, size_t messageSize)
{
    void *queue = qul_malloc(sizeof(MyMessageQueue));
    MessageQueueInterface *interface = new (queue) MyMessageQueue(queueCapacity, messageSize);
    return interface;
}

This function was introduced in Qt Quick Ultralite (Platform) 1.9.

See also deleteQueue(), maximumQueueMessageSize(), Qul::Platform::MessageQueue, and Qul::Platform::MessageQueueInterface.

[since Qt Quick Ultralite (Platform) 1.3] 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 Quick Ultralite (Platform) 1.3.

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

[since 1.8] uint64_t 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 update()
{
    const uint64_t timestamp = currentTimestamp();

    if (timestamp >= nextUpdate) {
        // Handle deadline or pending events
        Qul::PlatformInterface::updateEngine(timestamp);
    }

    return nextUpdate;
}

Qul::Platform::exec uses this function.

This function was introduced in Qt 1.8.

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

[since Qt Quick Ultralite 1.2] 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.