Update Camera.ViewportSize with behavior for notched devices

content/en-us/reference/engine/classes/Camera.yaml

@@ -238,6 +238,8 @@ properties:
       viewport to its opposite corner) the camera can view. See
       `Class.Camera.FieldOfView|FieldOfView` for a more general explanation of
       field of view.
+
+      Note that `DiagonalFieldOfView` represents the field of view that is visible by the `Class.Camera` rendering into the fullscreen area which may be occluded by notches or screen cutouts on some devices. See `Class.Camera.ViewportSize|ViewportSize` for more information.
     code_samples:
     type: float
     tags:
@@ -271,6 +273,8 @@ properties:
         using binoculars.
       - Increasing FOV when the player is "sprinting" to give the impression of
         a lack of control.
+
+      Note that `FieldOfView` represents the field of view that is visible by the `Class.Camera` rendering into the fullscreen area which may be occluded by notches or screen cutouts on some devices. See `Class.Camera.ViewportSize|ViewportSize` for more information.
     code_samples:
     type: float
     tags: []
@@ -534,15 +538,28 @@ properties:
     writeCapabilities: []
   - name: Camera.ViewportSize
     summary: |
-      Describes the dimensions, in pixels, of the client's viewport.
+      The dimensions of the device safe area on a Roblox client.
     description: |
