API Reference

Class TSprite

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleGLImages

Declaration

type TSprite = class(TObject)

Description

Warning: this symbol is deprecated: load sprite sheets to TCastleScene from .castle-sprite-sheet format

Sprite is an animation composed from frames arranged in rows and columns inside a single image. Frames are read from left to right and from top to bottom.

In the simple case, a sprite represents a single animation, and the frames are just in consecutive order.

With the help of "custom animations" feature, you can define many animations in a sprite. Each custom animation is an array of frames with corresponding frames duration. Frames can be in any order. It is valid to use some particural frame many times with different duration time.

Instead of this, load sprite sheets to TCastleScene from .castle-sprite-sheet format.

Hierarchy

  • TObject
  • TSprite

Overview

Methods

Public constructor Create(const Url: String; const AFrames, AColumns, ARows: Cardinal; const ASmoothScaling: Boolean = True; const ATimeLoop: Boolean = True; const APlay: Boolean = False);
Public constructor CreateFrameSize(const AImage: TDrawableImage; const AFrames, AColumns, AFrameWidth, AFrameHeight: Cardinal; const ATimeLoop: Boolean = True; const APlay: Boolean = False); overload;
Public constructor CreateFrameSize(const Url: String; const AFrames, AColumns, AFrameWidth, AFrameHeight: Cardinal; const ASmoothScaling: Boolean = True; const ATimeLoop: Boolean = True; const APlay: Boolean = False); overload;
Public destructor Destroy; override;
Public procedure Update(const SecondsPassed: TFloatTime);
Public procedure Play;
Public procedure Stop;
Public procedure Pause; deprecated 'use Stop';
Public procedure Draw; overload;
Public procedure Draw(const AX, AY: Single); overload;
Public procedure Draw(const AX, AY, DrawWidth, DrawHeight: Single); overload;
Public procedure Draw(const ScreenRectangle: TRectangle); overload;
Public procedure Draw(const ScreenRectangle: TFloatRectangle); overload;
Public procedure DrawFlipped(const ScreenRect: TRectangle; const FlipHorizontal, FlipVertical: Boolean); overload;
Public procedure DrawFlipped(const ScreenRect: TFloatRectangle; const FlipHorizontal, FlipVertical: Boolean); overload;
Public procedure Move(AX, AY: Single; ARot: Single=0);
Public function AddAnimation(const AAnimation: TSpriteAnimation): Integer; overload;
Public function AddAnimation(const AnimationFrames: array of Cardinal): Integer; overload;
Public function AddSpriteAnimation(const AnimationFrames: array of TSpriteAnimationFrame): Integer; deprecated 'use AddAnimation';
Public function SwitchToAnimation(const AAnimIndex: Integer; const ACustomFrame: Cardinal = 0): Boolean;
Public function Duration: TFloatTime;

Properties

Public property OwnsImage: Boolean read FOwnsImage write FOwnsImage default true;
Public property X: Single read FX write FX;
Public property Y: Single read FY write FY;
Public property Position: TVector2 read GetPosition write SetPosition;
Public property CenterX: Single read GetCenterX write SetCenterX default 0.5; deprecated 'use RotationCenter';
Public property CenterY: Single read GetCenterY write SetCenterY default 0.5; deprecated 'use RotationCenter';
Public property DrawingWidth: Single read FDrawingWidth write FDrawingWidth;
Public property DrawingHeight: Single read FDrawingHeight write FDrawingHeight;
Public property DrawRect: TFloatRectangle read GetDrawRect write SetDrawRect;
Public property RotationCenter: TVector2 read GetRotationCenter write SetRotationCenter;
Public property Center: TVector2 read GetRotationCenter write SetRotationCenter; deprecated 'use RotationCenter';
Public property Rotation: Single read GetRotation write SetRotation default 0;
Public property Color: TCastleColor read GetColor write SetColor;
Public property Frames: Cardinal read FFrames;
Public property FramesPerSecond: Single read FFramesPerSecond write SetFramesPerSecond default DefaultFramesPerSecond;
Public property Frame: Cardinal read FFrame write SetFrame;
Public property Playing: Boolean read FPlaying write FPlaying default False;
Public property TimeLoop: Boolean read FTimeLoop write FTimeLoop;
Public property Time: TFloatTime read FTime write SetTime;
Public property FrameWidth: Cardinal read FFrameWidth write FFrameWidth;
Public property FrameHeight: Cardinal read FFrameHeight write FFrameHeight;
Public property LeftMargin: Cardinal read FLeftMargin write FLeftMargin default 0;
Public property LeftMarginOffset: Cardinal read FLeftMargin write FLeftMargin default 0; deprecated 'use LeftMargin';
Public property TopMargin: Cardinal read FTopMargin write FTopMargin default 0;
Public property TopMarginOffset: Cardinal read FTopMargin write FTopMargin default 0; deprecated 'use TopMargin';
Public property HorizontalSpacing: Cardinal read FHorizontalSpacing write FHorizontalSpacing default 0;
Public property VerticalSpacing: Cardinal read FVerticalSpacing write FVerticalSpacing default 0;
Public property VerticalSpacingBottom: boolean read FVerticalSpacingBottom write FVerticalSpacingBottom default false;
Public property TimeBackwards: Boolean read FTimeBackwards write FTimeBackwards default False;
Public property CurrentAnimation: Integer read FCurrentAnimation default -1;
Public property HorizontalFlip: Boolean read FHorizontalFlip write FHorizontalFlip default False;
Public property VerticalFlip: Boolean read FVerticalFlip write FVerticalFlip default False;
Public property SmoothScaling: boolean read FSmoothScaling write SetSmoothScaling;
Public property SmoothScalingSafeBorder: Boolean read FSmoothScalingSafeBorder write FSmoothScalingSafeBorder default false;

