class SF::Transformable

• SF::Transformable
• Reference
• Object

Overview

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

Defined in:

Constructors

• .new

  Default constructor

Instance Method Summary

• #dup : Transformable

  Returns a shallow copy of this object.

• #finalize

  Virtual destructor

• #inverse_transform : Transform

  get the inverse of the combined transform of the object

• #move(offset_x : Number, offset_y : Number)

  Move the object by a given offset

• #move(offset : Vector2 | Tuple)

  Move the object by a given offset

• #origin : Vector2f

  get the local origin of the object

• #origin=(origin : Vector2 | Tuple)

  set the local origin of the object

• #position : Vector2f

  get the position of the object

• #position=(position : Vector2 | Tuple)

  set the position of the object

• #rotate(angle : Number)

  Rotate the object

• #rotation : Float32

  get the orientation of the object

• #rotation=(angle : Number)

  set the orientation of the object

• #scale(factor_x : Number, factor_y : Number)

  Scale the object

• #scale(factor : Vector2 | Tuple)

  Scale the object

• #scale : Vector2f

  get the current scale of the object

• #scale=(factors : Vector2 | Tuple)

  set the scale factors of the object

• #set_origin(x : Number, y : Number)

  set the local origin of the object

• #set_position(x : Number, y : Number)

  set the position of the object

• #set_scale(factor_x : Number, factor_y : Number)

  set the scale factors of the object

• #transform : Transform

  get the combined transform of the object

Constructor Detail

Instance Method Detail

pos = object.position
object.set_position(pos.x + offset_x, pos.y + offset_y)

object.position += offset

object.rotation += angle

scale = object.scale
object.set_scale(scale.x * factor_x, scale.y * factor_y)

scale = object.scale
object.scale = {scale.x * factor.x, scale.y * factor.y}