-      **ViewportSize** describes the dimensions, in pixels, of the client's
-      viewport.
+      `Class.Camera.ViewportSize` returns the dimensions of the device safe area on the current screen. The device safe area is a rectangle which includes the Roblox top bar area, but does not include any cutouts in the display. The units of `Class.Camera.ViewportSize` are Roblox UI offset units, which may be different from native display pixels.
+
+      <img src="../../../assets/engine-api/enums/ScreenInsets/DeviceSafeInsets.png" width="840"
+      alt="Mobile device screen with cutout showing device safe area." />
+
+      Note: `Class.Camera.ViewportSize` is not equal to the fullscreen area size on displays with cutouts or notches. To obtain the fullscreen area size on all displays, you can query the `AbsoluteSize` property of a `Class.ScreenGui` with `ScreenInsets=None`. See `Enum.ScreenInsets` for a more information about how screen areas are defined.
+      `Class.Camera.ViewportSize` is not equal to the fullscreen size in order to improve cross-platform compatibility and backwards compatibility with legacy experiences.
+
+      <img src="../../../assets/engine-api/enums/ScreenInsets/None.png" width="840"
+      alt="Mobile device screen with cutout showing fullscreen area." />
+
+      Note: `Class.Camera.ViewportSize` is not the actual viewport size the camera uses for rendering. The Camera renders in the fullscreen area. Also the `Class.Camera.FieldOfView` and `Class.Camera.DiagonalFieldOfView` properties are based on the fullscreen area, not `Class.Camera.ViewportSize`.
+
+      To learn more about how your experience will run on a device with notches/cutouts, please see [this post](https://devforum.roblox.com/t/notched-screen-support-full-release/2074324/1).
 
-      This property ignores the GUI inset applied by the top bar, meaning the
-      center of the screen can be found at precisely at 50% of the viewport in
-      both directions. You can find the position of a `Datatype.Vector3` in the
-      world on the viewport using `Class.Camera:WorldToViewportPoint()`.
+      Only one `Class.Camera` has its `Class.Camera.ViewportSize` updated each frame: the `Class.Camera` currently referred to by `Class.Workspace.CurrentCamera`. The `ViewportSize` of all other `Class.Camera`s in your experience won't be updated. This includes `Class.Camera`s that are used for `Class.ViewportFrame`s.
+
+      The initial value of `Class.Camera.ViewportSize` is `(1, 1)`. The `Class.Workspace.CurrentCamera`'s `Class.Camera.ViewportSize` is updated once each frame during the render prepare step.
+
+      For example, a `Class.ViewportFrame` with `Class.ViewportFrame.CurrentCamera` set to a different `Class.Camera` than the `Class.Workspace.CurrentCamera` will have its `ViewportSize` equal to the initial value of `(1, 1)`.
     code_samples:
     type: Vector2
     tags:
@@ -1158,20 +1175,30 @@ methods:
     summary: |
       Creates a unit `Datatype.Ray` from a position on the viewport (in pixels),
       at a given depth from the `Class.Camera`, orientated in the camera's
-      direction. Does not account for the GUI inset.
+      direction. Does not account for the `Enum.ScreenInsets|CoreUISafeInsets` inset.
     description: |
-      This function creates a unit `Datatype.Ray` from a 2D position on the
-      viewport (defined in pixels). This position does **not** account for the
-      GUI inset. The `Datatype.Ray` originates from the `Datatype.Vector3`
-      equivalent of the 2D position in the world at the given depth (in studs)
-      away from the `Class.Camera`.
-
-      As this function does not acknowledge the GUI inset, the viewport position
-      given is not equivalent to the screen position used by GUI elements. If
-      you are not using `Class.ScreenGui.IgnoreGuiInset` and need an otherwise
-      identical function that accounts for the GUI offset, use
+      This function creates a unit `Datatype.Ray` from a 2D position in device safe viewport coordinates,
+      defined in pixels. That is, `(0, 0)` corresponds to the top-left point of the Roblox top bar. The input
+      2D position does **not** account for the `Enum.ScreenInsets|CoreUISafeInsets` inset, but it does
+      account for any `Enum.ScreenInsets|DeviceSafeInsets`.
+
+      <img src="../../../assets/engine-api/classes/Camera/DeviceSafeViewportCoordinates.png" width="840" alt="Diagram showing the origin of the device safe area viewport coordinate system." />
+
+      The `Datatype.Ray` originates from the `Datatype.Vector3` equivalent of the 2D position in the
+      world at the given depth (in studs) away from the `Class.Camera`.
+
+      Note that UI instances use a different coordinate system. `Class.GuiObject.AbsolutePosition` uses
+      the `Enum.ScreenInsets|CoreUISafeInsets` viewport coordinate system, while this function uses the
+      `Enum.ScreenInsets|DeviceSafeInsets` viewport coordinate system. If you would like to specify
+      position in core UI coordinates, please use
       `Class.Camera:ScreenPointToRay()`.
 
+      This function only works for the current Workspace camera. Other cameras,
+      such as those you create for a `Class.ViewportFrame`, have an initial
+      viewport size of `(1, 1)` and are only updated after you set them to
+      `Class.Workspace.CurrentCamera`. The mismatch in viewport size causes the
+      camera to return a ray with an incorrect `Datatype.Ray.Direction`.
+
       This function can be used in conjunction with the
       `Class.Camera.ViewportSize` property to create a ray from the centre of
       the screen, for example:
@@ -1191,28 +1218,20 @@ methods:
       local unitRay = camera:ScreenPointToRay(100, 100)
       local extendedRay = Ray.new(unitRay.Origin, unitRay.Direction * length)
       ```
-
-      This function only works for the current Workspace camera. Other cameras,
-      such as those you create for a `Class.ViewportFrame`, have an initial
-      viewport size of `(1, 1)` and are only updated after you set them to
-      `Class.Workspace.CurrentCamera`. The mismatch in viewport size causes the
-      camera to return a ray with an incorrect `Datatype.Ray.Direction`.
     code_samples:
     parameters:
       - name: x
         type: float
         default:
         summary: |
-          The position on the X axis, in pixels, of the viewport point at which
-          to originate the `Datatype.Ray`. This position does not account for
-          the GUI inset.
+          The position on the **X** axis, in pixels, of the viewport point at which
+          to originate the `Datatype.Ray`, in device safe area coordinates.
       - name: 'y'
         type: float
         default:
         summary: |
-          The position on the Y axis, in pixels, of the viewport point at which
-          to originate the `Datatype.Ray`. This position does not account for
-          the GUI inset.
+          The position on the **Y** axis, in pixels, of the viewport point at which
+          to originate the `Datatype.Ray`, in device safe area coordinates.
       - name: depth
         type: float
         default: 0