Drawing

Note

Creating your own drawables

A drawable is an object that can be drawn directly to render target, e.g. you can write window.draw(a_drawable).

In the past, creating a drawable involved inheriting the Drawable class and overriding its render() method. With the new graphics API, you only have to define a draw() method that takes two parameters:

def draw(self, target, states):
    target.draw(self.logo)
    target.draw(self.princess)

target and states are RenderTarget and RenderStates objects, respectively. See examples/customdrawable.py for a working example, which also shows how you can use the low-level API.

The Transformable class now contains the operations that can be appied to a drawable. Most drawable (i.e. objects that can be drawn on a target) are transformable as well.

C++ documentation:

class sfml.RenderStates(blend_mode=-1, shader=None, texture=None, transform=None)

The constructor first creates a default RenderStates object, then sets its attributes with respect to the provided arguments. Constructing a default set of render states is equivalent to using RenderStates.DEFAULT. The default set defines

Contains the states used for drawing to a RenderTarget. There are four global states that can be applied to the drawn objects:

  • The blend mode: how pixels of the object are blended with the background.
  • The transform: how the object is positioned/rotated/scaled.
  • The texture: which image is mapped to the object.
  • The shader: which custom effect is applied to the object.

High-level objects such as sprites or text force some of these states when they are drawn. For example, a sprite will set its own texture, so that you don’t have to care about it when drawing the sprite.

The transform is a special case: sprites, texts and shapes (and it’s a good idea to do it with your own drawable classes too) combine their transform with the one that is passed in the RenderStates structure. So that you can use a “global” transform on top of each object’s transform.

Most objects, especially high-level drawables, can be drawn directly without defining render states explicitely — the default set of states is ok in most cases:

window.draw(sprite)

If you just want to specify a shader, you can pass it directly to the RenderTarget.draw() method:

window.draw(sprite, shader)

Note that unlike in C++ SFML, this only works for shaders and not for other render states. This is because adding other possibilities means writing a lot of boilerplate code in the binding, and shader seemed to be most used state when writing this method.

When you’re inside the draw method of a drawable object, you can either pass the render states unmodified, or change some of them. For example, a transformable object will combine the current transform with its own transform. A sprite will set its texture. Etc.

DEFAULT

A RenderStates object with the default values, as a class attribute.

blend_mode

See Blend modes for a list of the valid values.

shader

A Shader object.

texture

A Texture object.

transform

A Transform object.

class sfml.RenderTarget

Base class for RenderWindow and RenderTexture. It is abstract; the constructor will raise NotImplementedError if you call it.

RenderTarget defines the common behaviour of all the 2D render targets. It makes it possible to draw 2D entities like sprites, shapes, text without using any OpenGL command directly.

A RenderTarget is also able to use views (View), which are some kind of 2D cameras. With views you can globally scroll, rotate or zoom everything that is drawn, without having to transform every single entity.

On top of that, render targets are still able to render direct OpenGL stuff. It is even possible to mix together OpenGL calls and regular SFML drawing commands. When doing so, make sure that OpenGL states are not messed up by calling the push_gl_states()/pop_gl_states() methods.

default_view

Read-only. The default view has the initial size of the render target, and never changes after the target has been created.

height

Read-only. The height of the rendering region of the target.

size

Read-only. The size of the rendering region of the target, as a tuple.

view

The view is like a 2D camera, it controls which part of the 2D scene is visible, and how it is viewed in the render-target. The new view will affect everything that is drawn, until another view is set. The render target keeps its own copy of the view object, so it is not necessary to keep the original one alive after calling this function. To restore the original view of the target, you can pass the result of default_view to this function.

width

Read-only. The width of the rendering region of the target.

clear([color])

Clear the entire target with a single color. This function is usually called once every frame, to clear the previous contents of the target. The default is black.

map_coords_to_pixel(int x, int y[, view=None])

Convert a point from view coordinates to target coordinates, as a tuple of ints. This method finds the pixel of the render target that matches the given 2D point. In other words, it goes through the same process as the graphics card, to compute the final position of a rendered point.

Initially, both coordinate systems (world units and target pixels) match perfectly. But if you define a custom view or resize your render-target, this assertion is not true anymore, ie. a point located at (150, 75) in your 2D world may map to the pixel (10, 50) of your render-target – if the view is translated by (140, 25).

When the view argument isn’t provided, the current view of the render target is used.

map_pixel_to_coords(int x, int y[, view=None])

Convert a point from target coordinates to view coordinates, as a tuple of floats. This is typically used when the user clicked on a pixel and you want to know the corresponding world coordinates.

Initially, a unit of the 2D world matches a pixel of the render target. But if you define a custom view, this isn’t true anymore, e.g. a point located at (10, 50) in your render target (for example a window) may map to the point (150, 75) in your 2D world — for example if the view is translated by (140, 25). For render windows, this method is typically used to find which point (or object) is located below the mouse cursor.

When the view argument isn’t provided, the current view of the render target is used.

draw(drawable, ...)

drawable may be:

get_viewport(view)

Return the viewport of a view applied to this render target, as an IntRect. The viewport is defined in the view as a ratio, this method simply applies this ratio to the current dimensions of the render target to calculate the pixels rectangle that the viewport actually covers in the target.

