Introduction

The AddDrawableBatch method is used to add an existing IDrawableBatch-implementing instance to the engine. Once an IDrawableBatch instance is part of the engine, then it will be automatically rendered.

Code Example

The following code can be used to add a drawable batch to the engine, assuming that MyDrawableBatch is a valid DrawableBatch instance:

SpriteManager.AddDrawableBatch(MyDrawableBatch);

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.

Introduction

The SpriteManager is a static class which handles Sprite addition, removal, and common behavior. The SpriteManager also manages automatically updated PositionedObjects. By default all entity instances are added to the SpriteManager to have their every-frame activity called.

In most cases you will not need to write code to interact with the SpriteManager since most Sprites are created in generated code. However, if you are creating or destroying Sprite instances manually, you will probably need to work with the SpriteMangaer.

Sprites

The SpriteManager provides numerous methods for for working with Sprites. The following sections provide code samples for working with Sprite-related methods.

Sprite Addition

Most AddSprite methods both instantiate a new Sprite as well as add it to SpriteManager for management. The following methods instantiate and add a Sprite to the SpriteManager:

// This loads the texture "content/redball.png" using the global content manager
// then assigns it to the Sprite's Texture property
Sprite sprite = SpriteManager.AddSprite("content/redball.png");

// This loads the texture "content/redball.png" using a content manager named
// "Content Manager Name" then assigns it to the Sprite's Texture property.
Sprite sprite = SpriteManager.AddSprite("content/redball.png", "Content Manager Name");

// This manually loads the texture and then uses the resulting Texture2D to 
// create a Sprite and assigns the Sprite's Texture property.
Texture2D texture = FlatRedBallServices.Load<Texture2D>("redball.bmp");
Sprite sprite = SpriteManager.AddSprite(texture);

// Textures can (and often do) come from generated code, so textures from generated code
// can also be used to instantiate sprites:
Sprite sprite = SpriteManager.AddSprite(TextureFile);

For information on content managers, see the FlatRedBall Content Manager wiki entry.

Adding Sprites and Layers

Sprites can also be added to Layers.

Layer layer = SpriteManager.AddLayer();
Texture2D texture = FlatRedBallServices.Load<Texture2D>("content/redball.png");
Sprite sprite = SpriteManager.AddSprite(texture, layer);

Sprites which have already been created can be moved to layers.

// Assume sprite is a valid Sprite and layer is a valid Layer
SpriteManager.AddToLayer(sprite, layer);

The Sprite will no longer be an un-layered Sprite. Similarly entire lists can be added:

// Assume scene is a valid Scene that contains Sprites in its Sprites property
// and that layer is a valid Layer.
SpriteManager.AddToLayer(scene.Sprites, layer);

For more information, see the Layer wiki entry.

Sprite Removal

The RemoveSprite methods remove Sprites from the engine as well as two way PositionedObjectLists that the Sprites belong to.

// Assuming sprite is a valid Sprite which has been added to the SpriteManager
SpriteManager.RemoveSprite(sprite);

RemoveSprite can also remove entire lists:

 SpriteList spriteList = new SpriteList();
 // populate SpriteList by adding Sprites to it.

 // This will remove all Sprites contained in spriteList and also
 // clear spriteList if spriteList is a two-way list.
 SpriteManager.RemoveSprite(spriteList);

For more information see AttachableLists.

Managing PositionedObjects

See the PositionedObject page.

Read Only Lists

The SpriteManager provides read only access to its internal lists for debugging. It is not recommended to directly work with objects through these lists. The following lists the read only lists available:

• AutomaticallyUpdatedSprites

• DrawableBatches

• SpriteFrames

• ManagedPositionedObjects

These are static so you simply access them through the SpriteManager:

for(int i = 0; i < AutomaticallyUpdatedSprites.Count; i++)
{
   // do whatever
}

These lists are used by the ScreenManager to verify that all objects have been destroyed.

Introduction

The AddManagedInvisibleSprite method can optionally create and add a Sprite or simply add an already-created Sprite to a list which receives full every-frame updates without being rendered. In other words, any Sprite that has passed through the AddManagedInvisibleSprite method will be fully functional (velocity, attachments, animation, instructions), but will not pass through the rendering code. This can be used if you are rendering your own Sprites using .

When to use AddManagedInvisibleSprite

