class EE::Graphics::Sprite¶

Overview¶

A Sprite controller class, can hold and control sprites animations. More…

#include <sprite.hpp>

class Sprite: public EE::Graphics::Drawable {
public:
    // typedefs

    typedef std::function<void(Uint32, Sprite*, void*)> SpriteCallback;

    // enums

    enum SpriteEvents;

    // structs

    struct Frame;
    struct SpriteCbData;

    // construction

    Sprite();
    Sprite(const std::string& name, const std::string& extension = "", TextureAtlas* SearchInTextureAtlas = NULL);
    Sprite(TextureRegion* TextureRegion);
    Sprite(const Uint32& TexId, const Sizef& DestSize = Sizef(0, 0), const Vector2i& offset = Vector2i(0, 0), const Rect& TexSector = Rect(0, 0, 0, 0));
    virtual ~Sprite();

    // methods

    static Sprite* New();
    static Sprite* New(const std::string& name, const std::string& extension = "", TextureAtlas* SearchInTextureAtlas = NULL);
    static Sprite* New(TextureRegion* TextureRegion);
    static Sprite* New(const Uint32& TexId, const Sizef& DestSize = Sizef(0, 0), const Vector2i& offset = Vector2i(0, 0), const Rect& TexSector = Rect(0, 0, 0, 0));
    static Sprite* fromGif(IOStream& gif);
    Sprite& operator=(const Sprite& Other);
    void setRotation(const Float& rotation);
    Float getRotation() const;
    void rotate(const Float& angle);
    void setScale(const Float& scale);
    void setScale(const Vector2f& scale);
    const Vector2f& getScale() const;
    void setOrigin(const OriginPoint& origin);
    const OriginPoint& getOrigin() const;
    void setSize(const Sizef& size, const unsigned int& FrameNum, const unsigned int& SubFrame);
    void setSize(const Sizef& size);
    Sizef setSize(const unsigned int& FrameNum, const unsigned int& SubFrame);
    virtual Sizef getSize();
    virtual Sizef getPixelsSize();
    void setAnimationSpeed(const Float& animSpeed);
    Float getAnimationSpeed() const;
    bool isAnimationPaused() const;
    void setAnimationPaused(const bool& Pause);
    void setCurrentFrame(unsigned int CurFrame);
    const unsigned int& getCurrentFrame() const;
    const Float& getExactCurrentFrame() const;
    void setExactCurrentFrame(const Float& currentFrame);
    void setCurrentSubFrame(const unsigned int& CurSubFrame);
    const unsigned int& getCurrentSubFrame() const;
    void setRenderMode(const RenderMode& Effect);
    const RenderMode& getRenderMode() const;
    void setBlendMode(const BlendMode& Blend);
    const BlendMode& getBlendMode() const;
    void reset();
    Rectf getAABB();
    void updateVertexColors(const Color& Color0, const Color& Color1, const Color& Color2, const Color& Color3);
    void disableVertexColors();
    bool createStatic(TextureRegion* TextureRegion);
    bool createStatic(const Uint32& TexId, const Sizef& DestSize = Sizef(0, 0), const Vector2i& offset = Vector2i(0, 0), const Rect& TexSector = Rect(0, 0, 0, 0));
    bool createStatic(Texture* tex, const Sizef& DestSize = Sizef(0, 0), const Vector2i& offset = Vector2i(0, 0), const Rect& TexSector = Rect(0, 0, 0, 0));
    void createAnimation(const unsigned int& SubFramesNum = 1);
    unsigned int addFrame(const Uint32& TexId, const Sizef& DestSize = Sizef(0, 0), const Vector2i& offset = Vector2i(0, 0), const Rect& TexSector = Rect(0, 0, 0, 0));
    unsigned int addFrame(Texture* tex, const Sizef& DestSize = Sizef(0, 0), const Vector2i& offset = Vector2i(0, 0), const Rect& TexSector = Rect(0, 0, 0, 0));
    unsigned int addFrame(TextureRegion* TextureRegion);
    bool addFrames(const std::vector<TextureRegion*> TextureRegions);
    bool addFramesByPattern(const std::string& name, const std::string& extension = "", TextureAtlas* SearchInTextureAtlas = NULL);
    bool addFramesByPatternId(const Uint32& TextureRegionId, const std::string& extension, TextureAtlas* SearchInTextureAtlas);
    bool addSubFrame(Texture* tex, const unsigned int& NumFrame, const unsigned int& NumSubFrame, const Sizef& DestSize = Sizef(0, 0), const Vector2i& offset = Vector2i(0, 0), const Rect& TexSector = Rect(0, 0, 0, 0));
    bool addSubFrame(const Uint32& TexId, const unsigned int& NumFrame, const unsigned int& NumSubFrame, const Sizef& DestSize = Sizef(0, 0), const Vector2i& offset = Vector2i(0, 0), const Rect& TexSector = Rect(0, 0, 0, 0));
    bool addSubFrame(TextureRegion* TextureRegion, const unsigned int& NumFrame, const unsigned int& NumSubFrame);
    virtual void draw();
    void draw(const BlendMode& Blend, const RenderMode& Effect);
    virtual void draw(const Vector2f& position);
    virtual void draw(const Vector2f& position, const Sizef& size);
    virtual bool isStateful();
    void setRepetitions(const int& Repeations);
    void setAutoAnimate(const bool& Autoanim);
    bool getAutoAnimate() const;
    Quad2f getQuad();
    Vector2i getOffset();
    void setOffset(const Vector2i& offset);
    void setReverseAnimation(const bool& Reverse);
    bool getReverseAnimation() const;
    unsigned int getEndFrame();
    Uint32 getNumFrames();
    void setReverseFromStart();
    TextureRegion* getCurrentTextureRegion();
    TextureRegion* getTextureRegion(const unsigned int& frame);
    TextureRegion* getTextureRegion(const unsigned int& frame, const unsigned int& SubFrame);
    void goToAndPlay(Uint32 GoTo);
    void goToAndStop(Uint32 GoTo);
    void animToFrameAndStop(Uint32 GoTo);
    void setEventsCallback(const SpriteCallback& Cb, void* UserData = nullptr);
    Uint32 pushEventsCallback(const SpriteCallback& cb, void* UserData = nullptr);
    bool popEventsCallback(const Uint32& callbackId);
    Sprite clone();
    void update(const Time& ElapsedTime);
    void update();
    void fireEvent(const Uint32& Event);
    Sprite& setAsTextureRegionOwner(bool set);
    bool isTextureRegionOwner() const;
    Sprite& setAsTextureOwner(bool set);
    bool isTextureOwner() const;
};

