Layers

Layers allow the application to group primitives. Each layer results in a separate set of calls to the draw callback, which gives the application opportunity to modify the draw state on a per-layer basis.

As with other draw state, the layer ID is controlled by a stack:

PushLayerId("Foo");
	// primitives drawn here belong to layer "Foo"
PopLayerId();

// primitives drawn here belong to the default layer (ID 0)

PushLayerId("Foo");
	// passing the same ID again draws to the same layer
PopLayerId();

Note that PushLayerId(const char*) is equivalent to PushLayer(MakeId(const char*)).

Sorting

Layers can be used to achieve simple, coarse-grained sorting. Layers are drawn in the order which the application declares them, hence layers may be pre-declared to define a layer ordering as follows:

// set the layer order
PushLayerId("First");  PopLayerId();
PushLayerId("Second"); PopLayerId();
PushLayerId("Third");  PopLayerId();

// draw to layers in any order - the declaration order is preserved
PushLayerId("Second");
	// ...

Draw

Within the application-defined draw callback, the current layer may be used as follows:

void Im3d_Draw(const DrawList& _drawList)
{
	if (_drawList.m_layerId == MakeId("Foo")) {
	 // modify draw state per-layer (e.g. enable depth test)
	}
	// ...