update nullability of drawAtlas methods and flesh out docs

[flar]

These changes fix two outstanding issues with the Canvas.drawAtlas and Canvas.drawRawAtlas methods:

• Canvas.drawAtlas and Canvas.drawRawAtlas have unnecessary parameter restrictions flutter#62457 (unnecessary non-null restrictions on their parameters)
• Document the operation of canvas.drawAtlas() and canvas.drawRawAtlas() flutter#62450 (document their operation in more detail)

The changes bring the null-ness of 2 of their parameters into compliance with the Skia implementations and the needs of common uses of these methods. Since nulls will now be allowed where they were not before, the changes represent a relaxing of restrictions and so should be backwards compatible with existing apps that use these methods.

The implementation is complete for the regular engine and includes new tests, but the web_ui version of these classes will need some updates to match (and I expect some check failures on this initial push due to the temporarily mismatched method signatures).

The changes are ready to have their API changes reviewed in their current form, though.

[flar]

This is odd, I haven't updated the web_ui signatures, but I guess the API tests don't test the nullability parts of the signatures.

I still have to update the implementation of the methods in web_ui to match the changes in the lib/ui files, though.

[flar]

The web_ui files are all updated as far as I could understand them. I pasted in the new lengthy doc comments even though I understand that the doc comments in the web_ui api file are not actually used to generate any documents...?

[dnfield]

I haven't double checked but isn't the C++ side expecting these to not be Dart_Null? I really like the doc updates but it's not clear to me why we would start accepting null instead of an empty array. I think in general it makes the code more complex and if you forget the null check somewhere you crash.

[flar]

I haven't double checked but isn't the C++ side expecting these to not be Dart_Null? I really like the doc updates but it's not clear to me why we would start accepting null instead of an empty array. I think in general it makes the code more complex and if you forget the null check somewhere you crash.

I looked through and it appears that they handle null lists being sent down in the arg converters. I am certainly running a test case where I send down nulls and it behaves as expected.

[flar]

Tagging @chinmaygarde regarding the question about whether the nulls will be handled correctly by the DartNative argument converters. Since an empty colors array used to translate into a null value being sent down, I think this is mostly a moot question, but it would be good to verify that my null handling here is kosher with respect to the native code.

[jason-simmons]

The Tonic wrapper for typed lists such as Int32List will construct an empty list if the converted Dart handle is a Dart null.

See https://github.com/flutter/engine/blob/master/third_party/tonic/typed_data/typed_list.cc#L20

[flar]

The Tonic wrapper for typed lists such as Int32List will construct an empty list if the converted Dart handle is a Dart null.

See https://github.com/flutter/engine/blob/master/third_party/tonic/typed_data/typed_list.cc#L20

It looks like the data_ field, which is what the value of the argument is, will be nullptr in that case.

See https://github.com/flutter/engine/blob/master/third_party/tonic/typed_data/typed_list.cc#L19
and https://github.com/flutter/engine/blob/master/third_party/tonic/typed_data/typed_list.h#L40
and https://github.com/flutter/engine/blob/master/lib/ui/painting/canvas.cc#L462

[flar]

Does this need to go through any formal API review?

[dnfield]

Nah. If you're concerned though feel free to ping @Hixie or @zanderso