Introduction

The AnimateSelf function updates advances a Sprite through its animation (if it is animated) and updates the Sprite's Texture and texture coordinates according to its current animation. Sprites which are updated automatically (default) will automatically have this function called by the SpriteManager. Typically you only need to manually call this if a Sprite has been converted to manually updated, but it should still be animated.

Code Example

Typicalily the AnimateSelf function takes the TimeManager.CurrentTime value. The following code would animate a Sprite:

// assuming the Sprite SpriteInstance exists:
SpriteInstance.AnimateSelf(TimeManager.CurrentTime);

The AnimationChains property defines the AnimationChains used by the Sprite. This can be assigned in code or in the FlatRedBall Editor. For more information on working with AnimationChains in code, see the IAnimationChainAnimatable AnimationChains page.

Introduction

Many situations in game development can be simplified by changing the origin of an object (such as a Sprite). For example, you may make a tank turret Sprite, but the turret should not necessarily rotate around its center, but rather about the "base" of the turret. Another example may be a game where the player controls a character (such as a 2D platformer). In this situation you may want to make the origin of the Character at his feet. Unfortunatley, Sprites cannot have their origin simply changed. The center of a Sprite defines its rotation and the Scale values measure from the middle of the Sprite outward. However, shifting the origin can easily be simulated by using a PositionedObject as a parent and setting relative values.

For Glue Users

If you are using Glue, then most of your Sprites are probably already attached to Entities, which are PositionedObjects. Therefore, if you want to re-define the "center" of a Sprite, simply open the SpriteEditor for the given Entity and reposition the Sprite. The Sprite will be positioned with an offset so that the Sprite will be offset from the Entity's position.

For code users

If you are using code, then you will want to do the following:

1. Create a PositionedObject

2. Attach the Sprite to the PositionedObject

3. Set the offset using relative values

4. Control using the Entity

For example, your code may look like this:

// Assuming mySprite is a valid Sprite:
PositionedObject parent = new PositionedObject();
mySprite.AttachTo(parent, false);
mySprite.RelativeX = 3; // this gives the Sprite an X offset of 3 units
mySprite.RelativeY = 2; // this gives the Sprite a Y offset of 2 units
SpriteManager.AddPositionedObject(parent); // this makes the PositionedObject updated
// Now simply control "parent" and the Sprite will follow

Introduction

The Top, Bottom, Left, and Right properties return the X or Y values (as appropriate) of the edges of the Sprite in absolute coordinates. These values are equal to adding half of the width or height to the X or Y of the Sprite, but are provided for convenience.

Getting values

The following code example shows how to use the four edge values to position four Sprites. It assumes a Sprite named LogoSprite:

Circle topCircle = ShapeManager.AddCircle();
topCircle.Radius = 16;
topCircle.Y = LogoSprite.Top;

Circle bottomCircle = ShapeManager.AddCircle();
bottomCircle.Radius = 16;
bottomCircle.Y = LogoSprite.Bottom;

Circle leftCircle = ShapeManager.AddCircle();
leftCircle.Radius = 16;
leftCircle.X = LogoSprite.Left;

Circle rightCircle = ShapeManager.AddCircle();
rightCircle.Radius = 16;
rightCircle.X = LogoSprite.Right;

For information on ColorOperation, see the page.

Introduction

The Sprite is a flat graphical object which is commonly used as the visuals for entities and for particles. Sprites can also be used to display tilemaps and UI, although Tiled and Gum provide more flexibility and performance. The Sprite class inherits from the class.

Sprites are usually created through the FlatRedBall Editor when associated with entities, although Sprites can also be created in code when dynamic visuals are needed.

Creating a Sprite in Code

In most cases, a Sprite can be created in code by instantiating it, assigning a texture, and adding it to the SpriteManager so that it is drawn. The following code assumes that TextureFile is a valid Texture2D:

Once the Sprite has been created, it will persist until it is removed. If your game does not navigate to other Screens, and if you do not need to remove the Sprite, then no additional code is needed.

If you would like to remove your Sprite, you can call SpriteManager.RemoveSprite:

If you are creating a Sprite that is owned by a FlatRedBall Screen or Entity, then you will need to either:

• Explicitly call RemoveSprite when it is time to destroy the object containing the Sprite (usually CustomDestroy )

• Add the Sprite to a PositionedObjectList<Sprite> created in the FlatRedBall Editor on the container. When the container is removed, then the contents of the sprite list will automatically get removed from the engine.

Sprite Scale

Texture

Color and Alpha

Z Buffered Sprites

Particle Sprites

Introduction

The TopTextureCoordinate, BottomTextureCoodinate, LeftTextureCoordinate, and RightTextureCoordinate properties control the coordinates in "uv space" of the top, bottom, left, and right sides of the Sprite. In other words, these values can be used to make a Sprite draw part of a texture instead of the entire thing. These properties are often used when working on games that use sprite sheets. The default values are as follows:

• TopTextureCoordinate = 0

• BottomTextureCoordinate = 1

• LeftTextureCoordinate = 0

• RightTextureCoordinate = 1

