Tutorials¶

Some knowledge is required to help understand the binding from an SFML background. After reading this tutorial you should be able to start coding serious projects.

Note

I started to translate the official tutorials and while there are only a few available, they will soon be finished. This page should be replaced with this future page.

System
Window
Graphics
Audio
Socket
Miscellaneous & Tricks

System ¶

Vectors¶

To manipulate vectors you use sfml.system.Vector2 or sfml.system.Vector3 and unlike in C++ they have no specific type. It means you can set a float, an integer or whatever inside.

vector = sfml.system.Vector3()
vector.x = 5.56 # set a float
vector.y = -4 # set an integer
vector.z = Decimal(0.333333333)
x, y, z = vector # you can unpack the vector

To manipulate time there’s no major difference. Instead of getting the seconds, milliseconds or microseconds via a method named asSomething you do it via a property

t1 = sfml.milliseconds(500)
print(t1.seconds)
print(t1.microseconds)

clock = sfml.system.Clock()
print(clock.elapsed_time)
t2 = clock.restart()

time = t1 + t2
time *= t2
time -= t1

sfml.sleep(time)

Exception¶

Warning

sf.SFMLException has been removed and was replaced with standard exceptions.

SFML functions that may fail raise exception. If you use one of them and want to give a specific task in case of failure, you can handle them with a try... except statement.

try:
    # huge texture, will fail for sure
    # (except maybe if you read that in 2075 and if your processor works with light speed)
    texture = sf.Texture.create(987654321, 987654321)
except ValueError as error:
    print(error) # print the error
    exit(1)      # maybe quit ?

Note that load/open methods raise a traditional IOError:

try:
   music = sf.Music.from_file("song.ogg")

except IOError:
   exit(1)

Window ¶

Event¶

The way you handle events in pySFML2 is slightly different from how you do it in SFML2.

Here, rather than checking that the type property matches an event type, you check that event is an instance of a particular event class. While you could do this using python’s builtin type or isinstance functions, The Event class implements rich comparison operators to make things simpler:

for event in window.events:
   if event == ...: # provide an event class name

Available event classes and their SFML2 equivalents are shown below:

pySFML	SFML (C++)
`CloseEvent`	sf::Event::Closed
`sfml.window.ResizeEvent`	sf::Event::Resized
`sfml.window.FocusEvent`	sf::Event::LostFocus sf::Event::GainedFocus
`sfml.window.TextEvent` `sfml.window.KeyEvent`	sf::Event::TextEntered sf::Event::KeyPressed sf::Event::KeyReleased
`sfml.window.MouseWheelEvent` `sfml.window.MouseButtonEvent`	sf::Event::MouseWheelMoved sf::Event::MouseButtonPressed sf::Event::MouseButtonReleased
`sfml.window.MouseMoveEvent` `sfml.window.MouseEvent`	sf::Event::MouseMoved sf::Event::MouseEntered sf::Event::MouseLeft
`sfml.window.JoystickButtonEvent`	sf::Event::JoystickButtonPressed sf::Event::JoystickButtonReleased
`sfml.window.JoystickMoveEvent` `sfml.window.JoystickConnectEvent`	sf::Event::JoystickMoved sf::Event::JoystickConnected sf::Event::JoystickDisconnected

Once you know the type of the event you can get the data inside.:

if event == sf.MouseMoveEvent:
    x, y = event.position

For events like KeyEvent, MouseButtonEvent, etc. which can have two “states”, you’ll have to check it via their properties.:

if event == sf.KeyEvent:
    if event.pressed:
        ...
    elif event.released:
        ...

if event == sf.KeyEvent and event.pressed:
    ...

if event == sf.FocusEvent:
    if event.gained:
        ...
    if event.lost:
        ...

Read the Window class description for information about events.

Graphics ¶

Rectangle¶

Although unpacking a rectangle will give you four integers/floats (respectively its left, its top, its width and its height) its constructor takes two Vector2 or tuple; its position and its size.

rectangle = mytext.local_bounds
left, top, width, height = rectangle

position, size = sf.Vector2(5, 10), sf.Vector2(150, 160)
rectangle = sf.Rectangle(position, size)

This has been implemented as such because you may want to create a rectangle at any time and the variable you have in hand can either be four variables representing the top, the left, the width or two variables representing the position and the size. In both cases you can create a rectangle in one line!

left, top, width, height = 5, 10, 150, 160
rectangle = sf.Rectangle((left, top), (width, height))
# or the ugly and verbose alternative
rectangle = sf.Rectangle(sf.Vector2(left, top), sf.Vector2(width, height))

position, size = (5, 10), (150, 160)
rectangle = sf.Rectangle(position, size)

