The LayerCameraSettings property is of type FlatRedBall.Graphics.LayerCameraSettings which can be used to override the settings of the Camera when rendering the particular Layer. For more information on how to use this, see the LayerCameraSettings page.

Introduction

The Remove method is responsible for removing the argument object from the calling Layer. Remove has the following signatures:

Remove(Sprite spriteToRemove)

Remove(SpriteFrame spriteFrame)

Remove(Text textToRemove)

Remove(Scene scene)

Remove(IDrawableBatch batchToRemove)

When to call Remove

Calling Remove is usually not necessary. The reason is because the internal list that Layers use to keep track of objects is a two-way list. In other words, consider the following code:

// Assuming layer is a valid Layer
Sprite sprite = new Sprite();
SpriteManager.AddToLayer(sprite, layer);
// At this point the Sprite is part of the Layer
SpriteManager.RemoveSprite(sprite);
// Now the Sprite is no longer part of the Layer
if(layer.Sprites.Count == 0)
{
  // This will be true
}

Therefore, you will not need to call Remove to take a Sprite off of a Layer if you are using the SpriteManager to remove it. However, Remove can be useful if you would like to move a Sprite from one Layer to another:

// Assuming that layer1 and layer2 are valid Layers:
// Assuming layer is a valid Layer
Sprite sprite = new Sprite();
SpriteManager.AddToLayer(sprite, layer1);
// At this point the Sprite is part of layer1
layer1.Remove(sprite);
SpriteManager.AddToLayer(sprite, layer2);
// Now the Sprite is no longer part of layer1, but it is a part of layer2

Introduction

Layers provide a way to force a particular order of drawing on a single Camera. While the concept is fairly straight-forward, things can become more complicated when objects are moved from being layered to unlayered, or when objects have presence on multiple layers. Since there are a variety of ways to layer and unlayer objects, this article will present a number of small code blocks and explain what each one does.

The setup

First, let's start with some common code that all samples below will use. Consider the following line of code:

Layer firstLayer = SpriteManager.AddLayer();
Layer secondLayer = SpriteManager.AddLayer();

Okay, so far we have two layers that have been added to the SpriteManager. Keep in mind that secondLayer will actually be drawn on top of firstLayer - they are drawn in the order that they are created, so first is drawn first, then second is drawn on top of first.

A simple unlayered Sprite

Here's a very common setup (of course, assuming the lines above are still in the code).

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

As you may have guessed, the above code creates a Sprite which is managed and drawn, but not layered. We can show the membership as follows:

This table is just another way of showing what we mentioned before.

Making a layered Sprite

There are two ways to make a layered Sprite. The first is to use the AddToLayer method:

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

The AddToLayer method in the SpriteManager as well as all other Managers does two things:

1. Adds the Sprite (or other object) to the argument Layer

2. Removes the Sprite (or other object) from unlayered drawing

The result:

The SpriteManager provides a shortcut method for adding a Sprite directly to a Layer:

Sprite sprite = SpriteManager.AddSprite(
    "redball.bmp", 
    FlatRedBallServices.GlobalContentManager,
    firstLayer);

This code does the exact same thing if used instead of the two lines of code above. That is, this method both adds the Sprite for membership as well as adds it to the firstLayer but not to unlayered drawing.

Multiple Layer membership

The AddToLayer method does remove the argument Sprite from unlayered drawing, but it does not remove the argument Sprite from any other Layers that it belongs to. Therefore, a Sprite can be added to two Layers simply by calling AddToLayer twice:

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

The result:

Removal from Layers

To remove a Sprite (or any other object) from a Layer, simply call the Remove method. Keep in mind that calling Remove will not re-add the object to unlayered drawing.

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

As shown below, this makes the Sprite managed, but it will not be drawn.

Layered and Unlayered Drawing

Having an object be drawn layered an unlayered is not something supported by the FlatRedBall Engine. One reason for this is that in most cases, this is an undesirable behavior. It can hurt performance, as well as result in unexpected graphical behavior. But we're going to cover this anyway because it may help expose bugs that you are experiencing if you've tried this (or stumbled across it unintentionally).

// DON'T DO THIS!!!!!!!
Sprite sprite = SpriteManager.AddSprite("redball.bmp");
SpriteManager.AddToLayer(sprite, firstLayer);
SpriteManager.AddSprite(sprite);

