UIVirtualScreen

Overview

UIVirtualScreen works like, well, a virtual screen in your game world, onto which you can render a texture of a UI elsewhere in your scene. (Think of the computer screens in Doom 3, for example.) Basically, all you have to do is map a render texture onto whatever object you want, and then if you've added a UIVirtualScreen component to it, it acts like a virtual screen in your game. It takes care of relaying input properly to the controls that sit in front of your camera that is rendering to texture.

What it's good for

* A virtual book, complete with turning, bendy pages.
* Doom 3-like in-game computer interfaces. (This can be better than the approach in the original hangar FPS demo since you don't have to use managed sprites, etc, to make sure control depth-sorting doesn't mess up ordering when using a perspective camera. Using this method, you can set up an orthographic camera to render your GUI, and then map that onto an object in 3D space and view it without issue using a perspective camera.)

How to use it

* Setup a UI somewhere in your scene and point a camera at it that renders to texture. We will call this camera the "screen camera". NOTE: This camera should not be added to the UIManager's "UI Cameras" array as it is handled by the virtual screen instead.
* Add an object in your scene that uses this render texture. This could be a Cube, a SimpleSprite, or any arbitrary object. We will call this the "screen object".
* Add the virtual screen component to your screen object (you'll find the Virtual Screen item under Components->EZ GUI->Controls).
* Make sure your object has a mesh collider on it. It has to be a mesh collider, or else it won't receive the info it needs to relay the input.
* Then, drag your screen camera onto the "Screen Camera" field of the UIVirtualScreen inspector.
* If you have any scroll bars or scroll lists, you will probably want to make sure the "Process Pointer Info" box is checked, and then drag the common parent object of all your controls you're rendering to texture onto the "Control Parent" field. If you don't have a common parent, group them together under one. They don't have to be the immediate children of the same parent. Just some parent object somewhere up the chain that they all have in common.

Now when you mouse over/touch anywhere on the 3D object that is using the render texture (and of course has the virtual screen component on it), the UI being rendered will respond accordingly.

Class

UIVirtualScreen

Properties

Screen Camera	The camera that is rendering the controls for our "screen".
Layer Mask	Mask used to filter out what controls will are checked for input.
Ray Depth	The distance from the screen camera that input should "reach".
Process Pointer Info	When set to true, the pointer information sent to the controls in the "screen" will be intercepted first and processed so that coordinates, etc, are correct in the context of the "screen". This is recommended if you are using scroll lists or any custom input delegates that need to have accurate input delta or coordinate information that is accurate relative to the screen camera.
Control Parent	This only needs to be assigned if the processPointInfo option is set to true. This points to the common parent object of all the controls being rendered to this "screen".
Only Render When Needed	This setting only applies if processPointerInfo is set to true. When enabled, the render texture will only be updated when the screen detects input to one of the controls on the screen. Otherwise, the "screen camera" is deactivated until new input is detected.
Render Timeout	This setting only applies if onlyRenderWhenNeeded is enabled. This setting determines how many seconds to wait after the pointer has stopped interacting with a control before the screen camera is deactivated. A value of 0 waits until the next frame.
Tab Size	The number of spaces that will be inserted when a tab character is encountered in the string.
Font	References the font definition file to use for the text. This file is a TextAsset that you generate. See Creating Fonts for more details.
Color	The "global" color of the text. This is overridden by any color tags in-line in the text. See the notes above regarding coloring.
Pixel Perfect	When checked, the Character Size (see above) will be automatically calculated so that there is a 1:1 font pixel to screen pixel correlation.
Max Width	When set to 0, there is no limit to the width of the text displayed. Otherwise, this value indicates the width, in world space units, that the text is allowed to be. If it exceeds this width, the text will be word-wrapped to the next line.
Multiline	When set to true, the text object will allow multi-line content. This also enables word-wrapping when the maxWidth setting is set to a non-zero value. If multiline is false, then a non-zero maxWidth setting will cause text that exceeds the maxWidth to be truncated and have "..." appended. NOTE: The actual text contents are preserved and only the display string is truncated.
Dynamic Length	This setting is reserved for future use. It presently has no effect.
Remove Unsupported Characters	When checked, any characters which are not defined in your font definition will be rejected and will not be attempted to be displayed.
Parse Color Tags	When this option is enabled, color tags will be parsed from the text. However, if it is unchecked, color tags will be ignored. This is useful for things like player name fields.
Render Camera	The camera that will render this text. This is important when using pixel-perfect as the size calculation is based upon the camera.
Hide At Start	When checked, the object will not be rendered at start.
Persistent	Check this box if the object should survive level loading. Otherwise, when you load a new level/scene, it will be automatically destroyed along with the rest of the existing scene.