Inherited Members¶

public:
    // enums

    enum Type;

    // methods

    virtual Sizef getSize() = 0;
    virtual Sizef getPixelsSize() = 0;
    virtual void draw() = 0;
    virtual void draw(const Vector2f& position) = 0;
    virtual void draw(const Vector2f& position, const Sizef& size) = 0;
    virtual bool isStateful() = 0;
    void setAlpha(Uint8 alpha);
    const Uint8& getAlpha();
    void setColor(const Color& color);
    const Color& getColor() const;
    void setColorFilter(const Color& color);
    RGB getColorFilter();
    void clearColor();
    void clearColorFilter();
    void resetAlpha();
    Type getDrawableType() const;
    const Vector2f& getPosition() const;
    void setPosition(const Vector2f& position);
    virtual bool isDrawableResource() const;

Detailed Documentation¶

A Sprite controller class, can hold and control sprites animations.

Typedefs¶

typedef std::function<void(Uint32, Sprite*, void*)> SpriteCallback

Event ID - Sprite - User Data.

Construction¶

Sprite()

Instanciate an empty sprite

Sprite(const std::string& name, const std::string& extension = "", TextureAtlas* SearchInTextureAtlas = NULL)

Creates an animated Sprite from a animation name. It will search for a pattern name. For example search for name “car” with extensions “png”, i will try to find car00.png car01.png car02.png, and so on, it will continue if find something, otherwise it will stop ( it will always search at least for car00.png and car01.png ).

Note

Texture atlases saves the TextureRegions names without extension by default.

Parameters:

name	First part of the sub texture name
extension	Extension of the sub texture name ( if have one, otherwise is empty )
SearchInTextureAtlas	If you want only to search in a especific atlas ( NULL if you want to search in all atlases )

Methods¶

void setRotation(const Float& rotation)

Set the Angle for the rendered sprite

Float getRotation() const

Returns:

The Angle for the rendered sprite

void rotate(const Float& angle)

Rotates the sprite. Adds the new angle to the current rotation. Same as:

sprite.Angle( sprite.Angle() + angle );

void setScale(const Float& scale)

Set the Scale for the rendered sprite

void setScale(const Vector2f& scale)

Set the Scale for the rendered sprite

const Vector2f& getScale() const

Returns:

The Scale for the rendered sprite

void setOrigin(const OriginPoint& origin)

Set the local origin of the sprite The origin of an object defines the center point for all transformations (scale, rotation). The coordinates of this point must be relative to the top-left corner of the sprite. The default origin point is the center of the sprite.

const OriginPoint& getOrigin() const

Returns:

The local origin of the sprite

void setSize(const Sizef& size, const unsigned int& FrameNum, const unsigned int& SubFrame)

Set the Frame Number Sprite Size

