Description
For the atlas operations the colors parameter is optional and represents a color to blend with the elements in the atlas. If this blending isn't needed then the colors aren't needed and neither is the blend mode. The underlying Skia operation offers a variant that takes no colors or blend mode arguments and calls the full version of the method with a null for colors and a default (unused) mode for the blend mode but we offer no such variant in the Flutter Canvas API.
The suggested use of this method - as a way to render a lot of sprites quickly - would not use the colors at all, so making it easy to do so is a critical Quality of Life feature for these methods. Ideally this method would have made the colors and blend mode optional.
The drawAtlas version of the method allows an empty array for the colors (so that the non-nullness can be asserted), but this is essentially a dodge for not offering any colors. It should just be allowed to be null so that callers don't have to construct an empty array. Allowing it to be null would be a backward-compatible change.
The drawRawAtlas version of the method, on the other hand, does not allow a null color list, and it asserts that the color list contains a color for every rectangle. This means that the caller not only can't ignore the colors parameter (which is rarely used) and must instead construct a list of colors (extra memory usage and CPU work), but they must also figure out a set of color values and a blend mode such that the (not very well documented) colors that they don't want can avoid modifying their operation.
Even more critically, the drawRawAtlas method is meant to be an optimization. The parameters are typed lists, which are harder for developers to manipulate than Dart class objects, so that they can be passed directly to the native code without any pre-processing. Unfortunately, this method requires a colors array to be specified which means that we have to pass that data to Skia and they must apply it. Applying those colors is added overhead for the rendering (on a per-atlas-entry basis) which means that the method provided for fastest processing ends up ironically forcing the rendering code into the slowest rendering procedure.
The drawAtlas method also says that all parameters must not be null, but this statement does not apply to the cull rectangle. In fact, the implementation has explicit handling for a null cull rectangle, which is appropriate since the cull rectangle is an optional optimization so that the operation can be quick-rejected if it falls outside the clip. In this case, the handling of null cull rectangles is already the right implementation, but it conflicts with the documentation which should be fixed.
Note that there is a separate issue submitted to properly document how this method operates and provide examples, but the changes mentioned here in this issue are more about making sure that the implementation is correct and useful, as a sort of pre-cursor for documenting the (hopefully fixed) operation of the method.