UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
FAQ
Программирование
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
CIGI Client Plugin
Rendering-Related Classes

Bit Masking

A bit masking is a flexible mechanism used to access only the specific bits in a set of data. It can be applied to the following systems:

  • Rendering into viewport
  • Lighting and shadowing
  • Reflections rendering
  • Collisions
  • Intersections
  • Decals
  • Fields
  • Sound sources
  • Physicals
  • Pathfinding

To specify the mask, double click the corresponding mask button (Viewport, Light, Intersection, etc.) and turn on required values from a 32-bit mask. Turning on a bit means setting 1 value (when turned off, the value is 0). The resulting mask (when the bit mask window is closed) is displayed as hexadecimal characters.

Notice
Some masks store less than 32 bits. For example, the material mask.
Surface viewport mask
Bit mask with the first bit turned on
  • Set turns on all the bits in the mask
  • Clear turns off all the bits in the mask

Comparing Masks

The masks are compared bitwise using binary operator and. As a result, the first bit of the first mask is compared to the first bit of the second mask, the second bit - to the second one, and so on.

Notice
If two masks have at least one matching bit, the masks match. Values of other bits won't influence the result.

For example the following viewport masks have 4 matching bits, so they match:

  • The camera viewport mask with the first 6 bits turned on:

    A hexadecimal representation:
  • The object's viewport mask with the 2nd, 3rd, 4th and 5th bits turned on:

    A hexadecimal representation:

Rendering into Viewport

Objects (along with decals and lights) can be selectively rendered into viewport. For that end, the camera viewport mask (set in the Camera Settings window opened via the Camera panel), should match the following masks:

  • Object surface viewport mask (set in the Viewport Mask field in the Node tab of the Parameters window).
  • Object material viewport mask to render the object's material (set in the Viewport mask field in the Common tab of the material editor).
Notice
All masks match each other by default.

Usage Example

Suppose we have two objects with the same material. To make one of them to be rendered into viewport, and the other one not to be rendered, we need to change its viewport mask.

Surface viewport masks of both objects are set to 00000001
Surface viewport mask of the first object is set to 00000000

Reflection Mask

A reflection mask controls rendering of environment probe's and planar dynamic reflections into the camera's viewport.

The reflection mask can be set:

  • For environment probes, in the Reflection mask field in the Environment Probe tab of the Parameters window. The mask is available only when dynamic reflections are enabled for the environment probe.
  • For planar reflections, in the Mask field on the Parameters tab of the selected material.

For the dynamic reflections to be rendered, its reflections mask must match the following masks (one bit, at least):

  • A reflection mask of the camera (set in the Reflection field of the Camera Settings window).
  • A viewport mask of the object (set in the Viewport mask field in the Node tab of the Parameters window).
  • A viewport mask of the object's material (in other words, the reflected material; set in the Viewport mask field in the Common tab of the Parameters window).

Usage Example

Suppose, you have a reflecting surface and 2 objects reflected in this surface.

  • To render an object without a reflection, either its viewport mask or its material viewport mask should not match the camera's reflection mask.
  • To render a reflection without an object, its viewport mask or its material viewport mask should not match the camera's viewport mask.

In the example below, masks are given in the binary representation. For masks to match, they should share 1 in the appropriate bit position. You can convert these masks to the hexadecimal number representation and set the obtained values via UnigineEditor.

An object without reflection
A reflection without an object
MaskValue
Camera viewport mask0111
Camera reflection mask1100
Viewport mask for the 1st object0001
Viewport mask for the 2nd object0110
Reflection mask for reflecting material1110
MaskValue
Camera viewport mask0111
Camera reflection mask1100
Viewport mask for the 1st object1000
Viewport mask for the 2nd object0110
Reflection mask for reflecting material1110

In the 1st example, the object's viewport mask doesn't match the camera's reflection mask. However, it matches the camera's viewport mask, so the object is rendered.

In the 2nd example, the object's viewport mask doesn't match the camera's viewport mask. However, it matches the camera;s reflection mask, so the reflection is rendered.

