AddToLayer

Introduction

The AddToLayer object adds an existing object instance to the argument FlatRedBall.Graphics.Layer. The first argument object may or may not already be added to the SpriteManager. If the object is an unlayered object then it will be removed from the "world layer" and added to the argument Layer. However, if an object is already part of a different Layer it will continue to hold that membership after this call as well as being a member of the new Layer. In other words, this method can be called multiple times to have an object be drawn on multiple Layers.

Overloads

static public void AddToLayer(Sprite spriteToAdd, Layer layerToAddTo)
static public void AddToLayer(IDrawableBatch batchToAdd, Layer layerToAddTo)
static public void AddToLayer(SpriteFrame spriteFrame, Layer layerToAddTo)
static public void AddToLayer<T>(AttachableList<T> listToAdd, Layer layerToAddTo)

Code Example

The AddToLayer is very simple to use. Assuming you have a valid Layer and a valid object that can be added to the Layer, you can add it as follows:

// Assume myObject is a valid Sprite or SpriteFrame or IDrawableBatch and
// myLayer is a valid Layer:
SpriteManager.AddToLayer(myObject, myLayer);

Performance

The SpriteManager's AddToLayer method can be useful but suffers a small performance penalty when called on Sprites which have already been added to the SpriteManager. For example, the following code is functional but suffers a small performance penalty.

Sprite sprite = SpriteManager.AddSprite("redball.bmp");
Layer layer = SpriteManager.AddLayer();
SpriteManager.AddToLayer(sprite, layer);

Why is this expensive? The SpriteManager.AddSprite method tells the SpriteManager that the Sprite being added should be managed and drawn by the SpriteManager. This places the Sprite in the same category as unlayered Sprites. Calling SpriteManager.AddToLayer then places the Sprite on the argument layer. However, the SpriteManager must then remove the argument sprite from its internal SpriteLists. The following code is more efficient and preferred:

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

This code is functionally identical but slightly more efficient.