Layer

Introduction

Layers provide a method of enforcing the order in which objects are drawn. This means that Layers can be used to override the default ordering of objects. In other words Layers can be used to make objects which are further from the Camera draw on top of objects which are closer to the Camera.

Draw order for Layers depends on their order in the SpriteManager’s Layer list.

For information on how to use Layers in Glue, see this article

Layer-able Types

The following types can be added to Layers:

Ordering with Layers as opposed to Z values

Although ordering does normally obey objects’ Z value, changing Z also changes an object’s size (if not in orthogonal mode) and can place an object outside of the Camera’s NearClipPlane and FarClipPlane. Furthermore, some objects such as HUDs and in-game UI should not be overlapped by any other objects.

Understanding the purpose of Layers

Layers are used only to control the drawing order of objects. This means that layers have nothing to do with the position of the objects that they contain.

For example, consider the Entity pattern. Entities usually are composed of 3 PositionedObjects:

  • The Entity itself
  • The visible representation which is attached to the Entity
  • The collision object which is also attached to the Entity

Of these three, the only PositionedObject which will get added to a Layer (if you want your Entity to be layered) is the visible representation. You can add the collision to a Layer, but this does not have any impact on the behavior of your collision. The only reason you might want to add the collision object to a layer is so it will be drawn if on the same layer as the visible representation if you desire to have it drawn for debugging reasons.

To clarify, adding the collision to a Layer will not provide some form of categorization. Two entities on different Layers will still be able to have their collision objects collide. The collision objects do not consider Layers when performing collision.

Using Layers

Layers are created through the SpriteManager. The following code creates a layer and two Sprites. Although the Sprite named nearSprite is closer than the Sprite named farSprite, farSprite is not hidden by nearSprite.

 Layer layer = SpriteManager.AddLayer();

 Texture2D texture = FlatRedBallServices.Load<Texture2D>("redball.bmp");

 Sprite nearSprite = SpriteManager.AddSprite(texture);
 nearSprite.Z = 20; // Brings it closer to the camera.

 Sprite farSprite = SpriteManager.AddSprite(texture);
 SpriteManager.AddToLayer(farSprite, layer); 

 // This puts the farSprite behind the nearSprite.
 farSprite.Z = -5;

LayeredSpriteBehindUnlayered.png

AddToLayer Method

Adding PositionedModels to Layers

Similar to Sprite and Texts, PositionedModels can also be layered. The following code creates a PositionedModel and adds it to a layer.

 Layer layer = SpriteManager.AddLayer();

 PositionedModel model = ModelManager.AddModel(ModelShape.Sphere);
 ModelManager.AddToLayer(model, layer);

Removing Objects from Layers

There are two ways to remove objects from Layers:

  1. Completely remove the object from the engine and its Layer(s)
  2. Remove the object just from the Layer but keep it in the engine

For reference, let’s use the following setup to discuss this point:

Texture2D texture = FlatRedBallServices.Load<Texture2D>("redball.bmp", "Global");
Layer layer = SpriteManager.AddLayer();

Sprite sprite = SpriteManager.AddSprite(texture, layer);
Text text = TextManager.AddText("I'm on a layer", layer);

1. Completely remove the object

This is the most common method of removing an object. It’s usually what you’ll do if you’re manually handling the removal of your objects (as opposed to letting Glue do it for you). To do this, simply use the manager removal methods:

// Here's how to remove the Sprite
SpriteManager.RemoveSprite(sprite);

// Here's how to remove the Text object
TextManager.RemoveText(text);
// Everything is now gone from the engine and Layer

In other words, remove your objects just like normal – they’ll automatically get removed from their Layers too.

2. Remove the object just from the Layer

Objects can be removed from Layers through the Remove method.

layer.Remove(sprite);
layer.Remove(text);

Now the Sprite and Text object are no longer on the layer, so they will not be drawn. However, the two objects have not been removed from their respective managers so they are still in memory and still managed every frame!

Using Multiple Layers

Multiple layers can exist at a given time. Calling AddLayer multiple times creates multiple layers. The newest layer is always on top while the oldest is on bottom.

Sorting objects within Layers

This section discusses sorting objects (such as Sprites within a Layer. For information on how to control the order that Layers are drawn, see the SpriteManager MoveToBack and MoveToFront page.

While Layers represent Lists in some ways, they cannot sort objects that they hold (like SpriteLists or PositionedObjectLists). The reason for this is because the internal SpriteList that a Layer references is used directly by the engine to draw the Layer. The engine may perform sorting on this list to ensure proper overlapping and to improve runtime performance so user-controlled sorting of the SpriteList may disrupt this behavior. If objects in a Layer need to be sorted they should be added to a separate SpriteList and sorted there.

Camera Layers

See FlatRedBall.Camera.Layer.

Adding an Entity to a Layer

If you are using Glue then you can add an Entity to a Layer. See this article for information on this.

Controlling Destination Rectangle

Layers will render to the full screen by default. Layers can be adjusted to only render to part of the Screen. For more information see the LayerCameraSettings destination coordinate page.