pop_gl_states()

Restore the previously saved OpenGL render states and matrices. See push_gl_states().

push_gl_states()

Save the current OpenGL render states and matrices. This method can be used when you mix SFML drawing and direct OpenGL rendering. Combined with pop_gl_states(), it ensures that:

  • SFML’s internal states are not messed up by your OpenGL code.
  • Your OpenGL states are not modified by a call to a SFML method.

More specifically, it must be used around code that calls draw() methods. Example:

# OpenGL code here...
window.push_gl_states()
window.draw(...)
window.draw(...)
window.pop_gl_states()
# OpenGL code here...

Note that this method is quite expensive: it saves all the possible OpenGL states and matrices, even the ones you don’t care about. Therefore it should be used wisely. It is provided for convenience, but the best results will be achieved if you handle OpenGL states yourself (because you know which states have really changed, and need to be saved and restored). Take a look at the reset_gl_states() method if you do so.

reset_gl_states()

Reset the internal OpenGL states so that the target is ready for drawing. This function can be used when you mix SFML drawing and direct OpenGL rendering, if you choose not to use push_gl_states()/pop_gl_states(). It ensures that all OpenGL states needed by SFML are set, so that subsequent draw() calls will work as expected.

Example:

# OpenGL code here...
glPushAttrib(...)
window.reset_gl_states()
window.draw(...)
window.draw(...)
glPopAttrib(...)
# OpenGL code here...
class sfml.RenderTexture(int width, int height[, bool depth=False])

This class inherits RenderTarget.

Target for off-screen 2D rendering into an texture. RenderTexture is the little brother of RenderWindow.

It implements the same 2D drawing and OpenGL-related functions (see their base class RenderTarget for more details), the difference is that the result is stored in an off-screen texture rather than being show in a window.

Rendering to a texture can be useful in a variety of situations:

  • Precomputing a complex static texture (like a level’s background from multiple tiles).
  • Applying post-effects to the whole scene with shaders.
  • Creating a sprite from a 3D object rendered with OpenGL.
  • Etc.

Usage example:

# Create a new render-window
window = sfml.RenderWindow(sf.VideoMode(800, 600), 'pySFML window')

# Create a new render texture
render_texture = sfml.RenderTexture(500, 500)

# The main loop
while window.open:
   # Event processing
   # ...

   # Clear the whole texture with red color
   render_texture.clear(sfml.Color.RED)

   # Draw stuff to the texture
   render_texture.draw(sprite)  # sprite is a Sprite
   render_texture.draw(shape)   # shape is a Shape
   render_texture.draw(text)    # text is a Text

   # We're done drawing to the texture
   render_texture.display()

   # Now we start rendering to the window, clear it first
   window.clear()

   # Draw the texture
   sprite = sfml.Sprite(render_texture.texture)
   window.draw(sprite);

   # End the current frame and display its contents on screen
   window.display()
active

Write-only. If true, the render texture’s context becomes current for future OpenGL rendering operations (so you shouldn’t care about it if you’re not doing direct OpenGL stuff). Only one context can be current in a thread, so if you want to draw OpenGL geometry to another render target (like a RenderWindow), don’t forget to activate it again.

If an error occurs, PySFMLException is raised.

texture

Read-only.The target texture, as a Texture. After drawing to the render-texture and calling display(), you can retrieve the updated texture using this function, and draw it using a sprite (for example).

Warning

Textures obtained with this property should never be modified. The object itself is a normal Texture object, but the underlying C++ object is specified as const and a C++ compiler wouldn’t let you attempt to modify it.

smooth

Whether the smooth filtering is enabled or not. Default value: False.

display()

Update the contents of the target texture. This method updates the target texture with what has been drawn so far. Like for windows, calling this function is mandatory at the end of rendering. Not calling it may leave the texture in an undefined state.

class sfml.Shader

The constructor will raise NotImplementedError if called. Use class methods like load_from_file() or load_from_memory() instead.

Shaders are programs written using a specific language, executed directly by the graphics card and allowing to apply real-time operations to the rendered entities.

There are two kinds of shaders:

  • Vertex shaders, that process vertices.
  • Fragment (pixel) shaders, that process pixels.

A shader can be composed of either a vertex shader alone, a fragment shader alone, or both combined (see the variants of the load classmethods).

Shaders are written in GLSL, which is a C-like language dedicated to OpenGL shaders. You’ll probably need to learn its basics before writing your own shaders for SFML.

Like any Python program, a shader has its own variables that you can set from your Python. Shader handles four different types of variables:

  • floats
  • vectors (2, 3 or 4 components)
  • textures
  • transforms (matrices)

The value of the variables can be changed at any time with set_parameter():

shader.set_parameter('offset', 2.0)
shader.set_parameter('color', 0.5, 0.8, 0.3)
shader.set_parameter('matrix', transform); # transform is a sfml.Transform
shader.set_parameter('overlay', texture) # texture is a sfml.Texture
shader.set_parameter('texture', sfml.Shader.CURRENT_TEXTURE)

The special Shader.CURRENT_TEXTURE argument maps the given texture variable to the current texture of the object being drawn (which cannot be known in advance).