What are "texture coordinates" and how do they compare to pixels

Texture coordinates are often used in games (not just FlatRedBall) to measure points on a texture. Texture coordinates are often displayed as two values separated by commas within parenthesis. For example:

and

The texture coordinate is a coordinate which measures location on a texture, but this coordinate does not use pixels. For example, if you're used to using pixels, you may be familiar with (0,0) being the top-left of an image. If your image is 32 pixels tall and 32 pixels wide, then the bottom-right of the image would be (32, 32). In texture coordinates, the top left is (0, 0). The bottom-right is (1, 1). You can think of texture coordinates as representing a percentage. In other words, a value of 0 means 0%. 1 means 100%. A value of 0.5 means 50%. Therefore, a value of (.5, 0) means "50% of the width (starting at the left) and 0% of the height (starting at the top). Therefore, the very center of the image is (.5, .5).

Code example

Texture coordinates can be adjusted to create objects which show only part of a texture, such as health bars. The following code shows how to create a Diablo-like health meter (of course, using a red ball): Files used:

Add the following at class scope:

Add the following to Initialize after initializing FlatRedBall:

Add the following to Update:

Add UpdateFill at class scope:

For Glue users

If you are modifying the code above to be used in an Entity, and if the Sprite you are modifying is part of the given Entity, then it is likely that the Sprite is attached to the Entity. Therefore, you will need to replace any code that gets or sets the mFillSprite's Y value with RelativeY. In the code this is done in two parts - in Initialize where mBaseY is set, and the last line in UpdateFill where the Sprite's Y is set.

Additional Information

Controls the playback speed of animations when the Sprite is displaying an AnimationChain. For more information, see the IAnimationChainAnimatable AnimationSpeed page.

The JustCycled returns true when the Sprite has just finished its animation and has cycled (returned from the last frame to the first). This can be used to perform logic when a Sprite has looped its animation. For more information, see the IAnimationChainAnimatable.JustCycled page.

In general it is not recommended to inherit from the Sprite class. This can reslt in cluttered interfaces and improper instantiation of objects. Instead, we recommend using the Entity pattern for your game objects. However, if you are sure that inheriting from the Sprite class is the only solution to your problem, you can do so by instantiating an object using your derived class, then adding it to the SpriteManager. Assuming DerivedSprite is a class which inherits from the Sprite class, the following code can be used to add a newly created instance of the derived class to the SpriteManager and assign its texture.

DerivedSprite derivedSprite = new DerivedSprite();
derivedSprite.Texture = FlatRedBallServices.Load<Texture2D>("redball.bmp");
SpriteManager.AddSprite(derivedSprite);

Introduction

The IgnoreAnimationChainTextureFlip property can be used to control whether a Sprite's FlipHorizontal and FlipVertical values are changed by the current AnimationChain. This value defaults to true, meaning that a Sprite's current AnimationChain will overwrite the Sprite's FlipHorizontal and FlipVertical when the frame changes. In other words, if IgnoreAnimationChainTextureFlip is true (default value), and a Sprite is using an AnimationChain, then the FlipHorizontal and FlipVertical will be overwritten by the AnimationChain so they should not be manually set.

Code Example

The following code assigns a Sprite instance's CurrentChainName property to "Walk" , but tells the sprite to not apply the AnimationFrame.FlipHorizontal value:

// assume SpriteInstance is a valid Sprite with AnimationChains containing "WalkRight"

SpriteInstance.IgnoreAnimationChainTextureFlip = true;
SpriteInstance.CurrentChainName = "WalkRight";

Usage Discussion

The IgnoreAnimationChainTextureFlip value is often used to prevent an AnimationChain from controlling a Sprite instance's FlipHorizontal value. It also prevents the FlipVertical value from being modified, but FlipHorizontal value is more commonly used to face a character left or right in a side-view game. Games including characters which can face to the left or right have two options for flipping the visuals:

1. Create two AnimationChains - one facing left and one facing right. Since each frame can flip the sprite, the left and right-facing animations can use the same source images/sprite sheets.

2. Create a single AnimationChain, but control Sprite.FlipHorizontal in code.

The first approach lets the AnimationChain (.achx) file fully control the visuals of the sprite. This means that the walk left vs. walk right may simply be flipped, or it means that different animations can be created for each direction. For example, if the character carries a sword, the sword may be in front of the character when walking one direction, but behind the character when walking the other direction. The second approach can be easier to implement in code since it does not require additional content (modifications to the .achx file). Developers are encouraged to use the first approach as it does not introduce any performance penalty, and allows content to be modified without any code at a future time.

Sprite implements the IAnimationChainAnimatable interface. For more information, see the IAnimationChainAnimatable.CurrentFrameIndex page.

Introduction

The Alpha value controls the opacity of a Sprite. A value of 1 (default) results in a fully-opaque Sprite, while a value of 0 is a fully-transparent Sprite. For more information see the Alpha property on IColorable. Sprite Alpha can be also be set in Glue directly and through states. Sprites can also be made fully invisible by setting the FlatRedBall.Sprite.Visible property to false.

