Documentation of SFML 2.4.0

Warning: this page refers to an old version of SFML. Click here to switch to the latest version.
sf::Transformable Class Reference

Decomposed transform defined by a position, a rotation and a scale. More...

#include <Transformable.hpp>

Inheritance diagram for sf::Transformable:
sf::Shape sf::Sprite sf::Text sf::CircleShape sf::ConvexShape sf::RectangleShape

Public Member Functions

 Transformable ()
 Default constructor. More...
 
virtual ~Transformable ()
 Virtual destructor. More...
 
void setPosition (float x, float y)
 set the position of the object More...
 
void setPosition (const Vector2f &position)
 set the position of the object More...
 
void setRotation (float angle)
 set the orientation of the object More...
 
void setScale (float factorX, float factorY)
 set the scale factors of the object More...
 
void setScale (const Vector2f &factors)
 set the scale factors of the object More...
 
void setOrigin (float x, float y)
 set the local origin of the object More...
 
void setOrigin (const Vector2f &origin)
 set the local origin of the object More...
 
const Vector2fgetPosition () const
 get the position of the object More...
 
float getRotation () const
 get the orientation of the object More...
 
const Vector2fgetScale () const
 get the current scale of the object More...
 
const Vector2fgetOrigin () const
 get the local origin of the object More...
 
void move (float offsetX, float offsetY)
 Move the object by a given offset. More...
 
void move (const Vector2f &offset)
 Move the object by a given offset. More...
 
void rotate (float angle)
 Rotate the object. More...
 
void scale (float factorX, float factorY)
 Scale the object. More...
 
void scale (const Vector2f &factor)
 Scale the object. More...
 
const TransformgetTransform () const
 get the combined transform of the object More...
 
const TransformgetInverseTransform () const
 get the inverse of the combined transform of the object More...
 

Detailed Description

Decomposed transform defined by a position, a rotation and a scale.

This class is provided for convenience, on top of sf::Transform.

sf::Transform, as a low-level class, offers a great level of flexibility but it is not always convenient to manage. Indeed, one can easily combine any kind of operation, such as a translation followed by a rotation followed by a scaling, but once the result transform is built, there's no way to go backward and, let's say, change only the rotation without modifying the translation and scaling. The entire transform must be recomputed, which means that you need to retrieve the initial translation and scale factors as well, and combine them the same way you did before updating the rotation. This is a tedious operation, and it requires to store all the individual components of the final transform.

That's exactly what sf::Transformable was written for: it hides these variables and the composed transform behind an easy to use interface. You can set or get any of the individual components without worrying about the others. It also provides the composed transform (as a sf::Transform), and keeps it up-to-date.

In addition to the position, rotation and scale, sf::Transformable provides an "origin" component, which represents the local origin of the three other components. Let's take an example with a 10x10 pixels sprite. By default, the sprite is positioned/rotated/scaled relatively to its top-left corner, because it is the local point (0, 0). But if we change the origin to be (5, 5), the sprite will be positioned/rotated/scaled around its center instead. And if we set the origin to (10, 10), it will be transformed around its bottom-right corner.

To keep the sf::Transformable class simple, there's only one origin for all the components. You cannot position the sprite relatively to its top-left corner while rotating it around its center, for example. To do such things, use sf::Transform directly.

sf::Transformable can be used as a base class. It is often combined with sf::Drawable – that's what SFML's sprites, texts and shapes do.

class MyEntity : public sf::Transformable, public sf::Drawable
{
virtual void draw(sf::RenderTarget& target, sf::RenderStates states) const
{
states.transform *= getTransform();
target.draw(..., states);
}
};
MyEntity entity;
entity.setPosition(10, 20);
entity.setRotation(45);
window.draw(entity);

It can also be used as a member, if you don't want to use its API directly (because you don't need all its functions, or you have different naming conventions for example).

class MyEntity
{
public:
void SetPosition(const MyVector& v)
{
myTransform.setPosition(v.x(), v.y());
}
void Draw(sf::RenderTarget& target) const
{
target.draw(..., myTransform.getTransform());
}
private:
sf::Transformable myTransform;
};

A note on coordinates and undistorted rendering:
By default, SFML (or more exactly, OpenGL) may interpolate drawable objects such as sprites or texts when rendering. While this allows transitions like slow movements or rotations to appear smoothly, it can lead to unwanted results in some cases, for example blurred or distorted objects. In order to render a sf::Drawable object pixel-perfectly, make sure the involved coordinates allow a 1:1 mapping of pixels in the window to texels (pixels in the texture). More specifically, this means:

  • The object's position, origin and scale have no fractional part
  • The object's and the view's rotation are a multiple of 90 degrees
  • The view's center and size have no fractional part
See also
sf::Transform

Definition at line 41 of file Transformable.hpp.

Constructor & Destructor Documentation

sf::Transformable::Transformable ( )

Default constructor.

virtual sf::Transformable::~Transformable ( )
virtual

