)]}'
{
  "commit": "5deb2deeb3507a39fca4ee17d29e45113302b93e",
  "tree": "3ea8eea0f2455e0388579af6903dee424ba564c7",
  "parents": [
    "e320c993c4ee501b488dadb0a6bfe64f91ce7404"
  ],
  "author": {
    "name": "David Davidović",
    "email": "david@davidovic.io",
    "time": "Sun Oct 20 00:51:46 2024 +0200"
  },
  "committer": {
    "name": "GitHub",
    "email": "noreply@github.com",
    "time": "Sat Oct 19 15:51:46 2024 -0700"
  },
  "message": "Drop shadow overhaul: improve correctness and performance (#2548)\n\n## High-level summary\r\n\r\nThis PR introduces a large change to how drop shadows are rendered, introducing an `applyShadowsToLayers` flag which, by analogy to `applyOpacitiesToLayers`, allows layers to be treated as a whole for the purposes of drop shadows, improving the accuracy and bringing lottie-android in line with other renderers (lottie-web and lottie-ios).\r\n\r\nSeveral different codepaths for different hardware/software combinations are introduced to ensure the fastest rendering available, even on legacy devices.\r\n\r\nThe calculation of shadow direction with respect to transforms is improved so that the output matches lottie-web and lottie-ios.\r\n\r\nImage layers now cast shadows correctly thanks to a workaround to device-specific issues when combining `Paint.setShadowLayer()` and bitmap rendering.\r\n\r\nEven in non-`applyShadowsToLayers` mode, correctness is improved by allowing the shadow-to-be-applied to propagate in a similar way as alpha. This allows some amount of visual fidelity to be recovered for animations or environments where enabling `applyShadowsToLayers` is not possible.\r\n\r\nA number of issues that caused incorrect rendering in some other cases have been fixed.\r\n\r\n## Background\r\n\r\n### Drop shadows in Lottie\r\n\r\nLottie specifies drop shadows as a tuple of (angle, distance, radius, color, alpha), with each element being animatable.\r\n\r\nThe consensus behavior for the rendering of a layer with a drop shadow, which seems to be mostly respected in lottie-web and lottie-ios, seems to be:\r\n\r\n1. Evaluate the values at the current frame for angle (`theta`), distance (`d`), radius (`r`), color with alpha (`C`).\r\n2. Apply the layer transform and render the layer normally to a surface `So` (original layer).\r\n3. Copy `So` to new surface `Ss` (shadow).\r\n4. Apply a gaussian blur of radius `r\u0027 \u003d c * r` to `Ss`, where `c` is some platform-specific constant intended to normalize blur implementations between platforms. (Ours is 0.33, lottie-web\u0027s is 0.25; see https://github.com/airbnb/lottie-android/pull/2541).\r\n5. Tint `Ss` with the color and combine the alpha by applying the following for each pixel `P`: `P.rgb \u003d C.rgb * P.a; P.a \u003d C.a * P.a`.\r\n6. Now the shadow is ready on `Ss`, and needs to be drawn into its final position.\r\n7. Convert from polar coordinates `theta` and `d` into `dx` and `dy`, with the 0 position at 12 o\u0027clock: `dx \u003d d * cos(theta - pi/2); dy \u003d d*sin(theta - pi/2)`.\r\n8. Draw `Ss` onto `Si` (intermediate surface) with a translation of `(dx, dy)`.\r\n9. Draw `So` (original layer) onto `Si` with identity transform.\r\n10. Compose `Si` into the framebuffer using the layer\u0027s alpha and blend mode.\r\n\r\nSome non-obvious consequences of the definition above:\r\n- The angle, distance, and radius are relative to the layer post-transform, not pre-transform. That is, rotating the layer (via its transform) still keeps the same screen-space direction of the shadow, and scaling the layer (via its transform) still keeps the same screen-space shadow blur radius.\r\n- The drop shadow is not based on any derived outline, so a layer\u0027s drop shadow can be seen through its non-fully-opaque pixels. At the same time, reducing the alpha of a pixel in a layer reduces its alpha in the drop shadow.\r\n- A layer\u0027s shadow and the layer do not blend on top of each other on the final canvas in case the layer has a blend mode or alpha. Instead, the shadow and the layer are alpha-blended with each other, and the result is then composited onto the canvas.\r\n  - In case the layer has a normal blend mode, this is equivalent to alpha-blending the layer\u0027s shadow and then the shadow onto the canvas separately.\r\n\r\n### Drop shadows in lottie-android currently\r\n\r\nlottie-android\u0027s current implementation of drop shadows differs in important ways:\r\n1. **Shadows are applied per-shape.** This means that a case like a shape with both fill and stroke has incorrect shadows, since both the fill and the stroke render a separate shadow on top of each other.\r\n2. **Precomp layer shadows are ignored.** This means that a precomp cannot cause any of its child shapes to cast a shadow. This is a consequence of the current implementation of (1).\r\n3. **Image layers do not render correct shadows,** due to the minefield that is the support matrix (or in Android\u0027s case, a more apt name would be a support tensor) of Android\u0027s graphics stack - `setShadowLayer()` simply doesn\u0027t work for images consistently. (See the last image in https://github.com/airbnb/lottie-android/pull/2523#issue-2428578510.)\r\n\r\n## Contributions of this PR\r\n\r\nThis PR introduces the following improvements and additions.\r\n\r\n1. **Move the drop shadow model from individual content elements to layers,** and add some missing keypath callbacks. This is a prerequisite for handling drop shadows on a layer level.\r\n2. **An `OffscreenLayer` implementation,** which serves as an abstraction that can replace `canvas.saveLayer()` for off-screen rendering and composition onto the final bitmap, but with the important distinction that it can also handle drop shadows, and possibly use hardware-accelerated `RenderNode`s and `RenderEffects` where available.\r\n    - To use an `OffscreenLayer`, call its `.start()` method with a parent canvas and a `ComposeOp`, and draw on the *returned canvas.* Once finished, call `OffscreenLayer.finish()` to compose everything from the returned canvas to the parent canvas, applying alpha, blend mode, drop shadows, and color filters.\r\n    - `OffscreenLayer` makes a dynamic decision on what to use for rendering - a no-op, forward to `.saveLayer()`, a HW-accelerated `RenderNode`, or a software bitmap, depending on the requested `ComposeOp` and hardware/SDK support.\r\n    - The hope is that `OffscreenLayer` becomes a useful abstraction that can be extended to e.g. support hardware blurs, multiple drop shadows, or to support mattes in a hardware-accelerated fashion where possible. \r\n3. **The `applyShadowsToLayers` flag** which, by analogy to `applyOpacityToLayers`, turns on a more accurate mode that implements the drop shadow algorithm described above.\r\n    - `OffscreenLayer` is used to apply alpha if `applyOpacityToLayers` is enabled, and to apply shadows if `applyShadowsToLayers` is enabled. The cost is paid only once if both alpha and drop shadows are present on a layer.\r\n    - Not all `saveLayer()` calls in the code have been rewritten to use `OffscreenLayer` - the blast radius is minimized. `OffscreenLayer` is presently used only to apply alpha and drop shadows, and blend mode and color filters are still applied in `BaseLayer` using `saveLayer()` directly.\r\n4. **More accurate shadow transformations.** Previously, the angle and distance were pre-transform, and only the radius was post-transform (contrary to step (2) of the algorithm). We correct this to match other renderers.\r\n5. **More complete shadow handling even when `applyShadowsToLayers` is `false`:** we plumb the shadow through `.draw()` and `drawLayer()` calls similarly to alpha, and this allows us to render per-shape shadows on children of composition layers too.\r\n6. ***Workaround for drop shadows on image layers.**\r\n    - The workaround relies on `OffscreenLayer` as well, and image layers now render shadows properly in all cases.\r\n7. **Fixes to a few subtle issues** causing incorrect rendering in other cases. (will be marked using PR comments, I might have forgotten some)\r\n\r\n## Open questions\r\n\r\n* **Should `applyShadowsToLayers` be `true` by default?** Some codepaths, such as when rendering purely via software, can be slow if shadow-casting layers are exceedingly large. But, the performance is still acceptable, and in the vast majority of cases everything is quite snappy.\r\n* **Have I introduced any regressions?** The snapshot tests should answer this.\r\n* **How does this perform on older devices?** `applyShadowsToLayers` plus an old device should trigger the purely-software shadow rendering mode. Simulating this in condition manually yields accurate results, and the performance seems surprisingly good, but it\u0027s unclear what will happen on a lower-end phone. There\u0027s also always the possibility of some device subtlety being missed. I don\u0027t have access to an older Android device.\r\n\r\n## Testcases\r\n\r\nThese files now match between lottie-web and lottie-android:\r\n\r\n[drop_shadow_comparator.json](https://github.com/user-attachments/files/16997070/drop_shadow_comparator.json)\r\n\r\n[simple_shadow_casters_ll2.json](https://github.com/user-attachments/files/16997084/simple_shadow_casters_ll2.json)\r\n\r\nThe files from this earlier PR still all render the same: https://github.com/airbnb/lottie-android/pull/2523, with the exception of the fix for image layer bug, which fixes the rendering of the Map icon as mentioned in the comment of that PR.\r\n\r\nThis file has been used as a perf stress test with many \u003c255 opacity precomps, some stacked inside each other, that must all be blended separately: [precomp_opacity_killer.json](https://github.com/user-attachments/files/16997261/precomp_opacity_killer.json)",
  "tree_diff": [
    {
      "type": "modify",
      "old_id": "fbecccd9cfee637020fabf344b5634314db67680",
      "old_mode": 33188,
      "old_path": "lottie-compose/api/lottie-compose.api",
      "new_id": "03d752ee5b7ad20ef0366f732b2203799ca25961",
      "new_mode": 33188,
      "new_path": "lottie-compose/api/lottie-compose.api"
    },
    {
      "type": "modify",
      "old_id": "c4644009b3e0bfe4146a9123055bcae048182eb9",
      "old_mode": 33188,
      "old_path": "lottie-compose/src/main/java/com/airbnb/lottie/compose/LottieAnimation.kt",
      "new_id": "d372b46405f58dca1e6c3f86e73183d728cc5f69",
      "new_mode": 33188,
      "new_path": "lottie-compose/src/main/java/com/airbnb/lottie/compose/LottieAnimation.kt"
    },
    {
      "type": "modify",
      "old_id": "6152fef7b70e1623ceb66f60599ad461d949d1e2",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/LottieAnimationView.java",
      "new_id": "8972e08a0618c9cf7dfd3f4dfa1ad4069b25f032",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/LottieAnimationView.java"
    },
    {
      "type": "modify",
      "old_id": "5a0de484205558175765dfdb8a6e92fd4fcba0dc",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/LottieDrawable.java",
      "new_id": "f9bc737b49c69d3d40173fa74c6138c148dded3a",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/LottieDrawable.java"
    },
    {
      "type": "modify",
      "old_id": "3c0e5ebda5e81eabdd5d85bbc998ba9a65f0d88c",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/animation/content/BaseStrokeContent.java",
      "new_id": "183e33d0ea40f6ae0b8d28a2cfef7947fe45a248",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/animation/content/BaseStrokeContent.java"
    },
    {
      "type": "modify",
      "old_id": "cc3d1661e9f5b5820615f757685be4d95ef99f13",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/animation/content/ContentGroup.java",
      "new_id": "951c242ef3ea9389d2b1947ab444e54d571e8299",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/animation/content/ContentGroup.java"
    },
    {
      "type": "modify",
      "old_id": "c6501e30943b3b7a869857c743f58454e1662093",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/animation/content/DrawingContent.java",
      "new_id": "a3f5e4c0f83021b8aeedf140c690cf4cfba6faff",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/animation/content/DrawingContent.java"
    },
    {
      "type": "modify",
      "old_id": "5a59fc104a30bb2f68216df3085c04c214e01143",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/animation/content/FillContent.java",
      "new_id": "5f4a5fb7136eb9dfb178b6e6aa297933d0348c1a",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/animation/content/FillContent.java"
    },
    {
      "type": "modify",
      "old_id": "944d769ac1ef985e3e710f03c2511e0f47fac4aa",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/animation/content/GradientFillContent.java",
      "new_id": "20a511935a2b7537154f626b477a9a803278a90d",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/animation/content/GradientFillContent.java"
    },
    {
      "type": "modify",
      "old_id": "d5f78ddd907cc54174083b910adfd5d3bba66347",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/animation/content/GradientStrokeContent.java",
      "new_id": "5b5a74fc8fda4976e0948c348d3d3360fd114d9b",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/animation/content/GradientStrokeContent.java"
    },
    {
      "type": "modify",
      "old_id": "4a721fb5eefe151e10c5a13f06daf01b891256dc",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/animation/content/RepeaterContent.java",
      "new_id": "f59b3e86fbaa907a1985de58dba32a0b2dffda76",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/animation/content/RepeaterContent.java"
    },
    {
      "type": "modify",
      "old_id": "212aa55f4a95f470097470b2fd90728756c7ef5c",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/animation/content/StrokeContent.java",
      "new_id": "c68298b2774f6493dff58ac9fa684b70d3c90f69",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/animation/content/StrokeContent.java"
    },
    {
      "type": "modify",
      "old_id": "425b8a4bf53facb855ebad80157ffa101a9e53bd",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/animation/keyframe/DropShadowKeyframeAnimation.java",
      "new_id": "643b03ee0330c067848ac75861b6062dc6bf1925",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/animation/keyframe/DropShadowKeyframeAnimation.java"
    },
    {
      "type": "modify",
      "old_id": "ca56d277bdd61a145d40b50af608095928770f96",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/model/layer/BaseLayer.java",
      "new_id": "daaad778a3dcad157c2c5dd3d7e6e88f893dca09",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/model/layer/BaseLayer.java"
    },
    {
      "type": "modify",
      "old_id": "92745ab79992d3337cfddcf051059d58393796e7",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/model/layer/CompositionLayer.java",
      "new_id": "8752d47fb61d3a7ac6bfdcfe639c63f25522184e",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/model/layer/CompositionLayer.java"
    },
    {
      "type": "modify",
      "old_id": "e99a120f9aa331420cafaf32c1865297850b1593",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/model/layer/ImageLayer.java",
      "new_id": "bb757a3169ad3fbcf3c68ab2429d8edef7996e5e",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/model/layer/ImageLayer.java"
    },
    {
      "type": "modify",
      "old_id": "045cabfed408c2ffc968557aa3b267925205afb2",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/model/layer/NullLayer.java",
      "new_id": "9af09afe4d99304de8a4c3751b3a6ffb87a1de37",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/model/layer/NullLayer.java"
    },
    {
      "type": "modify",
      "old_id": "3a82138f2c17c2892adf6dcc1441b50dde0b3a59",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/model/layer/ShapeLayer.java",
      "new_id": "4eafb63d22afb29b13001f50e6337bf4d9e52c30",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/model/layer/ShapeLayer.java"
    },
    {
      "type": "modify",
      "old_id": "19e7d53bd3bfb685d2af4fd99eb0eea38397d01f",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/model/layer/SolidLayer.java",
      "new_id": "3fbf4594d35e32384d0b4432012110bb69f5525d",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/model/layer/SolidLayer.java"
    },
    {
      "type": "modify",
      "old_id": "309950cec804f1a6fd9442fcd85801e16d359557",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/model/layer/TextLayer.java",
      "new_id": "d3a3c11fd51592ae6b2f76741010939d9c1683b1",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/model/layer/TextLayer.java"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "cb50eaf6f59785af349c30ec604e25c94d505b66",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/utils/DropShadow.java"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "892f96f93a1ef5b2c9968ae04dd027a1c9471ffd",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/utils/OffscreenLayer.java"
    },
    {
      "type": "modify",
      "old_id": "c48a6d32ae91cf3419ef8069477be8499331a928",
      "old_mode": 33188,
      "old_path": "lottie/src/main/java/com/airbnb/lottie/utils/Utils.java",
      "new_id": "788c9f3d9c4f0498ae5d1d54312e8fe5ca1f781d",
      "new_mode": 33188,
      "new_path": "lottie/src/main/java/com/airbnb/lottie/utils/Utils.java"
    },
    {
      "type": "modify",
      "old_id": "d9299f36fff0f3fa8aded61b2125a9cb9266fae8",
      "old_mode": 33188,
      "old_path": "lottie/src/main/res/values/attrs.xml",
      "new_id": "be1fdda3075a3ab3b33015bd7712c12e4bdd0014",
      "new_mode": 33188,
      "new_path": "lottie/src/main/res/values/attrs.xml"
    }
  ]
}