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 field (Viewport, Light, Intersection, etc.) or click 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.

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

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.

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:

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

• Object surface viewport mask (set in the Viewport field of the Surfaces tab of the chosen object).
• Object material viewport mask to render the object's material (set in the Viewport mask field of the Common tab of the chosen material).

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

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 on the Light tab of the Nodes 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 Materials window.

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 field on the Surfaces tab of the selected object).
• A viewport mask of the object's material (in other words, the reflected material; set in the Viewport mask field on the Common tab of the Materials 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
Mask Value Camera viewport mask 0111 Camera reflection mask 1100 Viewport mask for the 1st object 0001 Viewport mask for the 2nd object 0110 Reflection mask for reflecting material 1110	Mask Value Camera viewport mask 0111 Camera reflection mask 1100 Viewport mask for the 1st object 1000 Viewport mask for the 2nd object 0110 Reflection mask for reflecting material 1110

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.

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 field of the Surfaces tab of the chosen object).
• Object material shadow mask (set in the Shadow mask field of the Common tab of the chosen material).

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

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 material on the Parameters tab of the Materials window:

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.

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:

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.

Masks can be set via both UnigineEditor and API.

Source Mask

Reverberation 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 on the Navigation tab of the Nodes window.
• Via Unigine 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.

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:

• Via UnigineEditor on the Obstacle tab of the Nodes window.
• Via Unigine API.

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.