To apply a shader to a drawable, you must pass it as an additional parameter to RenderTarget.draw():

window.draw(sprite, shader)

Which is in fact just a shortcut for this:

states = sfml.RenderStates()
states.shader = shader
window.draw(sprite, states)

Shaders can be used on any drawable, but some combinations are not interesting. For example, using a vertex shader on a Sprite is limited because there are only 4 vertices, the sprite would have to be subdivided in order to apply wave effects. Another bad example is a fragment shader with Text: the texture of the text is not the actual text that you see on screen, it is a big texture containing all the characters of the font in an arbitrary order; thus, texture lookups on pixels other than the current one may not give you the expected result.

Shaders can also be used to apply global post-effects to the current contents of the target (like the old PostFx class in SFML 1). This can be done in two different ways:

  • Draw everything to a RenderTexture, then draw it to the main target using the shader.
  • Draw everything directly to the main target, then use Texture.update() to copy its contents to a texture and draw it to the main target using the shader.

The first technique is more optimized because it doesn’t involve retrieving the target’s pixels to system memory, but the second one doesn’t impact the rendering process and can be easily inserted anywhere without impacting all the code.

Like Texture that can be used as a raw OpenGL texture, Shader can also be used directly as a raw shader for custom OpenGL geometry:

window.active = True
shader.bind()
# render OpenGL geometry ...
IS_AVAILABLE

True if the system supports shaders. You shoul always test this class attribute before using the shader features. If it is false, then any attempt to use Shader will fail.

CURRENT_TEXTURE

Special type/value that can be passed to set_parameter(), and that represents the texture of the object being drawn.

FRAGMENT

Fragment (pixel) shader type, as an int class attribute.

VERTEX

Vertex shader type, as an int class attribute.

classmethod load_both_types_from_file(str vertex_shader_filename, str fragment_shader_filename)

Load both the vertex and the fragment shaders. If one of them fails to load, the shader is left empty (the valid shader is unloaded). The sources must be text files containing valid shaders in GLSL language. GLSL is a C-like language dedicated to OpenGL shaders; you’ll probably need to read a good documentation for it before writing your own shaders.

PySFMLException is raised if an error occurs.

classmethod load_both_types_from_memory(str vertex_shader, str fragment_shader)

Load both the vertex and the fragment shaders. If one of them fails to load, the shader is left empty (the valid shader is unloaded). The sources must be valid shaders in GLSL language. GLSL is a C-like language dedicated to OpenGL shaders; you’ll probably need to read a good documentation for it before writing your own shaders.

PySFMLException is raised if an error occurs.

classmethod load_both_types_from_stream(InputStream vertex_stream, InputStream fragment_stream)

Load both the vertex and fragment shaders from custom streams. If one of them fails to load, the shader is left empty (the valid shader is unloaded). The source codes must be valid shaders in GLSL language. GLSL is a C-like language dedicated to OpenGL shaders; you’ll probably need to read a good documentation for it before writing your own shaders.

PySFMLException is raised if an error occurs.

classmethod load_from_file(filename, int type)

Load a single shader, either vertex or fragment, identified by the type parameter, which must be Shader.FRAGMENT or Shader.VERTEX. The source must be a text file containing a valid shader in GLSL language. GLSL is a C-like language dedicated to OpenGL shaders; you’ll probably need to read a good documentation for it before writing your own shaders.

PySFMLException is raised if an error occurs.

classmethod load_from_memory(str shader, int type)

Load a single shader, either vertex or fragment, identified by the type argument, which must be Shader.FRAGMENT or Shader.VERTEX. The source code must be a valid shader in GLSL language. GLSL is a C-like language dedicated to OpenGL shaders; you’ll probably need to read a good documentation for it before writing your own shaders.

PySFMLException is raised if an error occurs.

classmethod load_from_stream(InputStream stream, int type)

Load a single shader, either vertex or fragment, identified by the type argument, which must be Shader.FRAGMENT or Shader.VERTEX. GLSL is a C-like language dedicated to OpenGL shaders; you’ll probably need to read a good documentation for it before writing your own shaders.

PySFMLException is raised if an error occurs.

bind()

Bind the shader for rendering (activate it). This method is normally for internal use only, unless you want to use the shader with a custom OpenGL rendering instead of a SFML drawable:

window.active = True
shader.bind()
# ... render OpenGL geometry ...
set_parameter(str name, ...)

Set a shader parameter.

The first parameter, name, is the name of the variable to change in the shader. After name, you can pass an argument or several floats, depending on your need:

  • 1 float,
  • 2 floats,
  • 3 floats,
  • 4 floats,
  • a color,
  • a transform,
  • a texture.

If you want to pass the texture of the object being drawn, which cannot be known in advance, you can pass the special value CURRENT_TEXTURE:

shader.set_parameter('the_texture', sfml.Shader.CURRENT_TEXTURE)
class sfml.Transform([float a00, float a01, float a02, float a10, float a11, float a12, float a20, float a21, float a22])

If called with no arguments, the value is set to the IDENTITY transform.

A Transform is a 3x3 transform matrix that specifies how to translate, rotate, scale, shear, project, etc. In mathematical terms, it defines how to transform a coordinate system into another.

