Compatibility settings

Overview #

To continuously improve Prysm, new versions may update feature behaviors, remove obsolete settings, or introduce better defaults. To ensure these changes don’t break your integration during an upgrade, Prysm offers Compatibility settings. They provide a smoother transition by allowing you to temporarily fall back to legacy behaviors for specific features.

Example usage #

In version 3.0, Prysm removes the ViewSettings::ExecuteCommandProcessingWithLayout option and defaults to processing front-end rendering commands on the layout thread instead of the render thread. Because of this, the ISubLayerCompositor::OnDrawSubLayer callback now executes on the layout thread.

If this breaks your engine’s integration, you can revert to the previous behavior. Simply apply the VCF_ForceFrontEndCommandProcessingOnPaint compatibility flag to your ViewSettings to force front-end commands to process on the render thread.

cohtml::ViewSettings viewSettings;
viewSettings.CompatibilitySettings |= cohtml::CompatibilityFlags::VCF_ForceFrontEndCommandProcessingOnPaint;
cohtml::View* view = theSystem->CreateView(viewSettings);

Lifecycle Policy #

Compatibility flags are intentionally short-lived. They are designed to ease migration, not to serve as long-term solutions. We strongly encourage you to update your integration to support the new feature behaviors as soon as possible.

The typical lifecycle of a compatibility flag is as follows:

• Introduction: The flag is introduced in a major or a minor release.
• Transition: It remains available for a minimum of 3 months.
• Removal: The flag is permanently removed in the next major release once the transition period ends.

Naming Convention #

Compatibility flags use a prefix-based naming scheme to ensure consistency, discoverability, and clear ownership across different parts of the system.

• VCF_ — View compatibility flag (e.g., VCF_SynchronousStyleSolving)
• LCF_ — Library compatibility flag (e.g., LCF_DisableFontDataPreloading)
• (Additional prefixes may be introduced for other subsystems as needed)

Best Practices #

• Use sparingly: Apply only the flags strictly necessary for immediate compatibility.
• Plan migrations early: Treat these flags as temporary bridges, and schedule time to update your implementation before they are deprecated.