When several objects overlap partially, some objects
appear in front of other objects. This effect is called drawing order or Z-order. Objects of layer N are placed
in front of objects of layers N-1 to zero. Moving objects from one
layer to another is one way of influencing the drawing order.
If there are several objects within the same layer, then
these objects again have a drawing order. Each layer has a spatial
data structure called quadtree which allows you to determine very
quickly which objects are at which position. By default, the quadtree
is enabled and determines the drawing order automatically in order
to achieve optimal performance. In this case, the drawing order cannot
be influenced.
If you want to specify the drawing order of objects within
the same layer, you must first enable the Z-ordering option of the
layer, by using the following method:
setZOrdering(boolean enable)
When Z-ordering is enabled for the layer, you can specify
the drawing order of the objects within the layer:
setIndex(IlvGraphic object, int index)
Note that the index is always a continuous range from
0 to N. This means that if you set the index of an object, the index
of other objects will shift by +1 or -1 to adjust the index range.
The current index can be retrieved by
getIndex(IlvGraphic object)
When Z-ordering is enabled, objects with a higher index
appear in front of objects of the same layer with a lower index.
Note
The drawing order between different layers takes precedence
over the drawing order within each layer: An object that is in a higher-numbered
layer is drawn in front of another object in a lower-numbered layer
even if the Z-order index of the first object is smaller than Z-order
index of the second object. Therefore, the Z-order index determines
only the drawing order of objects within the same layer.
Scenarios for experts
There are basically three scenarios:
The quadtree is enabled and Z-ordering
is disabled. This results in the highest performance. In particular
the hit-test (determining which objects are at a given position) is
optimally fast. However, it is not possible to influence the drawing
order within each layer.
The quadtree is enabled and Z-ordering
is enabled. This is slightly slower, depending on how many objects
overlap in average. The hit-test uses the quadtree and is still fast.
It is possible to specify the drawing order completely.
The quadtree is disabled. No matter
whether Z-ordering is enabled or disabled, it results in the same
speed, which is a large magnitude slower than when the quadtree is
enabled. When the quadtree is disabled, it is also possible to specify
the drawing order.
A test with 10000 objects showed that enabling Z-ordering
slows down the hit-test in average by a factor of 1.2-5, but disabling
the quadtree slows down the hit-test by a factor of 20-70. These factors
depend on the number of objects, and the factors are negligible if
you have only a very few objects. Furthermore, if Z-ordering is enabled,
the slowdown is mainly influenced by the overlapping depth (the number
of objects that are overlapping cover exactly the same location):
the higher the overlapping depth, the larger the slowdown of enabled
Z-ordering.