Highlighting System 5.0

Highlighting System 5.0
User Guide

Highlighting System for Unity Engine available at: http://u3d.as/hUz


Contents

Overview
  1.1  Package overview
Integration to your project
  2.1  Basic integration
  2.2  Hover highlight
  2.3  Quick tips
API
  3.1  Highlighter
  3.2  HighlighterBlocker
  3.3  HighlighterCore
  3.4  HighlightingBase
  3.5  HighlightingBlitter
  3.6  HighlightingRenderer
  3.7  HighlightingPreset
  3.8  AntiAliasing
  3.9  BlurDirections
  3.10  Easing
  3.11  HighlighterMode
  3.12  LoopMode
  3.13  RendererFilterMode
Advanced tips
  4.1  Using custom transparent shaders
  4.2  Anti-aliasing
Limitations
Known issues
Support
Changelog
  8.1  v5.0
Upgrade notes
  9.1  Upgrading from v4.3 to v5.0

  

Overview

Highlighting System package allows you to easily integrate outline glow effect for objects highlighting in your Unity project. It allows you to make any object highlightable and works on all major platforms, where Image Effects is supported.

  

Package overview

After the package installation, in the Plugins\HighlightingSystem folder you will find all the scripts and shaders required for the Highlighting System to work. All scripts in this folder are in the HighlightingSystem namespace.

In the HighlightingSystemDemo folder, you will find example scenes and scripts intended to demonstrate how to integrate and use Highlighting System in your own projects. Feel free to completely remove this folder at any time. All scripts in this folder are in the HighlightingSystem.Demo namespace.

  

Integration to your project

  

Basic integration

  1. Import Highlighting System package from the Unity Asset Store to your project.
  2. Add HighlightingRenderer component to the Camera. Order of this component (among other Image Effects on this Camera) defines when the highlighting buffer will be applied to the rendered frame.

  3. Add Highlighter component to the GameObject's you want to make highlightable.

  4. Setup Highlighter components as you need. Refer to the Highlighter API to figure out what each option means.

  5. Tweak settings of the HighlightingRenderer component to change the look of highlighting. Please note that the highlighting presets are stored (serialized) in the component itself (will be saved in scenes and / or prefabs), and you can manipulate them at runtime using HighlightingRenderer API.

  

Hover highlight

  1. Add RaycastController component to Camera.
  2. Add HighlighterHover component to Camera or any other persistent GameObject.
  3. Hook HighlighterHover to the OnHover event of the RaycastController by pressing the + button on the bottom right first, then dragging HighlighterHover component to the appeared None (Object) field and selecting HighlighterHover > OnHover function. You can also hook any other custom handlers to the OnHover event this way.

  4. Set desired highlighting hover color in the HighlighterHover component.

See also HighlighterInteractionDemo class source for an example of more advanced interaction with the Highlighter's.

  

Quick tips

  

API

  

Highlighter

class in HighlightingSystem / Inherits from: HighlighterCore

Description:
Main component to use on the objects you want to make highlightable. Three different highlighting modes available (listed in descending priority order):

  1. Hover

    Highlights object only for a single frame, so you can trigger it every frame for the object under the mouse cursor.

  2. Tween

    Useful to pay attention on a specific object (game tutorial item for example).

  3. Constant

    Used to turn on/off constant highlighting on an object (for example, to highlight all pickable items on screen).

  4. Occluder

    Not actually a highlighting mode, but highlighter will turn into occluder only if no other modes are active.

In case multiple highlighting modes enabled on the highlighter - mode with higher priority will take effect.

using UnityEngine;
using HighlightingSystem;

public class Example : MonoBehaviour
{
  private Highlighter highlighter;
  
  void Awake()
  {
    highlighter = gameObject.AddComponent<Highlighter>();
    highlighter.ConstantOn(Color.red);
  }
}

See also: HighlighterCore

Properties:

Public Methods:

Static Methods:

  

HighlighterBlocker

class in HighlightingSystem / Inherits from: MonoBehaviour