AddManagedInvisibleSprite is usually used in the following situations:

1. Sprites which require management but will not be drawn for a long time (perhaps their entire life).

2. Sprites which will be drawn using custom rendering code.

The AddParticleSprite returns a Sprite from the SpriteManager's internal particle pool. AddParticleSprite is internally used in the Emitter's Emit method, but can also be used if your game needs to create Sprites but you do not want to incur memory allocation during runtime.

The AddZBufferedDrawableBatch method adds an existing IDrawableBatch instance to the engine and tells the engine to render the IDrawableBatch so that it modifies the z buffer (also known as the depth buffer).

Introduction

The AddPositionedObject method is a method which adds an existing PositionedObject instance to the SpriteManager for management. Managed PositionedObjects will have velocity, acceleration, drag, and attachment properties applied automatically every frame. This method should only be called for objects which are otherwise not handled specifically by the FlatRedBall Engine. For example, Sprites are managed by the SpriteManager when they are added to the SpriteManager, so they should not also be added as PositionedObjects to the SpriteManager - doing so would result in update logic being called twice per frame.

AddPositionedObject and Entities

Entities added to Screens will automatically have AddPositionedObject called by default. The AddPositionedObject call is performed inside of all Entities' AddToManagers call. Therefore, in all but the rarest circumstances you will not need to call AddPositionedObject on an Entity.

When to use AddPositionedObject

AddPositionedObject can be used if you are creating a custom type which inherits directly from PositionedObject, and which should have every-frame logic called.

What does the SpriteManager call?

PositionedObjects which are added to the SpriteManager will have the following methods/logic called:

• FlatRedBall.PositionedObject.ExecuteInstructions

• FlatRedBall.PositionedObject.TimedActivity

• FlatRedBall.PositionedObject.Pause (If the engine is paused)

• FlatRedBall.PositionedObject.UpdateDependencies

Introduction

The AddSprite function is one of the most common functions in FlatRedBall. The AddSprite function adds a Sprite instance to the SpriteManager. It can also create new Sprite instances depending on which overload is called.

AddSprite Signatures

public static Sprite AddSprite(string texture)

public static Sprite AddSprite(AnimationChainList animationChainList)

public static Sprite AddSprite(AnimationChain animationChain)

public static Sprite AddSprite(string texture, string contentManagerName)

public static Sprite AddSprite(string texture, string contentManagerName, Layer layer)

public static Sprite AddSprite(Texture2D texture)

public static void AddSprite(Sprite spriteToAdd)

public static Sprite AddSprite(Texture2D texture, Layer layer)

Adding Sprites to Layers

To add a Sprite to a Layer, use the SpriteManager.AddToLayer method.

Note: The preferred way to access the Camera is through Camera.Main. This page is left here for historical purposes, but may be removed at some point in the future. Use Camera.Main in future code.

Introduction

The static Camera property in the SpriteManager class represents the main FlatRedBall Camera. This Camera is created automatically when FlatRedBall is initialized, and it is never destroyed. Most games only use one Camera, and this is the Camera that is used. For more information on Cameras in general, see the Camera page.

Accessing the Camera

The Camera can be accessed at any point after FlatRedBall has been initialized. For example, the following sets the Camera's XVelocity to 3:

SpriteManager.Camera.XVelocity = 3;

Introduction