Description

Methods

Public constructor Create(const Url: String; const AFrames, AColumns, ARows: Cardinal; const ASmoothScaling: Boolean = True; const ATimeLoop: Boolean = True; const APlay: Boolean = False);

Constructor.

Parameters
Url
URL of source image.
AFrames
Total numer of animation frames.
AColumns
Mumber of columns.
ARows
Number of rows.
ASmoothscaling
Enables interpolation, see TDrawableImage.SmoothScaling for details, default True.
ATimeLoop
Should animation be repeated?, default True.
APlay
Is animation playing? if not then current frame will be displayed.
Public constructor CreateFrameSize(const AImage: TDrawableImage; const AFrames, AColumns, AFrameWidth, AFrameHeight: Cardinal; const ATimeLoop: Boolean = True; const APlay: Boolean = False); overload;

Constructor that takes explicit frame size, and loaded TDrawableImage instance.

Parameters
AImage
Source image (will be owned by this sprite).
AFrames
Total numer of animation frames.
AColumns
Number of columns.
AFrameWidth
Width of each frame.
AFrameHeight
Height of each frame.
ATimeLoop
Should animation be repeated?, default True.
APlay
Is animation playing? if not then current frame will be displayed.
Public constructor CreateFrameSize(const Url: String; const AFrames, AColumns, AFrameWidth, AFrameHeight: Cardinal; const ASmoothScaling: Boolean = True; const ATimeLoop: Boolean = True; const APlay: Boolean = False); overload;

Constructor that takes explicit frame size.

Parameters
Url
URL of source image.
AFrames
Total numer of animation frames.
AColumns
Number of columns.
AFrameWidth
Width of each frame.
AFrameHeight
Height of each frame.
ASmoothscaling
Enables interpolation, see TDrawableImage.SmoothScaling for details, default True.
ATimeLoop
Should animation be repeated?, default True.
APlay
Is animation playing? if not then current frame will be displayed.
Public destructor Destroy; override;

This item has no description.

Public procedure Update(const SecondsPassed: TFloatTime);

Update current frame.

Parameters
SecondsPassed
Time from previous update.
Public procedure Play;

Play playing animation., When playing, the Time will move forward when you call Update.

Public procedure Stop;

Stop playing animation. When stopped, the Time will not move forward, regardless if you call Update.

Public procedure Pause; deprecated 'use Stop';

Warning: this symbol is deprecated: use Stop

For Delphi, deprecated on method is not allowed if we want to later deprecate a class

Public procedure Draw; overload;

Draw the sprite.

The overloaded version without AX, AY or ScreenRectangle parameters uses the last position set by Move method. This is the position of the bottom-left frame corner on screen.

The overloaded version without DrawWidth, DrawHeight or ScreenRectangle parameters uses the last size set by DrawingWidth, DrawingHeight properties. This is the size of the frame on screen.

All versions use the rotation set by the last Move method. This is the rotation of the frame on screen.

The overloaded versions deliberately look and work similar to TDrawableImage.Draw versions.

Public procedure Draw(const AX, AY: Single); overload;

This item has no description.

Public procedure Draw(const AX, AY, DrawWidth, DrawHeight: Single); overload;

This item has no description.

