diff --git a/com.unity.cinemachine/Documentation~/CinemachineGroupFraming.md b/com.unity.cinemachine/Documentation~/CinemachineGroupFraming.md index dde0ef60a..4367aefc6 100644 --- a/com.unity.cinemachine/Documentation~/CinemachineGroupFraming.md +++ b/com.unity.cinemachine/Documentation~/CinemachineGroupFraming.md @@ -1,30 +1,36 @@ -# Group Framing +# Cinemachine Group Framing component -This CinemachineCamera extension adds the ability to frame one or more targets when they are members of a CinemachineTargetGroup. It can be used to dynamically adjust the zoom or to move the camera closer to or farther from the targets, to keep them in the frame at the desired size. +This component is a Cinemachine Camera extension that adds the ability to frame one or more targets when they are members of a Cinemachine Target Group. You can use it to dynamically adjust the zoom or to move the camera closer to or farther from the targets, to keep them in the frame at the desired size. -For this to work, the CinemachineCamera's Tracking Target must be a CinemachineTargetGroup, with at least one member, and having a nonzero size. +To enable the functionality of the Cinemachine Group Framing component, you must: +* Add it to an existing GameObject that contains a [Cinemachine Camera](CinemachineCamera.md) component. +* Create a separate GameObject with a [Cinemachine Target Group](CinemachineTargetGroup.md) component that targets the GameObjects you want to frame together in your Scene. + * Make sure the Cinemachine Target Group has at least one member, and has a nonzero size. +* Set the Cinemachine Camera's Tracking Target property to target the created Cinemachine Target Group. -## Properties - -| **Property:** || **Function:** | -|:---|:---|:---| -| __Framing Mode__ || Specifies the screen dimensions to consider when framing. | -| | _Horizontal_ | Consider only the horizontal dimension. Ignore vertical framing. | -| | _Vertical_ | Consider only the vertical dimension. Ignore horizontal framing. | -| | _Horizontal And Vertical_ | Use the larger of the horizontal and vertical dimensions to get the best fit. | -| __Adjustment Mode__ || How to adjust the camera in depth to get the desired framing. You can zoom, dolly in or out, or do both. | -| | _Zoom Only_ | Don’t move the camera, only adjust the FOV. | -| | _Dolly Only_ | Move the camera, don’t change the FOV. | -| | _Dolly Then Zoom_ | Move the camera as much as permitted by the ranges, then adjust the FOV if necessary to make the shot. | -| __Lateral Adjustment__ || How to adjust the camera horizontally and vertically to get the desired framing. You can change position to reframe, or rotate the camera to reframe. | -| | _Change Position_ | Camera is moved horizontally and vertically until the desired framing is achieved. | -| | _Change Rotation_ | Camera is rotated to achieve the desired framing. | -| __Framing Size__ || The screen-space bounding box that the targets should occupy. Use 1 to fill the whole screen, 0.5 to fill half the screen, and so on. | -| __Center Offset__ || A nonzero value will offset the group in the camera frame. | -| __Damping__ || How gradually to make the framing adjustment. A larger number gives a slower response, smaller numbers a snappier one. | -| __Dolly Range__ || The allowable range that the camera may be moved in order to achieve the desired framing. A negative distance is towards the target, and a positive distance is away from the target. | -| __FOV Range__ || If adjusting FOV, it will be clamped to this range. | -| __Ortho Size Range__ || If adjusting Orthographic Size, it will be clamped to this range. | +![](images/ref-component-cinemachine-group-framing.png) +## Properties +> [!NOTE] +> The availability of some properties depend on the type of Unity Camera you're using: [perspective or orthographic](https://docs.unity3d.com/Manual/CamerasOverview.html). +| Property || Function | +| :--- | :--- | :--- | +| **Framing Mode** || Specifies the screen dimensions to consider when framing. | +|| _Horizontal_ | Consider only the horizontal dimension. Ignore vertical framing. | +|| _Vertical_ | Consider only the vertical dimension. Ignore horizontal framing. | +|| _Horizontal And Vertical_ | Use the larger of the horizontal and vertical dimensions to get the best fit. | +| **Framing Size** || The screen-space bounding box that the targets should occupy. Use 1 to fill the whole screen, 0.5 to fill half the screen, and so on. | +| **Center Offset** || Horizontally and vertically offsets the position of the group in the camera frame. | +| **Damping** || How gradually to make the framing adjustment. Larger numbers give a slower response, smaller numbers a snappier one. | +| **Size Adjustment** || How to adjust the camera in depth to get the desired framing. You can zoom, dolly in or out, or do both.
Only available when using a perspective Unity Camera. | +|| _Zoom Only_ | Don’t move the camera, only adjust the Field of View. | +|| _Dolly Only_ | Move the camera, don’t change the Field of View. | +|| _Dolly Then Zoom_ | Move the camera as much as permitted by the ranges, then adjust the FOV if necessary to make the shot. | +| **Lateral Adjustment** || How to adjust the camera horizontally and vertically to get the desired framing. You can change position to reframe, or rotate the camera to reframe.
Only available when using a perspective Unity Camera. | +|| _Change Position_ | Move the camera horizontally and vertically until the desired framing is achieved. | +|| _Change Rotation_ | Rotate the camera to achieve the desired framing. | +| **Fov Range** || Clamps the camera's Field of View to the specified range.
Only available when including Zoom in **Size Adjustment**. | +| **Dolly Range** || Limits the camera movements to the specified range when achieving the desired framing. A negative distance is towards the target, and a positive distance is away from the target.
Only available when including Dolly in **Size Adjustment**. | +| **Ortho Size Range** || Clamps the camera's Orthographic Size to the specified range.
Only available when using an orthographic Unity Camera. | diff --git a/com.unity.cinemachine/Documentation~/images/ref-component-cinemachine-group-framing.png b/com.unity.cinemachine/Documentation~/images/ref-component-cinemachine-group-framing.png new file mode 100644 index 000000000..18223be64 Binary files /dev/null and b/com.unity.cinemachine/Documentation~/images/ref-component-cinemachine-group-framing.png differ diff --git a/com.unity.cinemachine/Documentation~/index.md b/com.unity.cinemachine/Documentation~/index.md index 954c3c858..acf5a9704 100644 --- a/com.unity.cinemachine/Documentation~/index.md +++ b/com.unity.cinemachine/Documentation~/index.md @@ -2,6 +2,9 @@ ![Unity Cinemachine](images/CinemachineSplash.png) +>[!NOTE] +>To use the Cinemachine package, you must install it separately from the Unity Editor. For detailed information about package requirements and installation instructions, refer to [Installation](InstallationAndUpgrade.md). + Cinemachine is a suite of modules for controlling the Unity camera. Cinemachine solves the complex mathematics and logic of tracking targets, composing, blending, and cutting between shots. It is designed to significantly reduce the number of time-consuming manual manipulations and script revisions that take place during development. The procedural nature of these modules makes Cinemachine robust and forgiving. When you make adjustments - for example, change an animation, vehicle speed, terrain, or other GameObjects in your Scene - Cinemachine dynamically adjusts its behavior to make the best shot. There is no need, for example, to re-write camera scripts just because a character turns left instead of right.