Mistake in documentation for Camera.ScreenToWorldPoint and similar methods

Unity Engine
1

Hello,

I think there is a mistake in the documentation for the method Camera.ScreenToWorldPoint and other similar methods.

The documentation for Camera.ScreenToWorldPoint says:

However, the size of the screen is not necessarily pixelWidth x pixelHeight, e.g. if the Camera’s viewport is only a subsection of the entire screen. I believe the correct values are Screen.width x Screen.height.

The reference pages for the following Camera methods have this error:
WorldToScreenPoint
ScreenToWorldPoint
ScreenToViewportPoint
ViewportToScreenPoint
ScreenPointToRay

(and possibly others)

2

If the viewport of a particular camera is only a subsection of the screen (say for instance, a 320x240px rectangle in the corner), that camera’s .pixelWidth and .pixelHeight should still be 320 and 240.

Screen.width and .height will return the dimensions in pixels of the entire game window, regardless of how many viewports there are.

3

That’s why it’s not an error. ScreenToWorldPoint etc. are based on a given camera, not the screen, so the docs are correct.

–Eric

4

I think you misunderstand.

It is very easy to see that the documentation is incorrect.

Let’s assume that it’s correct: that the top-right corner of the screen is at pixelWidth x pixelHeight.

So let’s move an object to the top-right corner of the screen. We’ll create a vector for the top-right corner of the screen, transform it to the camera’s world space, and then move the object to that location in the world. A simple operation.

The code below will move objToMove to the top-right corner of the screen:

    public Transform objToMove; // assign a large Cube to this, for example

    void Start () {
        Camera camera = this.camera;

        // Use an orthographic camera.
        camera.orthographic = true;
        camera.nearClipPlane = 5f;
        camera.farClipPlane = 15f;

        // Change the viewport to see the top-right
        // quadrant of the screen only.
        camera.rect = new Rect(0.5f, 0.5f, 0.5f, 0.5f);

        // Transform the top-right corner of the screen
        // to the camera's world coordinates.
        Vector3 topRightCorner = new Vector3(camera.pixelWidth, camera.pixelHeight, 10f);
        Vector3 worldPos = camera.ScreenToWorldPoint(topRightCorner);

        // Move the object to the top-right corner of the screen.
        // The object's localPosition is in the camera's world space.
        objToMove.localPosition = worldPos;
    }

The result: the object appears in the middle of the screen and not in the top-right corner as we expected.

Again, the documentation states that the top-right corner of screen space is pixelWidth x pixelHeight, but, as demonstrated here, clearly it is not. The top-right corner of the screen is always at Screen.width x Screen.height.