Code Example

The following shows how to make a Sprite fully transparent:

SpriteInstance.Alpha = 0;

The following shows how to make a Sprite fully opaque:

SpriteInstance.Alpha = 1;

The following shows how to make a Sprite half opaque:

SpriteInstance.Alpha = .5f;

OBSOLETE The PixelSize property is an obsolete property which was commonly used prior to summer 2013. The property has replaced the PixelSize property. The PixelSize property is equivalent to TexutureScale/2. The PixelSize property was originally created to work well with ScaleX and ScaleY values, but since then , Width, and Height have replaced PixelSize, ScaleX, and ScaleY as the most common ways to interact with a Sprite.

Introduction

The TopTextureCoordinate, BottomTextureCoodinate, LeftTextureCoordinate, and RightTextureCoordinate properties control the coordinates in "uv space" of the top, bottom, left, and right sides of the Sprite. In other words, these values can be used to make a Sprite draw part of a texture instead of the entire thing. These properties are often used when working on games that use sprite sheets. The default values are as follows:

• TopTextureCoordinate = 0

• BottomTextureCoordinate = 1

• LeftTextureCoordinate = 0

• RightTextureCoordinate = 1

What are "texture coordinates" and how do they compare to pixels

Texture coordinates are often used in games (not just FlatRedBall) to measure points on a texture. Texture coordinates are often displayed as two values separated by commas within parenthesis. For example:

and

The texture coordinate is a coordinate which measures location on a texture, but this coordinate does not use pixels. For example, if you're used to using pixels, you may be familiar with (0,0) being the top-left of an image. If your image is 32 pixels tall and 32 pixels wide, then the bottom-right of the image would be (32, 32). In texture coordinates, the top left is (0, 0). The bottom-right is (1, 1). You can think of texture coordinates as representing a percentage. In other words, a value of 0 means 0%. 1 means 100%. A value of 0.5 means 50%. Therefore, a value of (.5, 0) means "50% of the width (starting at the left) and 0% of the height (starting at the top). Therefore, the very center of the image is (.5, .5).

Code example

Texture coordinates can be adjusted to create objects which show only part of a texture, such as health bars. The following code shows how to create a Diablo-like health meter (of course, using a red ball): Files used:

Add the following at class scope:

Add the following to Initialize after initializing FlatRedBall:

Add the following to Update:

Add UpdateFill at class scope:

For Glue users

If you are modifying the code above to be used in an Entity, and if the Sprite you are modifying is part of the given Entity, then it is likely that the Sprite is attached to the Entity. Therefore, you will need to replace any code that gets or sets the mFillSprite's Y value with RelativeY. In the code this is done in two parts - in Initialize where mBaseY is set, and the last line in UpdateFill where the Sprite's Y is set.

Additional Information

Introduction

The Position field can be used to get or set the position of a Sprite. A Sprite's position represents the center of the Sprite.

If a Sprite is attached to another object (such as an Entity) then its Position is determined by the position of its parent Entity and its Relative values. Attached Sprites may also be moved by their animation. In these situations, the Position value is effectively read-only.

Introduction

The TopTextureCoordinate, BottomTextureCoodinate, LeftTextureCoordinate, and RightTextureCoordinate properties control the coordinates in "uv space" of the top, bottom, left, and right sides of the Sprite. In other words, these values can be used to make a Sprite draw part of a texture instead of the entire thing. These properties are often used when working on games that use sprite sheets. The default values are as follows:

• TopTextureCoordinate = 0

• BottomTextureCoordinate = 1

• LeftTextureCoordinate = 0

• RightTextureCoordinate = 1

What are "texture coordinates" and how do they compare to pixels

Texture coordinates are often used in games (not just FlatRedBall) to measure points on a texture. Texture coordinates are often displayed as two values separated by commas within parenthesis. For example:

and

The texture coordinate is a coordinate which measures location on a texture, but this coordinate does not use pixels. For example, if you're used to using pixels, you may be familiar with (0,0) being the top-left of an image. If your image is 32 pixels tall and 32 pixels wide, then the bottom-right of the image would be (32, 32). In texture coordinates, the top left is (0, 0). The bottom-right is (1, 1). You can think of texture coordinates as representing a percentage. In other words, a value of 0 means 0%. 1 means 100%. A value of 0.5 means 50%. Therefore, a value of (.5, 0) means "50% of the width (starting at the left) and 0% of the height (starting at the top). Therefore, the very center of the image is (.5, .5).

Code example

Texture coordinates can be adjusted to create objects which show only part of a texture, such as health bars. The following code shows how to create a Diablo-like health meter (of course, using a red ball): Files used:

Add the following at class scope:

Add the following to Initialize after initializing FlatRedBall:

Add the following to Update:

Add UpdateFill at class scope:

For Glue users

If you are modifying the code above to be used in an Entity, and if the Sprite you are modifying is part of the given Entity, then it is likely that the Sprite is attached to the Entity. Therefore, you will need to replace any code that gets or sets the mFillSprite's Y value with RelativeY. In the code this is done in two parts - in Initialize where mBaseY is set, and the last line in UpdateFill where the Sprite's Y is set.