Public procedure Draw(const ScreenRectangle: TRectangle); overload;

This item has no description.

Public procedure Draw(const ScreenRectangle: TFloatRectangle); overload;

This item has no description.

Public procedure DrawFlipped(const ScreenRect: TRectangle; const FlipHorizontal, FlipVertical: Boolean); overload;

Draw the sprite, optionally flipped horizontally and/or vertically. These methods ignore the HorizontalFlip, VerticalFlip – which axis is flipped (if any) depends only on the parameters to these methods.

Public procedure DrawFlipped(const ScreenRect: TFloatRectangle; const FlipHorizontal, FlipVertical: Boolean); overload;

This item has no description.

Public procedure Move(AX, AY: Single; ARot: Single=0);

Move sprite to position and rotation.

Public function AddAnimation(const AAnimation: TSpriteAnimation): Integer; overload;

Add a custom animation (using an explicit sequence of frames), that can be later used by SwitchToAnimation.

Parameters
AAnimation
The animation information. The animation instance (TSpriteAnimation) becomes owned by this object, so don't free it yourself.
AnimationFrames
The animation information can also be given as a simple list of frame indexes. In this case, all frames are assumed to take the same time: 1 / FramesPerSecond.
Returns

The animation index, that can be used with SwitchToAnimation.

Public function AddAnimation(const AnimationFrames: array of Cardinal): Integer; overload;

This item has no description.

Public function AddSpriteAnimation(const AnimationFrames: array of TSpriteAnimationFrame): Integer; deprecated 'use AddAnimation';

Warning: this symbol is deprecated: use AddAnimation

This item has no description.

Public function SwitchToAnimation(const AAnimIndex: Integer; const ACustomFrame: Cardinal = 0): Boolean;

Switch to the animation with index AAnimIndex. Use animation index obtained from AddAnimation to use a custom animation, or use -1 to use the default animation (spanning all sprite frames).

Returns

True on success, False if AAnimIndex is out of bounds.

Public function Duration: TFloatTime;

Duration, in seconds, of the currently used animation. See CurrentAnimation to know what the current animation is.

Properties

Public property OwnsImage: Boolean read FOwnsImage write FOwnsImage default true;

By default this class "owns" the underlying image, even when passed explicitly to CreateFrameSize as TDrawableImage instance. That is, the underlying TDrawableImage instance will be automatically freed when the sprite will be freed. You turn it off with this property.

Public property X: Single read FX write FX;

This item has no description.

Public property Y: Single read FY write FY;

This item has no description.

Public property Position: TVector2 read GetPosition write SetPosition;

This item has no description.

Public property CenterX: Single read GetCenterX write SetCenterX default 0.5; deprecated 'use RotationCenter';

Warning: this symbol is deprecated: use RotationCenter

Center X of rotation. Values between 0 and 1.

Public property CenterY: Single read GetCenterY write SetCenterY default 0.5; deprecated 'use RotationCenter';

Warning: this symbol is deprecated: use RotationCenter

Center Y of rotation. Values between 0 and 1.

Public property DrawingWidth: Single read FDrawingWidth write FDrawingWidth;

Destination frame width to draw.

Public property DrawingHeight: Single read FDrawingHeight write FDrawingHeight;

Destination frame height to draw.

Public property DrawRect: TFloatRectangle read GetDrawRect write SetDrawRect;

Drawing rectangle. This is just a shortcut to get / set properties X, Y, DrawingWidth, DrawingHeight.

Public property RotationCenter: TVector2 read GetRotationCenter write SetRotationCenter;

Center of rotation. Expressed as a fraction within the drawn ScreenRectangle, (0,0) means bottom-left corner, (1,1) means top-right corner. Default (0.5,0.5).

Public property Center: TVector2 read GetRotationCenter write SetRotationCenter; deprecated 'use RotationCenter';

Warning: this symbol is deprecated: use RotationCenter

This item has no description.

Public property Rotation: Single read GetRotation write SetRotation default 0;

Rotation in degrees.

Public property Color: TCastleColor read GetColor write SetColor;

Color multiplier of the sprite, see TDrawableImage.Color

Public property Frames: Cardinal read FFrames;

Total number of frames. Readonly. Defined at creation.

Public property FramesPerSecond: Single read FFramesPerSecond write SetFramesPerSecond default DefaultFramesPerSecond;

How many frames per second to play. This is used only for the default sprite animation (spanning all frames). For the custom animations (added by AddAnimation), each frame has an explicit (possibly different) duration.

