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.

Source: src/base_rendering/castleglimages_sprite.inc (line 61).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 113).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 127).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 141).

Public destructor Destroy; override;

This item has no description.

Source: src/base_rendering/castleglimages_sprite.inc (line 153).

Public procedure Update(const SecondsPassed: TFloatTime);

Update current frame.

Parameters
SecondsPassed
Time from previous update.

Source: src/base_rendering/castleglimages_sprite.inc (line 157).

Public procedure Play;

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

Source: src/base_rendering/castleglimages_sprite.inc (line 161).

Public procedure Stop;

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

Source: src/base_rendering/castleglimages_sprite.inc (line 166).

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

Source: src/base_rendering/castleglimages_sprite.inc (line 169).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 187).

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

This item has no description.

Source: src/base_rendering/castleglimages_sprite.inc (line 188).

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

This item has no description.

Source: src/base_rendering/castleglimages_sprite.inc (line 189).

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

This item has no description.

Source: src/base_rendering/castleglimages_sprite.inc (line 190).

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

This item has no description.

Source: src/base_rendering/castleglimages_sprite.inc (line 191).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 198).

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

This item has no description.

Source: src/base_rendering/castleglimages_sprite.inc (line 200).

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

Move sprite to position and rotation.

Source: src/base_rendering/castleglimages_sprite.inc (line 205).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 335).

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

This item has no description.

Source: src/base_rendering/castleglimages_sprite.inc (line 336).

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

Warning: this symbol is deprecated: use AddAnimation

This item has no description.

Source: src/base_rendering/castleglimages_sprite.inc (line 337).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 347).

Public function Duration: TFloatTime;

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

Source: src/base_rendering/castleglimages_sprite.inc (line 351).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 151).

Public property X: Single read FX write FX;

This item has no description.

Source: src/base_rendering/castleglimages_sprite.inc (line 207).

Public property Y: Single read FY write FY;

This item has no description.

Source: src/base_rendering/castleglimages_sprite.inc (line 208).

Public property Position: TVector2 read GetPosition write SetPosition;

This item has no description.

Source: src/base_rendering/castleglimages_sprite.inc (line 209).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 213).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 217).

Public property DrawingWidth: Single read FDrawingWidth write FDrawingWidth;

Destination frame width to draw.

Source: src/base_rendering/castleglimages_sprite.inc (line 222).

Public property DrawingHeight: Single read FDrawingHeight write FDrawingHeight;

Destination frame height to draw.

Source: src/base_rendering/castleglimages_sprite.inc (line 225).

Public property DrawRect: TFloatRectangle read GetDrawRect write SetDrawRect;

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

Source: src/base_rendering/castleglimages_sprite.inc (line 229).

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).

Source: src/base_rendering/castleglimages_sprite.inc (line 235).

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

Warning: this symbol is deprecated: use RotationCenter

This item has no description.

Source: src/base_rendering/castleglimages_sprite.inc (line 238).

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

Rotation in degrees.

Source: src/base_rendering/castleglimages_sprite.inc (line 243).

Public property Color: TCastleColor read GetColor write SetColor;

Color multiplier of the sprite, see TDrawableImage.Color

Source: src/base_rendering/castleglimages_sprite.inc (line 246).

Public property Frames: Cardinal read FFrames;

Total number of frames. Readonly. Defined at creation.

Source: src/base_rendering/castleglimages_sprite.inc (line 249).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 255).

Public property Frame: Cardinal read FFrame write SetFrame;

Current frame.

Source: src/base_rendering/castleglimages_sprite.inc (line 260).

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

Does the animation proceeds forward when you call Update method.

Source: src/base_rendering/castleglimages_sprite.inc (line 263).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 267).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 273).

Public property FrameWidth: Cardinal read FFrameWidth write FFrameWidth;

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

Source: src/base_rendering/castleglimages_sprite.inc (line 276).

Public property FrameHeight: Cardinal read FFrameHeight write FFrameHeight;

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

Source: src/base_rendering/castleglimages_sprite.inc (line 279).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 283).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 284).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 288).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 289).

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).

Source: src/base_rendering/castleglimages_sprite.inc (line 295).

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).

Source: src/base_rendering/castleglimages_sprite.inc (line 304).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 309).

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

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

Source: src/base_rendering/castleglimages_sprite.inc (line 314).

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.

Source: src/base_rendering/castleglimages_sprite.inc (line 323).

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

Is sprite horizontal flipped?

Source: src/base_rendering/castleglimages_sprite.inc (line 354).

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

Is sprite vertical flipped?

Source: src/base_rendering/castleglimages_sprite.inc (line 357).

Public property SmoothScaling: boolean read FSmoothScaling write SetSmoothScaling;

Use smooth "bilinear" filtering when this is scaled.

Source: src/base_rendering/castleglimages_sprite.inc (line 360).

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

Source: src/base_rendering/castleglimages_sprite.inc (line 386).

Generated by PasDoc 0.17.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.