Home

Awesome

Vision - CullingGroup API for everyone

Created by Hiroya Aramaki (Makihiro)

Tests Build Release openupm

What is CullingGroup API ?

TreasureRogue_Culling

CullingGroup offers a way to integrate your own systems into Unityโ€™s culling and LOD pipeline.

Unity Manual: https://docs.unity3d.com/Manual/CullingGroupAPI.html

Why Vision ?

CullingGroup is a great feature, but its implementation is a difficult because it can only be accessed through scripts and its usage is quirky.

Vision has made such a CullingGroup available to everyone.

Vision Features

<a id="index" href="#index"> Table of Contents </a>

<a id="installation" href="#installation"> ๐Ÿ“ฅ Installation </a>

Download any version from releases.

Releases: https://github.com/mackysoft/Vision/releases

Install via Open UPM

Or, you can install this package from the Open UPM registry.

More details here.

openupm add com.mackysoft.vision

<a id="usage" href="#requirements"> ๐Ÿ”ฐ Usage </a>

<a id="create-the-culling-group-proxy" href="#create-the-culling-group-proxy"> 1. Create the CullingGroupProxy </a>

First, create a CullingGroupProxy, which is the core of Vision.

1. From the Tools/Vision/Create New CullingGroupProxy menu, create a CullingGroupProxy.

NewCullingGroupProxy

2. Set the key to the created CullingGroupProxy.

Set the key by clicking the Key popup in CullingGroupProxy. By default, there is a Main key.

If you don't see the key, open settings from the <add key> or Tools/Vision/Open Settings menu. You can define a new key in the GroupKeyDefinitions list.

VisionSettings

3. Distances

By setting DistanceReferencePoint and BoundingDistances of CullingGroupProxy, you can calculate the relative distance between a reference point (for example, camera, player) and the bounding sphere's.

CullingGroupPRoxy_Distances

If BoundingDistances is set to { 10f, 20f, 30f },

Distance LevelRange
Level 00m ~ 10m
Level 110m ~ 20m
Level 220m ~ 30m

The last level and beyond will be treated as invisible.

If Distances is empty, { 0f , Mathf.Infinity } will be used as a fallback. In that case, currentDistance will always be 1.

BoundingDistances can be adjusted visually from the scene view !

CullingTargetProxy_Distances_Gizmo

<a id="attach-the-culling-target-behaviour" href="#attach-the-culling-target-behaviour"> 2. Attach the CullingTargetBehaviour </a>

CullingTargetBehaviour is a component that attaches to the object to be culled.

1. Attach CullingTargetBehaviour from Component/MackySoft/Vision/Culling Group Behaviour menu.

Attach this component to objects that you want to show/hide depending on their visibility, or change their quality depending on their relative distance.

CullingTargetBehaviour

2. Set the group key to the attached CullingGroupBehaviour.

The GroupKey of the CullingGroupBehaviour is used to find a CullingGroupProxy with the same key specified, and the CullingGroupBehaviour will be registered with the found CullingGroupProxy.

3. Adjust the radius of CullingGroupBehaviour.

The bounding sphere of the CullingGroupBehaviour is used to calculate the visibility by the CullingGroup. Completely enclose the object you want to cull with the bounding sphere.

Radius can be adjusted visually from the scene view !

CullingTargetBehaviour_Idle

Also, during play mode, the color changes depending on visibility.

<img src="https://user-images.githubusercontent.com/13536348/111074733-bf061e00-8527-11eb-8e19-e6796e56c63a.jpg" height="200" title="CullingTargetBehaviour_Visible" /> <img src="https://user-images.githubusercontent.com/13536348/111074737-c6c5c280-8527-11eb-9275-220103d8d59a.jpg" height="200" title="CullingTargetBehaviour_Invisible" />

4. Select the BoundingSphereUpdateMode.

This is an important value for performance.

BoundingSphereUpdateMode is set to Dynamic by default. This means that the transform of bounding sphere will be updated every frame.

However, there are some objects that do not move. In such cases, you can avoid the extra update cost by setting the BoundingSphereUpdateMode to Static.

<a id="receive-callback" href="#receive-callback"> 3. Receive a callback </a>

Use CullingTargetBehaviour.OnStateChanged callback to respond to changes in the visibility and distance state of the bounding sphere.

using UnityEngine;
using MackySoft.Vision;

[RequireComponent(typeof(CullingTargetBehaviour))]
public class ReceiveCallbackExample : MonoBehaviour {

    void Awake () {
        var cullingTarget = GetComponent<ICullingTarget>();
        cullingTarget.OnStateChanged += OnStateChanged;
    }

    void OnStateChanged (CullingGroupEvent ev) {
        if (ev.isVisible) {
            Debug.Log("Visible!");
        } else {
            Debug.Log("Invisible!");
        }
    }

}

<a id="utilities" href="#utilities"> Utilities </a>

Vision provides utility components that can be used with no coding.

<a id="culling-target-renderers" href="#culling-target-renderers"> Culling Target Renderers </a>

Enable / Disable the specified renderer's depending on the visibility of the bounding sphere.

CullingTargetRenderers

<a id="help-and-contribute" href="#help-and-contribute"> โœ‰ Help & Contribute </a>

Questions and ideas are welcome in discussions.

We welcome contributions such as bug reports and pull requests.

<a id="author-info" href="#author-info"> ๐Ÿ“” Author Info </a>

Hiroya Aramaki is a indie game developer in Japan.

<a id="license" href="#license"> ๐Ÿ“œ License </a>

This library is under the MIT License.