Virtual destructor.

Member Function Documentation

const Transform& sf::Transformable::getInverseTransform ( ) const

get the inverse of the combined transform of the object

Returns
Inverse of the combined transformations applied to the object
See also
getTransform
const Vector2f& sf::Transformable::getOrigin ( ) const

get the local origin of the object

Returns
Current origin
See also
setOrigin
const Vector2f& sf::Transformable::getPosition ( ) const

get the position of the object

Returns
Current position
See also
setPosition
float sf::Transformable::getRotation ( ) const

get the orientation of the object

The rotation is always in the range [0, 360].

Returns
Current rotation, in degrees
See also
setRotation
const Vector2f& sf::Transformable::getScale ( ) const

get the current scale of the object

Returns
Current scale factors
See also
setScale
const Transform& sf::Transformable::getTransform ( ) const

get the combined transform of the object

Returns
Transform combining the position/rotation/scale/origin of the object
See also
getInverseTransform
void sf::Transformable::move ( float  offsetX,
float  offsetY 
)

Move the object by a given offset.

This function adds to the current position of the object, unlike setPosition which overwrites it. Thus, it is equivalent to the following code:

sf::Vector2f pos = object.getPosition();
object.setPosition(pos.x + offsetX, pos.y + offsetY);
Parameters
offsetXX offset
offsetYY offset
See also
setPosition
void sf::Transformable::move ( const Vector2f offset)

Move the object by a given offset.

This function adds to the current position of the object, unlike setPosition which overwrites it. Thus, it is equivalent to the following code:

object.setPosition(object.getPosition() + offset);
Parameters
offsetOffset
See also
setPosition
void sf::Transformable::rotate ( float  angle)

Rotate the object.

This function adds to the current rotation of the object, unlike setRotation which overwrites it. Thus, it is equivalent to the following code:

object.setRotation(object.getRotation() + angle);
Parameters
angleAngle of rotation, in degrees
void sf::Transformable::scale ( float  factorX,
float  factorY 
)

Scale the object.

This function multiplies the current scale of the object, unlike setScale which overwrites it. Thus, it is equivalent to the following code:

sf::Vector2f scale = object.getScale();
object.setScale(scale.x * factorX, scale.y * factorY);
Parameters
factorXHorizontal scale factor
factorYVertical scale factor
See also
setScale
void sf::Transformable::scale ( const Vector2f factor)

Scale the object.

This function multiplies the current scale of the object, unlike setScale which overwrites it. Thus, it is equivalent to the following code:

sf::Vector2f scale = object.getScale();
object.setScale(scale.x * factor.x, scale.y * factor.y);
Parameters
factorScale factors
See also
setScale
void sf::Transformable::setOrigin ( float  x,
float  y 
)

set the local origin of the object

The origin of an object defines the center point for all transformations (position, scale, rotation). The coordinates of this point must be relative to the top-left corner of the object, and ignore all transformations (position, scale, rotation). The default origin of a transformable object is (0, 0).

Parameters
xX coordinate of the new origin
yY coordinate of the new origin
See also
getOrigin
void sf::Transformable::setOrigin ( const Vector2f origin)

set the local origin of the object

The origin of an object defines the center point for all transformations (position, scale, rotation). The coordinates of this point must be relative to the top-left corner of the object, and ignore all transformations (position, scale, rotation). The default origin of a transformable object is (0, 0).

Parameters
originNew origin
See also
getOrigin
void sf::Transformable::setPosition ( float  x,
float  y 
)

set the position of the object

This function completely overwrites the previous position. See the move function to apply an offset based on the previous position instead. The default position of a transformable object is (0, 0).

Parameters
xX coordinate of the new position
yY coordinate of the new position
See also
move, getPosition
void sf::Transformable::setPosition ( const Vector2f position)

set the position of the object

This function completely overwrites the previous position. See the move function to apply an offset based on the previous position instead. The default position of a transformable object is (0, 0).

Parameters
positionNew position
See also
move, getPosition
void sf::Transformable::setRotation ( float  angle)

set the orientation of the object

This function completely overwrites the previous rotation. See the rotate function to add an angle based on the previous rotation instead. The default rotation of a transformable object is 0.

Parameters
angleNew rotation, in degrees
See also
rotate, getRotation
void sf::Transformable::setScale ( float  factorX,
float  factorY 
)

set the scale factors of the object

This function completely overwrites the previous scale. See the scale function to add a factor based on the previous scale instead. The default scale of a transformable object is (1, 1).

Parameters
factorXNew horizontal scale factor
factorYNew vertical scale factor
See also
scale, getScale
void sf::Transformable::setScale ( const Vector2f factors)

set the scale factors of the object

This function completely overwrites the previous scale. See the scale function to add a factor based on the previous scale instead. The default scale of a transformable object is (1, 1).

Parameters
factorsNew scale factors
See also
scale, getScale

The documentation for this class was generated from the following file: