Unity RectTransformUtility.ScreenPointToLocalPointInRectangle

Question

What does the unity's RectTransformUtility.ScreenPointToLocalPointInRectangle do I've read unity documentation but I didn't get the clear meaning.

Answer 1

Preface

This question starts with a small geometry problem. You have two different planes which may or may not be parallel.

1) Your screen space. This is the actual screen coordinates your computer is displaying and its where your arrow icon moves around in when you move your mouse. This can be thought of as a 2D plane across the surface of your screen.

2) A rectangle in your scene. Due to how Unity3D (the 3d part is important here) sets up the scene you have objects that exist in an environment with depth. In a 2D scene this plane will most likely be parallel to your screen, however in a 3D scene this plane may intersect your screen instead of running along side of it.

What does this function do?

This function will take a coordinate on your screen (a common example is mouse position) and translate it so that instead of sliding along your screen, it slides along the plane of a rectangle in your scene.

Documentation

Now lets go over each part of the documentation in a little extra detail.

Parameters

Names are in bold, and Unity3D's documentation is in italics.

rect: The RectTransform to find a point inside. This rectangle defines the plane you want to transform your screen space coordinate into.

cam: The camera associated with the screen space position. This is a camera object which is representing your screen space coordinate. So this function will take a point from this camera's reference and adjust it so its relative to the rect parameter.

screenPoint: Screen space position. This is a point you have (calculated, or gotten. Maybe even your mouse position from the example above?) and that you would like to move into your rectangle's plane.

localPoint: Point in local space of the rect transform. This is an "out" parameter. This means that you pass in a blank point object and this function will populate it. This localPoint is populated with the screenPoint translated from cam-space to rect-space.

Returns

bool Returns true if the plane of the RectTransform is hit, regardless of whether the point is inside the rectangle. This means that the function will return true if it worked, and it will return false if it was unable to convert the cam-space point into rect-space. The reason it returns a bool is so that it can let you know if it failed to calculate in a way other than just crashing your program. Checking the bool before you use the returned out localPoint is probably a good idea, although it may be unnecessary for what your doing.

Description

This just provides some warnings and info on edge cases. But we've already covered the gist of the documentation so I'll let you ask another question if you run into any issues using this function.

Hope this helps! Let me know if there are any other questions.

= EDIT =

Sorry for the delay, just saw your comment. I also don't have access to Unity3D on this computer so the examples are not guaranteed to work. I may be able to find some time tonight to write a sample program, but no promises (sorry in advance if I can't get around to it!)

Returns in-depth

This function only has 2 different returns. It returns a boolean(true/false, yes/no) value.

It returns 'true' if the function was ran successfully. This means that there will be some Point coordinate in the localPoint out parameter that you can trust (only trust it as far as you trust your inputs).

If the function returns false that means that it was unable to calculate a localPoint. This can potentially happen if you pass in a null object, or perhaps a camera that isn't active.

Example

Scenario:
You want some small critter to follow your mouse around on the main menu.

Things you'll need:
1) The RectTransform which describes the background for your main menu.
2) The GameObject of your small critter.

Untested example code

void Update()
{
    // this is a hard-attach. you can move it over a Time.delta or
    // give it some other behavior to make it more interesting.
    RectTransformUtility.WorldToScreenPoint(menu_background_rect,
        Input.mousePosition, Camera.main, critter.transform.position);
}

You'll likely have an easier time figuring out what it does by trying it yourself and seeing first hand what the results are, but I hope this is a good enough starting point. Good luck!