This code needs some explanation. The first line makes the Sprite managed and drawn unlayered. The second line makes the Sprite layered, but removes it from unlayered drawing. Now, you may be thinking "Ok, the last line just re-adds the Sprite to the SpriteManager so it is drawn unlayered." Well, you're half right. The second AddSprite call does add the Sprite to be drawn, but it also has a nasty side-effect. The Sprite will actually be added to the SpriteManager twice. It was added once on the first line, and once again on the third line. This means that the Sprite will have its every-frame management performed twice. Not only does this hurt performance, but it results in properties like Velocity and Acceleration applied twice. In other words, you may get very unexpected behavior if you do this.

The AddToLayer behavior

The AddToLayer method has a little bit of inconsistent behavior. Let's explore it a little bit. FlatRedBall assumes that in most cases whenever you want an object drawn, you also want it managed. So, let's look at the following code:

// Let's make the Sprite manually instead of through the SpriteManager
Sprite sprite = new Sprite();
sprite.Texture = FlatRedBallServices.Load<Texture2D>("redball.bmp");
// Now add it to a layer
SpriteManager.AddToLayer(sprite, firstLayer);

So it's a safe bet that the Sprite will be drawn on the firstLayer, but what about management? Is it managed by the SpriteManager? We never called AddSprite. Drum roll please...

The SpriteManager actually added the object both to the layer as well as to itself for management. This behavior is present because it's assumed that drawn objects should be managed. There is one exception, however. The ShapeManager's AddToLayer method. Shapes have somewhat unique behavior in that they are most often used for collision, and many times they can exist and be used, but not be managed by the ShapeManager for performance reasons. Therefore, the ShapeManager does not add a shape for management unless you explicitly tell it to do so. In other words, adding a shape to a layer, but not to the ShapeManager results in the shape being drawn, but not managed. For more information on the reasoning behind this type of behavior, see the "Why Limit Shape Management" section of the ShapeManager page.

Introduction

The Sprites collection provides access to all ordered Sprites stored within this layer. This is a read-only collection so it cannot be directly modified through the layer. Note that this list only contains ordered sprites. Z-buffered sprites are stored in the Layer's ZBufferedSprites property.

Code Example

The Sprites property can be used to check if a Sprite is being displayed on a layer. The following code shows how to check if a Sprite is on a Layer.

if(LayerInstance.Sprites.Contains(SpriteInstance))
{
    // The sprite is contained on LayerInstance
}

Introduction

Each Layer can have its own SortType which controls how Sprites, Text, and IDrawableBatches sort. This property allows each Layer to have its own Sort type. By default objects on Layers will be sorted by their Z values - objects with smaller Z values (which are in the distance) will draw behind objects which have larger Z values (which are closer to the Camera).

General information

For general information abou tthe SortTypes property, see the SpriteManager's OrderedSortType property article. This article will discuss how sorting can be modified. Keep in mind that the SpriteManager article linked here discusses object sorting and uses the SpriteManager's OrderedSortType property which only controls how unlayered objects sort. In other words, changing the SpriteManager's OrderedSortType will not impact how Layers sort. Unlayered objects can sort differently than Layered objects, and each Layer can specify its own SortType.

Layer SortType and Camera rotation

If a Camera is unrotated, then the default SortType (Z) will work well. However, if your game uses a camera which can be rotated, then the default SortType may no longer produce desired results. For example, in a typical 3D game the Camera can face in any direction. When this occurs, objects with larger Z values are not guaranteed to be closer to the Camera than objects with smaller Z values. This is very noticeable when working with UI elements which are attached to the Camera. This is the main reason for the DistanceAlongForwardVector SortType. In most you can resolve ordering issues on UI/HUD elements which are attached to a rotated Camera by setting the Layer's SortType to DistanceAlongForwardVector:

UiLayer.SortType = SortType.DistanceAlongForwardVector;

Introduction

Layers can be used to control the order of visual objects on screen. Typically objects with a larger Z value appear on top of objects with smaller Z values, but this relationship is only true if the objects are on the same layer.

Layers take priority over the Z value of objects when performing rendering. Typically Layers are used to force groups of visual objects to draw on top of other objects. For example, a HUD layer can be used to force HUD UI such as score and health bars to appear on top of everything else in a game regardless of Z value.

Layers can be added in the FlatRedBall Editor or in code through the SpriteManager. For information on how to use Layers in the FRB Editor, see this article.