For example, if you apply a rotation transform to a sprite, the result will be a rotated sprite. And anything that is transformed by this rotation transform will be rotated the same way, according to its initial position.

Transforms are typically used for drawing. But they can also be used for any computation that requires to transform points between the local and global coordinate systems of an entity (like collision detection).

Example:

# Define a translation transform
translation = sfml.Transform()
translation.translate(20, 50)

# Define a rotation transform
rotation = sf.Transform()
rotation.rotate(45)

# Combine them
transform = translation * rotation

# Use the result to transform stuff...
point = transform.transform_point(10, 20)
rect = transform.transform_rect(sfml.FloatRect(0, 0, 10, 100))

This class provides the following special methods:

  • * and *= operators.
  • str() returns the content of the matrix in a human-readable format.
IDENTITY

Class attribute containing the identity matrix.

matrix

Read-only. a list of 16 floats containing the transform elements as a 4x4 matrix, which is directly compatible with OpenGL functions.

combine(transform)

Combine the current transform with transform. The result is a transform that is equivalent to applying this followed by transform. Mathematically, it is equivalent to a matrix multiplication.

copy()

Return a new transform object with the same content as self.

get_inverse()

Return the inverse of the transform. If the inverse cannot be computed, an IDENTITY transform is returned.

rotate(float angle[, float center_x, float center_y])

Combine the current transform with a rotation. This method returns self, so calls can be chained:

transform = sfml.Transform()
transform.rotate(90).translate(50, 20)

The center of rotation can be provided with center_x and center_y, so that you can build rotations around arbitrary points more easily (and efficiently) than the usual translate(-center).rotate(angle).translate(center).

scale(float scale_x, float scale_y[, float, center_x, float center_y])

Combine the current transform with a scaling. The center of scaling can be provided with center_x and center_y, so that you can build scaling around arbitrary points more easily (and efficiently) than the usual translate(-center).scale(factors).translate(center).

This method returns self, so calls can be chained:

transform = sfml.Transform()
transform.scale(2, 1, 8, 3).rotate(45)
transform_point(float x, float y)

Transform the point and return it as a tuple.

transform_rect(FloatRect rectangle)

Transform a rectangle and return it as a FloatRect. Since SFML doesn’t provide support for oriented rectangles, the result of this function is always an axis-aligned rectangle. Which means that if the transform contains a rotation, the bounding rectangle of the transformed rectangle is returned.

translate(float x, float y)

Combine the current transform with a translation. This method returns self, so calls can be chained:

transform = sfml.Transform()
transform.translate(100, 200).rotate(45)
class sfml.Transformable

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

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

Transform, as a low-level class, offers a great level of flexibility but it’s not always convenient to manage. 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, 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 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 Transform object), and keeps it up-to-date.

In addition to the position, rotation and scale, 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 positionned/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 positionned/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 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 this kind of thing, use Transform directly.

Transformable can be used as a base class. It is often combined with a draw() method — that’s what SFML’s sprites, texts and shapes do:

// TODO: port to Python
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):

// TODO: port to Python
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;
};
origin

The local origin of the object, as a tuple. When setting the attribute, you can also pass a Vector2f. 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).

position

The position of the object, as a tuple. When setting the attribute, you can also pass a Vector2f. This method completely overwrites the previous position. See move() to apply an offset based on the previous position instead. The default position of a transformable object is (0, 0).

rotation

The orientation of the object, as a float in the range [0, 360]. This method completely overwrites the previous rotation. See rotate() to add an angle based on the previous rotation instead. The default rotation of a transformable object is 0.

scale

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

The object returned by this property will behave like a tuple, but it might be important in some cases to know that its exact type isn’t tuple, although its class does inherit tuple. In practice it should behave just like one, except if you write code that checks for exact type using the type() function. Instead, use isinstance():

if isinstance(some_object, tuple):
    pass # We now know that some_object is a tuple
x

Shortcut for self.position[0].

y

Shortcut for self.position[1].

get_inverse_transform()

Return the inverse of the combined Transform of the object.

get_transform()

Return the combined Transform of the object.

move(float x, float y)

Move the object by a given offset. This method adds to the current position of the object, unlike position() which overwrites it. So it is equivalent to the following code:

object.position = object.position + offset
rotate(float angle)

Rotate the object. This method adds to the current rotation of the object, unlike rotation() which overwrites it. So it is equivalent to the following code:

object.rotation = object.rotation + angle
scale(float x, float y)

Scale the object. This method multiplies the current scale of the object, unlike the scale attribute which overwrites it. So it is equivalent to the following code:

scale = object.scale
object.scale(scale[0] * factor_x, scale[1] * factor_y)
class sfml.Vertex([position[, color[, tex_coords]]])

A vertex is an improved point. It has a position and other extra attributes that will be used for drawing: a color and a pair of texture coordinates.

The vertex is the building block of drawing. Everything which is visible on screen is made of vertices. They are grouped as 2D primitives (triangles, quads, ... see Blend modes), and these primitives are grouped to create even more complex 2D entities such as sprites, texts, etc.

