Also update Camera.ViewportPointToRay

Author: ap4123

content/en-us/assets/engine-api/classes/Camera/DeviceSafeViewportCoordinates.jpg

@@ -1175,20 +1175,24 @@ 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 Core UI 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.
+
+      <img src="/assets/engine-api/classes/Camera/DeviceSafeViewportCoordinates.jpg" width="720" alt="Diagram showing the origin of the device safe area viewport coordinate system." />
+      
+      The input 2D position does **not** account for the Core UI inset, but does account for any device safe insets.
+      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 Core UI viewport coordinate system, while this function uses the device safe 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:
@@ -1208,28 +1212,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.
+          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.
+          to originate the `Datatype.Ray`. In device safe area coordinates.
       - name: depth
         type: float
         default: 0