C
Runtime API Changes
Qt Safe Renderer 2.2.0 Release candidate 1 contains changes and additions to the Qt Safe Renderer Runtime API. This page documents both modifications to existing APIs and newly introduced classes and functions.
Contents
- Changes to Existing API
- Unify the exception usage across all QSR modules
- Change in QSafeEventVisibility API
- OutputVerifier Singleton Pattern
- SafeWindow Constructor Changes
- VerifyRegion State Tracking
- QSafeFile API Changes
- Checksum API Changes
- Utility Functions Reorganization
- OutputVerifier Platform-Specific Constructor Changes
- Constraint Value Updates
- QSafeFont Constructor and Method Visibility Changes
- OutputVerifierInterface verifyOutput Return Status
- New Classes and Functions
Changes to Existing API
Unify the exception usage across all QSR modules
See the Qt Safe Renderer Runtime C++ API documentation: SafeRenderer::QSafeException and its inherited classes.
Description
Unify the exception usage across all QSR modules. In Qt Safe Renderer 2.0, adaptations used the exceptions differently from the core QSR. Qt Safe Renderer 2.1 adds new exception classes containing an exception ID and an exception reason string. Also, some exception classes provide additional information about the failure. The new SafeRenderer::QSafeException class serves as a base class for all exceptions in the Qt Safe Renderer modules.
Impact
This change will affect any code that relies on the previous exception handling mechanisms in the Qt Safe Renderer module. Developers should update their code to use the new SafeRenderer::QSafeException class and its inherited classes to avoid any compatibility issues with the latest version of the software.
Change in QSafeEventVisibility API
See the Qt Safe Renderer Runtime C++ API documentation: SafeRenderer::QSafeEventVisibility.
Description
The method setId() was renamed to setItemId(). This change ensures that the name of the method is more descriptive and accurately reflects its purpose.
Impact
This change will affect any code that relies on the SafeRenderer::QSafeEventVisibility API. Developers should update their code accordingly to avoid any compatibility issues with the latest version of the software.
OutputVerifier Singleton Pattern
See the Qt Safe Renderer Runtime C++ API documentation: SafeRenderer::OutputVerifier.
Description
The SafeRenderer::OutputVerifier class has been refactored to use the Singleton design pattern. The constructor is now private, and access to the SafeRenderer::OutputVerifier instance must be obtained through the static method getOutputVerifierInstance(). This ensures that only one instance of the output verifier exists throughout the application lifecycle, improving resource management and preventing multiple verifier instances from interfering with each other.
Impact
This is a breaking change. Code that previously instantiated SafeRenderer::OutputVerifier objects directly must be updated to use getOutputVerifierInstance(). The singleton pattern ensures consistent verification state across the application.
SafeWindow Constructor Changes
See the Qt Safe Renderer Runtime C++ API documentation: SafeRenderer::SafeWindow.
Description
The SafeRenderer::SafeWindow constructor that accepted an SafeRenderer::OutputVerifier parameter has been removed across all platform implementations (DRM, OpenWFD, QNX Screen, QtGUI, RCar3, and Stub). This change optimizes rendering performance by refactoring the rendering loop to no longer request output verification. Output verification is now controlled by the event handler loop instead of the rendering loop, improving overall performance.
Impact
This is a breaking change. Code that used the three-parameter SafeRenderer::SafeWindow constructor must be updated to use the two-parameter constructor. Output verification is now handled separately through the event handler loop rather than during rendering.
VerifyRegion State Tracking
See the Qt Safe Renderer Runtime C++ API documentation: SafeRenderer::VerifyRegion.
Description
The SafeRenderer::VerifyRegion class has been enhanced to include state tracking. The constructor now requires a state parameter, and new methods state() and setState() have been added. This allows verification regions to be associated with specific UI states, enabling state-aware CRC verification where the expected CRC values can differ based on the current state of the UI element.
Impact
This is a breaking change. Code that creates SafeRenderer::VerifyRegion objects must be updated to provide the state parameter in the constructor. Applications can now implement state-dependent verification strategies to handle dynamic UI elements more accurately.
QSafeFile API Changes
See the Qt Safe Renderer Runtime C++ API documentation: SafeRenderer::QSafeFile.
Description
The QSafeFile class has been updated with several changes. The available() method is now const-qualified for improved const-correctness. The rewindToStart() method has been removed. The checksum function qt_checksum_file() has been moved from qsafechecksum.h to qsafefile.h as it is more closely related to file operations.
Impact
Code using rewindToStart() must be refactored to use alternative positioning methods or reopen the file. The available() method can now be called on const QSafeFile objects. Code using qt_checksum_file() should include qsafefile.h instead of qsafechecksum.h.
Checksum API Changes
Description
The checksum API has been updated with the addition of qt_checksum_partial(), which enables incremental CRC calculation over multiple data chunks. The qt_checksum_file() function has been moved from qsafechecksum.h to SafeRenderer::QSafeFile. A new CRC32 calculator has been introduced in calccrc/crc32/calccrc_crc32.h with the updateCRC() function for updating CRC values with color data.
Impact
Applications performing incremental checksum calculations can now use qt_checksum_partial(). Code using qt_checksum_file() should include qsafefile.h. The CRC32 calculator provides an alternative CRC algorithm for platform-specific requirements.
Utility Functions Reorganization
Description
Utility functions max() and min() have been moved from qsafeglobal.h to a new dedicated header qsafeminmax.h. The StaticAssert template has been removed from qsafeglobal.h. These changes improve code organization by separating general utilities into more focused headers.
Impact
Code using max() or min() should include qsafeminmax.h. In many cases, the header will be transitively included, but explicit inclusion is recommended for clarity. Code using StaticAssert should use C++11 static_assert instead if the project is using C++11 or later.
OutputVerifier Platform-Specific Constructor Changes
See the Qt Safe Renderer Runtime C++ API documentation: SafeRenderer::OutputVerifier, SafeRenderer::OutputVerifierInterface.
Description
Platform-specific output verifier implementations (SafeRenderer::NXPVerifier, SafeRenderer::TestVerifier, SafeRenderer::MISRVerifier) have updated constructor signatures. Verifiers now accept a SafeRenderer::QSafeRect as a parameter directly for the surface size instead of an SafeRenderer::OutputVerifier reference. The SafeRenderer::OutputVerifierInterface base class has been updated to accept and store the safe surface region. SafeRenderer::MISRVerifier methods setupRoi() and readRoi() now require device and port parameters.
Impact
Applications implementing custom output verifiers must update their constructor signatures and initialization code. The SafeRenderer::MISRVerifier API changes require passing device and port information explicitly. This aligns with the singleton pattern for SafeRenderer::OutputVerifier.
Constraint Value Updates
Description
The Constraints::MAX_NUM_ROI constant has been increased from 4 to 8, allowing verification of up to 8 regions of interest simultaneously. A new constant Constraints::ENABLE_ALPHA_CRC_BYPASS has been added with value 1U to control alpha channel bypass in CRC calculations on supported platforms.
Impact
Applications can now verify up to 8 ROIs concurrently, improving verification throughput for complex UIs. The alpha bypass flag enables platform-specific optimizations. Existing code using fewer than 8 ROIs is not affected.
QSafeFont Constructor and Method Visibility Changes
See the Qt Safe Renderer Runtime C++ API documentation: SafeRenderer::QSafeFont.
Description
The SafeRenderer::QSafeFont default constructor is now public (previously protected), and the load() method has been moved from protected to public visibility. The font file loader destructor has been made virtual to ensure proper cleanup in inheritance hierarchies.
Impact
Applications can now construct SafeRenderer::QSafeFont objects directly and load font data using the public API. This provides more flexibility for custom font loading implementations. Existing code continues to work without modification.
OutputVerifierInterface verifyOutput Return Status
See the Qt Safe Renderer Runtime C++ API documentation: SafeRenderer::OutputVerifierInterface and SafeRenderer::OutputVerifier.
Description
The verifyOutput() method signature changed from void to bool to enable error reporting from the adaptation layer. Returns true on success and false when an error occurs while setting the region of interest or reading CRC values from the display hardware.
Impact
This is a breaking change. Custom output verifier implementations must be updated to return bool instead of void.
New Classes and Functions
Exception Handler Framework
See the Qt Safe Renderer Runtime C++ API documentation: SafeRenderer::QSafeExceptionHandler, QSafeExceptionHandlerInterface, and SafeRenderer::QSafeException.
Description
A new exception handling framework has been introduced in Qt Safe Renderer 2.2 to provide centralized exception management. The SafeRenderer::QSafeExceptionHandler class provides a global exception handler that can be customized by installing a custom QSafeExceptionHandlerInterface. All exceptions now include a type() method that returns an ExceptionType enum value, enabling type-safe exception handling and categorization. This allows applications to implement custom error recovery strategies and logging mechanisms.
Impact
Applications can now install custom exception handlers using QSafeExceptionHandler::installExceptionHandler() to implement application-specific error handling strategies. Existing exception catching code continues to work, but applications can now distinguish exception types using the type() method for more granular error handling.
Monitor C API
See the Qt Safe Monitor C API documentation: <qsrmonitor.h>, <crccache.h>, <monitorconfig.h>, and <eventProcessor.h>.
Description
Qt Safe Renderer 2.2 introduces a comprehensive C API for the monitor functionality, enabling integration with C-based systems. The API includes functions for adding items to verification (addItemToVerification), verifying output (verifyOutput), managing CRC caches (crcCache_setCRC, crcCache_getCRC), and configuring verification regions (getRegionForItemInStateAtIndex). The crccache.h header provides a CRC caching mechanism supporting up to 256 entries, which allows applications to add dynamic golden CRC values at runtime in addition to the static golden CRC structures generated at build time.
Impact
These are new APIs for Qt Safe Renderer Monitor use cases where the OutputVerifier adaptation is integrated with the C-based Monitor process. The CRC cache enables runtime configuration of expected CRC values for dynamic verification scenarios. Existing solutions are not affected.
AUTOSAR C API
Description
Qt Safe Renderer 2.2 adds AUTOSAR-compliant C API wrappers for the Qt Safe Monitor C API to enable integration with AUTOSAR-based automotive systems. The qsr_monitor_autosar.h header provides AUTOSAR-compatible wrapper functions such as QsrMonitor_AddItemToVerification, QsrMonitor_VerifyOutput, and QsrMonitor_InitVerifierDevice. The cdd_qsr.h header defines the Complex Device Driver (CDD) interface for CRC calculation requests. AUTOSAR-standard type definitions (uint8, sint8, etc.) are provided in Platform_Types.h.
Impact
This is new functionality that enables Qt Safe Renderer integration with AUTOSAR Classic. Developers working on AUTOSAR projects can now use Qt Safe Renderer with AUTOSAR-compliant APIs and type definitions. Non-AUTOSAR projects are not affected.
Output Verifier C API
See the Qt Safe Renderer Runtime C API documentation: <outputverifier_capi.h> and <regiondefinition.h>.
Description
A new C API for output verification has been introduced in outputverifier_capi.h, providing functions for initializing verifier devices, adding regions for verification, and retrieving verification results. The API includes OutputVerifier_initVerifierDevice, OutputVerifier_addRegionForVerification, OutputVerifier_verifyOutput, and OutputVerifier_getVerificationResult. The RegionDefinition structure provides a C-compatible representation of verification regions with fields for ID, state, position, dimensions, and expected CRC values.
Impact
This API enables the OutputVerifier adaptation to be integrated with the C-based monitor process, allowing output verification to run within the monitor alongside the Qt Safe Renderer process. This is particularly useful for safety-critical systems where verification needs to be performed independently. C-based applications can now use output verification functionality directly. Existing C++ code continues to work without modification.
Text Rendering API
Description
A new QSafeTextRenderer class has been introduced providing static utility methods for text rendering operations. The class includes fillBackground() for filling bitmap buffers with a solid color, and drawGlyph() for rendering individual glyph data to bitmap buffers with specified draw and fill colors. These utilities are primarily used internally by Qt for Qt Ultralite's optimized text rendering implementation.
Impact
This API is utilized internally by Qt for Qt Ultralite integration. Most applications do not need to use these low-level rendering utilities directly. Existing high-level text rendering code is not affected.
Rendering Utilities API
Description
A new header qsaferenderingutils.h has been introduced providing utility functions for rendering operations. It includes INTERPOLATE_PIXEL_255() for pixel color interpolation with alpha blending, and calcBitmapBufferSizeBytes() for calculating the required buffer size for bitmap data given width, height, and bytes per pixel. These utilities are primarily used internally by Qt for Qt Ultralite's custom rendering implementation.
Impact
This API is utilized internally by Qt for Qt Ultralite integration. Most applications do not need to use these low-level rendering utilities directly. Existing code is not affected.
Memory Allocator API Extension
Description
A new global function deallocFromMemoryPool() has been added, which allows memory allocated from the memory pool to be explicitly returned. This function is primarily used internally by Qt for Qt Ultralite's dynamic memory allocation and deallocation implementation. Note that deallocation is not supported by the default Qt Safe Renderer memory pool implementation.
Impact
This API is utilized internally by Qt for Qt Ultralite integration. Most applications do not need to explicitly deallocate memory from the pool. Existing code is not affected.
QSafeBitmapBuffer Raw Data Access
See the Qt Safe Renderer Runtime C++ API documentation: SafeRenderer::QSafeBitmapBuffer.
Description
The SafeRenderer::QSafeBitmapBuffer class now provides rawBitmapData() methods (both const and non-const versions) that return direct pointers to the underlying bitmap data. These methods are primarily used internally by Qt for Qt Ultralite's optimized text rendering implementation, providing low-level access to the raw pixel data.
Impact
This API is utilized internally by Qt for Qt Ultralite integration. Most applications do not need direct access to raw bitmap data. Existing high-level bitmap operations are not affected.
Enhanced Layout Position Validation
See the Qt Safe Renderer Runtime C++ API documentation: SafeRenderer::QSafeLayout.
Description
The SafeRenderer::QSafeLayout class has been extended with new isPositionValidForItem() methods that accept both string-based and numeric item IDs. These methods allow validation of whether a given (x, y) position is valid for a specific item in the layout, which is useful for hit testing and interactive UI element selection.
Impact
Applications implementing interactive UIs or performing hit testing can now validate positions against layout items. This is new functionality that does not affect existing code.
Available under certain Qt licenses.
Find out more.