Shadow Mask

Warning
Light mask was renamed shadow mask. However, the deprecated name can occur in UnigineEditor. This is temporarily and will be fixed soon. Please, treat a light mask as a shadow mask.

A shadow mask controls rendering of a shadow cast by an object lit by a light source.

For the shadow to be rendered, the shadow mask of the light source that illuminates the object must match the following masks (one bit, at least):

  • Object surface shadow mask (set in the Light maks field in the Node tab of the Parameters window).
  • Object material shadow mask (set in the Shadow mask field in the Common tab of the material editor).

Usage Example

In the example below, the shadow mask of the surface and its material doesn't match the shadow mask of the light source so the shadow isn't rendered.

Shadow mask of the surface and its material
Shadow mask of the surface and its material
Shadow mask of the light source
Shadow mask of the light source

Material Mask

Notice
Decal mask was renamed Material mask.

A material mask is a 24-bit mask that specifies objects, onto which the decal can be projected. An object or one of its surfaces can receive the decal only if its material mask corresponds to the material mask of the decal.

The material mask can be specified for a selected material on the Parameters tab of the material editor:

Material mask field

Intersection Mask

An intersection mask specifies objects (including objects, nodes, shapes, collision objects and obstacles) for which intersections will be/won't be found. An intersection is found only if the object's intersection mask matches the intersection mask passed as a function argument, otherwise it is ignored.

The mask for the object can be specified via both UnigineEditor or API.

The intersection mask can be used to clarify the object search or to increase performance by limiting the number of objects that can participate in intersections.

Collision Mask

A collision mask allows you to filter particular shapes and bodies for physical interaction: only those will collide, that have a matching collision mask. If the masks do not match, shapes and bodies will simply ignore each other by going through.

For example, we've got four bodies that need to collide in the following way:

Body A Body B Body C Body D
Body A
Body B
Body C
Body D

For that, each colliding body should share 1 in the appropriate bit position:

Body Mask
Body A 0001
Body B 0010
Body C 0110
Body D 1111

Physical Mask

A physical mask is a bit mask that filters objects interacting with physical nodes: force, wind and water. It is set according to the same principle as Collision mask. For example, body with unmatching mask placed in the physical water will not float.

Sound Sources Masks

Masks can be set via both UnigineEditor and API.

Source Mask

A source mask is a bit mask that determines to what sound channels the sound source belongs to. For a sound source to be heard, its mask should match with the player's sound mask in at least one bit.

Reverberation Mask

A reverb mask is a bit mask that determines which reverberation zones can be heard. For sound to reverberate, at least one bit of this mask should match the player's reverberation mask. At the same time, the reverb mask of the player should match the reverb mask of the sound source (but not necessarily in the same bits).

Navigation Mask

A naviagtion mask is used to specify navigation areas that participate/don't participate in pathfinding. The navigation mask must match the navigation mask of the route that is calculated within the navigation area. Otherwise, the area will not participate in pathfinding.

The navigation mask for the navigation areas can be specified:

  • Via UnigineEditor in the Navigation Sector/Navigation Mesh tab of the Parameters window.
  • Via Unigine API.
Notice
The navigation mask of the route can be specified only via API.

Using the navigation mask, you can limit the number of navigation areas, inside which the specific route can be calculated. For example, you can use the mask to calculate 2 non-intersecting routes inside the intersecting navigation areas.

Obstacle Mask

An obstacle mask is used to specify obstacles inside navigation areas that are bypassed/aren't bypassed during pathfinding. The obstacle mask of the obstacle must match the obstacle mask of the route that is calculated. Otherwise, the obstacle will not be taken into account.

As well as the navigation mask, the obstacle mask can be specified:

Notice
The obstacle mask of the route can be specified only via API.

Field Mask

A field mask specifies an area of the field to be applied to grass or water. The field will be applied to grass or water only if they have matching field masks.

The field mask can be set via UnigineEditor or API.

Last update: 10.08.2018