fix!: Correct coordinate system for a circular viewport (#2174)

examples/lib/stories/camera_and_viewport/camera_component_example.dart

@@ -67,17 +67,18 @@ class CameraComponentExample extends FlameGame with PanDetector {
 
   void _updateMagnifyingGlassPosition(Vector2 point) {
     // [point] is in the canvas coordinate system.
-    // This shifts the original [point] by 1.4142*radius, which happens to be
-    // in the middle of the magnifying glass' handle.
-    final handlePoint = point - Vector2.all(radius);
     magnifyingGlass
-      ..viewport.position = handlePoint
-      ..viewfinder.position = handlePoint - canvasSize / 2 + center;
+      ..viewport.position = point - Vector2.all(radius)
+      ..viewfinder.position = point - canvasSize / 2 + center;
   }
 }
 
-class Bezel extends Component {
-  Bezel(this.radius);
+class Bezel extends PositionComponent {
+  Bezel(this.radius)
+      : super(
+          size: Vector2.all(2 * radius),
+          position: Vector2.all(radius),
+        );
 
   final double radius;
   late final Path rim;

packages/flame/lib/experimental.dart

@@ -9,6 +9,18 @@
 /// After the components lived here for some time, and when we gain more
 /// confidence in their robustness, they will be moved out into the main Flame
 /// library.
+export 'src/camera/behaviors/bounded_position_behavior.dart'
+    show BoundedPositionBehavior;
+export 'src/camera/behaviors/follow_behavior.dart' show FollowBehavior;
+export 'src/camera/camera_component.dart' show CameraComponent;
+export 'src/camera/viewfinder.dart' show Viewfinder;
+export 'src/camera/viewport.dart' show Viewport;
+export 'src/camera/viewports/circular_viewport.dart' show CircularViewport;
+export 'src/camera/viewports/fixed_aspect_ratio_viewport.dart'
+    show FixedAspectRatioViewport;
+export 'src/camera/viewports/fixed_size_viewport.dart' show FixedSizeViewport;
+export 'src/camera/viewports/max_viewport.dart' show MaxViewport;
+export 'src/camera/world.dart' show World;
 export 'src/events/component_mixins/drag_callbacks.dart' show DragCallbacks;
 export 'src/events/component_mixins/tap_callbacks.dart' show TapCallbacks;
 export 'src/events/flame_game_mixins/has_draggable_components.dart'
@@ -26,24 +38,12 @@ export 'src/events/messages/drag_update_event.dart' show DragUpdateEvent;
 export 'src/events/messages/tap_cancel_event.dart' show TapCancelEvent;
 export 'src/events/messages/tap_down_event.dart' show TapDownEvent;
 export 'src/events/messages/tap_up_event.dart' show TapUpEvent;
-export 'src/experimental/bounded_position_behavior.dart'
-    show BoundedPositionBehavior;
-export 'src/experimental/camera_component.dart' show CameraComponent;
-export 'src/experimental/circular_viewport.dart' show CircularViewport;
-export 'src/experimental/fixed_aspect_ratio_viewport.dart'
-    show FixedAspectRatioViewport;
 export 'src/experimental/fixed_integer_resolution_viewport.dart'
     show FixedIntegerResolutionViewport;
-export 'src/experimental/fixed_size_viewport.dart' show FixedSizeViewport;
-export 'src/experimental/follow_behavior.dart' show FollowBehavior;
 export 'src/experimental/geometry/shapes/circle.dart' show Circle;
 export 'src/experimental/geometry/shapes/polygon.dart' show Polygon;
 export 'src/experimental/geometry/shapes/rectangle.dart' show Rectangle;
 export 'src/experimental/geometry/shapes/rounded_rectangle.dart'
     show RoundedRectangle;
 export 'src/experimental/geometry/shapes/shape.dart' show Shape;
 export 'src/experimental/has_game_reference.dart' show HasGameReference;
-export 'src/experimental/max_viewport.dart' show MaxViewport;
-export 'src/experimental/viewfinder.dart' show Viewfinder;
-export 'src/experimental/viewport.dart' show Viewport;
-export 'src/experimental/world.dart' show World;

packages/flame/lib/src/experimental/follow_behavior.dart → packages/flame/lib/src/camera/behaviors/follow_behavior.dart

@@ -1,8 +1,8 @@
+import 'package:flame/src/camera/viewfinder.dart';
+import 'package:flame/src/camera/viewport.dart';
 import 'package:flame/src/components/core/component.dart';
 import 'package:flame/src/components/position_component.dart';
 import 'package:flame/src/effects/provider_interfaces.dart';
-import 'package:flame/src/experimental/viewfinder.dart';
-import 'package:flame/src/experimental/viewport.dart';
 
 /// This behavior will make the [owner] follow the [target].
 ///

packages/flame/lib/src/experimental/camera_component.dart → packages/flame/lib/src/camera/camera_component.dart

@@ -1,18 +1,18 @@
 import 'dart:ui';
 
+import 'package:flame/src/camera/behaviors/bounded_position_behavior.dart';
+import 'package:flame/src/camera/behaviors/follow_behavior.dart';
+import 'package:flame/src/camera/viewfinder.dart';
+import 'package:flame/src/camera/viewport.dart';
+import 'package:flame/src/camera/viewports/max_viewport.dart';
+import 'package:flame/src/camera/world.dart';
 import 'package:flame/src/components/core/component.dart';
 import 'package:flame/src/components/position_component.dart';
 import 'package:flame/src/effects/controllers/effect_controller.dart';
 import 'package:flame/src/effects/move_effect.dart';
 import 'package:flame/src/effects/move_to_effect.dart';
 import 'package:flame/src/effects/provider_interfaces.dart';
-import 'package:flame/src/experimental/bounded_position_behavior.dart';
-import 'package:flame/src/experimental/follow_behavior.dart';
 import 'package:flame/src/experimental/geometry/shapes/shape.dart';
-import 'package:flame/src/experimental/max_viewport.dart';
-import 'package:flame/src/experimental/viewfinder.dart';
-import 'package:flame/src/experimental/viewport.dart';
-import 'package:flame/src/experimental/world.dart';
 import 'package:meta/meta.dart';
 import 'package:vector_math/vector_math_64.dart';
 

packages/flame/lib/src/experimental/viewfinder.dart → packages/flame/lib/src/camera/viewfinder.dart

@@ -1,9 +1,9 @@
 import 'dart:math';
 
 import 'package:flame/src/anchor.dart';
+import 'package:flame/src/camera/camera_component.dart';
 import 'package:flame/src/components/core/component.dart';
 import 'package:flame/src/effects/provider_interfaces.dart';
-import 'package:flame/src/experimental/camera_component.dart';
 import 'package:flame/src/game/transform2d.dart';
 import 'package:meta/meta.dart';
 import 'package:vector_math/vector_math_64.dart';

packages/flame/lib/src/experimental/viewport.dart → packages/flame/lib/src/camera/viewport.dart

@@ -1,9 +1,9 @@
 import 'dart:ui';
 
 import 'package:flame/src/anchor.dart';
+import 'package:flame/src/camera/camera_component.dart';
 import 'package:flame/src/components/core/component.dart';
 import 'package:flame/src/effects/provider_interfaces.dart';
-import 'package:flame/src/experimental/camera_component.dart';
 import 'package:meta/meta.dart';
 import 'package:vector_math/vector_math_64.dart';
 
@@ -24,6 +24,8 @@ abstract class Viewport extends Component
     implements AnchorProvider, PositionProvider, SizeProvider {
   Viewport({super.children});
 
+  final Vector2 _size = Vector2.zero();
+
   /// Position of the viewport's anchor in the parent's coordinate frame.
   ///
   /// Changing this position will move the viewport around the screen, but will
@@ -53,7 +55,6 @@ abstract class Viewport extends Component
   /// size cannot be negative.
   @override
   Vector2 get size => _size;
-  final Vector2 _size = Vector2.zero();
   @override
   set size(Vector2 value) {
     assert(
@@ -87,10 +88,15 @@ abstract class Viewport extends Component
   @override
   bool containsLocalPoint(Vector2 point);
 
-  /// Override in order to perform a custom action upon resize.
+  /// Called after the size of the viewport has changed.
+  ///
+  /// The new size will be stored in the [size] property. This method could be
+  /// invoked either when the user explicitly changes the size of the viewport,
+  /// or when the size changes automatically in response to the change in game
+  /// canvas size.
   ///
-  /// A typical use-case would be to adjust the viewport's clip mask to match
-  /// the new size.
+  /// A typical implementation would need to adjust the viewport's clip mask to
+  /// match the new size.
   @protected
   void onViewportResize();
 

packages/flame/lib/src/camera/viewports/circular_viewport.dart

@@ -0,0 +1,46 @@
+import 'dart:ui';
+
+import 'package:flame/src/camera/viewport.dart';
+import 'package:vector_math/vector_math_64.dart';
+
+/// A fixed-size viewport in the shape of a circle (or ellipse).
+///
+/// This viewport does not adjust its size or position on the screen in response
+/// to game resize events. However, the [size] of the viewport can be changed
+/// manually at runtime.
+class CircularViewport extends Viewport {
+  CircularViewport(double radius, {super.children}) {
+    // This will also call [onViewportResize]
+    size = Vector2.all(2 * radius);
+  }
+
+  CircularViewport.ellipse(double radiusX, double radiusY, {super.children}) {
+    size = Vector2(2 * radiusX, 2 * radiusY);
+  }
+
+  Path _clipPath = Path();
+  double _radiusX = 0.0;
+  double _radiusY = 0.0;
+
+  @override
+  void clip(Canvas canvas) => canvas.clipPath(_clipPath, doAntiAlias: false);
+
+  @override
+  bool containsLocalPoint(Vector2 point) {
+    final fx = point.x / _radiusX - 1;
+    final fy = point.y / _radiusY - 1;
+    return fx * fx + fy * fy <= 1;
+  }
+
+  @override
+  void onViewportResize() {
+    _radiusX = size.x / 2;
+    _radiusY = size.y / 2;
+    _clipPath = Path()..addOval(Rect.fromLTRB(0, 0, size.x, size.y));
+  }
+
+  @override
+  void renderDebugMode(Canvas canvas) {
+    canvas.drawPath(_clipPath, debugPaint);
+  }
+}

packages/flame/lib/src/experimental/fixed_aspect_ratio_viewport.dart → packages/flame/lib/src/camera/viewports/fixed_aspect_ratio_viewport.dart

@@ -1,6 +1,6 @@
 import 'dart:ui';
 
-import 'package:flame/src/experimental/viewport.dart';
+import 'package:flame/src/camera/viewport.dart';
 import 'package:vector_math/vector_math_64.dart';
 
 class FixedAspectRatioViewport extends Viewport {

packages/flame/lib/src/experimental/fixed_size_viewport.dart → packages/flame/lib/src/camera/viewports/fixed_size_viewport.dart

@@ -1,6 +1,6 @@
 import 'dart:ui';
 
-import 'package:flame/src/experimental/viewport.dart';
+import 'package:flame/src/camera/viewport.dart';
 import 'package:vector_math/vector_math_64.dart';
 
 /// A rectangular viewport with fixed dimensions.

packages/flame/lib/src/experimental/max_viewport.dart → packages/flame/lib/src/camera/viewports/max_viewport.dart

@@ -1,6 +1,6 @@
 import 'dart:ui';
 
-import 'package:flame/src/experimental/viewport.dart';
+import 'package:flame/src/camera/viewport.dart';
 import 'package:vector_math/vector_math_64.dart';
 
 /// The default viewport, which is as big as the game canvas allows.

packages/flame/lib/src/experimental/world.dart → packages/flame/lib/src/camera/world.dart

@@ -1,8 +1,8 @@
 import 'dart:ui';
 
+import 'package:flame/src/camera/camera_component.dart';
 import 'package:flame/src/components/core/component.dart';
 import 'package:flame/src/components/mixins/coordinate_transform.dart';
-import 'package:flame/src/experimental/camera_component.dart';
 import 'package:meta/meta.dart';
 import 'package:vector_math/vector_math_64.dart';