Example - Creating a Layer in FlatRedBall Editor

To create a new Layer:

1. Expand the Screen which should contain a layer. Note that layers are usually added to GameScreen and not Level screens unless you need to have a layer specific to a level.

2. Right-click on the Objects folder and select Add Object

3. Find the Layer type

4. Enter a name for the Layer

5. Click OK

Layer-able Types

The following types can be added to Layers:

• FlatRedBall.Graphics.IDrawableBatch

• FlatRedBall.Graphics.Text

• FlatRedBall.Math.Geometry.AxisAlignedCube

• FlatRedBall.Math.Geometry.AxisAlignedRectangle

• FlatRedBall.Math.Geometry.Capsule2D

• FlatRedBall.Math.Geometry.Circle

• FlatRedBall.Math.Geometry.Line

• FlatRedBall.Math.Geometry.Polygon

• FlatRedBall.Math.Geometry.Sphere

• FlatRedBall.Sprite

Additionally, Entities can be added to shapes through the FlatRedBall Editor, or through their MoveToLayer method.

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, objects in an entity which are attached to the root entity can span multiple layers despite having their positions controlled by the parent/child relationship. For example we can consider a typical entity which is made up of three (3) objects:

• The Entity itself

• The visible representation which is attached to the Entity, such as a Sprite

• The collision object which is also attached to the Entity, such as an AxisAlignedRectangle

Of these three, only the visible representation needs to be layered. 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 does not impact collision. 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.

Code Example - Using Layers

In code, 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;

AddToLayer Method

• SpriteManager.AddToLayer - Responsible for adding SpriteFrames, Sprites, and IDrawableBatches to Layers.

• TextManager.AddToLayer - Responsible for adding Texts to Layers.

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.

Adding Gum Screens to Layers

For more information, see the Adding Gum Components to Layers page.

Introduction

The UsePixelCoordinates can be used to easily create a 2D Layer. This method is often used in combination with attaching Entities to a Camera so that they can be placed in screen space. This method is used by Glue if a given Layer's "Is 2D" property is set true.

Code Example

The following example shows a situation where a Camera which is 3D (default) draws a 2D layer which contains some text. Add the following using statement:

using FlatRedBall.Graphics;

Add the following to Initialize after initializing FlatRedBall:

Layer layer = SpriteManager.AddLayer();
layer.UsePixelCoordinates();

Text text = TextManager.AddText("Hello I am text that sits on the top-left of the screen");
TextManager.AddToLayer(text, layer);

text.HorizontalAlignment = HorizontalAlignment.Left;
text.VerticalAlignment = VerticalAlignment.Top;
text.X = -SpriteManager.Camera.DestinationRectangle.Width / 2.0f;
text.Y = SpriteManager.Camera.DestinationRectangle.Height / 2.0f;
text.SetPixelPerfectScale(layer);

A note about attachments

The code above creates two different coordinate systems; however, if the Camera is moved, then the Text that is on the 2D layer will also be affected. Usually when creating 2D HUD and UI elements, they should also be attached to the Camera. If an object is attached to the Camera, it will always stay in the same place on-screen even if the Camera moves or rotates. Therefore, the positioning code could be modified as follows:

// After the Text is created and added to the Layer:
text.AttachTo(SpriteManager.Camera, false);

text.HorizontalAlignment = HorizontalAlignment.Left;
text.VerticalAlignment = VerticalAlignment.Top;
// Change the X and Y settings to relative
text.RelativeX = -SpriteManager.Camera.DestinationRectangle.Width / 2.0f;
text.RelativeY = SpriteManager.Camera.DestinationRectangle.Height / 2.0f;
// We want to make sure the Text is not at the same Z as the Camera.
text.RelativeZ = -40;

Introduction

The RenderTarget property can be set so a given Layer renders to the RenderTarget rather than to screen. The RenderTarget property can be used for a number of reasons:

• To create textures used in a multi-pass rendering system, such as to apply layer-wide effects like color tinting or bloom

• To improve the performance of complicated, static visuals on a Layer by eliminating the management of multiple objects and multiple draw calls with a single object and draw call (for a collection of objects which do not require every-frame activity)

If a Layer's RenderTarget is set, then the Layer will not render directly to the screen. Instead, the contents of the Layer are rendered to the RenderTarget which must then be rendered to the screen using another graphical object such as a FlatRedBall Sprite, a Gum Sprite, or SpriteBatch.