Public property Frame: Cardinal read FFrame write SetFrame;

Current frame.

Public property Playing: Boolean read FPlaying write FPlaying default False;

Does the animation proceeds forward when you call Update method.

Public property TimeLoop: Boolean read FTimeLoop write FTimeLoop;

Does the animation loop, that is display the same animation over and over when time exceeded the animation duration.

Public property Time: TFloatTime read FTime write SetTime;

Current time within the animation, it determines the current frame. Yoy can set this explicity. Alternatively, you can call the Update method continuously while the animation is Playing, and then the time will increase automatically.

Public property FrameWidth: Cardinal read FFrameWidth write FFrameWidth;

Width of a single frame. Initial value is set by the constructor.

Public property FrameHeight: Cardinal read FFrameHeight write FFrameHeight;

Height of a single frame. Initial value is set by the constructor.

Public property LeftMargin: Cardinal read FLeftMargin write FLeftMargin default 0;

X margin for frame position on the underlying image. Useful if the first frame doesn't start at X=0.

Public property LeftMarginOffset: Cardinal read FLeftMargin write FLeftMargin default 0; deprecated 'use LeftMargin';

Warning: this symbol is deprecated: use LeftMargin

This item has no description.

Public property TopMargin: Cardinal read FTopMargin write FTopMargin default 0;

Y margin for frame position on the underlying image. Useful if the first frame doesn't start at Y=0.

Public property TopMarginOffset: Cardinal read FTopMargin write FTopMargin default 0; deprecated 'use TopMargin';

Warning: this symbol is deprecated: use TopMargin

This item has no description.

Public property HorizontalSpacing: Cardinal read FHorizontalSpacing write FHorizontalSpacing default 0;

Horizontal spacing between frames. Use this if you have an empty space at the right of every frame in your spritesheet. This is useful to avoid frames "bleeding" into each other (due to smooth scaling).

Public property VerticalSpacing: Cardinal read FVerticalSpacing write FVerticalSpacing default 0;

Vertical spacing between frames. Use this if you have an empty space at the top (or bottom, if VerticalSpacingBottom) of every frame in your spritesheet. This is useful to avoid frames "bleeding" into each other (due to smooth scaling).

Public property VerticalSpacingBottom: boolean read FVerticalSpacingBottom write FVerticalSpacingBottom default false;

When True, the VerticalSpacing is assumed to be at the bottom of every frame, not top.

Public property TimeBackwards: Boolean read FTimeBackwards write FTimeBackwards default False;

Should we play the animation backwards after playing it forward. See TVideo.TimeBackwards.

Public property CurrentAnimation: Integer read FCurrentAnimation default -1;

Currently used animation. Equal to -1 when we're using the default animation spanning all sprite frames. Otherwise, indicates a custom animation index (added by AddAnimation and used by SwitchToAnimation).

Call SwitchToAnimation to change this.

Public property HorizontalFlip: Boolean read FHorizontalFlip write FHorizontalFlip default False;

Is sprite horizontal flipped?

Public property VerticalFlip: Boolean read FVerticalFlip write FVerticalFlip default False;

Is sprite vertical flipped?

Public property SmoothScaling: boolean read FSmoothScaling write SetSmoothScaling;

Use smooth "bilinear" filtering when this is scaled.

Public property SmoothScalingSafeBorder: Boolean read FSmoothScalingSafeBorder write FSmoothScalingSafeBorder default false;

Prevent the color outside of rendered frame from creeping in, by scaling image a bit to the inside. Because of bilinear filtering (used when SmoothScaling), the colors of neighboring pixels may be visible when you render the sprite frame, and the sprite is significantly scaled. The "neighboring pixels" may mean "pixels from the adjacent sprite frame", or sprite border (in case sprite frame is at the edge of the image), or spacing between sprite frames (if any).

One way to workaround this is to add a 1-pixel or 2-pixel spacing between each sprite frames, and fill this spacing with the same color (including alpha) as the neighbor pixels.

Another workaround is to use this property. This renders a slightly smaller sprite frame, such that bilinear filtering doesn't have a chance to introduce colors from outside of the desired sprite frame. This is done only when SmoothScaling, otherwise this property is ignored.

The downside is that everything is slightly scaled, and doesn't look perfect if you look closely at each pixel. This property is ignored

Generated by PasDoc 0.16.0-snapshot.

Copyright Michalis Kamburelis and Castle Game Engine Contributors.

This webpage is also open-source and we welcome pull requests to improve it.

We use cookies for analytics. See our privacy policy.