System¶

Vector2
Vector3
seconds
milliseconds
microseconds
Time
Clock
sleep
Thread
Mutex
Lock

Vector2 ¶

class sfml.system.Vector2¶

Utility class for manipulating 2-dimensional vectors.

Vector2 is a simple class that defines a mathematical vector with two coordinates (x and y).

It can be used to represent anything that has two dimensions: a size, a point, a velocity, etc.

Vector2 supports arithmetic operations (+, -, /, *), unary operations and comparisons (==, !=).

It contains no mathematical function like dot product, cross product, length, etc.

Usage example:

v1 = sf.Vector2(16.5, 24)
v1.x = 18.2
y = v1.y

v2 = v1 * 5

v3 = v1 + v2

different = v2 != v3

Note: for 3-dimensional vectors, see Vector3

Vector2(x=0, y=0)¶: Construct an sfml.system.Vector2

x¶: X coordinate of the vector.

y¶: Y coordinate of the vector.

Vector3 ¶

class sfml.system.Vector3¶

Utility class for manipulating 3-dimensional vectors.

Vector3 is a simple class that defines a mathematical vector with three coordinates (x, y and z).

It can be used to represent anything that has three dimensions: a size, a point, a velocity, etc.

Vector3 supports arithmetic operations (+, -, /, *), unary operations and comparisons (==, !=).

It contains no mathematical function like dot product, cross product, length, etc.

Usage example:

v1 = sf.Vector3(16.5, 24, -8.2)
v1.x = 18.2
y = v1.y
z = v1.z

v2 = v1 * 5

v3 = v1 + v2

different = v2 != v3

Note: for 2-dimensional vectors, see Vector2

Vector3(x=0, y=0, z=0)¶: Construct an sfml.system.Vector3

x¶: X coordinate of the vector.

y¶: Y coordinate of the vector.

z¶: Z coordinate of the vector.

seconds ¶

sfml.system.seconds(amount)¶

Construct a time value from a number of seconds.

Parameters:	amount (float) – Number of seconds
Returns:	Time value constructed from the amount of seconds
Return type:	`sfml.system.Time`

milliseconds ¶

sfml.system.milliseconds(amount)¶

Construct a time value from a number of milliseconds.

Parameters:	amount (int) – Number of milliseconds
Returns:	Time value constructed from the amount of milliseconds
Return type:	`sfml.system.Time`

microseconds ¶

sfml.system.microseconds(amount)¶

Construct a time value from a number of microseconds.

Parameters:	amount (int) – Number of microseconds
Returns:	Time value constructed from the amount of microseconds
Return type:	`sfml.system.Time`

Time ¶

class sfml.system.Time¶

Represents a time value.

Time encapsulates a time value in a flexible way.

It allows to define a time value either as a number of seconds, milliseconds or microseconds. It also works the other way round: you can read a time value as either a number of seconds, milliseconds or microseconds.

By using such a flexible interface, the API doesn’t impose any fixed type or resolution for time values, and let the user choose its own favorite representation.

Time values support the usual mathematical operations: you can add or subtract two times, multiply or divide a time by a number, compare two times, etc.

Since they represent a time span and not an absolute time value, times can also be negative.

Usage example:

t1 = sf.seconds(0.1)
milli = t1.milliseconds

t2 = sf.milliseconds(30)
micro = t2.microseconds

t3 = sf.microseconds(-800000)
sec = t3.seconds

def update(elapsed):
   position += speed * elapsed.seconds

update(sf.milliseconds(100))

Clock ¶

class sfml.system.Clock¶

Utility class that measures the elapsed time.

Clock is a lightweight class for measuring time.

It provides the most precise time that the underlying OS can achieve (generally microseconds or nanoseconds). It also ensures monotonicity, which means that the returned time can never go backward, even if the system time is changed.

Usage example:

clock = sf.Clock()
# ...
time1 = clock.elapsed_time
# ...
time2 = clock.restart()

The Time value returned by the clock can then be converted to a number of seconds, milliseconds or even microseconds.

sleep ¶

sfml.system.sleep(duration)¶

Make the current thread sleep for a given duration.

sleep() is the best way to block a program or one of its threads, as it doesn’t consume any CPU power.

Parameters:	duration (sfml.system.Time) – Time to sleep

Thread ¶

class sfml.system.Thread¶

Utility class to manipulate threads.

Threads provide a way to run multiple parts of the code in parallel.