Additional Information

Introduction

Many FlatRedBall users often mistake "Sprites", "image files", and "Textures". This misconception can be supported by the close relationship between the three, especially since Sprites can be created as follows:

At first glance, the code above may look like it is "creating a Sprite from a bitmap." This is technically not true, and in some cases the details of what is happening behind the scenes in the above call are very important. This wiki entry discusses the differences between image files, Textures, and Sprites in an effort to reduce the confusion.

Image, Texture2D, and Sprite

So far we've been using the more general "Texture" term to describe the class. In FlatRedBall XNA, the class is a class that is part of the XNA framework. This article will use this class in discussion, but many of the same concepts apply to FlatRedBall MDX's Texture2D class and the Texture2D class provided by SilverSprite used in FlatSilverBall. The Sprite class can be thought of as a canvas to display a Texture2D. A Texture2D can be swapped without changing the size, location, or any other property of the Sprite that is displaying the Texture2D - at least unless the PixelSize is set to a non-zero value. However, for this article we'll assume that PixelSize is not used. Textures are different from image files as well, although this distinction isn't quite as important as Sprite vs. Texture2D. Image files are loaded to create Texture2Ds out of them. The image file is the image that sits on disk while the Texture2D is the information sitting in RAM which Sprites and other objects can reference. One way to think about a Sprite is to imagine it as a . The image it displays (Texture2D) can be swapped without modifying its size, position, or other property.

Dissecting AddSprite

The following code is both very common but actually performs a lot of functinality "under the hood":

To understand what the above code does, consider the following block of code which is functionally identical:

The Texture property is simply set inside the AddSprite method when passing a file name to the method. Almost all Sprites have a non-null Texture2D set to their Texture property so the SpriteManager provides the AddSprite(string textureFileName) method for convenience.

Texture Caching

When Textures are created through FlatRedBallServices, they are cached to offer faster access in the future. For example, the following code loads the redball.bmp image just once, then uses the cached version for additional calls:

Introduction

Many games require to overlap to create realistic scenes. FlatRedBall offers a number of ways to control sorting. This article will discuss and link to various methods of controlling how (and other objects) overlap.

What are the methods?

There are a number of methods of controlling overlapping . Keep in mind that these methods are not just used for , but for as well. and also use many of the methods mentioned below. These methods are:

• Setting Z value

• Using the depth buffer (also known as the z buffer)

• Using

• Using multiple

Setting Z Value

Setting the Z value of objects is an easy way to control sorting of objects. Of course, this method is mostly used when the is in its default, unrotated state. and are, by default, created as "ordered" objects. This means that FlatRedBall sorts these objects by their Z values every frame, then draws them "back-to-front" so that objects in back are overlapped by objects in front. This method of sorting is very common and is acceptable for many games. Often if the is not , then the Z value can also be used to place objects in the distance, making them smaller due to the natural perspective of a 3D . In this case, the Z value has the dual purpose of making objects seem like they are in the distance due to on-screen size changes as well as controlling the sorting. If the is (also known as a 2D ), then the Z value won't impact the on-screen size of an object, but it will still impact its sorting. In these cases, the Z value is used purely to control sorting. It is also common when using a 3D to use very small differences in the Z value between objects to force a particular sorting. For example, if you are making a 2D platformer which has a player and grass both on the ground, you may set the player's Z to 0 and the grass to -.0001 so that they are drawn in front of the player.

Objects with the same Z

If two objects have the same Z value, their sorting priority is undefined. While there technically is a method to how FlatRedBall picks the order, this order is subject to performance optimizations and can vary between different versions of the engine. The bottom line is, you should never rely on the particular sorting order that you see for two objects that have the same Z value. If you require a particular sorting order, enforce it by explicitly setting different Z values, or by using one of the other sorting methods mentioned below.

Sorting on Y

Many top-down games have objects that should overlap each other depending on their Y positions. This functionality is built-in to FlatRedBall. For more information see the .

Using the depth buffer

Diagram

Introduction

The TextureAddressMode controls how Sprites display their texture outside of the 0 - 1 range. TextureAddressMode can be used to create tiles and texture scrolling. TextureAddressMode is usually used in combination with . For more information on texture coordinates, see the .

Usage Example

The following code creates three sprites. It assumes that the texture star is in scope (such as added to the Screen containing the code);

Note: The Wrap texture address mode requires that textures are a power of 2 on the Windows Phone.

Simulating Scrolling

Changing a Sprite's texture coordinate values while using TextureAddressMode.Wrap is an easy way to simulate a scrolling background with one Sprite. The following code creates a single Sprite which appears to be scrolling. Add the following using statements:

Add the following in Initialize after initializing FlatRedBall:

Add the following in Update:

The TextureFilter property controls how a given Sprite renders when zoomed in. This is a nullable value, which defaults to null. If null, then the Sprite will use the GraphicsOptions.TextureFilter value when rendering. In other words, setting the Sprite's TextureFilter overwrites the default TextureFilter. For an example of how TextureFilter impacts rendering, see the GraphicsOptions.TextureFilter page.