If you use the graphical entities of SFML (Sprite, Text, Shape) you won’t have to deal with vertices directly. But if you want to define your own 2D entities, such as tiled maps or particle systems, using vertices will allow you to get maximum performances.

This class provides the following special methods:

  • repr(vertex) returns a description in format Vertex(position, color, tex_coords.

Example:

# define a 100x100 square, red, with a 10x10 texture mapped on it
vertices = [sfml.Vertex((0, 0), sfml.Color.RED, (0, 0)),
            sfml.Vertex((0, 100), sfml.Color.RED, (0, 10)),
            sfml.Vertex((100, 100), sfml.Color.RED, (10, 10)),
            sfml.Vertex((100, 0), sfml.Color.RED, (10, 0))]

# draw it
window.draw(vertices, sfml.QUADS)

Note: although texture coordinates are supposed to be an integer amount of pixels, their type is float because of some buggy graphics drivers that are not able to process integer coordinates correctly.

color

Color of the vertex.

position

2D position of the vertex. The value is always retrieved as a tuple. It can be set as a tuple or a Vector2f.

tex_coords

Coordinates of the texture’s pixel map to the vertex. The value is always retrieved as a tuple. It can be set as a tuple or a Vector2f.

copy()

Return a new vertex with the same value as self.

Shapes

class sfml.Shape

This abstract class inherits Transformable.

Shape is a drawable class that allows to define and display a custom convex shape on a render target.

Every shape has the following attributes:

  • a texture,
  • a texture rectangle,
  • a fill color,
  • an outline color,
  • an outline thickness.

Each feature is optional, and can be disabled easily:

  • the texture can be None,
  • the fill/outline colors can be Color.TRANSPARENT,
  • the outline thickness can be zero.

You can write your own derived shape class, there are only two methods to override:

A few concrete shapes are provided: RectangleShape, CircleShape and ConvexShape.

fill_color

The fill color of the shape. This color is modulated (multiplied) with the shape’s texture if any. It can be used to colorize the shape, or change its global opacity. You can use Color.TRANSPARENT to make the inside of the shape transparent, and have the outline alone. By default, the shape’s fill color is opaque white.

global_bounds

Read-only. The global bounding rectangle of the entity, as a FloatRect. The returned rectangle is in global coordinates, which means that it takes in account the transformations (translation, rotation, scale, ...) that are applied to the entity. In other words, this function returns the bounds of the sprite in the global 2D world’s coordinate system.

local_bounds

Read-only. The local bounding rectangle of the entity, as a FloatRect. The returned rectangle is in local coordinates, which means that it ignores the transformations (translation, rotation, scale, ...) that are applied to the entity. In other words, this function returns the bounds of the entity in the entity’s coordinate system.

texture

The source texture of the shape. Can be None to disable texturing. Also see set_texture(), which allows you to update texture_rect automatically.

texture_rect

The sub-rectangle of the texture that the shape will display. The texture rect is useful when you only want to display a part of the texture. By default, the texture rect covers the entire texture.

outline_color

The outline color of the shape. You can use Color.TRANSPARENT to disable the outline. By default, the shape’s outline color is opaque white.

outline_thickness

The thickness of the shape’s outline, as a float. This number cannot be negative. Using zero disables the outline. By default, the outline thickness is 0.0.

get_point(int index)

This method should be overriden to return a tuple or a Vector2f containing the coordinates at the position index.

get_point_count()

This method should be overriden to return the number of points, as an integer.

set_texture(texture[, reset_rect=False])

Set the source texture of the shape. texture can be None to disable texturing. If reset_rect is true, the texture_rect property of the shape is automatically adjusted to the size of the new texture. If it is false, the texture rect is left unchanged.

Calling this method does the same thing as modifiying the texture attribute, except when the reset_rect parameter is used.

update()

Recompute the internal geometry of the shape. This method must be called by the derived class everytime the shape’s points change (i.e. the result of either get_point_count() or get_point() is different). This includes when the shape object is created.

If you call this method from a built-in shape, it will raise NotImplementedError.

class sfml.RectangleShape([size])

This class inherits Shape. size can be either a tuple or a Vector2f.

Usage example:

rectangle = sfml.RectangleShape((100, 50))
rectangle.outline_color = sfml.Color.RED
rectangle.outline_thickness = 5
rectangle.position = (10, 20)
# ...
window.draw(rectangle)
size

The size of the rectangle, as a tuple. The value can also be set from a Vector2f.

class sfml.CircleShape([float radius[, int point_count]])

This class inherits Shape.

Usage example:

circle = sfml.CircleShape(150)
circle.outline_color = sfml.Color.Red
circle.outline_thickness = 5
circle.position = (10, 20)
# ...
window.draw(circle)

Since the graphics card can’t draw perfect circles, we have to fake them with multiple triangles connected to each other. The point_count property defines how many of these triangles to use, and therefore defines the quality of the circle.

The number of points can also be used for another purpose; with small numbers you can create any regular polygon shape: equilateral triangle, square, pentagon, hexagon, ...

point_count

The number of points in the circle.

radius

The radius of the circle, as a float.

class sfml.ConvexShape([int point_count])

This class inherits Shape.

Specialized shape representing a convex polygon.

It is important to keep in mind that a convex shape must always be... convex, otherwise it may not be drawn correctly. Moreover, the points must be defined in order; using a random order would result in an incorrect shape.

Usage example:

polygon = sfml.ConvexShape(3)
polygon.set_point(0, (0, 0))
polygon.set_point(1, (0, 10))
polygon.set_point(2, (25, 5))
polygon.outline_color = sfml.Color.RED
polygon.outline_thickness = 5
polygon.position = (10, 20)
# ...
window.draw(polygon)
get_point(int index)

Return the position of a point. The result is undefined if index is out of the valid range.

get_point_count()

Return the number of points of the polygon.

set_point(int index, point)

Set the position of a point. Don’t forget that the polygon must remain convex, and the points need to stay ordered! set_point_count() must be called first in order to set the total number of points. The result is undefined if index is out of the valid range.

point may be either a tuple or a Vector2f.

set_point_count(int count)

Set the number of points of the polygon. count must be greater than 2 to define a valid shape.

Image dislay

class sfml.Image(int width, int height[, color])

Image is an abstraction to manipulate images as bidimensional arrays of pixels. It allows you to load, manipulate and save images.

The constructor create images of the specified size, filled with a color. For loading images, you should use one of the class methods. load_from_file() is the most common one.

Image can handle a unique internal representation of pixels, which is RGBA 32 bits. This means that a pixel must be composed of 8 bits red, green, blue and alpha channels — just like a Color. All the functions that return an array of pixels follow this rule, and all parameters that you pass to Image methods (such as load_from_pixels()) must use this representation as well.

An image can be copied, but you should note that it’s a heavy resource.

Usage example:

# Load an image file from a file
background = sfml.Image.load_from_file('background.jpg')

# Create a 20x20 image filled with black color
image = sfml.Image(20, 20, sfml.Color.BLACK)

# Copy image1 on image2 at position (10, 10)
image.copy(background, 10, 10)

# Make the top-left pixel transparent
color = image[0,0]
color.a = 0
image[0,0] = color

# Save the image to a file
image.save_to_file('result.png')

This class provides the following special methods:

  • image[tuple] returns a pixel from the image, as a Color object. Equivalent to get_pixel(). Example:

    print image[0,0]  # Create tuple implicitly
    print image[(0,0)]  # Create tuple explicitly
    
  • image[tuple] = color sets a pixel of the image to a Color object value. Equivalent to set_pixel(). Example:

    image[0,0] = sfml.Color(10, 20, 30)  # Create tuple implicitly
    image[(0,0)] = sfml.Color(10, 20, 30)  # Create tuple explicitly
    
height

Read-only. The height of the image.

size

Read-only. The size of the image, as a tuple.

width

Read-only. The width of the image.

classmethod load_from_file(filename)

Load the image from filename on disk and return a new Image object. The supported image formats are bmp, png, tga, jpg, gif, psd, hdr and pic. Some format options are not supported, like progressive jpeg.

PySFMLException is raised if an error occurs.

classmethod load_from_memory(bytes mem)

Load the image from a file in memory. The supported image formats are bmp, png, tga, jpg, gif, psd, hdr and pic. Some format options are not supported, like progressive jpeg.

PySFMLException is raised if an error occurs.

classmethod load_from_pixels(int width, int height, bytes pixels)

Return a new image, created from a str/bytes object of pixels. pixels is assumed to contain 32-bits RGBA pixels, and have the given width and height. If not, the behavior is undefined. If pixels is None, an empty image is created.

classmethod load_from_stream(InputStream stream)

Load the image from a custom stream. The supported image formats are bmp, png, tga, jpg, gif, psd, hdr and pic. Some format options are not supported, like progressive jpeg.

PySFMLException is raised if an error occurs.

copy(Image source, int dest_x, int dest_y[, source_rect, apply_alpha])

Copy pixels from another image onto this one. This method does a slow pixel copy and should not be used intensively. It can be used to prepare a complex static image from several others, but if you need this kind of feature in real-time you’d better use RenderTexture.

Without source_rect, the whole image is copied. source_rect can be either an IntRect or a tuple.

If apply_alpha is provided, the transparency of source‘s pixels is applied. If it isn’t, the pixels are copied unchanged with their alpha value.

create_mask_from_color(color, int alpha)

Create a transparency mask from a specified color-key. This method sets the alpha value of every pixel matching the given color to alpha (0 by default), so that they become transparent.

flip_horizontally()

Flip the image horizontally (left <-> right).

flip_vertically()

Flip the image vertically (top <-> bottom).

get_pixel(int x, int y)

Return the color of the pixel at (x, y).

IndexError is raised if the pixel is out of range.

get_pixels()

Return a str (in Python 2) or a bytes (Python 3) object to the pixels. The returned value points to an array of RGBA pixels made of 8 bits integers components. The size of the object is width * height * 4. If the image is empty, None is returned.

save_to_file(filename)

Save the image to a file on disk. The format of the image is automatically deduced from the extension. The supported image formats are bmp, png, tga and jpg. The destination file is overwritten if it already exists. This method fails if the image is empty.

PySFMLException is raised if saving fails.

set_pixel(int x, int y, color)

Set the color of the pixel at (x, y) to color. This method doesn’t check the validity of the pixel coordinates, using out-of-range values will result in an undefined behaviour.

IndexError is raised if the pixel is out of range.

class sfml.Texture([int width[, int height]])

The constructor serves the same purpose as Texture.create() in C++ SFML. It raises PySFMLException if texture creation fails.

Image living on the graphics card that can be used for drawing. A texture lives in the graphics card memory, therefore it is very fast to draw a texture to a render target, or copy a render target to a texture (the graphics card can access both directly).

Being stored in the graphics card memory has some drawbacks. A texture cannot be manipulated as freely as a Image, you need to prepare the pixels first and then upload them to the texture in a single operation (see update()).

Texture makes it easy to convert from/to Image, but keep in mind that these calls require transfers between the graphics card and the central memory, therefore they are slow operations.

A texture can be loaded from an image, but also directly from a file/memory/stream. The necessary shortcuts are defined so that you don’t need an image first for the most common cases. However, if you want to perform some modifications on the pixels before creating the final texture, you can load your file to a Image, do whatever you need with the pixels, and then call load_from_image().

Since they live in the graphics card memory, the pixels of a texture cannot be accessed without a slow copy first. And they cannot be accessed individually. Therefore, if you need to read the texture’s pixels (like for pixel-perfect collisions), it is recommended to store the collision information separately, for example in an array of booleans.

Like Image, Texture can handle a unique internal representation of pixels, which is RGBA 32 bits. This means that a pixel must be composed of 8 bits red, green, blue and alpha channels — just like a Color.

Usage example:

# This example shows the most common use of Texture:
# drawing a sprite

# Load a texture from a file
texture = sfml.load_from_file('texture.png')

# Assign it to a sprite
sprite = sfml.Sprite(texture)

# Draw the textured sprite
window.draw(sprite)
# This example shows another common use of Texture:
# streaming real-time data, like video frames

# Create an empty texture
texture = sfml.Texture(640, 480)

# Create a sprite that will display the texture
sprite = sfml.Sprite(texture)

while True:
    # ...

    # Update the texture
    # Get a fresh chunk of pixels (the next frame of a movie, for example)
    # This should be a string object in Python 2, and a bytes object in Python 3
    pixels = get_pixels()
    texture.update(pixels)

    # draw it
    window.draw(sprite)

    # ...
MAXIMUM_SIZE

Read-only. The maximum texture size allowed, as a class attribute. This maximum size is defined by the graphics driver. You can expect a value of 512 pixels for low-end graphics card, and up to 8192 pixels or more for newer hardware.

NORMALIZED

Constant for the type of texture coordinates where the range is [0 .. 1], as a class attribute.

PIXELS

Constant for the type of texture coordinates where the range is [0 .. size], as a class attribute.

height

Read-only. The height of the texture.

repeated

Whether the texture is repeated or not. Repeating is involved when using texture coordinates outside the texture rectangle [0, 0, width, height]. In this case, if repeat mode is enabled, the whole texture will be repeated as many times as needed to reach the coordinate (for example, if the X texture coordinate is 3 * width, the texture will be repeated 3 times). If repeat mode is disabled, the “extra space” will instead be filled with border pixels. Repeating is disabled by default.

Warning

On very old graphics cards, white pixels may appear when the texture is repeated. With such cards, repeat mode can be used reliably only if the texture has power-of-two dimensions (such as 256x128).

size

Read-only. The size of the texture.

smooth

Whether the smooth filter is enabled or not. When the filter is activated, the texture appears smoother so that pixels are less noticeable. However if you want the texture to look exactly the same as its source file, you should leave it disabled. The smooth filter is disabled by default.

width

Read-only. The width of the texture.

classmethod load_from_file(filename[, area])

Load the texture from a file on disk. This function is a shortcut for the following code:

image = sfml.Image.load_from_file(filename)
sfml.Texture.load_from_image(image, area)

area, if specified, may be either a tuple or an IntRect. Then only a sub-rectangle of the whole image will be loaded. If the area rectangle crosses the bounds of the image, it is adjusted to fit the image size.

The maximum size for a texture depends on the graphics driver and can be retrieved with the getMaximumSize function.

PySFMLException is raised if an error occurs.

classmethod load_from_image(image[, area])

Load the texture from an image.

area, if specified, may be either a tuple or an IntRect. Then only a sub-rectangle of the whole image will be loaded. If the area rectangle crosses the bounds of the image, it is adjusted to fit the image size.

The maximum size for a texture depends on the graphics driver and is accessible with the MAXIMUM_SIZE class attribute.

PySFMLException is raised if an error occurs.

classmethod load_from_memory(bytes data[, area])

Load the texture from a file in memory. This function is a shortcut for the following code:

image = sfml.Image.load_from_memory(data)
texture = sfml.Texture.load_from_image(image, area)

area, if specified, may be either a tuple or an IntRect. Then only a sub-rectangle of the whole image will be loaded. If the area rectangle crosses the bounds of the image, it is adjusted to fit the image size.

The maximum size for a texture depends on the graphics driver and is accessible with the MAXIMUM_SIZE class attribute.

PySFMLException is raised if an error occurs.

classmethod load_from_stream(InputStream stream[, area])

Load the texture from a custom stream. This class method is a shortcut for the following code:

image = sfml.Image.load_from_stream(stream)
texture = sfml.Texture.load_from_image(image, area)

area can a tuple of an IntRect, and is used to load only a sub-rectangle of the whole image. If you want the entire image then leave the default value (which is an empty IntRect). If the area rectangle crosses the bounds of the image, it is adjusted to fit the image size.

The maximum size for a texture depends on the graphics driver and can be retrieved with the MAXIMUM_SIZE class attribute.

PySFMLException is raised if an error occurs.

bind([int coordinate_type])

Activate the texture for rendering. This method is mainly used internally by the SFML rendering system. However it can be useful when using Texture with OpenGL code (this method is equivalent to glBindTexture()).

coordinate_type controls how texture coordinates will be interpreted. If NORMALIZED (the default), they must be in range [0 .. 1], which is the default way of handling texture coordinates with OpenGL. If PIXELS, they must be given in pixels (range [0 .. size]). This mode is used internally by the graphics classes of SFML, it makes the definition of texture coordinates more intuitive for the high-level API, users don’t need to compute normalized values.

copy_to_image()

Copy the texture pixels to an image and return it. This method performs a slow operation that downloads the texture’s pixels from the graphics card and copies them to a new image, potentially applying transformations to pixels if necessary (texture may be padded or flipped).

update(source, ...)

This method can be called in three ways, to be consistent with the C++ method overloading:

update(bytes pixels[, width, height, x, y])

Update a part of the texture from an array of pixels. The size of pixels must match the width and height arguments, and it must contain 32-bits RGBA pixels. No additional check is performed on the size of the pixel array or the bounds of the area to update, passing invalid arguments will lead to an undefined behaviour.

update(image[, x, y])

Update the texture from an image. Although the source image can be smaller than the texture, it’s more convenient to use the x and y parameters for updating a sub-area of the texture.

update(window[, x, y])

Update the texture from the contents of a window. Although the source window can be smaller than the texture, it’s more convenient to use the x and y parameters for updating a sub-area of the texture. No additional check is performed on the size of the window, passing a window bigger than the texture will lead to an undefined behaviour.

class sfml.Sprite([texture])

This class inherits Transformable.

Drawable representation of a texture, with its own transformations, color, etc.

It inherits all the attributes from Transformable: position, rotation, scale, origin. It also adds sprite-specific properties such as the texture to use, the part of it to display, and some convenience functions to change the overall color of the sprite, or to get its bounding rectangle.

Sprite works in combination with the Texture class, which loads and provides the pixel data of a given texture.

The separation of Sprite and Texture allows more flexibility and better performances: indeed a Texture is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, a sf::Sprite is a lightweight object which can use the pixel data of a Texture and draw it with its own transformation/color/blending attributes.

Usage example:

# Load a texture
texture = sfml.Texture.load_from_file('texture.png')

# Create a sprite
sprite = sfml.Sprite(texture)
sprite.texture_rect = sfml.IntRect(10, 10, 50, 30)
sprite.color = sfml.Color(255, 255, 255, 200)
sprite.position = (100, 25)

# Draw it
window.draw(sprite)
color

The global color of the sprite. This color is modulated (multiplied) with the sprite’s texture. It can be used to colorize the sprite, or change its global opacity. By default, the sprite’s color is opaque white.

global_bounds

Read-only. The global bounding rectangle of the entity, as a FloatRect.

The returned rectangle is in global coordinates, which means that it takes into account the transformations (translation, rotation, scale, ...) that are applied to the entity. In other words, this function returns the bounds of the sprite in the global 2D world’s coordinate system.

local_bounds

Read-only. The local bounding rectangle of the entity, as a FloatRect.

The returned rectangle is in local coordinates, which means that it ignores the transformations (translation, rotation, scale, ...) that are applied to the entity. In other words, this function returns the bounds of the entity in the entity’s coordinate system.

texture

The source Texture of the sprite, or None if no texture has been set. Also see set_texture(), which lets you provide another argument.

copy()

Return a new Sprite object with the same value. The new sprite’s texture is the same as the current one (no new texture is created).

get_texture_rect()

Return the sub-rectangle of the texture displayed by the sprite, as an IntRect. The texture rect is useful when you only want to display a part of the texture. By default, the texture rect covers the entire texture.

Warning

This method returns a copy of the rectangle, so code like this won’t work as expected:

sprite.get_texture_rect().top = 10
# Or this:
rect = sprite.get_texture_rect()
rect.top = 10

Instead, you need to call set_texture_rect() with the desired rect:

rect = sprite.get_texture_rect()
rect.top = 10
sprite.set_texture_rect(rect)
set_texture(texture[, reset_rect=False])

Set the source Texture of the sprite. If reset_rect is True, the texture rect of the sprite is automatically adjusted to the size of the new texture. If it is False, the texture rect is left unchanged.

set_texture_rect(rect)

Set the sub-rectangle of the texture displayed by the sprite, as an IntRect. The texture rect is useful when you only want to display a part of the texture. By default, the texture rect covers the entire texture. rect may be an IntRect or a tuple.