ConvertToAutomaticallyUpdated can be used to convert an object back to an automatically updated object. This is useful for objects which typically do not move (so they shouldn't be automatically updated), but which may move from time to time. ConvertToAutomaticallyUpdated can be called on Sprites and PositionedObject.

Code Example

The following shows how an entity can implement its own ConvertToAutomaticallyUpdated in custom code:

public void ConvertToAutomaticallyUpdated()
{
   // Convert the entity itself:
   SpriteManager.ConvertToAutomaticallyUpdated(this);
   
   // Convert any Sprites:
   SpriteManager.ConvertToAutomaticallyUpdated(BodySprite);

   // Text objects may need to be converted too:
   TextManager.ConvertToAutomaticallyUpdated(HealthText);

}

Introduction

If you have never used the AddManualSprite method, then you have most likely worked with "automatically updated" Sprites. In fact, most objects which are added to managers are automatically updated, so the concept of whether something is updated or not may not have even been a consideration. While automatic updating or "management" is very convenient, it can also be inefficient - especially if situations with a large number of objects which do not need every-frame updates. One common example of unnecessary updating is when Sprites are used as "environment" such as tiles in a tile map. In these situations the Sprites are initially set, but after the initial positioning the Sprites will never move. Therefore, every-frame updates are unnecessary. In these situations manual Sprites can be used to reduce the overhead of each instance. The AddManualSprite method creates a Sprite which will not have its update called automatically. While this improves performance, any update(s) must be followed by a call to SpriteManager.ManualUpdate(spriteToUpdate). Without this call the changes will not be visible.

Code Example

The following code example shows a performance difference between manually and automatically updated Sprites. The performance numbers are recorded on a laptop which does not have a powerful graphics card. Therefore, computers with more powerful graphics cards may see more drastic changes in numbers between the two types of Sprites

Add the following using statement:

using FlatRedBall.Graphics;

Add the following at class scope:

Text text;

Do one of the following two:

Add the following to Initialize after initializing FlatRedBall to create a group of automatically updated Sprites:

 IsFixedTimeStep = false;
 graphics.SynchronizeWithVerticalRetrace = false;

 int numberOfSprites = 4000;
 for (int i = 0; i < numberOfSprites; i++)
 {
     // This will add automatically updated Sprites
     Sprite sprite = SpriteManager.AddSprite("redball.bmp");
     SpriteManager.Camera.PositionRandomlyInView(sprite, 45, 80);
 }

 text = TextManager.AddText("");

OR...

Add the following to Initialize after initializing FlatRedBall to create a group of manually updated Sprites:

 IsFixedTimeStep = false;
 graphics.SynchronizeWithVerticalRetrace = false;

 int numberOfSprites = 4000;
 for (int i = 0; i < numberOfSprites; i++)
 {
     Sprite sprite = SpriteManager.AddManualSprite("redball.bmp");
     SpriteManager.Camera.PositionRandomlyInView(sprite, 45, 80);
     // Since the Sprite has been "changed" by the 
     // PositionRandomlyInView, it must be updated
     SpriteManager.ManualUpdate(sprite);
 }

 text = TextManager.AddText("");

Add the following to Update to display frame time:

text.DisplayText = TimeManager.SecondDifference.ToString();

Related Articles

• FlatRedBall.SpriteManager.ConvertToManuallyUpdated - Can be used to convert an already-created object to be manually updated.

• Manually updated objects tutorial - Discusses details of manually updated objects.

Introduction

A Z-buffered uses the (also known as a ) to perform proper overlapping. Since the does not consider partial transparency, creating with transparency can create graphical artifacts.

Z-buffered sprites will only write to and read from the z buffer if the Camera's is true.

Code Example

The following code creates two .

Example without Z Buffer

Overlapping Problems

Z Buffered Sprites and Transparency

Z Buffered Sprites with transparency may not draw correctly. The reason for this is because the depth buffer does not necessarily know how to treat transparent pixels. FlatRedBall XNA attempts to resolve this issue by setting an alpha threshold for what gets drawn to the depth buffer (see below). If you are experiencing issues with transparency, consider the following:

• Eliminate transparency - this may not be preferred, but if you can eliminate transparency from your source image, you may be able to avoid this artifact.

• Reposition objects or your camera to avoid the undesired graphical issues.

Alpha Threshold

The Alpha Threshold (also known as ReferenceAlpha in XNA terms) is a value that defines the minimum alpha that will be rendered. FlatRedBall uses this value to prevent fully-transparent pixels from rendering to the depth buffer. The end result is that if you have an image which has either fully-opaque or fully transparent pixels, then you can use this image as a Z-Buffered Sprite without any problems. More specifically, the RenderState's ReferenceAlpha property is set to 1 (in a range of 0-255). This means that anything with an alpha value of 1 or greater will be rendered while pixels with an alpha of 0 will not be rendered, and more importantly will not modify the depth buffer.

More Information

A read-only collection of DrawableBatches, ordered bottom-to-top.

Introduction

The ConvertToManuallyUpdated method allows for the conversion of an automatically updated object to a manually updated object. Objects can be made manually updated so that they are still rendered by the engine, but automatic updates won't be performed. This can be done to improve performance. At the time of this writing, the following types can be converted to manually updated objects:

• FlatRedBall.Sprite

• FlatRedBall.PositionedObject (this includes Entities in Glue)

What does converting to manually updated do?

Converting a Sprite or PositionedObject to a manually updated disables the application of:

• Velocity

• Acceleration

• Drag

• RotationZVelocity

• RelativeVelocity

• Attachments

• Instructions

• Animations

Furthermore, the engine assumes that manually updated Sprites will not change very often. Therefore, it pre-calculates the vertices needed for rendering and caches them. If a Sprite does actually get updated, then it will need to have these vertices re-calculated. This can be performed through the ManualUpdate method.

Moving Manually-Updated Sprites

If a Sprite is moving and it is manually updated, then it will not visually reflect the movement unless:

• ManualUpdate is called

• The Sprite is converted back to being an automatically updated Sprite using ConvertToAutomaticallyUpdated

When to convert

In short, an object should be manually updated if it does not need automatic updates. This can improve performance. For more information, see the manually updated objects tutorial.

Introduction

ManagedInvisible Sprites are Sprites which the SpriteManager performs every-frame updates on them (such as applying Velocity, Acceleration, and attachment logic). These Sprites are not drawn by the engine. For more information on managed invisible Sprites, see the AddManagedInvisibleSprite method.

When to use ConvertToManagedInvisible

The most common way of creating managed invisible Sprites is to use SpriteManager.AddManagedInvisibleSprite. However, the AddManagedInvisibleSprite method both instantiates and places the newly-instantiated Sprite in the proper internal lists to make it managed invisible. If you are working with already-created Sprites, then you can use ConvertToManagedInvisible to convert the Sprites to be managed invisible Sprites.

Code Usage

Method signature:

public static void ConvertToManagedInvisible(Sprite sprite)

Common usage:

// assumes mySprite is a valid Sprite
SpriteManager.ConvertToManagedInvisible(mySprite);

Undoing ConvertToManagedInvisible

Since ConvertToManagedInvisible removes a Sprite from the engine, this function can be undone by re-adding the Sprite to the engine to be drawn. Specifically the SpriteManager.AddToLayer method can be used to have the Sprite be drawn by the engine:

// assuming SpriteInstance is a valid Sprite and LayerInstance is a valid Layer:
SpriteManager.AddToLayer(SpriteInstance, LayerInstance);

To add the Sprite so it is drawn but not on a Layer, it can be removed from the SpriteManager using SpriteManager.RemoveSpriteOneWay, then re-added using SpriteManager.AddSprite:

// assuming SpriteInstance is a valid Sprite
SpriteManager.RemoveSpriteOneWay(SpriteInstance);
SpriteManager.AddSprite(SpriteInstance);

Introduction

The ConvertToZBufferedSprite method can be used on Sprites which have already been added to the SpriteManager as ordered (not z-buffered). This method assumes:

• That the argument Sprite has already been added to the SpriteManager

• That the Sprite is not on a Layer

Code Example

The following code adds a Sprite regularly, then converts it to a ZBuffered Sprite:

Sprite sprite = SpriteManager.AddSprite("redball.bmp");
SpriteManager.ConvertToZBufferedSprite(sprite);

Additional Information

Sprites can be converted back to ordered Sprites. For more information, see the FlatRedBall.SpriteManager.ConvertToOrderedSprite page.

Introduction

ManualUpdate "applies" any changes to a manually-updated Sprite. Sprites are often made manually-updated for performance reasons. If you convert an entire FlatRedBall.Scene to be manually-updated, but you want parts of the Scene to have activity (such as rotational velocity), then you will need to call ManualUpdate on any Sprite which should be updated. Manually-updated Sprites must also have ManualUpdate called on them to have any render changes applied, such as changes to ColorOperations.

Code Example

To update a Sprite, simply call ManualUpdate on it:

SpriteManager.ManualUpdate(SpriteInstance);

The ManagedPositionedObject list in the SpriteManager object is a list of PositionedObjects which the SpriteManager is managing. In a typical project (using Glue), this list will contain mostly instances of Entities in your game, so you can look at this list to see what is actively managed.

Introduction

The AutomaticallyUpdatedSprites property in the SpriteManager is a list of all Sprites which the SpriteManager will apply standard behavior to. This includes velocity, rotational velocity, attachment, color rate changes, scale velocity, and animation. This list is made available for debugging and testing. It can be added to a watch window when Visual Studio has hit a breakpoint:

Adding and Removing from AutomaticallyUpdatedSprites

AutomaticallyUpdatedSprites is a SpriteList which is exposed for debugging, tools development, and advanced FlatRedBall programming. Most games do not need to add or remove Sprites directly from this list. This list is added to and removed from using more common FlatRedBall methods.

Adding to AutomaticallyUpdatedSprites

AutomaticallyUpdatedSprites gets populated whenever a Sprite is added through the SpriteManager. For example:

SpriteManager.AddSprite("redball.bmp"); // Instantiates a Sprite and adds it to AutomaticallyUpdatedSprites

Adding existing instances also adds the Sprite to AutomaticallyUpdatedSprites:

Sprite sprite = new Sprite();
SpriteManager.AddSprite(sprite);

Also adding a Sprite to a Layer will add it to AutomaticallyUpdatedSprites:

// assuming mySprite and myLayer are valid:
SpriteManager.AddToLayer(mySprite, myLayer);

Removing from AutomaticallyUpdatedSprites

AutomaticallyUpdatedSprites is a SpriteList which means it inherits from PositionedObjectList so it shares a two-way relationship with any Sprite that is added to it. Calling SpriteManager.RemoveSprite is the recommended way of removing a Sprite from this List.

Introduction

The SpriteManager performs pooling on its particle Sprites to prevent continual memory allocation. The MaxParticleCount property controls the size of the pool. A larger pool means that more particle Sprites can live at one time; however, it also means that the game will require more memory at runtime to store extra Sprites.

Code Example

MaxParticleCount defaults to a value of 2,900 at the time of this writing. This following code increases the maximum number of particles to 4,000.

SpriteManager.MaxParticleCount = 4000;

Why are particles pooled?

Particles generally have short lives and are created at a frequent interval. If all particles were allocated when needed and destroyed when not, this would result in a considerable amount of memory allocation and would cause the garbage collector to work more frequently than necessary. The garbage collector can cause significant hops in frame rate on the Xbox 360 and in Silverlight.

Why doesn't the engine automatically grow MaxParticleCount?

Usually the only time you need to grow MaxParticleCount is if you have created more particles (or anticiapte creating more) than the default MaxParticleCount value. You may be wondering why the engine doesn't simply expand this list as more particles are needed. There are two main reasons:

1. Expanding the list requires allocation. If the engine were to automatically expand the internal pool, this would likely be done in the middle of game play. All (or as much as possible) allocation should be done when a Screen is loaded and not during its Activity to prevent the garbage collector from working.

2. The MaxParticleCount can be used to catch bugs where particle Sprites are created but not destroyed. For example, if you have a single Emitter, but after 1 minute of emission you hit the MaxParticleCount, then it's likely that you are not removing emitted particles. If the engine automatically expanded the list, this bug would result in worse and worse frame rate - a symptom which doesn't lead you to the problem as quickly as an exception.

Introduction

The MoveToBack and MoveToFront methods can be used to control the order that Layers are drawn. Layers will, by default, draw in the order that they are added to the engine. If you are using Glue, Layers are drawn top-to-bottom. More information on Layer ordering in Glue can be found here.

Code Example

The following code creates three layers, then moves the first Layer to the "front" so that it is drawn on top of the other two. Without calling MoveToFront, the Layer would be drawn behind the other two as opposed to in front.

Layer layer1 = SpriteManager.AddLayer(); // This is drawn first (behind the other two)
Layer layer2 = SpriteManager.AddLayer(); // This is drawn second (between the other two)
Layer layer3 = SpriteManager.AddLayer(); // This is drawn last (in front of the other two)

SpriteManager.MoveToFront(layer1); // This makes layer1 drawn last (in front of the other now

The OrderedSprites list contains all of the Sprites that will be rendered by the SpriteManager. It does not include any Sprites which are on Layers, nor any Sprites which are z-buffered. This list can be used at runtime to verify whether Sprites that you expect to be created actually are created, or to investigate their properties in the watch window.

Introduction

RemovePositionedObject removes the argument PositionedObject from the SpriteManager and any other lists that it is a part of. This is usually called in generated code when an Entity's Destroy method is called, and is rarely called in custom game code.

RemoveSprite removes a Sprite from the SpriteManager. It also removes the Sprite from any rendering that may be done by the engine (such as if the Sprite is part of a Layer. This method can be called on any Sprite regardless of whether it belongs to a particular Layer, whether it is automatically or manually updated, or whether it is a particle or regular Sprite. Since Sprites have a two-way relationship with any PositionedObjectList or SpriteList that they are a part of, this method will also remove the Sprite from those lists.

The FlatRedBall.SpriteManager method will perform a "secondary" sort of all Sprites by their Texture. The first sort condition must be Z to preserve draw order. Sprites with the same Z value will then be sorted by Texture.

Introduction

The OrderedSortType property controls how Sprites and IDrawableBatches are ordered when they are drawn. Z Buffered Sprites do not use this property when drawing. The following available options exist:

Usage

The following code sets the SpriteManager's OrderedSortType to sort by distance from camera:

SpriteManager.OrderedSortType = SortType.DistanceFromCamera;

Code Example

The following code creates 10 Sprites, rotates them on the X axis, and sizes them to be a little larger so they overlap. Setting the OrderedSortType to DistanceFromCamera results in the Sprites overlapping properly whether the Camera is above or below the Sprites.

 for (int i = 0; i < 10; i++)
 {
     Sprite sprite = SpriteManager.AddSprite("redball.bmp");
     sprite.Y = - 15 + 3 * i;
     sprite.ScaleX = sprite.ScaleY = 12f;
     sprite.RotationX = 1.57f;
 }

 SpriteManager.OrderedSortType = SortType.DistanceFromCamera;

ZSecondaryParentY Details

The ZSecondaryParentY sort type is useful for top down and 3/4 view games. It allows moving objects (such as character entities) to be sorted based on their Y.

This is recommended for top-down and 3/4 view games. Note that Sprites use this sorting type only if they have the same Z. Therefore, if your entities have mulitple sprites with different Z values, they will interlace with other instances of the same entity.

For example if a character has a BodySprite and ShadowSprite, the ShadowSprite may have a Z value of -0.1 so that it always sorts behind the BodySprite of all other instances of the same entity type.

The following code shows how to set the OrderedSortType to ZSecondaryParentY:

SpriteManager.OrderedSortType = SortType.ZSecondaryParentY;

Using Entities to Set Sprite Origin

For Sprites, the sorting is performed according to the sprite's parent. This allows sorting to be performed at a point other than the Sprite's origin (center) for more natural sorting. For example, consider a game with units with different sizes. In this situation, developers are advised to align the Sprite objects to the bottom of the entity. For example, the red X marks the origin of the entity:

If these origins are used, then units will sort properly according to where they are "standing" as shown in the following image:

IDrawableBatch Sorting Details

The name ZSecondaryParentY suggests that objects are sorted by their Z value, then secondarily by their parents' Y value. Using a parent object (such as an entity) to control the sorting of a Sprite is useful (as shown above). Although IDrawableBatch implementations can have parents (especially if inheriting PositionedObject), IDrawableBatches are not required to have a parent. Therefore, the secondary sorting for IDrawableBatch instances is done by the Y property. While this limitation prevents using entities to set the origin of an IDrawableBatch, this can be resolved by offsetting the rendering of an IDrawableBatch so that its position marks its bottom. Furthermore, IDrawableBatch instances and Sprite will sort within the same category using Y values, but then Sprite vs. IDrawableBatch rendering is only performed by the Z value, even if the sort type is set to ZSecondaryParentY. If your game requires sorting Sprite vs. IDrawableBatch instances, you may need to adjust their Z value to force a particular sorting rather than relying on the Z value, or you may need to move all of your rendering to one type of object (either all Sprite or all IDrawableBatch).

Example with default OrderedSortType

The default OrderedSortType is SortType.Z. This sort type will result in Sprites overlapping incorrectly with the above example. To see the difference, replace the above code with:

 for (int i = 0; i < 10; i++)
 {
     Sprite sprite = SpriteManager.AddSprite("redball.bmp");
     sprite.Y = - 15 + 3 * i;
     sprite.ScaleX = sprite.ScaleY = 12f;
     sprite.RotationX = 1.57f;
 }

 // SortType.Z is the default value, but we'll explicitly set it anyway
 SpriteManager.OrderedSortType = SortType.Z;

Since all Sprites have an equal Z value (default of 0), then they are drawn in the order that they were added to the SpriteManager; from bottom-up. That means that the Sprites seen from below (at the top of the screen) will appear to overlap incorrectly.

CustomComparer

The SortType.CustomComparer allows you to define custom sorting logic for your Sprites. The following shows how to create and use an IComparer that sorts all ordered Sprites along their X axis: Add the following using statement:

using FlatRedBall.Graphics

Add the following to Initialize after initializing FlatRedBall:

for (int i = 0; i < 500; i++)
{
    Sprite sprite = SpriteManager.AddSprite("redball.bmp");
    sprite.ScaleX = 3;
    sprite.ScaleY = 3;
    SpriteManager.Camera.PositionRandomlyInView(sprite, 40, 40);
}

SpriteManager.OrderedSortType = SortType.CustomComparer;
Renderer.SpriteComparer = new SortByX();

Define the SortByX class:

public class SortByX : IComparer<Sprite>
{
    public int Compare(Sprite first, Sprite second)
    {
        return first.Position.X.CompareTo(second.Position.X);
    }
}

SpriteManager.OrderedSortType = SortType.DistanceFromCamera;

Sort Type Performance

For simple games (or on faster platforms) the OrderedSortType will not have much impact on performance. However, it may be useful to adjust your sort type if possible for performance if you suspect that the sort type is impacting your frame rate. The fastest sort type is OrderedSortType.Z. This is a stable sorting algorithm performing O(n) operations, and each operation is simply a comparison of Z values. The next fastest is OrderedSortType.ZSecondaryParentY which is a stable sorting algorithm which performs simple comparisons, but it must do two passes to sort first along Z, then along the Parent Y. OrderedSortType.DistanceFromCamera is a stable sort also performong O(n) operations, but requies math operations for comparison. The slowest sort type is OrderedSortType.DistanceAlongForwardVector. Due to floating point errors this is not guaranteed to be a stable sort which hurts its performance. It must also perform numerous math operations per Sprite prior to performing sorting so it can be expensive. The performance of custom sorting is not defined because any type of sorting can be performed in custom code; however, this type of sorting is not stable and uses a binary sorting algorithm meaning it performs O(n*log(n)) operations.

Introduction

The default ordering mode for Sprites in FlatRedBall is SortType.Z. The definition is rather straight forward - objects which have a Z that positions them further away from the Camera (smaller Z in all but FlatRedBall MDX) will be drawn first. Since closer Sprites are drawn after (within the same frame) Sprites which are further, they will overlap appropriately.

Same-Z Sprites

While it may be easy to image how Sprites with different Z values will draw, SortType.Z does not define how Sprites will be drawn when they have the same Z value. Of course, the engine doesn't use a random number generator to decide which should be drawn first - there is a method to it. Most articles which mention this topic encourage you to consider same-Z Sprites to have a random sorting order, but we'll cheat a little bit and explore. Internally FlatRedBall maintains a list of Sprites (as well as other ordered objects like Texts and IDrawableBatches). This list is sorted every frame just prior to drawing to guarantee proper ordering. It is very important that the sorting algorithm used is a "stable sorting algorithm". In other words, the sorting maintains the relative order of all same-Z Sprites. If this wasn't the case, then Sprites with the same Z value would shift positions every time the Sort method was called, causing them to flicker on screen. This means that if Sprite A is drawn on top of Sprite B, then it will *always* be drawn on top of B unless something in the program changes. Therefore, you might be thinking, there must be something that is controlling which is drawn on top of which. There is: For same-Z Sprites, the order is whichever Sprite was added first. Let's look at two blocks of code and their results to see this in action. This block of code adds two Sprites. The one on the right is added last. Since it is added last, it appears later in the list. Since FlatRedBall renders from the front to back of lists, Sprites added later will be drawn in front:

Sprite sprite1 = SpriteManager.AddSprite("redball.bmp");
Sprite sprite2 = SpriteManager.AddSprite("redball.bmp");
sprite2.X = 1;

Why depending on order is so bad

In the example above everything seems pretty clear and predictable - sprite2 is added after sprite1, so sprite2 will appear on top of sprite1 (assuming their Z values aren't changed). Of course, this code is far simpler than code you'll normally write when working with FlatRedBall. In many cases you won't be writing the code that actually creates Sprites. In the following cases the order of Sprite creation may be something you have no control over:

• Loading Scenes - Scenes loaded from .scnx files often instantiate Sprites. The instantiation of these Sprites is done inside of FlatRedBall calls, so you do not control which Sprite is instantiated first. Furthermore, different tools may be written in different versions of FlatRedBall, so the way they sort Sprites may also differ.

• SpiteGrids - SpriteGrids create and destroy Sprites if they are managed. This means that some Sprites in a SpriteGrid may be created at a much later time than other Sprites. It is possible to create situations where some Sprites in a SpriteGrid appear behind a large Sprite, while others appear in front when the SpriteGrid and the large Sprite all have the same Z.

• Emitters - Emitters can continually create Sprites while they are alive. Since they are continually created you may not have control over their ordering relative to other Sprites with the same Z value.

The moral of the story

You guessed it: Set your Z values. If you want to control how Sprites sort, then you should set Z values to prevent unexpected sorting.

Introduction

The RemoveDrawableBatch method removes the argument IDrawableBatch from the engine. Specifically it removes it from being rendered if it's layered, unlayered, Z-buffered, or specific to a Camera Layer.

Code Example

The following assumes a valid IDrawableBatch-implementing instance called DrawableBatchInstance:

Introduction

The RemoveSpriteOneWay method removes the argument Sprite from the SpriteManager (for both rendering and automatic updates) but does not modify any relationships between the Sprite and objects outside of the game engine. Specifically, RemoveSpriteOneWay will remove a Sprite from:

• Rendering

  • Ordered rendering

  • Z-Buffered rendering

  • Layered rendering

• Automatic engine updates

RemoveSpriteOneWay will not remove a Sprite from:

• Glue entities and other game-level

• Parent/child relationships

Code Example

The following code will remove a Sprite from the SpriteManager, but will preserve any game-level relationships:

Example - Moving Entity Sprites to Layers

RemoveSpriteOneWay can be used to move a Sprite from an entity to a different layer. Keep in mind that if the entire entity should be moved from one entity to another, call . However, to move an individual Sprite which is a part of an entity (such as a Sprite used to render glowing light), it needs to first be removed from the engine, then added to a different layer. The following code moves a Sprite which is part of a TorchInstance entity to a layer called LightLayer:

Introduction

The RemoveLayer function removes the current Layer from the SpritManager. This function can be used to remove Layers once they are no longer needed (such as Layers created in custom code), or to move Layers between different .

Code Example

The following code shows how to create and destroy a Layer in custom code. This code is similar to code created by Glue in generated code when a Layer is added to a Screen:

Moving Layers between containers

Layers can be contained in and in the SpriteManager (not associated with any Camera). For example the following code would remove a Layer from the SpriteManager and move it to a :

Note that the above code will result in an exception if the Layer is not manually removed from the when the Screen is destroyed.

Introduction

The UnderAllDrawn Layer is a Layer that is automatically created by the FlatRedBall Engine and available through the SpriteManager as a static member. This Layer can be used to render objects which should appear under other objects, such as game backgrounds. This layer can be used if your game already has a large number of un-layered objects and you want to add something that should always be drawn behind these objects. It will likely be much easier to add one (or a few) objects to the UnderAllDrawnLayer than to move all existing objects onto a new Layer.

Code Example

The following code creates a Sprite and adds it to the UnderAllDrawnLayer:

Sprite sprite = SpriteManager.AddSprite("redball.bmp");
SpriteManager.AddToLayer(sprite, SpriteManager.UnderAllDrawnLayer);

Introduction

The SortYSpritesSecondary performs a sort on all ordered so that sprites with a larger Y are drawn first. The sorting based off of Y is only done on Sprites which have the same Z value. Therefore, Z takes first priority, then with the same Z will be sorted so Sprites at the bottom of the screen (smaller Y values) will be drawn last (on top). If you desire to sort the Sprites by their Y to control drawing order, it is usually better to assign so that the ordered sort type doesn't conflict with the manual Y-based sorting.

Code Example - Manually Calling SortYSpritesSecondary

The SortYSpritesSecondary method can be called manually. Note that this is not needed if you have set the . To use SortYSpritesSecondary manually, call the method every frame at the end of Update. Add the following code at the end of your Update call (or your Activity method):