Introduction

The SetAnimationChain method sets the Sprite's current AnimationChain.

SetAnimationChain(AnimationChain chainToSet, double timeIntoAnimation)

This method can be used if the to set both the AnimationChain as well as how far into the AnimationChain the Sprite should set itself. The overload for SetAnimationChain which takes a double as a second argument sets how far into the argument chainToSet the Sprite beings animatingn after this call is made. For example, if the chainToSet has AnimationFrames of length .1, then passing a value of .25 will set the Sprite's CurrentFrameIndex to 2, and the AnimationFrame at index 2 will show for .05 seconds instead of the full .1 seconds. Setting a value of 0 will make the Sprite start the animation at the beginning. If a value of less than 0 is passed as the timeIntoAnimation, the SetAnimationChain method will throw an exception. If a value that is greater than the argument chainToSet's TotalLength, the TotalLength of the chainToSet will be continually subtracted from timeIntoAnimation until the resulting value is less than the TotalLength value. Then the remainder will be applied. This simulates cycling the animation.

Introduction

The UseAnimationRelativePosition value controls whether relative values from the current AnimationFrame are applied to the Sprite. Relative values can be set in code, or can be set in the AnimationEditor. A Sprite must be attached to another PositionedObject for relative values to have an impact on absolute position. In Glue this value is set to true by default. This means that any Sprite using an AnimationChain will automatically be positioned within its entity using the relative values of the AnimationChain. If this is not desired, the value should be set to false.

When to use this value

If you are applying offset values in a .achx and you want these offset values to apply to Sprites (usually within an Entity) then this value should be true. If you are using a .acxh file, if the Sprite is part of an Entity, and if you want to manually move the Sprite around (either in code or in Glue), then this value should be set to false.

Default Values

Sprites which originate from Scenes (.scnx files) will have this property set to true, therefore their relative values will be overridden by their AnimationChain. If you are using Glue, you can set this to false through a tunneled variable, or in custom code if you want to use custom positioning:

SpriteInstance.UseAnimationRelativePosition = false;

TimeIntoAnimation returns the number of seconds since the start of the animation. This value is used to determine which frame of animation a Sprite should show. This value can be set to change the frame that the animation is in.

Introduction

The Vertices property provides control over setting color values on individual corners of a Sprite. Setting the Red, Green, Blue, or Alpha values changes the values on all four vertices.

Code Example

Assuming that SpriteInstance is a valid sprite, this sets the top left and top right corners to have a red value of 1:

SpriteInstance.Vertices[0].Color.X = 1;
SpriteInstance.Vertices[1].Color.X = 1;

Setting Color

Color values are represented by a Vector4 value, with the following mapping:

• X = Red

• Y = Green

• Z = Blue

• W = Alpha

Sets the current AnimationChain based on its name. The AnimationChain must be part of the Sprite's AnimationChains. For more information on working with the CurrentChainName property, see the IAnimationChainAnimatable CurrentChainName page.

Introduction

The TextureScale property can be used to size a Sprite according to its Texture and texture coordiantes. If a Sprite which is displaying its full texture is using a TextureScale of 1, then the Sprite's width will match its Texture's width, and the Sprite's height will match the Texture's Height. A TextureScale of 1 is the most common value, and this is the default for Sprites created in a 2D Entity in the FlatRedBall Editor. TextureScale works by changing a Sprite's Width and Height properties according to a Sprite's Texture and texture coordinate values. Therefore, whenever a Sprite's Texture or texture coordinates change, the Sprite's Width or Height may change if the Sprite is using a TextureScale. If TextureScale of 0, the Sprite will ignore this value and use its existing Width and Height values instead.

When does TextureScale change Width and Height values values?

The TextureScale value changes the Width and Height values according to the Texture size. The Width and Height of a Sprite will change when the following occur (assuming TextureScale greater than 0):

• Setting TextureScale

• Setting Texture

• Setting LeftTextureCoordinate, RightTextureCoordinate, TopTextureCoordinate, BottomTextureCoordinate

• When an animation frame changes (if the Sprite is using AnimationChains)

TextureScale can overwrite Scale/Width/Height values

Whenever TextureScale is not 0, it will overwrite Width/Height values when any of the values mentioned above change. For example:

// assuming mySprite is a valid Sprite
mySprite.TextureScale = 1f;
mySprite.Width = 10; // We'll assume this value is different than what is set by TextureScale
mySprite.Texture = SomeTexture; // This will reset the Width, overwriting the 10 value

Code Example

The following example creates two Sprites. Their TextureScale is set to the same value. Therefore, their sizes relative to each other is the same as the sizes of their Textures relative to each other.

Sprite ball = SpriteManager.AddSprite("redball.bmp");
ball.TextureScale = 1;
ball.Y = 100;

Sprite logo = SpriteManager.AddSprite(@"Assets\Scenes\frblogo.png");
logo.TextureScale = 1;
logo.Y = 200;

TextureScale and Power of Two

