class SF::Transformable
inherits Reference
#
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 < SF::Transformable
include SF::Drawable
def draw(target, states)
states.transform *= self.transform
target.draw(..., states)
end
end
entity = MyEntity.new
entity.position = {10, 20}
entity.rotation = 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
@transform : SF::Transformable
forward_missing_to @transform
end
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
Direct known subclasses
SF::Shape
SF::Sprite
SF::Text
Constructors#
Methods#
#dup : Transformable
#
Returns a shallow copy of this object.
This allocates a new object and copies the contents of
self
into it.
#inverse_transform : Transform
#
get the inverse of the combined transform of the object
Returns: Inverse of the combined transformations applied to the object
See also: transform
#move(offset_x : Number, offset_y : Number)
#
Move the object by a given offset
This function adds to the current position of the object, unlike position= which overwrites it. Thus, it is equivalent to the following code:
pos = object.position
object.set_position(pos.x + offset_x, pos.y + offset_y)
- offset_x - X offset
- offset_y - Y offset
See also: position=
#move(offset : Vector2 | Tuple)
#
Move the object by a given offset
This function adds to the current position of the object, unlike position= which overwrites it. Thus, it is equivalent to the following code:
object.position += offset
- offset - Offset
See also: position=
#origin : Vector2f
#
View source
#origin=(origin : Vector2 | Tuple)
#
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).
- origin - New origin
See also: origin
#position : Vector2f
#
View source
#position=(position : Vector2 | Tuple)
#
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).
- position - New position
#rotate(angle : Number)
#
Rotate the object
This function adds to the current rotation of the object,
unlike rotation=
which overwrites it.
Thus, it is equivalent to the following code:
object.rotation += angle
- angle - Angle of rotation, in degrees
#rotation : Float32
#
get the orientation of the object
The rotation is always in the range 0.0 ... 360.0
Returns: Current rotation, in degrees
See also: rotation=
#rotation=(angle : Number)
#
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.
- angle - New rotation, in degrees
#scale(factor_x : Number, factor_y : Number)
#
Scale the object
This function multiplies the current scale of the object,
unlike scale=
which overwrites it.
Thus, it is equivalent to the following code:
scale = object.scale
object.set_scale(scale.x * factor_x, scale.y * factor_y)
- factor_x - Horizontal scale factor
- factor_y - Vertical scale factor
See also: scale=
#scale(factor : Vector2 | Tuple)
#
Scale the object
This function multiplies the current scale of the object,
unlike scale=
which overwrites it.
Thus, it is equivalent to the following code:
scale = object.scale
object.scale = {scale.x * factor.x, scale.y * factor.y}
- factor - Scale factors
See also: scale=
#scale : Vector2f
#
View source
#scale=(factors : Vector2 | Tuple)
#
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).
- factors - New scale factors
#set_origin(x : Number, y : Number)
#
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).
- x - X coordinate of the new origin
- y - Y coordinate of the new origin
See also: origin
#set_position(x : Number, y : Number)
#
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).
- x - X coordinate of the new position
- y - Y coordinate of the new position
#set_scale(factor_x : Number, factor_y : Number)
#
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).
- factor_x - New horizontal scale factor
- factor_y - New vertical scale factor
#transform : Transform
#
get the combined transform of the object
Returns: Transform combining the position/rotation/scale/origin of the object
See also: inverse_transform