Description:
Renderer's on GameObject's with this component (or any of it's children) will never be highlighted.

  

HighlighterCore

class in HighlightingSystem / Inherits from: MonoBehaviour

Description:
Base class for all highlighters. If you doesn't want to use provided Highlighter component and want to implement custom highlighting logic instead - inherit from this class and override UpdateHighlighting() method where you should update mode and color properties. See Highlighter class sources for an example. Please note that for safety (to avoid exceptions), this class hides MonoBehaviour's Awake(), OnEnable(), OnDisable(), OnDestroy() methods from all inheritors, so instead you should override AwakeSafe(), OnEnableSafe(), OnDisableSafe(), OnDestroySafe() methods correspondingly.

Delegates:

Properties:

Public Methods:

Static Properties:

Static Methods:

  

HighlightingBase

class in HighlightingSystem / Inherits from: MonoBehaviour

Description:
Internal base class which implements core Highlighter's rendering functionality. In most cases you should use HighlightingRenderer instead.

Properties:

Public Methods:

  

HighlightingBlitter

class in HighlightingSystem / Inherits from: MonoBehaviour

Description:
You should add this component to the current camera if you want to apply the highlighting buffer rendered on another camera during current camera rendering. You should assign this component instance to the blitter field in that case. Order of this component (among other Image Effects on this Camera) will define the point at which highlighting buffer will be applied to the rendered frame. Make sure that the Camera with HighlightingBlitter component has higher depth than the Camera with HighlightingRenderer which is using this HighlightingBlitter component instance.

  

HighlightingRenderer

class in HighlightingSystem / Inherits from: HighlightingBase

Description:
Main component to assign to the Camera. This class, on top of the core HighlightingBase implements functionality to manipulate highlighters rendering presets. Highlighting presets stored locally, in each instance of the HighlightingRenderer component using Unity native serialization system. That means they are saved along with prefabs and/or scenes. To reset to default, copy and paste presets between instances of the HighlightingRenderer components or between projects – please use Reset, Copy Component and Paste Component Values context menu options correspondingly (you can access them by clicking on a little gear icon to the right):

Properties:

Public Methods:

Static Properties:

  

HighlightingPreset

struct in HighlightingSystem / Inherits from: ValueType

Description:
Struct used to store HighlightingRenderer (HighlightingBase) settings.

Properties:

  

AntiAliasing

enum in HighlightingSystem / Inherits from: Enum

Description:
Anti-aliasing settings to use when rendering highlighting.

Static Properties:

  

BlurDirections

enum in HighlightingSystem / Inherits from: Enum

Description:
Defines blur directions of the highlighting buffer.

Static Properties:

  

Easing

enum in HighlightingSystem / Inherits from: Enum

Description:
Defines how tween highlighting color gradient value is evaluated or how constant highlighting alpha channel value is eased during fade in and out transitions.

Static Properties:

  

HighlighterMode

enum in HighlightingSystem / Inherits from: Enum

Description:
Determines how to render each HighlighterCore instance.

Static Properties:

  

LoopMode

enum in HighlightingSystem / Inherits from: Enum

Description:
Determines how tweenGradient is sampled outside of a single tween iteration.

Static Properties:

  

RendererFilterMode

enum in HighlightingSystem / Inherits from: Enum

Description:
Defines how Highlighter will utilize filterList to perform Renderer's filtering.

Static Properties:

  

Advanced tips

  

Using custom transparent shaders

In order to make custom transparent shaders properly highlightable:

  1. Make sure that RenderType shader tag is set to TransparentCutout or Transparent (check this for more info). Otherwise – such shader will be interpreted by the Highlighting System as an opaque shader, and alpha channel of your material's main texture will not be taken into account.
  2. Make sure that your custom shader has _MainTex property of type 2D (Texture). Highlighting System will use texture assigned to this property to detect transparent areas by comparing texture alpha channel with the threshold value, taken from:
    • _Cutoff (Float) property if your custom shader has it, or
    • Highlighter's internal transparentCutoff variable otherwise (set to 0.5 by default. You can change this value in the HighlighterRenderer.cs script).

Note that the main texture with its offset and scale values is cached by the Highlighting System only on highlighter's initialization, which takes place after instantiating Highlighter component and after each call to SetDirty(). Because of that, your changes to the main texture properties will not be reflected by the highlighting without the call to SetDirty() method.

Also, please note that if your shader handles _Cutoff property differently (not with the default alpha clip clip(alpha - _Cutoff) expression) – the resulting higlighting may differ from what's rendered by your custom shader.

  

Anti-aliasing

Hardware anti-aliasing (or MSAA, Multi-Sample Anti-Aliasing) is enabled in Unity if Anti Aliasing property is not set to Disabled in Edit > Project Settings > Quality settings. Note that there are multiple quality levels all with their own anti-aliasing settings.

Hardware anti-aliasing has several significant drawbacks:

Due to all of the above – it is not recommended to use hardware anti-aliasing in your project. You can replace it with Antialiasing Image Effect from the Unity Standard Assets package.

  

Limitations

Due to the Image Effect nature of the Highlighting System – it has several limitations:

  1. Multi-layer highlighting. This isn't possible to show highlighting of an object which is obscured by other highlighted object.

  2. Inverse highlighting occlusion (highlight only parts obscured by other objects).

    Despite the fact that this can be implemented for simple convex geometry such as this shown on the image above – complex arbitrary meshes will occlude their own parts, so they will become highlighted:

  3. Mixing HighlightingRenderer settings.

    This isn't possible to use different highlighting settings on a per-object basis. HighlightingRenderer settings always apply to the whole image only.

  

Known issues

  1. Currently (in Unity 2018.1.0f1), there is no API exposed to properly support Single Pass Instanced (Preview) stereo rendering path for Image Effects.
  2. Unity Editor may hang or crash on high-resolution displays (such as Retina® displays used in MacBook®) when hardware anti-aliasing is enabled. Hardware anti-aliasing option (enabled by default for new Unity projects) basically acts as a multiplier for your game view resolution, so in case you're experiencing this issue – you are probably running out of video memory and/or exceeding maximum allowed RenderTexture size. To fix this - either disable hardware anti-aliasing in Quality Settings or reduce your game view screen resolution using Aspect Drop-down.
  3. Highlighting doesn't work properly on iOS platform if hardware anti-aliasing is enabled. There is a very low chance that someone needs this considering the device screen DPI and performance drop that comes from enabling this option on a mobile device.

  

Support

Here you can find Highlighting System development board which you can use to check if a specific bug fix or a feature is already known or in development: http://trello.com/b/GmwO3VNJ

New hot fixes and tips are always posted here: https://trello.com/c/lTRmC9Yv

Please feel free to send your bug reports, feedback, suggestions, questions or feature requests to:

In order to help me resolve your issue faster – please make sure to provide the following information in your email:

  1. Invoice number in case you're asking for support for the first time. This isn't 100% necessary, but I'm prioritizing emails from users with known invoice numbers, since that allows me to instantly send them modified scripts and/or shaders of the Highlighting System, or even the whole package as soon as I have a solution for any particular issue. You can find your invoice number in the PDF attached to the 'Unity Asset Store purchase confirmation' email here:

  2. Unity version
  3. Highlighting System version (v5.0 in case this Documentation is provided to you along with the package)
  4. Operating system version (e.g. Windows 10 64-bit)
  5. Graphics card model (e.g. NVIDIA GeForce GTX 980)
  6. Mobile device version in case of mobile-related issues (please find your device on http://www.gsmarena.com/ and include the link. For example: http://www.gsmarena.com/asus_zenfone_3_ze552kl-8106.php)
  7. (Optional) Archived example project to reproduce your issue (either attached to email if it's below 20Mb, or a link to any file sharing service). Please note that this is not necessary to include the Library folder (only Assets and ProjectSettings is required).
  8. (Optional) Screenshots or videos depicting the problem. This is optional, but often 1 screenshot worth 1000 words ;)

  

Changelog

  

v5.0

  

Upgrade notes

  

Upgrading from v4.3 to v5.0

  1. Open Unity Asset Store and locate Highlighting System asset. Press Update button.

  2. In the appeared Import Unity Package window - press All and then Import buttons.

  3. Remove the following files (you can use Alt + Click to expand all subdirectories recursively):

    Assets
    ├──HighlightingSystemDemo
    │  ├──Scripts
    │  │  ├──Advanced
    │  │  │  └──HighlighterItem.cs
    │  │  ├──Basic
    │  │  │  ├──BooHighlighterController.boo
    │  │  │  └──JSHighlighterController.js
    │  │  └──Service
    │  │     ├──ColorTool.cs
    │  │     ├──ScreenSpaceCanvas.cs
    │  │     └──WorldSpaceCanvas.cs
    │  └──Documentation.pdf
    └──Plugins
       └──HighlightingSystem
          ├──Scripts
          │  └──Internal
          │     └──HighlighterInternal.cs
          └──link.xml

  4. Rename CameraTargeting script (in the Assets/HighlightingSystemDemo/Scripts/Advanced/ folder) to HighlighterInteractionDemo.

  5. The following scripts have been deprecated: HighlighterBase HighlighterConstant HighlighterFlashing HighlighterInteractive HighlighterOccluder HighlighterSpectrum. If you haven't used these demo components in your project - simply remove them completely along with HighlightingUpgrade script.

    But if you do - you can automatically upgrade them to use Highlighter component now. In order to upgrade prefabs - press Upgrade button when you see such message, and save prefab:

    In order to upgrade GameObject's in the currently opened scene - open Tools/HighlightingSystem/Upgrade scene from v4.3 to v5.0 utility window, press Upgrade Current Scene (all upgraded components will be logged to console) and save it.

  6. Upgrade your custom scripts to use new API if you see similar warnings in console:

    Assets/HighlightingSystemDemo/Scripts/Basic/BooHighlighterController.boo(18,15): BCW0012: WARNING: 'HighlightingSystem.Highlighter.FlashingOn(UnityEngine.Color, UnityEngine.Color, single)' is obsolete. 

    Refer to the updated Highlighter, HighlightingBase and HighlightingRenderer API.

  7. Other important changes to take into account when upgrading:
    • seeThrough property of the Highlighter renamed to overlay.
    • ReinitMaterials() method of the Highlighter renamed to SetDirty();
    • Removed deprecated Highlighter API methods: SeeThrough(bool state), SeeThroughOn(), SeeThroughOff(), SeeThroughSwitch(), OccluderOn(), OccluderOff(), OccluderSwitch()
    • Deprecated Die() method of the Highlighter. Use Destroy(highlighter); instead.


In memory of my mother Nina and my friend Darwin.


Highlighting System are Copyright © 2020 Deep Dream Games. Unity, Unity Asset Store are Copyright © 2020 Unity Technologies. Microsoft, Xbox, and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. MacBook, iOS, Retina are trademarks of Apple Inc., registered in the U.S. and other countries. NVIDIA, GeForce, GeForce GTX are trademarks and/or registered trademarks of NVIDIA Corporation in the U.S. and/or other countries.