P3 Colors

import IMGLYEngine

@MainActor
func p3Colors(engine: Engine) async throws {
  // Demo scaffolding: a minimal scene to exercise the rendering pipeline.
  let scene = try engine.scene.create()
  let page = try engine.block.create(.page)
  try engine.block.setWidth(page, value: 800)
  try engine.block.setHeight(page, value: 600)
  try engine.block.appendChild(to: scene, child: page)

  let p3IsSupported = try engine.editor.supportsP3()

  do {
    try engine.editor.checkP3Support()
  } catch {
    print("P3 unavailable: \(error.localizedDescription)")
    // Fall back to sRGB.
  }

  if p3IsSupported {
    try engine.editor.setSettingBool("features/p3WorkingColorSpace", value: true)
  }

  do {
    try engine.editor.checkP3Support()
    try engine.editor.setSettingBool("features/p3WorkingColorSpace", value: true)
  } catch {
    print("Staying on sRGB: \(error.localizedDescription)")
  }
}

P3 is a wide color gamut that covers roughly 25% more visible colors than sRGB, especially in the reds, oranges, and green-cyan regions. CE.SDK can render and export in a 16-bit Display P3 working space on devices that support it, preserving colors that would otherwise be clipped to sRGB.

What is P3?#

The DCI-P3 color space was developed for digital cinema and has been adopted in modern consumer displays, particularly by Apple since 2016. CE.SDK uses the Display P3 variant, which keeps sRGB’s gamma curve and replaces only the color primaries. Compared to sRGB:

• Gamut size: P3 covers about 25% more visible colors
• Primary colors: P3 red and green are more saturated
• Precision: The P3 working space uses 16 bits per channel instead of 8, which reduces banding in gradients and color adjustments
• Backwards compatibility: P3 content displayed on sRGB hardware is automatically converted

On sRGB displays, colors are converted for display but the underlying P3 data is preserved in exports.

Check P3 Support#

supportsP3() returns true when the engine can run in the P3 working color space on the current device. Internal errors are coerced to false, so the boolean is the only signal you get — use checkP3Support() for a diagnostic message.

let p3IsSupported = try engine.editor.supportsP3()

P3 is supported on iOS devices, the iOS Simulator, and Mac Catalyst. Only native macOS returns false — there the engine continues using its default 8-bit sRGB working space.

For a richer diagnostic, use checkP3Support() instead. It throws an Error whose message explains why P3 is unavailable — typical reasons are no implementation on the platform, no 16-bit float GPU support, or no P3-capable display.

do {
  try engine.editor.checkP3Support()
} catch {
  print("P3 unavailable: \(error.localizedDescription)")
  // Fall back to sRGB.
}

Enable the P3 Working Color Space#

Switch the engine into a 16-bit Display P3 pipeline by setting the features/p3WorkingColorSpace flag. The setting affects everything the editor renders — including the color picker and the live preview — and image exports preserve the wider gamut by writing 16-bit Display P3 PNGs with an embedded ICC profile. What you see in the editor matches the exported file; there is no separate preview pipeline.

if p3IsSupported {
  try engine.editor.setSettingBool("features/p3WorkingColorSpace", value: true)
}

The setting is silently ignored on platforms where P3 is unavailable, so it is safe to call without a guard, but checking support first avoids enabling a feature that will not take effect.

Graceful Fallback#

Combine both calls into a single do/catch to enable P3 when available and continue in sRGB otherwise. Most applications can stay on this single pattern.

do {
  try engine.editor.checkP3Support()
  try engine.editor.setSettingBool("features/p3WorkingColorSpace", value: true)
} catch {
  print("Staying on sRGB: \(error.localizedDescription)")
}

When the device does not support P3, the engine continues using its default 8-bit sRGB working space. Existing colors and exports remain valid; no further code changes are required.

Platform Support#

CE.SDK Swift ships on iOS, Mac Catalyst, and macOS. P3 availability differs across these targets:

supportsP3() returns the right answer for each target at runtime, so the same code compiles and runs on all three without conditional code.

P3 vs sRGB: When to Use Each#

The P3 working space exports 16-bit PNGs with an embedded Display P3 ICC profile. The doubled bit depth means files are typically 1.5–2× the size of their 8-bit sRGB equivalents.

API Reference#

Next Steps#

• Apply Colors — Apply colors to fills, strokes, and shadows
• Color Conversion — Convert colors between sRGB and CMYK