Some older video cards cards expect that all textures have a power of two width and height. In some cases, textures may even be re-sized to fit this requirement. For example, if the current graphics card requires a power of two, an image that is 100X300 may be re-sized to a texture that is 128X512 when loaded in the game. The resizing always increases the resolution of images. This can cause problems if your code uses TextureScale for Sprites which are displaying textures which are not a power of two. The reason is because you may see different behavior on different machines. Using the example above, if you were to load the 100X300 image and display it with a Sprite using a TextureScale of 1, then you would see the following results: On a machine that doesn't resize:

mySprite.ScaleX will be 50
mySprite.ScaleY will be 150

On a machine that does resize:

mySprite.ScaleX will be 64
mySprite.ScaleY will be 256

The solution to this problem is to make sure all of your images have power of two width and height.

Animations "resetting" Scale

If you are using an Animation on your Sprite, and you are modifying the scale of your Sprite, then you must do one of two things:

• Change TextureScale instead of Width/Height (or ScaleX/ScaleY)

-- or --

• Set TextureScale to 0, then manually adjust Width/Height (or ScaleX/ScaleY)

Let's consider an example to see why this is the case. For this example, let's consider a Sprite that is displaying an animation. For simplicity purposes, we'll assume that each frame in the animation is displaying a 32x32 image. So our code may look something like this:

Sprite sprite = new Sprite();
SpriteManager.AddSprite(sprite);
// This sets the TextureScale to 1, meaning it will have a width matching its animation frames:
sprite.TextureScale = 1;
// Now, let's force the Width to some value (other than what our animation will have)
sprite.Width = 200;

// Now we'll set the animation:
sprite.AnimationChains = SomeAnimationChainList;
// This will change the texture, meaning that it will immediately change the width
// to the width of the frame:
sprite.CurrentChainName = "AnimationName";
// The Sprite's width will now be the width of the frame instead of 200

Introduction

The TextureCoordinate property provides the ability for Sprites to display part of a Texture2D. By default, Sprites display their entire Texture. Sprites in FRB often do not display their entire Texture, instead dispalying a portion of a Texture which contiains multiple individual frames.

Texture Coordinates allow you to display a portion of an image. Texture Coordinates also let you display "more" of a texture. Examples include stretching the edge pixels or wrapping (tiling) the texture.

Example - Setting Texture Coordiantes in the FRB Editor

Texture coordiantes can be manually set on a Sprite in the FRB editor. For example, consider the following image:

This image is an example of a sprite sheet combining multiple graphics into one file. This is often performed to improve loading and runtime efficiency. A single Sprite may display a portion of the image. To display part of an image, a Sprite can specify the four coordinates (left, right, top, and bottom). For example, the coin image has the following values in the image:

• Left = 0

• Right = 16

• Top = 128

• Bottom = 144

These values can be obtained through most image editors. The following image shows how to obtain these values in Paint.NET:

These values can be set in the FRB Editor as shown in the following image:

Keep in mind that the FRB Editor uses pixels as its unit for convenience. When working with Sprites in code, you can use either pixel or UV coordinates (values between 0 to 1).

Understanding TextureCoordinates and Pixels

By default all texture coordinates for a Sprite are either 0 or 1. This might seem a little weird considering Sprites usually do not reference textures of only 1 pixel size. Furthermore, regardless of the size of the referenced texture the texture coordinates will always default to 0 or 1. What does this mean? For a number of reasons, 3D APIs like DirectX and XNA use 0 - 1 for texture coordinates regardless of the width of the texture. The coordinate (0,0) indicates the top-left of the texture while the coordinate (1,1) represents the bottom right of the coordinate. The coordinate (1,0) is the top right. Therefore, if you are used to working with pixels, you need to divide your desired pixel coordinate by the width and height of your texture to get the desired texture coordinate. The following code converts a pixel coordinate to a texture coordinate.

int desiredPixelCoordinateX = 16;
int desiredPixelCoordinateY = 22;

float textureCoordinateX = desiredPixelCoordinateX / (float)someTexture.Width;
float textureCoordinateY = desiredPixelCoordinateY / (float)someTexture.Height;

Texture Coordinates

Sprites support setting texture coordinates on each vertex. This is useful for drawing from a sprite sheet. The vertex at index 0 is the top left. The count increases clockwise as follows:

0----1
|    |
3----2

The default values are:

mVertices[0].TextureCoordinate.X = 0;
mVertices[0].TextureCoordinate.Y = 0;

mVertices[1].TextureCoordinate.X = 1;
mVertices[1].TextureCoordinate.Y = 0;

mVertices[2].TextureCoordinate.X = 1;
mVertices[2].TextureCoordinate.Y = 1;

mVertices[3].TextureCoordinate.X = 0;
mVertices[3].TextureCoordinate.Y = 1;

Or graphically:

(0,0)----------(1, 0)
|                   |
|                   |
|                   |
|                   |
|                   |
(0,1)----------(1, 1)

Values range between 0 and 1 regardless of texture size, so conversions are necessary to work in pixel values. The following code creates three Sprites with modified texture coordinates.

