Lumberyard
User Guide (Version 1.16)

VisArea

This feature is in preview release and is subject to change.

A vis area (visible area) is a shape object that helps you manage visibility and culling in a scene. When a camera is in a visible area, the camera can see only other objects that are also in the visible area. You can use the VisArea component to define indoor areas and manage overdraw. Objects are inside a visible area only if their center is inside the area.

You can also attach a Portal component to an entity to create windows between visible areas. This helps you create beautiful areas that render efficiently.

Visible areas are only dynamic during editing. If you modify the VisArea component or move the entity to which the VisArea component is attached at run time, the area that the VisArea component defines is not affected. Also, the VisArea component does not work if spawned as part of a dynamic slice. For more information, see Working with the Event Bus (EBus) System.

Note

The OccluderArea, Portal, and VisArea components cannot be modified at run time.

VisArea Component Properties

The VisArea component has the following properties:

Height

The height of the visible area.

Valid values: 0100

Default value: 5

DisplayFilled

Display the visible area as a filled volume in the Lumberyard Editor viewport.

Default value: False

AffectedBySun

Objects in the visible area are affected by the sun.

Default value: False

ViewDistRatio

A multiplier on the view distance of the visible area during editing.

Valid values: 0100

Default value: 100

OceanIsVisible

The ocean is rendered outside the visible area.

Default value: False

Vertices

The vertices that define the floor of the visible area. You must specify at least three vertices for the VisArea component to affect the world. There is no upper limit for the number of vertices that you can specify. It is recommended that all vertices have the same z-value to keep the volume intuitive.

Vis Area Component Examples

Example 1

The following example shows two boxes. One box is inside the visible area and one is outside. From outside the visible area, the inside box is not visible. The DisplayFilled option is enabled, so that the visible area appears orange.

You can see the shadow of the box inside the visible area because the AffectedBySun option is enabled.


                The VisArea component hides on box from
                    another.

Example 2

In the same example, the DisplayFilled option is now disabled in the visible area.


                Use the VisArea component to create a shape to display
                    and hide objects.

Example 3

In the following example, you can see the box inside the visible area, but you can't see the box outside the visible area.

You can see the ocean inside the visible area because the OceanIsVisible option is enabled.


                The VisArea component displays an ocean in the visible
                    area.

Example : Nonplanar Legacy Vertices

If you are familiar with the legacy visible areas, you may be used to seeing the legacy visualization. In the legacy system, if you raise one vertex of the visible area higher than the other vertices, the legacy visualization displays the visible area incorrectly.

The following example is the legacy visualization for a visible area. Notice how one vertex appears higher than the others.


                    Legacy nonplanar visible area visualization.

Example : Planar Vertices with VisArea Component

The following is an example of the VisArea component with the same vertices.


                Use the VisArea component to create a shape to display
                    and hide objects.

The second example is correct because the visible area is the volume on the x- and y-plane with a z-position and a height. This makes it faster to determine whether or not an object is inside the VisArea component.

The position on the z-axis is the position of the lowest point. The height is the specified height plus the difference in height between the highest and lowest point. This remains true even after transformations. If you rotate a visible area on the x- or y-axis, you might see volumes that may not make sense. All points after a transformation are projected onto the x- and y-plane.

When legacy visible areas are converted, Lumberyard corrects this behavior for you. All points are made planar and any difference in height between points is applied to the visible area's height.