FrameInfo class Null safety

Information for a single frame of an animation.

To obtain an instance of the FrameInfo interface, see Codec.getNextFrame.

The recipient of an instance of this class is responsible for calling Image.dispose on image. To share the image with other interested parties, use Image.clone. If the FrameInfo object itself is passed to another method or object, that method or object must assume it is responsible for disposing the image when done, and the passer must not access the image after that point.

For example, the following code sample is incorrect:

/// BAD
Future<void> nextFrameRoutine(ui.Codec codec) async {
  final ui.FrameInfo frameInfo = await codec.getNextFrame();
  _cacheImage(frameInfo);
  // ERROR - _cacheImage is now responsible for disposing the image, and
  // the image may not be available any more for this drawing routine.
  _drawImage(frameInfo);
  // ERROR again - the previous methods might or might not have created
  // handles to the image.
  frameInfo.image.dispose();
}

Correct usage is:

/// GOOD
Future<void> nextFrameRoutine(ui.Codec codec) async {
  final ui.FrameInfo frameInfo = await codec.getNextFrame();
  _cacheImage(frameInfo.image.clone(), frameInfo.duration);
  _drawImage(frameInfo.image.clone(), frameInfo.duration);
  // This method is done with its handle, and has passed handles to its
  // clients already.
  // The image will live until those clients dispose of their handles, and
  // this one must not be disposed since it will not be used again.
  frameInfo.image.dispose();
}