This page covers:

  • How vertical layering works
  • A sizing reference to ensure good layering

Layering principles

Keysight is a 3D application, despite looking 2D under the stock layout configuration. This means that when thinking about layering (that is: which elements are visible on top of other elements) it is the Z-axis position that determines the layer order.

Z-fighting

Z-fighting is an incredibly common visual artifact in 3D rendering. It occurs when two surfaces occupy the exact same plane, and thus the renderer cannot satisfactorily resolve which surface should show on top. The following is an example of a red Gradient(*) component occupying the same space other black Gradients:(*) Z-fighting This must be resolved by slightly altering the Z-height of one of the conflicting components. In some instances, it may be impossible to resolve Z-fighting such as:

  • Note objects with other Note objects, using any flat-topped Shape with greater than 1.00 Size
  • Backdrop with the Piano, when the Backdrop is in Extend bounds vertically mode
  • Overlay with the Frame, when at 1.25 Z-height and Backdrop is in Extend bounds horizontally mode

Pulse and Particle sorting

Pulses and Particles do not Z-fight even when occupying the same Z-height due to using a custom Translucency Sort Priority system. Each of these elements is given an integer upon spawning based on their Z-height, and globally decrements (reduces by one) the sort priority integer on any other elements before having its integer assigned.

This means that if two Pulses or Particles occupy the same Z-height, the newest element is shown on top. Pulses are spawned after Particles.

Info

The sort priority integer is determined by Z-height * 1000, rounded to the nearest integer. The sort priority integer is a signed 16-bit int, so the maximum Z-height allowed for objects to layer correctly is 32.767cm.

Z-axis size reference

Knowing the Z-height size of different elements is critical to being able to layer elements as desired. The following diagram shows a wireframe, side-on view of the Keysight scene under stock settings: Size reference Important information:

  • Most Pulse and Particle templates are set to 0.10 Z-height to put them above the optional Damper visualisation
  • The backdrop divider bar does not change with Piano key length and will always be 1.25
  • Most Light bar templates are set to be 1.25 or 1.30 to ensure they are layered above everything else
  • Note objects can have their Z-height scale changed, but this is independent to their Z-height offset

As a usecase example: if looking to place a Particle above Notes, under stock settings this would require a Z-height of at least 1.10, and 1.11 would be preferable just to ensure no Z-fighting.