Parameters:

size	The new size
FrameNum	If the Frame Number is 0 it will use the Current Frame Number
SubFrame	If the Sub Frame Number is 0 it will use the Current Sub Frame Number

void setSize(const Sizef& size)

Set the current TextureRegion Size ( destination size )

Sizef setSize(const unsigned int& FrameNum, const unsigned int& SubFrame)

Parameters:

FrameNum	If the Frame Number is 0 it will use the Current Frame Number
SubFrame	If the Sub Frame Number is 0 it will use the Current Sub Frame Number

Returns:

the Frame Number Sprite Size

virtual Sizef getSize()

Returns:

The current Frame Size

void setAnimationSpeed(const Float& animSpeed)

Set the sprite animation speed ( AnimSpeed equals to Animation Frames per Second )

Float getAnimationSpeed() const

Returns:

The sprite animation speed ( AnimSpeed equals to Animation Frames per Second )

bool isAnimationPaused() const

Returns:

If the animation is paused

void setAnimationPaused(const bool& Pause)

Set the animation paused or not

void setCurrentFrame(unsigned int CurFrame)

Set the Current Frame

const unsigned int& getCurrentFrame() const

Returns:

The Current Frame

const Float& getExactCurrentFrame() const

Returns:

The Exact Current FrameData

The Float fpoint of the current frame, the exact position of the interpolation.

void setExactCurrentFrame(const Float& currentFrame)

Set the exact current FrameData

void setCurrentSubFrame(const unsigned int& CurSubFrame)

Set the Current Sub Frame

const unsigned int& getCurrentSubFrame() const

Returns:

The Current Sub Frame

void setRenderMode(const RenderMode& Effect)

Set the Render Type

const RenderMode& getRenderMode() const

Returns:

The Render Type

void setBlendMode(const BlendMode& Blend)

Set the Blend Mode

const BlendMode& getBlendMode() const

Returns:

The Blend Mode

void reset()

Reset the sprite as a new one.

Rectf getAABB()

Returns:

The AABB (axis-aligned bounding box)

void updateVertexColors(const Color& Color0, const Color& Color1, const Color& Color2, const Color& Color3)

Update the colors of every vertex rendered of the sprite ( this will override the default color )

Parameters:

Color0	The Left - Top vertex color
Color1	The Left - Bottom vertex color
Color2	The Right - Bottom vertex color
Color3	The Right - Top vertex color

void disableVertexColors()

This will disable the vertex colors

bool createStatic(TextureRegion* TextureRegion)

Creates an static sprite (no animation)

Parameters:

TextureRegion

The sprite TextureRegion

Returns:

True if success

bool createStatic(const Uint32& TexId, const Sizef& DestSize = Sizef(0, 0), const Vector2i& offset = Vector2i(0, 0), const Rect& TexSector = Rect(0, 0, 0, 0))

Creates an static sprite (no animation). It creates a new TextureRegion.

Parameters:

TexId	The internal Texture Id
DestSize	The destination size of the TextureRegion created
offset	The offset added to the position of the frame ( the TextureRegion)
TexSector	The texture sector to be rendered ( default all the texture )

Returns:

True if success

bool createStatic(Texture* tex, const Sizef& DestSize = Sizef(0, 0), const Vector2i& offset = Vector2i(0, 0), const Rect& TexSector = Rect(0, 0, 0, 0))

Creates an static sprite (no animation). It creates a new TextureRegion.

Parameters:

tex	The texture
DestSize	The destination size of the TextureRegion created
offset	The offset added to the position of the frame ( the TextureRegion)
TexSector	The texture sector to be rendered ( default all the texture )

Returns:

True if success

void createAnimation(const unsigned int& SubFramesNum = 1)

Creates an animated sprite

Parameters:

SubFramesNum

The number of subframes of the sprite

unsigned int addFrame(const Uint32& TexId, const Sizef& DestSize = Sizef(0, 0), const Vector2i& offset = Vector2i(0, 0), const Rect& TexSector = Rect(0, 0, 0, 0))

Add a frame to the sprite (on the current sub frame)

Parameters:

TexId	The internal Texture Id
DestSize	The destination size of the frame
offset	The offset added to the position of the frame
TexSector	The texture sector to be rendered ( default all the texture )

Returns:

The frame position or 0 if fails

unsigned int addFrame(Texture* tex, const Sizef& DestSize = Sizef(0, 0), const Vector2i& offset = Vector2i(0, 0), const Rect& TexSector = Rect(0, 0, 0, 0))

Add a frame to the sprite (on the current sub frame)

Parameters:

tex	The texture
DestSize	The destination size of the frame
offset	The offset added to the position of the frame
TexSector	The texture sector to be rendered ( default all the texture )

