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
• Reflections rendering
• Collisions
• Intersections
• Decals rendering
• Physicals
• Decals

To specify the mask, you should double click the corresponding mask field (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 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. If two masks have at least one matching bit, the masks match. Values of other bits would not influence the result.

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:

1. Object surface viewport mask (set in the Viewport field of the Surfaces tab of the chosen object)
2. Object material viewport mask to render the object's material (set in the Viewport field of the Common tab of the chosen material)
3. Light viewport mask to illuminate the object (set in the Viewport field of the Light tab of the chosen light source)

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

For the surface to be illuminated only by the chosen light sources, a bit mask should be used. Matching this mask to the one of light source (one bit, at least), allows you to control the intensity of the object illumination.

A decal mask specifies objects, onto which the decal can be projected. An object can receive the decal if its mask corresponds to this mask.

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.

Collision bit masking is a really flexible mechanism. After double clicking on the mask field, it is possible to specify a 32 bit mask for each shape or body. Each of 32 bits can either be turned on (1) or off (0) when clicking on the bit number. The resulting mask is displayed in the field as hexadecimal characters. After that, two masks are compared bitwise using binary operator and. If at least one pair of corresponding bits matches, objects will collide.

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:

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.