Setting RenderTarget in the FRB Editor

To set a RenderTarget in the FRB Editor:

1. Create a RenderTarget object
2. Create a Layer instance
3. Set the RenderTarget property on the layer to the previously-created RenderTarget

As mentioned above, the contents of the Layer are rendered to its RenderTarget instead of the screen. The easiest way to see the contents of the RenderTarget is to add a Sprite and use the RenderTarget as its Texture.

Code Example

The following code shows how a RenderTarget2D can be created and assigned to the Layer.RenderTarget property. This Layer contains a single Circle which is drawn with a separate unlayered Sprite:

using Microsoft.Xna.Framework.Graphics;

public partial class GameScreen
{
    // This Layer will contain all of the FRB objects which should be 
    // drawn on the render target:
    Layer layer;
    // This is the render target which will contain the final rendering 
    // of all FRB objects on 'layer'
    RenderTarget2D renderTarget;

    void CustomInitialize()
    {
        // Instantiate the layer:
        layer = SpriteManager.AddLayer();

        // Define the layer. This uses the current game's resolution, but it could be any size
        renderTarget = new RenderTarget2D(
            FlatRedBallServices.GraphicsDevice,
            FlatRedBallServices.GraphicsOptions.ResolutionWidth,
            FlatRedBallServices.GraphicsOptions.ResolutionHeight);
        layer.RenderTarget = renderTarget;

        var circle = new Circle();
        ShapeManager.AddToLayer(circle, layer);
        circle.Visible = true;
        circle.Radius = 40;

        var sprite = SpriteManager.AddSprite(renderTarget);
        // to show that the Sprite is rendering the circle, we'll squash it:
        sprite.Width = 300;
        sprite.Height = renderTarget.Height;
    }

    void CustomActivity(bool firstTimeCalled)
    {
    }

    void CustomDestroy()
    {
        SpriteManager.RemoveLayer(layer);
        renderTarget.Dispose();
    }

    static void CustomLoadStaticContent(string contentManagerName)
    {
    }
}

Note that the above code creates a Layer in code instead of creating one in the FRB editor. This is done purely to keep the example short - Layer instances created in the FRB editor can be used as well.

Update Frequency and One-Time Renders

RenderTarget instances can be updated every-frame, or can be rendered just one time (if the contents of the render target never change). The following code example shows how to create a RenderTarget which is used as the target only one time. This example differs in the following ways compared to the previous example:

• The layer is only needed temporarily until the render is done.

• The Renderer needs a temporary camera to perform rendering. While this example only uses a single Layer, multiple layers could be used to sort objects.

• Any rendered objects (such as entities, sprites, or shapes) are only needed for the Draw call and can be destroyed afterwards.

public partial class GameScreen
{
    // This is the render target which will contain the final rendering of all FRB objects on 'layer'
    RenderTarget2D renderTarget;

    void CustomInitialize()
    {
        // This layer holds whatever we want drawn
        var temporaryLayer = new Layer();
            
        // Define the layer. This uses the current game's resolution, but it could be any size
        renderTarget = new RenderTarget2D(
            FlatRedBallServices.GraphicsDevice,
            FlatRedBallServices.GraphicsOptions.ResolutionWidth,
            FlatRedBallServices.GraphicsOptions.ResolutionHeight);
        temporaryLayer.RenderTarget = renderTarget;

        // This example renders a rectangle, but the layer could have anything
        var rectangle = new AxisAlignedRectangle();
        rectangle.Visible = true;
        rectangle.Width = 50;
        rectangle.Height = 40;
        ShapeManager.AddToLayer(rectangle, temporaryLayer);

        // Rendering requires a camera. We'll create a temporary one (don't add it to the SpriteManager)
        var temporaryCamera = new Camera(null, renderTarget.Width, renderTarget.Height);
        // We only want the camera to draw the layer
        temporaryCamera.DrawsWorld = false;
        temporaryCamera.UsePixelCoordinates();
        temporaryCamera.Z = 40;
        temporaryCamera.AddLayer(temporaryLayer);

        Renderer.DrawCamera(temporaryCamera, null);

        // Anything which was rendered can be destroyed. In this case it's just a 
        // rectangle, but it could be entities, Gum objects, etc
        ShapeManager.Remove(rectangle);

        // This sprite will render our layer
        var sprite = SpriteManager.AddSprite(renderTarget);
        sprite.TextureScale = 1 ;
        // rotate it to show that the rectangle is drawn on the render target
        // (normally rectangles can't be rotated visually)
        sprite.RotationZ = Microsoft.Xna.Framework.MathHelper.ToRadians(45);
    }

