fix: Update flame_3d to support both old and newer Flutter APIs (#3663)

Several APIs started to return non-nullable types instead of null to
indicate errors. However we want to support both versions. If we do not
add `!`, it will fail on some versions, and if we do add `!`, the lint
will complain on others:

<img width="2428" height="1162" alt="image"
src="https://github.com/user-attachments/assets/73ee6679-4017-4c2b-a5d3-510d63ce5f27"
/>

This is a compromise, using a hacky "unwrap" method (a line-level
suppression would be fine; the unwrap just centralizes the hack in one
function for both methods).

Author: luanpotter

packages/flame_3d/lib/src/graphics/gpu_context_wrapper.dart

@@ -0,0 +1,45 @@
+import 'package:flutter_gpu/gpu.dart' as gpu;
+
+// TODO(luan): for now, we need to support both old (returns T?) and
+//             newer (returns T!) versions of some Flutter GPU context methods.
+class GpuContextWrapper {
+  static final Map<gpu.GpuContext, GpuContextWrapper> _instances = {};
+
+  final gpu.GpuContext _gpuContext;
+
+  factory GpuContextWrapper(gpu.GpuContext gpuContext) {
+    return _instances.putIfAbsent(
+      gpuContext,
+      () => GpuContextWrapper._(gpuContext),
+    );
+  }
+
+  GpuContextWrapper._(this._gpuContext);
+
+  gpu.Texture createTexture(
+    gpu.StorageMode storageMode,
+    int width,
+    int height, {
+    gpu.PixelFormat format = gpu.PixelFormat.r8g8b8a8UNormInt,
+  }) {
+    return unwrap(
+      _gpuContext.createTexture(
+        storageMode,
+        width,
+        height,
+        format: format,
+      ),
+    );
+  }
+
+  gpu.DeviceBuffer createDeviceBuffer(
+    gpu.StorageMode storageMode,
+    int sizeInBytes,
+  ) {
+    return unwrap(_gpuContext.createDeviceBuffer(storageMode, sizeInBytes));
+  }
+
+  static T unwrap<T>(T? t) {
+    return t!;
+  }
+}

packages/flame_3d/lib/src/graphics/graphics_device.dart

@@ -3,6 +3,7 @@ import 'dart:ui';
 
 import 'package:flame_3d/game.dart';
 import 'package:flame_3d/resources.dart';
+import 'package:flame_3d/src/graphics/gpu_context_wrapper.dart';
 import 'package:flame_3d/src/graphics/joints_info.dart';
 import 'package:flutter_gpu/gpu.dart' as gpu;
 
@@ -166,13 +167,14 @@ class GraphicsDevice {
     if (_previousSize != size) {
       _previousSize = size;
 
-      final colorTexture = _gpuContext.createTexture(
+      final gpuContext = GpuContextWrapper(_gpuContext);
+      final colorTexture = gpuContext.createTexture(
         gpu.StorageMode.devicePrivate,
         size.width.toInt(),
         size.height.toInt(),
       );
 
-      final depthTexture = _gpuContext.createTexture(
+      final depthTexture = gpuContext.createTexture(
         gpu.StorageMode.deviceTransient,
         size.width.toInt(),
         size.height.toInt(),

packages/flame_3d/lib/src/resources/mesh/surface.dart

@@ -3,6 +3,7 @@ import 'dart:typed_data';
 
 import 'package:flame_3d/game.dart';
 import 'package:flame_3d/resources.dart';
+import 'package:flame_3d/src/graphics/gpu_context_wrapper.dart';
 import 'package:flutter_gpu/gpu.dart' as gpu;
 
 enum PrimitiveType {
@@ -73,7 +74,7 @@ class Surface extends Resource<gpu.DeviceBuffer?> {
   gpu.DeviceBuffer? createResource() {
     final sizeInBytes = _vertices.lengthInBytes + _indices.lengthInBytes;
     resourceSizeInByes = sizeInBytes;
-    return gpu.gpuContext.createDeviceBuffer(
+    return GpuContextWrapper(gpu.gpuContext).createDeviceBuffer(
       gpu.StorageMode.hostVisible,
       sizeInBytes,
     )

packages/flame_3d/lib/src/resources/texture/texture.dart

@@ -2,6 +2,7 @@ import 'dart:typed_data';
 import 'dart:ui';
 
 import 'package:flame_3d/resources.dart';
+import 'package:flame_3d/src/graphics/gpu_context_wrapper.dart';
 import 'package:flutter_gpu/gpu.dart' as gpu;
 
 /// {@template texture}
@@ -23,7 +24,7 @@ class Texture extends Resource<gpu.Texture> {
 
   @override
   gpu.Texture createResource() {
-    return gpu.gpuContext.createTexture(
+    return GpuContextWrapper(gpu.gpuContext).createTexture(
       gpu.StorageMode.hostVisible,
       width,
       height,