feat: Added Shadow3DDecorator (#1812)

doc/flame/examples/lib/decorator_shadow3d.dart

@@ -0,0 +1,70 @@
+import 'dart:ui';
+
+import 'package:doc_flame_examples/flower.dart';
+import 'package:flame/components.dart';
+import 'package:flame/experimental.dart';
+import 'package:flame/game.dart';
+import 'package:flame/rendering.dart';
+
+class DecoratorShadowGame extends FlameGame with HasTappableComponents {
+  @override
+  Color backgroundColor() => const Color(0xFFC7C7C7);
+
+  @override
+  Future<void> onLoad() async {
+    var step = 0;
+    add(Grid());
+    add(
+      Flower(
+        size: 100,
+        position: canvasSize / 2,
+        decorator: Shadow3DDecorator(
+          base: canvasSize / 2 + Vector2(0, 50),
+        ),
+        onTap: (flower) {
+          step++;
+          final decorator = flower.decorator! as Shadow3DDecorator;
+          if (step == 1) {
+            decorator.xShift = 200;
+            decorator.opacity = 0.5;
+          } else if (step == 2) {
+            decorator.xShift = 400;
+            decorator.yScale = 3;
+            decorator.blur = 1;
+          } else if (step == 3) {
+            decorator.angle = 1.7;
+            decorator.blur = 2;
+          } else if (step == 4) {
+            decorator.ascent = 20;
+            decorator.angle = 1.7;
+            decorator.blur = 2;
+            flower.y -= 20;
+          } else {
+            decorator.ascent = 0;
+            decorator.xShift = 0;
+            decorator.yScale = 1;
+            decorator.angle = -1.4;
+            decorator.opacity = 0.8;
+            decorator.blur = 0;
+            flower.y += 20;
+            step = 0;
+          }
+        },
+      )..onTapUp(),
+    );
+  }
+}
+
+class Grid extends Component {
+  final paint = Paint()
+    ..color = const Color(0xffa9a9a9)
+    ..style = PaintingStyle.stroke
+    ..strokeWidth = 1;
+  @override
+  void render(Canvas canvas) {
+    for (var i = 0; i < 50; i++) {
+      canvas.drawLine(Offset(0, i * 25), Offset(500, i * 25), paint);
+      canvas.drawLine(Offset(i * 25, 0), Offset(i * 25, 500), paint);
+    }
+  }
+}

doc/flame/examples/lib/main.dart

@@ -3,6 +3,7 @@ import 'dart:html'; // ignore: avoid_web_libraries_in_flutter
 import 'package:doc_flame_examples/decorator_blur.dart';
 import 'package:doc_flame_examples/decorator_grayscale.dart';
 import 'package:doc_flame_examples/decorator_rotate3d.dart';
+import 'package:doc_flame_examples/decorator_shadow3d.dart';
 import 'package:doc_flame_examples/decorator_tint.dart';
 import 'package:doc_flame_examples/drag_events.dart';
 import 'package:doc_flame_examples/tap_events.dart';
@@ -14,27 +15,16 @@ void main() {
   if (page.startsWith('?')) {
     page = page.substring(1);
   }
-  Game? game;
-  switch (page) {
-    case 'tap_events':
-      game = TapEventsGame();
-      break;
-    case 'drag_events':
-      game = DragEventsGame();
-      break;
-    case 'decorator_blur':
-      game = DecoratorBlurGame();
-      break;
-    case 'decorator_grayscale':
-      game = DecoratorGrayscaleGame();
-      break;
-    case 'decorator_rotate3d':
-      game = DecoratorRotate3DGame();
-      break;
-    case 'decorator_tint':
-      game = DecoratorTintGame();
-      break;
-  }
+  final routes = <String, Game Function()>{
+    'decorator_blur': DecoratorBlurGame.new,
+    'decorator_grayscale': DecoratorGrayscaleGame.new,
+    'decorator_rotate3d': DecoratorRotate3DGame.new,
+    'decorator_shadow3d': DecoratorShadowGame.new,
+    'decorator_tint': DecoratorTintGame.new,
+    'drag_events': DragEventsGame.new,
+    'tap_events': TapEventsGame.new,
+  };
+  final game = routes[page]?.call();
   if (game != null) {
     runApp(GameWidget(game: game));
   } else {

doc/flame/rendering/decorators.md

@@ -119,6 +119,39 @@ Possible uses:
 - 3d falling particles such as snowflakes or leaves.
 
 
+### Shadow3DDecorator
+
+```{flutter-app}
+:sources: ../flame/examples
+:page: decorator_shadow3d
+:show: widget code infobox
+:width: 180
+:height: 160
+```
+
+This decorator renders a shadow underneath the component, as if the component was a 3D object
+standing on a plane. This effect works best for games that use isometric camera projection.
+
+The shadow produced by this generator is quite flexible: you can control its angle, length, opacity,
+blur, etc. For a full description of what properties this decorator has and their meaning, see the
+class documentation.
+
+```dart
+final decorator = Shadow3DDecorator(
+  base: Vector2(100, 150),
+  angle: -1.4,
+  xShift: 200,
+  yScale: 1.5,
+  opacity: 0.5,
+  blur: 1.5,
+);
+```
+
+The primary purpose of this decorator is to add shadows on the ground to your components. The main
+limitation is that the shadows are flat and cannot interact with the environment. For example, this
+decorator cannot handle shadows that fall onto walls or other vertical structures.
+
+
 ## Using decorators
 
 ### HasDecorator mixin

packages/flame/lib/rendering.dart

@@ -1,3 +1,4 @@
 export 'src/rendering/decorator.dart' show Decorator;
 export 'src/rendering/paint_decorator.dart' show PaintDecorator;
 export 'src/rendering/rotate3d_decorator.dart' show Rotate3DDecorator;
+export 'src/rendering/shadow3d_decorator.dart' show Shadow3DDecorator;

packages/flame/lib/src/rendering/shadow3d_decorator.dart

@@ -0,0 +1,153 @@
+import 'dart:ui';
+
+import 'package:flame/src/rendering/decorator.dart';
+import 'package:vector_math/vector_math_64.dart';
+
+/// [Shadow3DDecorator] casts a realistic-looking shadow from the component
+/// onto the ground.
+///
+/// This decorator is suitable for games that use an isometric projection.
+///
+/// The shadows are very flexible, allowing for different positions of sun in
+/// the sky, and even supporting airborne objects.
+///
+/// Still, these are not real 3D shadows cast by real 3D objects on a real 3D
+/// terrain, so many limitations apply. For example, the shadow must fall on
+/// the flat ground, having the sun too high in the sky is undesirable as it
+/// would betray the fact that the component is really flat, etc.
+class Shadow3DDecorator extends Decorator {
+  Shadow3DDecorator({
+    Vector2? base,
+    double? ascent,
+    double? angle,
+    double? xShift,
+    double? yScale,
+    double? blur,
+    double? opacity,
+  })  : _base = base?.clone() ?? Vector2.zero(),
+        _ascent = ascent ?? 0,
+        _angle = angle ?? -1.4,
+        _shift = xShift ?? 100.0,
+        _scale = yScale ?? 1.0,
+        _blur = blur ?? 0,
+        _opacity = opacity ?? 0.6;
+
+  /// Coordinates of the point where the component "touches the ground". If the
+  /// component is airborne (i.e. [ascent] is non-zero), then this should be the
+  /// coordinate of the point where the component would have touched the ground
+  /// if it landed.
+  ///
+  /// This point is in the parent's coordinate space.
+  Vector2 get base => _base;
+  final Vector2 _base;
+  set base(Vector2 value) {
+    _base.setFrom(value);
+    _transformMatrix = null;
+  }
+
+  /// How high is the component above the ground.
+  double get ascent => _ascent;
+  double _ascent;
+  set ascent(double value) {
+    _ascent = value;
+    _transformMatrix = null;
+  }
+
+  /// The amount of skew the shadow is experiencing. The value of 0 corresponds
+  /// to the shadow being right behind (or in front of) the object. Positive
+  /// shift skews the shadow to the right if it's behind the object, or to the
+  /// left if the shadow is in front of the object. Negative shift skews in the
+  /// opposite direction.
+  ///
+  /// This property should be determined by the meridian position of the sun.
+  double get xShift => _shift;
+  double _shift;
+  set xShift(double value) {
+    _shift = value;
+    _transformMatrix = null;
+  }
+
+  /// The length of the shadow relative to the height of the object. If the sun
+  /// is 45º above the horizon, this scale will be 1. When the sun is higher in
+  /// the sky, the scale factor should be less than 1, and when the sun is
+  /// lower, the scale factor ought to be greater than 1.
+  double get yScale => _scale;
+  double _scale;
+  set yScale(double value) {
+    _scale = value;
+    _transformMatrix = null;
+  }
+
+  /// Visual angle between a vertically standing component and the ground. This
+  /// angle is determined by your isometric projection. Use negative values
+  /// smaller than τ/4 (1.57) in magnitude to create shadows that are behind the
+  /// objects. Use positive angles that are slightly above τ/4 to make shadows
+  /// that are in front of the objects.
+  double get angle => _angle;
+  double _angle;
+  set angle(double value) {
+    _angle = value;
+    _transformMatrix = null;
+  }
+
+  /// The amount of blur to apply to the shadow. The value of 0 produces crisp
+  /// shadows with sharp edges, whereas positive [blur] produces softer-looking
+  /// shadows.
+  ///
+  /// Strictly speaking, the parts of the object that are closer to the ground
+  /// ought to experience less blur than those that are higher up. However, this
+  /// is not supported by this decorator. Still, you can try setting the amount
+  /// of blur proportional to the height of the object, or dependent on its
+  /// ascent above the ground.
+  double get blur => _blur;
+  double _blur;
+  set blur(double value) {
+    _blur = value;
+    _paint = null;
+  }
+
+  /// Shadow's intensity. The value of 1 will create a hard pitch-black shadow,
+  /// which can only happen when there are no ambient sources of light (e.g. in
+  /// a cave). Values close to 0 will make the shadow barely visible, such as
+  /// on a cloudy day.
+  double get opacity => _opacity;
+  double _opacity;
+  set opacity(double value) {
+    _opacity = value;
+    _paint = null;
+  }
+
+  Paint? _paint;
+  Paint _makePaint() {
+    final paint = Paint();
+    final color = Color.fromRGBO(0, 0, 0, opacity);
+    paint.colorFilter = ColorFilter.mode(color, BlendMode.srcIn);
+    if (_blur > 0) {
+      paint.imageFilter = ImageFilter.blur(sigmaX: blur, sigmaY: blur / _scale);
+    }
+    return paint;
+  }
+
+  Matrix4? _transformMatrix;
+  Matrix4 _makeTransform() {
+    return Matrix4.identity()
+      ..translate(0.0, 0.0, _scale * _ascent)
+      ..setEntry(3, 2, 0.001)
+      ..rotateX(_angle)
+      ..scale(1.0, _scale)
+      ..translate(-base.x - _shift, -base.y);
+  }
+
+  @override
+  void apply(void Function(Canvas) draw, Canvas canvas) {
+    _transformMatrix ??= _makeTransform();
+    _paint ??= _makePaint();
+
+    canvas.saveLayer(null, _paint!);
+    canvas.translate(base.x + _shift, base.y);
+    canvas.transform(_transformMatrix!.storage);
+    draw(canvas);
+    canvas.restore();
+    draw(canvas);
+  }
+}