Sprite sprite1 = SpriteManager.AddSprite("redball.bmp");
sprite1.Vertices[0].TextureCoordinate.X = .4f;
sprite1.Vertices[2].TextureCoordinate.Y = .6f;
sprite1.Vertices[3].TextureCoordinate.X = .4f;
sprite1.Vertices[3].TextureCoordinate.Y = .6f;

Sprite sprite2 = SpriteManager.AddSprite("redball.bmp");
sprite2.Vertices[2].TextureCoordinate.Y = .5f;
sprite2.Vertices[3].TextureCoordinate.Y = .5f;
sprite2.X = 3;

// This Sprite's texture coordinates are not axis aligned.
// This can cause graphical artifacts so be careful.
Sprite sprite3 = SpriteManager.AddSprite("redball.bmp");
sprite3.Vertices[0].TextureCoordinate.X = .2f;
sprite3.Vertices[0].TextureCoordinate.Y = .3f;
sprite3.X = 6;

TextureCoordinate Properties

Rather than working directly with the Vertices property, the Sprite exposes four properties to help set texture coordinates. These can be used to set texture coordinates much easier. The following two pieces of code produce identical results:

sprite1.Vertices[0].TextureCoordinate.X = .4f;
sprite1.Vertices[2].TextureCoordinate.Y = .6f;
sprite1.Vertices[3].TextureCoordinate.X = .4f;
sprite1.Vertices[3].TextureCoordinate.Y = .6f;

// AND

sprite1.LeftTextureCoordinate = .4f;
sprite1.BottomTextureCoordinate = .6f;

Tiling Graphics

Using TextureCoordinates outside of the 0-1 range enables you to tile textures. In other words, to tile an object vertically 5 times, you would want to set the right side TextureCoordinate's X's to 5:

mVertices[1].TextureCoordinate.X = 5;
mVertices[2].TextureCoordinate.X = 5;

You must also make sure that you have set the TextureAddressMode to TextureAddressMode.Wrap. See the TextureAddressMode page for more information.

Introduction

The TopTextureCoordinate, BottomTextureCoodinate, LeftTextureCoordinate, and RightTextureCoordinate properties control the coordinates in "uv space" of the top, bottom, left, and right sides of the Sprite. In other words, these values can be used to make a Sprite draw part of a texture instead of the entire thing. These properties are often used when working on games that use sprite sheets. The default values are as follows:

• TopTextureCoordinate = 0

• BottomTextureCoordinate = 1

• LeftTextureCoordinate = 0

• RightTextureCoordinate = 1

What are "texture coordinates" and how do they compare to pixels

Texture coordinates are often used in games (not just FlatRedBall) to measure points on a texture. Texture coordinates are often displayed as two values separated by commas within parenthesis. For example:

(0, 0)

and

(.75, .25)

The texture coordinate is a coordinate which measures location on a texture, but this coordinate does not use pixels. For example, if you're used to using pixels, you may be familiar with (0,0) being the top-left of an image. If your image is 32 pixels tall and 32 pixels wide, then the bottom-right of the image would be (32, 32). In texture coordinates, the top left is (0, 0). The bottom-right is (1, 1). You can think of texture coordinates as representing a percentage. In other words, a value of 0 means 0%. 1 means 100%. A value of 0.5 means 50%. Therefore, a value of (.5, 0) means "50% of the width (starting at the left) and 0% of the height (starting at the top). Therefore, the very center of the image is (.5, .5).

Code example

Texture coordinates can be adjusted to create objects which show only part of a texture, such as health bars. The following code shows how to create a Diablo-like health meter (of course, using a red ball): Files used:

• Media:Fill.png

• Media:Frame.png

Add the following at class scope:

Sprite mFrameSprite;
Sprite mFillSprite;
float mFillRatio = 1;

Add the following to Initialize after initializing FlatRedBall:

SpriteManager.Camera.UsePixelCoordinates(false);

mFillSprite = SpriteManager.AddSprite("content/fill.png");
mFrameSprite = SpriteManager.AddSprite("content/frame.png");

// Let's make them pixel perfect.
// PixelSize is a reactive property, and it reacts
// to texture coordinate changes too.  This means that
// we just have to change the texture coordinates and the
// Sprite will automatically resize itself in our activity logic.
// How handy!
mFillSprite.PixelSize = .5f;
mFrameSprite.PixelSize = .5f;

Add the following to Update:

// .5 means it will fill up .5 of the way (50%) in 1 second
float fillSpeed = .5f;

if (InputManager.Keyboard.KeyDown(Keys.Down))
{
    mFillRatio -= fillSpeed * TimeManager.SecondDifference;
    UpdateFill();
}
else if (InputManager.Keyboard.KeyDown(Keys.Up))
{
    mFillRatio += fillSpeed * TimeManager.SecondDifference;
    UpdateFill();
}