Making the rectangle require four numeric values in its constructor would have involved writing more lines if you had only a position and a size in hand

x, y = position
w, h = size
rectangle = sf.Rectangle(x, y, w, h)

Drawable¶

To create your own drawable just inherit your class from Drawable.

class MyDrawable(sf.Drawable):
    def __init__(self):
        sf.Drawable.__init__(self)

    def draw(self, target, states):
        target.draw(body)
        target.draw(clothes)

To have a transformable drawable you have two implementation choices. As Like SFML in C++, you can either use a transformable internally and combine your transformable at drawing time or inherit your drawable from both Drawable and Transformable.

sf.Transformable in an internal attribute

This consist of having a transformable in an attribute and combine with the states at drawing time.

class MyDrawable(sf.Drawable):
    def __init__(self):
        sf.Drawable.__init__(self)
        self._transformable = sf.Transformable()

    def draw(self, target, states):
        states.transform.combine(self._transformable.transform)

        target.draw(body)
        target.draw(clothes)

    def _get_position(self):
        return self._transfomable.position

    def _set_position(self, position):
        self._transformable.position = position

    position = property(_get_position, _set_position)

Only the position property has been implemented in this example but you can also implement rotation, scale, origin.

Inheriting from sf.Drawable and sf.Transformable

There’s a current issue concerning this way to do. As Python doesn’t allow you to subclass from two built-in types at the same time, you can’t technically do it. That’s why pySFML2 provides TransformableDrawable which is both an Drawable and Transformable. That way your class inherits from properties such position, rotation etc and their methods move(), rotate() etc.

class MyDrawable(sf.TransformableDrawable):
    def __init__(self):
        sf.Drawable.__init__(self)

    def draw(self, target, states):
        states.transform.combine(self.transformable.transform)
        target.draw(body)
        target.draw(clothes)

mydrawable = MyDrawable()
mydrawable.position = (20, 30) # we have properties \o/

HandledWindow¶

This extra class allows you to have a window handled by an external API such as PyQt4. This class is pretty straight forward and you should just follow the cookbook for integrating.

Warning

This class exists because of an issue with constructors. I still need to justify it or figure out how I can replace it.

Audio ¶

Using the audio module should be very simple since there’s no differences with the original API. Just note that the class Chunk allows you to manipulate an array of sf::Int16 which represents the audio samples. So far this class is pretty basic and offers access to each sample via the operator [] and you can get the data in a string for Python 2 or in bytes for Python 3 via Chunk.data.

Socket ¶

There’s no systematic STATUS to check. When something goes wrong an error is raised and you just have to handle it.

try:
    socket.send(b'hello world')

except sf.SocketError:
    socket.close()
    exit(1)

Miscellaneous & Tricks ¶

Once you know pySFML well you may be interested in knowing some tricks.

Unpacking¶

Many classes are unpackable

     x, y = sf.Vector2(5, 10)
     x, y, z = sf.Vector3(5, 10, 15)

     size, bpp = sf.VideoMode(640, 480, 32)
     depth_bits, stencil_bits, antialiasing, minor_version, major_version = sf.ContextSettings()

     r, g, b, a = sf.Color.CYAN
     left, top, width, height = sf.Rectangle((5, 10), (15, 20))

If you need to discard a value, use _

# I'm not interested in the alpha value
r, g, b, _ = get_color()

sfml.Image.show()¶

For debugging purpose pySFML provides a show() function. This allows you to see how an image will look after modification. This is to be sure all operations made on the picture were effective.

image = sf.Image.from_image("image.png")
image.create_mask_from_color(sf.Color.BLUE)
image.show()

texture = sf.Texture.from_image(image)
texture.update(window, (50, 60))
texture.to_image().show()

Attach an icon to a Window¶

Easily attach an icon to your window

icon = sf.Image.from_file("data/icon.bmp")
window.icon = icon.pixels

Tutorials¶

System ¶

Vectors¶

Exception¶

Window ¶

Event¶

Graphics ¶

Rectangle¶

Drawable¶

HandledWindow¶

Audio ¶

Socket ¶

Miscellaneous & Tricks ¶

Unpacking¶

sfml.Image.show()¶

Attach an icon to a Window¶

Table Of Contents

Previous topic

Next topic

This Page

Tutorials¶

System¶

Vectors¶

Exception¶

Window¶

Event¶

Graphics¶

Rectangle¶

Drawable¶

HandledWindow¶

Audio¶

Socket¶

Miscellaneous & Tricks¶

Unpacking¶

sfml.Image.show()¶

Attach an icon to a Window¶

System ¶

Window ¶

Graphics ¶

Audio ¶

Socket ¶

Miscellaneous & Tricks ¶