When you launch a new thread, the execution is split and both the new thread and the caller run in parallel.

To use a Thread, you construct it directly with the function to execute as the entry point of the thread.

The thread ends when its function is terminated. If the owner sf.Thread instance is destroyed before the thread is finished, the destructor will wait (see wait())

Usage example:

def functor(a, b, c):
   # do something in parallel

mythread = sf.Thread(functor, 16.8, 24, -8)
mythread.launch()

Thread(functor, *args, **kwargs)¶: Construct the thread from a callable object with optional arguments.

Note

This does not run the thread, use launch().

launch()¶

Run the thread.

This function starts the entry point passed to the thread’s constructor, and returns immediately. After this function returns, the thread’s function is running in parallel to the calling code.

terminate()¶

Terminate the thread.

This function immediately stops the thread, without waiting for its function to finish. Terminating a thread with this function is not safe, and can lead to local variables not being destroyed on some operating systems. You should rather try to make the thread function terminate by itself.

wait()¶

Wait until the thread finishes.

This function will block the execution until the thread’s function ends.

Warning

If the thread function never ends, the calling thread will block forever. If this function is called from its owner thread, it returns without doing anything.

Mutex ¶

class sfml.system.Mutex¶

Blocks concurrent access to shared resources from multiple threads.

Mutex stands for “MUTual EXclusion”.

A mutex is a synchronization object, used when multiple threads are involved.

When you want to protect a part of the code from being accessed simultaneously by multiple threads, you typically use a mutex. When a thread is locked by a mutex, any other thread trying to lock it will be blocked until the mutex is released by the thread that locked it. This way, you can allow only one thread at a time to access a critical region of your code.

Usage example:

database = Database() # this is a critical resource that needs some protection

mutex = sf.Mutex()

def thread1():
   mutex.lock() # this call will block the thread if the mutex is already locked by thread2
   database.write(...)
   mutex.unlock() # if thread2 was waiting, it will now be unblocked

def thread2():
   mutex.lock() # this call will block the thread if the mutex is already locked by thread1
   database.write(...)
   mutex.unlock() # if thread1 was waiting, it will now be unblocked

Be very careful with mutexes. A bad usage can lead to bad problems, like deadlocks (two threads are waiting for each other and the application is globally stuck).

To make the usage of mutexes more robust, particularly in environments where exceptions can be thrown, you should use the helper class class:`Lock to lock/unlock mutexes.

pySFML mutexes are recursive, which means that you can lock a mutex multiple times in the same thread without creating a deadlock. In this case, the first call to lock() behaves as usual, and the following ones have no effect. However, you must call meth:`unlock exactly as many times as you called lock(). If you don’t, the mutex won’t be released.

Mutex()¶: Construct a mutex.

lock()¶

Lock the mutex.

If the mutex is already locked in another thread, this call will block the execution until the mutex is released.

unlock()¶: Unlock the mutex.

Lock ¶

class sfml.system.Lock¶

Automatic wrapper for locking and unlocking mutexes.

Lock is a RAII wrapper for Mutex.

By unlocking it in its destructor, it ensures that the mutex will always be released when the current scope (most likely a function) ends. This is even more important when an exception or an early return statement can interrupt the execution flow of the function.

For maximum robustness, Lock should always be used to lock/unlock a mutex.

Usage example:

mutex = sf.Mutex()

def function():
   lock = sf.Lock(mutex) # mutex is now locked

   function_that_may_throw_an_exception() # mutex is unlocked if this function throws

   if (some_condition):
      return # mutex is unlocked

   # mutex is unlocked

Because the mutex is not explicitly unlocked in the code, it may remain locked longer than needed. If the region of the code that needs to be protected by the mutex is not the entire function, just delete the lock via del.

mutex = sf.Mutex()

def function():
   lock = sf.Lock(mutex)
   code_that_requires_protection()
   del lock
   code_that_doesnt_care_about_the_mutex()

Having a mutex locked longer than required is a bad practice which can lead to bad performances. Don’t forget that when a mutex is locked, other threads may be waiting doing nothing until it is released.

Lock(mutex)¶

Construct the lock with a target mutex.

The mutex passed to Lock is automatically locked.

System¶

Vector2 ¶

Vector3 ¶

seconds ¶

milliseconds ¶

microseconds ¶

Time ¶

Clock ¶

sleep ¶

Thread ¶

Mutex ¶

Lock ¶

Table Of Contents

Previous topic

Next topic

This Page