Add UpdateFill at class scope:

 void UpdateFill()
 {
     mFillRatio = Math.Max(0, mFillRatio);
     mFillRatio = Math.Min(1, mFillRatio);
 
     mFillSprite.TopTextureCoordinate = 1 - mFillRatio;

     float bottomOfFrame = mFrameSprite.Y - mFrameSprite.ScaleY;

     mFillSprite.Y =  bottomOfFrame + mFillSprite.ScaleY;
 }

For Glue users

If you are modifying the code above to be used in an Entity, and if the Sprite you are modifying is part of the given Entity, then it is likely that the Sprite is attached to the Entity. Therefore, you will need to replace any code that gets or sets the mFillSprite's Y value with RelativeY. In the code this is done in two parts - in Initialize where mBaseY is set, and the last line in UpdateFill where the Sprite's Y is set.

Additional Information

• Clipping Sprites - A tutorial on how to clip Sprites within a rectangle.

• TextureAddressMode - The visual behavior of Sprites depends on the TextureAddressMode. See this page for information on how to use texture coordinates.

Introduction

The VerticesForDrawing member that is sometimes used internally by FlatRedBall to draw Sprites. This member can be used to perform custom drawing in .

When is the VerticesForDrawing member valid?

The VerticesForDrawing is used to store vertices for one of two reasons:

1. To prevent every-frame calculation of vertices when it is not needed

2. To provide vertex information for custom drawing

If a Sprite is automatically updated and drawn by FlatRedBall (the default behavior), then the engine will not create or maintain this member. This is because the engine assumes that automatically updated, drawn Sprites will not be used for custom drawing. Also, the vertices will be re-calculated every frame so there is no need to store this information.

Creating Sprites for custom rendering

The first step in creating a Sprite for custom rendering is to use the SpriteManager to create a Sprite. This can be done with the AddManagedInvisibleSprite Sprite:

This will instantiate a Sprite and add it to the engine for every-frame updates so that properties like Velocity and Acceleration are applied and so that attachments work properly. However, this Sprite will not be drawn by FlatRedBall. This Sprite can now be used in for custom rendering.

Updating VerticesForDrawing

To update a Sprite's VerticesForDrawing, its ManualUpdate method must be called. In general this should be called inside your Update method:

Assuming the Sprite is not drawn by the engine (it was created with AddManagedInvisibleSprite), then this Sprite's VerticesForDawing will be usable in rendering code.

Rendering with VerticesForDrawing

Code Example

Introduction

The Sprite's Texture property controls which image the Sprite is displaying. This property is of type . When a Sprite is created through the AddSprite method, the Sprite's Texture property gets set inside that method.

Code Example

The following code explains how Textures are assigned. Files used: Add the following at class scope:

Add the following in Initialize after initializing FlatRedBall:

Add the following in update:

Introduction

SetScaleXRatioToY and SetScaleYRatioToX are two methods which can be used to adjust either the ScaleX or ScaleY values on a Sprite such that its aspect ratio (width to height ratio) matches the source Texture's aspect ratio. SetScaleXRatioToY will modify ScaleX and keep ScaleY constant. SetScaleYRatioToX will modify ScaleY and keep ScaleX constant.

Code Example

The following creates a large redball Sprite. The ScaleY is set, then the ScaleY is set through the SetScaleXRatioToY method. Add the following to initialize after initializing FlatRedBall:

Introduction

The TextureCoordinate property provides the ability for Sprites to display part of a Texture2D. By default, Sprites display their entire Texture. This behavior is desirable in many situations, but you may want to display only part of an image if you are using or in certain graphical effects. TextureCoordinates also let you display "more" of a texture. Examples include stretching the edge pixels or wrapping (tiling) the texture.

Understanding TextureCoordinates and Pixels

By default all texture coordinates for a Sprite are either 0 or 1. This might seem a little weird considering Sprites usually do not reference of only 1 pixel size. Furthermore, regardless of the size of the referenced the texture coordinates will always default to 0 or 1. What does this mean? For a number of reasons, 3D APIs like DirectX and XNA use 0 - 1 for texture coordinates regardless of the width of the . The coordinate (0,0) indicates the top-left of the while the coordinate (1,1) represents the bottom right of the coordinate. The coordinate (1,0) is the top right. Therefore, if you are used to working with pixels, you need to divide your desired pixel coordinate by the width and height of your to get the desired texture coordinate. The following code converts a pixel coordinate to a texture coordinate.

Texture Coordinates

Sprites support setting texture coordinates on each vertex. This is useful for drawing from a sprite sheet. The vertex at index 0 is the top left. The count increases clockwise as follows:

The default values are:

Or graphically:

Values range between 0 and 1 regardless of texture size, so conversions are necessary to work in pixel values. The following code creates three Sprites with modified texture coordinates.

TextureCoordinate Properties

Rather than working directly with the Vertices property, the Sprite exposes four properties to help set texture coordinates. These can be used to set texture coordinates much easier. The following two pieces of code produce identical results:

Tiling Graphics

Using TextureCoordinates outside of the 0-1 range enables you to tile textures. In other words, to tile an object vertically 5 times, you would want to set the right side TextureCoordinate's X's to 5:

Related Information

The Visible property controls whether a Sprite is rendered. For more information see the IVisible page.