    void CustomActivity(bool firstTimeCalled)
    {
    }

    void CustomDestroy()
    {
        renderTarget.Dispose();
    }

    static void CustomLoadStaticContent(string contentManagerName)
    {
    }
}

One-Time Renders and entities

The example above shows how to render an AxisAlignedRectangle using a one-time render to a RenderTarget. If entities (or other objects which have PositionedObject attachments) are rendered to a one-time render target, then dependencies (aka attachments) must be updated prior to rendering the render target. For example, the following snippet shows how multiple Ship instances might be rendered to a RenderTarget:

// This layer holds whatever we want drawn
var temporaryLayer = new Layer();
            
// Define the layer. This uses the current game's resolution, but it could be any size
renderTarget = new RenderTarget2D(
        FlatRedBallServices.GraphicsDevice,
        FlatRedBallServices.GraphicsOptions.ResolutionWidth,
        FlatRedBallServices.GraphicsOptions.ResolutionHeight);
temporaryLayer.RenderTarget = renderTarget;

// Create the ships (put them in a list so we can destroy them after drawing):
var temporaryShips = new PositionedObjectList<Ship>();
for(int i = 0; i < 10; i++)
{
    var ship = new Ship();
    ship.MoveToLayer(temporaryLayer);

    // The ship normally would have its dependencies automatically updated prior to
    // the regular FRB Draw method, but since we're doing custom rendering, 
    // the ship doesn't have chance to do so prior to our Draw call.
    // Therefore we'll manually update the dependencies after setting the
    // ship's position:
    ship.X = i * 30;
    ship.Y = 30;

    ship.UpdateDependenciesDeep();
}

// Rendering requires a camera. We'll create a temporary one (don't add it to the SpriteManager)
var temporaryCamera = new Camera(null, renderTarget.Width, renderTarget.Height);
// We only want the camera to draw the layer
temporaryCamera.DrawsWorld = false;
temporaryCamera.UsePixelCoordinates();
temporaryCamera.Z = 40;
temporaryCamera.AddLayer(temporaryLayer);

Renderer.DrawCamera(temporaryCamera, null);

// Anything which was rendered can be destroyed.
for(int i = temporaryShips.Count - 1; i > -1; i--)
{
    temporaryShips[i].Destroy();
}
        
// This sprite will render our layer
var sprite = SpriteManager.AddSprite(renderTarget);
sprite.TextureScale = 1 ;

Render Target Size

The RenderTarget2D constructor takes width and height parameters. These values can be as large as the current game's resolution, but they can also be smaller. If a smaller resolution is used, the Layer will be rendered at lower resolution, but the entire layer will still be drawn. For example, first we will modify the example above to no longer squash the Sprite:

    void CustomInitialize()
    {
        ...

        var sprite = SpriteManager.AddSprite(renderTarget);
        // Setting the TextureScale is an easy way to make it draw 1:1 on screen:
        sprite.TextureScale = 1;
    }

We can adjust the RenderTarget2D constructor so the RenderTarget is 1/4 the resolution, as shown in the following code snippet:

    void CustomInitialize()
    {
        layer = SpriteManager.AddLayer();

        renderTarget = new RenderTarget2D(
            FlatRedBallServices.GraphicsDevice,
            FlatRedBallServices.GraphicsOptions.ResolutionWidth / 4,
            FlatRedBallServices.GraphicsOptions.ResolutionHeight / 4);
        ...

Since the Sprite uses a TextureScale of 1, shrinking the RenderTarget2D will also shrink the Sprite:

To compensate for this, the Sprite.TextureScale property can be changed to 4. This will result in the RenderTarget2D being drawn at the same size as before, but it will be 1/4 the resolution, so it will appear pixellated (or blurred due to linear filtering):

    void CustomInitialize()
    {
        ...

        var sprite = SpriteManager.AddSprite(renderTarget);
        // Setting the TextureScale is an easy way to make it draw 1:1 on screen:
        sprite.TextureScale = 4;
    }

Rendering to a RenderTarget2D which is smaller than the game's resolution can improve performance, especially if the RenderTarget2D is used with effects which do not need full-resolution images, such as blurring.