Migration guide for wide gamut Color

The API for the Color class in dart:ui is changing to support wide gamut color spaces.

The Flutter engine already supports wide gamut color with Impeller, and the support is now being added to the framework.

The iOS devices that Flutter supports render to a larger array of colors, specifically in the DisplayP3 color space. After this change, the Flutter framework can render all of those colors on iOS Impeller, and the Color class will be better prepared for future color spaces or changes to color component bit depth.

Changes to Color:

1. Adds an enum field that specifies its ColorSpace.
2. Adds API to use normalized floating-point color components.
3. Removes API that uses 8-bit unsigned integer color components that can lead to data loss.

Changes to ColorSpace:

1. Adds a displayP3 property.

Constructors like Color.fromARGB remain unchanged and have continued support. To take advantage of Display P3 colors, you must use the new Color.from constructor that takes normalized floating-point color components.

// Before
final magenta = Color.fromARGB(0xff, 0xff, 0x0, 0xff);
// After
final magenta = Color.from(alpha: 1.0, red: 1.0, green: 0.0, blue: 1.0)

There are new methods being added to Color so any class that implements Color will break and have to implement the new methods like Color.a, and Color.b. Ultimately implementors should be migrated to take advantage of the new API. In the short-term, these methods can easily be implemented without changing the underlying structure of your class.

For example:

class Foo implements Color {
  int _red;

  @override
  double get r => _red * 255.0;
}

Clients that use Color and perform any sort of calculation on the color components should now first check the color space component before performing calculations. To help with that, you can use the new Color.withValues method to perform color space conversions.

Example migration:

// Before
double redRatio(Color x, Color y) => x.red / y.red;

// After
double redRatio(Color x, Color y) {
  final xPrime = x.withValues(colorSpace: ColorSpace.extendedSRGB);
  final yPrime = y.withValues(colorSpace: ColorSpace.extendedSRGB);
  return xPrime.r / yPrime.r;
}

Performing calculations with color components without aligning color spaces can lead to subtle unexpected results. In the example above the redRatio would have the difference of 0.09 when calculated with differing color spaces versus aligned color spaces.

If your app ever accesses a Color component, consider taking advantage of the floating-point components. In the short term, you can easily scale the components themselves.

extension IntColorComponents on Color {
  int get intAlpha => this.a ~/ 255;
  int get intRed => this.r ~/ 255;
  int get intGreen => this.g ~/ 255;
  int get intBlue => this.b ~/ 255;
}

Previously, Color had the concept of "opacity" which showed up in the methods opacity and withOpacity(). Opacity was introduced as a way to communicate with Color about its alpha channel with floating point values. Now that alpha is a floating-point value, opacity is redundant and opacity and withOpacity are deprecated and slated to be removed.

// Before
final x = color.opacity;
// After
final x = color.a;

// Before
final x = color.withOpacity(0.0);
// After
final x = color.withValues(alpha: 0.0);

Once Color stores its color components as floating-point numbers, equality works slightly differently. When calculating colors there might be tiny difference in values that could be considered equal. To accommodate this use the closeTo matcher or the isColorSameAs matcher.

// Before
expect(calculateColor(), const Color(0xffff00ff));
// After
expect(calculateColor(), isSameColorAs(const Color(0xffff00ff)));

Release to stable: TBD PR:: PR 54737

Release to stable: TBD

Relevant PRs:

• issue 127855: Implement wide gamut color support in the Framework

Unless stated otherwise, the documentation on this site reflects the latest stable version of Flutter. Page last updated on 2024-09-13. View source or report an issue.