Returns:

The frame position or 0 if fails

unsigned int addFrame(TextureRegion* TextureRegion)

Add a frame to the sprite (on the current sub frame)

Parameters:

TextureRegion

The TextureRegion used in the frame

Returns:

The frame position or 0 if fails

bool addFrames(const std::vector<TextureRegion*> TextureRegions)

Add a vector of TextureRegion as an animation.

Parameters:

TextureRegions

The Frames

bool addFramesByPattern(const std::string& name, const std::string& extension = "", TextureAtlas* SearchInTextureAtlas = NULL)

See also:

TextureAtlasManager::GetTextureRegionsByPattern

bool addSubFrame(Texture* tex, const unsigned int& NumFrame, const unsigned int& NumSubFrame, const Sizef& DestSize = Sizef(0, 0), const Vector2i& offset = Vector2i(0, 0), const Rect& TexSector = Rect(0, 0, 0, 0))

Add a frame on an specific subframe to the sprite

Parameters:

tex	The texture
NumFrame	The Frame Number
NumSubFrame	The Sub Frame Number
DestSize	The destination size of the frame
offset	The offset added to the x position of the frame
TexSector	The texture sector to be rendered ( default all the texture )

Returns:

True if success

bool addSubFrame(const Uint32& TexId, const unsigned int& NumFrame, const unsigned int& NumSubFrame, const Sizef& DestSize = Sizef(0, 0), const Vector2i& offset = Vector2i(0, 0), const Rect& TexSector = Rect(0, 0, 0, 0))

Add a frame on an specific subframe to the sprite

Parameters:

TexId	The internal Texture Id
NumFrame	The Frame Number
NumSubFrame	The Sub Frame Number
DestSize	The destination size of the frame
offset	The offset added to the x position of the frame
TexSector	The texture sector to be rendered ( default all the texture )

Returns:

True if success

bool addSubFrame(TextureRegion* TextureRegion, const unsigned int& NumFrame, const unsigned int& NumSubFrame)

Add a frame on an specific subframe to the sprite

Parameters:

TextureRegion	The TextureRegion used in the frame
NumFrame	The Frame Number
NumSubFrame	The Sub Frame Number

Returns:

True if success

virtual void draw()

Draw the sprite to the screen

void draw(const BlendMode& Blend, const RenderMode& Effect)

Draw the sprite to the screen forcing the Blend Mode and the Render Type

Parameters:

Blend	The Blend Mode
Effect	The Render Type

void setRepetitions(const int& Repeations)

Set the number of repetitions of the animation. Any number below 0 the animation will loop.

void setAutoAnimate(const bool& Autoanim)

Set if the class auto-animate the sprite ( default it’s active )

bool getAutoAnimate() const

Returns:

If the class is auto-animated

Quad2f getQuad()

Returns:

The four vertex position of the Sprite

Vector2i getOffset()

Returns:

The Offset of the current frame

void setOffset(const Vector2i& offset)

Set the Offset of the current frame

void setReverseAnimation(const bool& Reverse)

Reverse the animation from last frame to first frame.

bool getReverseAnimation() const

Returns:

If the animation is reversed

unsigned int getEndFrame()

Returns:

The current last frame

Uint32 getNumFrames()

Returns:

The number of frames

void setReverseFromStart()

Will set Reverse active and set the first frame as the last frame

TextureRegion* getCurrentTextureRegion()

Returns:

The Current TextureRegion

TextureRegion* getTextureRegion(const unsigned int& frame)

Returns:

The TextureRegion Frame from the current sub frame

TextureRegion* getTextureRegion(const unsigned int& frame, const unsigned int& SubFrame)

Returns:

The TextureRegion Frame from the SubFrame

void goToAndPlay(Uint32 GoTo)

Start playing from

Parameters:

GoTo	Frame that goes from 1 to Number of Frames

void goToAndStop(Uint32 GoTo)

Go to a frame and stop

Parameters:

GoTo	Frame that goes from 1 to Number of Frames

void animToFrameAndStop(Uint32 GoTo)

Animate to frame and when reach the frame stops

void setEventsCallback(const SpriteCallback& Cb, void* UserData = nullptr)

Set the sprite events callback

Uint32 pushEventsCallback(const SpriteCallback& cb, void* UserData = nullptr)

Push a new event callback.

Returns:

The Callback Id

bool popEventsCallback(const Uint32& callbackId)

Pop the event callback id indicated.

Sprite clone()

Creates a copy of the current sprite and returns it

void update(const Time& ElapsedTime)

Update the sprite animation

void update()

Update the sprite animation using the current elapsed time provided by Engine

void fireEvent(const Uint32& Event)

Fire a User Event in the sprite