Custom blend samples and doc

com.unity.cinemachine/CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to this package will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
-## [3.1.5] - 2025-012-31
+## [3.1.5] - 2025-12-31
 ### Unreleased
 
 ### Bugfixes
@@ -22,6 +22,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Added `CinemachineConfiner2D.CameraWasDisplaced()` and `CinemachineConfiner2D.GetCameraDisplacementDistance()` methods.
 - Added `InputAxisControllerBase.GetController()` method, to conveniently fetch an Input Controller having a specific name.
 - Added `InputAxisControllerBase.TriggerRecentering()` to trigger recentering of an axis having a specific name.
+- Added PerspectiveToOrthoCustomBlend sample scene.
 - Added "Recenter" button to input axis inspector, to immediately center the axis.
 - Added new Portals sample scene to illustrate camera teleportation.
 

com.unity.cinemachine/Documentation~/ControllingAndCustomizingBlends.md

@@ -0,0 +1,62 @@
+# Control and customize blends
+
+Cinemachine offers a number of ways to control how one camera blends to another when the active camera changes.
+
+* The easiest and most common ways involve setting up assets to define rules about how to blend between specific cameras or families of cameras. 
+
+* For more advanced users, it's possible to drive blend styles based on game events or other dynamic criteria, and even to customize the blend algorithm itself, but these techniques require some custom coding.
+
+## Default blend
+
+The most basic strategy is to set up a **Default Blend** in the [Cinemachine Brain](CinemachineBrain.md). Cinemachine uses this blend setting for all blends that are not covered by more specific settings and rules.
+
+**Default Blend** is available in the Cinemachine Brain, and in Cinemachine Manager Cameras which themselves control and blend between a set of child cameras, such as [Clear Shot Camera](CinemachineClearShot.md) and [State-Driven Camera](CinemachineStateDrivenCamera.md).
+
+## Custom blends with Blender Settings asset
+
+All Cinemachine components that have a **Default Blend** property also have a **Custom Blends** setting which holds a [Blender Settings asset](CinemachineBlending.md).
+
+A Blender Settings asset contains a list of blend settings to apply when blending between cameras with specific names. With this asset, you can control how individual cameras blend to other cameras by setting their blend curves and blend durations.
+
+Any blends with cameras that are not listed in the **Blender Settings** rules fall back to the **Default Blend**.
+
+## Timeline shot overlapping
+
+Timeline explicitly controls blends that you make by [overlapping Cinemachine Shots](setup-timeline.md) on the Timeline's [Cinemachine Track](concept-timeline.md). These blends are not affected by the other blend control settings like **Default Blend** and **Custom Blends** with Blender Settings assets.
+
+The blend duration is determined by the overlap size, and you can control the blend curve with the easing curves specified in the Cinemachine Shot (which by default are ease-in-ease-out).
+
+> [!NOTE]
+> This precise control is obtained only when overlapping Cinemachine Shots. If you use [Activation Tracks in Timeline](https://docs.unity3d.com/Packages/com.unity.timeline@latest/index.html?subfolder=/manual/insp-trk-act.html) to activate and deactivate Cinemachine Cameras, then the standard blending controls (**Default Blend** and **Custom Blends** with Blender Settings asset) always apply for those blends.
+
+## Blend Hints
+
+Each [Cinemachine Camera](CinemachineCamera.md) has a **Blend Hint** property. This influences the way that the camera is blended with other cameras. It doesn't control the timing, but rather the algorithm, so it's orthogonal to the other controls mentioned above. 
+
+The hints you set there can affect the way Cinemachine interpolates the camera position and rotation. You can control whether the LookAt target is taken into account. You can also control whether the blend is from a live moving camera or based on a snapshot of the outgoing camera taken at the start of the blend.
+
+## `CinemachineCore.GetBlendOverride`
+
+Every time Cinemachine creates a blend, a `CinemachineCore.GetBlendOverride` delegate is called giving you a chance to override the settings of that blend based on arbitrary dynamic criteria.
+
+If you install a handler for this delegate, then your handler can check things like game context and decide either to allow the blend to remain as-is, or to override such things as blend style, blend duration, or blend algorithm.
+
+This is an advanced technique and requires scripting to implement the event handler.
+
+> [!NOTE]
+> This delegate is NOT called for blends created by overlapping Timeline Shots. There is an expectation that Timeline precisely controls the blending, and this cannot be overridden.
+
+## `CinemachineCore.GetCustomBlender`
+
+The most advanced level of control is to customize the blend algorithm itself. Cinemachine has a sophisticated algorithm for lerping camera states (`CameraState.Lerp()`), which interpolates position, rotation, lens settings, and other attributes while taking into account blend hints and the screen position of the lookAt target.
+
+These things are all lerped at the same rate, so position, rotation, and lens all change together. You may have a situation where you want the rotation to happen first, or the position to follow a path, or some other requirement that Cinemachine doesn't handle natively.
+
+In this case, you can author a custom blender, which implements the `CinemachineBlend.IBlender` interface. You can provide Cinemachine with this blender by hooking into the `CinemachineCore.GetCustomBlender` delegate. Cinemachine calls this delegate whenever a blend is created, even from Timeline. You can check the cameras to be blended and whatever other state you like, and either provide a custom blender or return null for the default one.
+
+Cinemachine comes with two [sample scenes](samples-tutorials.md), `Early LookAt Custom Blend` and `Perspective To Ortho Custom Blend`, which illustrate this technique. Coding profficiency is required.
+
+## Additional resources
+
+* [Camera control and transitions](concept-camera-control-transitions.md)
+* [Cinemachine and Timeline](concept-timeline.md)

com.unity.cinemachine/Documentation~/TableOfContents.md

@@ -36,6 +36,7 @@
   * [Filtering impulses](CinemachineImpulseFiltering.md)
 * [Split screen and multiple Unity Cameras](CinemachineMultipleCameras.md)
 * [Use Input System with Cinemachine](InputSystemComponents.md)
+* [Control and customize blends](ControllingAndCustomizingBlends.md)
 * [Samples and tutorials](samples-tutorials.md)
   * [Import samples to your project](samples-import.md)
   * [Simple Player Controller](SimplePlayerController.md)

com.unity.cinemachine/Documentation~/concept-camera-control-transitions.md

@@ -57,4 +57,5 @@ _**Cut example:** two Cinemachine Cameras taking turns controlling the Unity Cam
 
 ## Additional resources
 
-* [Set up multiple Cinemachine Cameras and transitions](setup-multiple-cameras.md)
+* [Set up multiple Cinemachine Cameras and transitions](setup-multiple-cameras.md)
+* [Control and customize blends](ControllingAndCustomizingBlends.md)

com.unity.cinemachine/Documentation~/samples-tutorials.md

@@ -24,14 +24,15 @@ Once you import the 3D Samples set, the following scenes are available in the `A
 | :--- | :--- |
 | **Brain Update Modes** | <ul> <li>Prevent animated characters from jittering in the camera view.</li> <li>Understand the effect of the Cinemachine Brain Update Method according to the way you move the framed characters.</li> </ul> |
 | **Clear Shot** | <ul> <li>Set up a group of fixed and moving cameras that target the same player from different perspectives.</li> <li>Automatically select the best shot based on occlusion (when the current camera loses sight of the player).</li> </ul> |
-| **Custom Blends** | <ul> <li>Author a custom camera blending algorithm.</li> <li>Map the custom algorithm to a Cinemachine Brain event.</li> </ul> |
 | **Cutscene** | <ul> <li>Set up a cutscene with camera blends and asset animations in Timeline.</li> <li>Trigger a cutscene that blends in from the game camera, plays through, and then blends back out to the game camera.</li> </ul> |
+| **Early LookAt Custom Blend** | <ul> <li>Author a custom camera blending algorithm.</li> <li>Hook into Cinemachine's blend creation to override the default blend algorithm.</li> </ul> |
 | **Fly around** | <ul> <li>Set up a first-person fly around camera with basic height and speed controls. |
 | **FreeLook Deoccluder** | <ul> <li>Set up a free look camera that handles occlusion by walls to keep the player in view.</li> <li>Set up the scene and the camera to consider certain objects as transparent and ignore them in the occlusion evaluation.</li> </ul> |
 | **FreeLook on Spherical Surface** | <ul> <li>Set up a free look camera that automatically re-orients to follow a player that can walk on any surface.</li> <li>Set up the camera to follow the character either lazily or actively.</li> </ul> |
 | **Impulse Wave** | <ul> <li>Set up the the camera and objects in the scene to make them react to impulse waves.</li> <li>Invoke an impulse from a fixed epicenter.</li> <li>Trigger an impulse when the player jumps.</li> </ul> |
 | **Lock-on Target** | <ul> <li>Set up a simple third-person free look camera to look at the player and rotate around it with the mouse.</li> <li>Set up a camera that looks at the player and locks on a boss character when the player enters a trigger zone.</li> </ul>  |
 | **Mixing Camera** | <ul> <li>Set up a camera group that continuously blends multiple cameras as a function of the car speed.</li> <li>Set up a fixed camera that activates for a cut-in when the car enters a two-ramp stunt zone, to frame the car jump from the side.</li> </ul> |
+| **Perspective To Ortho Custom Blend** | <ul> <li>Author a custom camera blending algorithm.</li> <li>Hook into Cinemachine's blend creation to override the default blend algorithm.</li>  <li>Create a smooth perspective-to-orthographic blend, which is not natively supported by Cinemachine.</li> </ul> |
 | **Portals** | <ul> <li>Seamlessly teleport a player and its FreeLook camera.</li>  </ul> |
 | **Running Race** | <ul> <li>Set up a clear shot group of cameras that each follow a different runner.</li> <li>Customize the clear shot quality assessment to always have the race leader in the center of the camera view.</li> <li>Set up an on-demand camera that frames all runners.</li> <li>Emulate players that move along predefined paths.</li> </ul>  |
 | **Split Screen Car** | <ul> <li>Display two racing cars in a split screen configuration.</li> </ul> |