System ====== .. contents:: :local: .. py:module:: sfml.system Vector2 ^^^^^^^ .. class:: Vector2 Utility class for manipulating 2-dimensional vectors. :class:`Vector2` is a simple class that defines a mathematical vector with two coordinates (:attr:`x` and :attr:`y`). It can be used to represent anything that has two dimensions: a size, a point, a velocity, etc. :class:`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 :class:`.Vector3` .. method:: Vector2(x=0, y=0) Construct an :class:`sfml.system.Vector2` .. attribute:: x X coordinate of the vector. .. attribute:: y Y coordinate of the vector. Vector3 ^^^^^^^ .. class:: Vector3 Utility class for manipulating 3-dimensional vectors. :class:`Vector3` is a simple class that defines a mathematical vector with three coordinates (:attr:`x`, :attr:`y` and :attr:`z`). It can be used to represent anything that has three dimensions: a size, a point, a velocity, etc. :class:`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 :class:`.Vector2` .. method:: Vector3(x=0, y=0, z=0) Construct an :class:`sfml.system.Vector3` .. attribute:: x X coordinate of the vector. .. attribute:: y Y coordinate of the vector. .. attribute:: z Z coordinate of the vector. seconds ^^^^^^^ .. py:function:: seconds(amount) Construct a time value from a number of seconds. :param float amount: Number of seconds :return: Time value constructed from the amount of seconds :rtype: :class:`sfml.system.Time` milliseconds ^^^^^^^^^^^^ .. py:function:: milliseconds(amount) Construct a time value from a number of milliseconds. :param int amount: Number of milliseconds :return: Time value constructed from the amount of milliseconds :rtype: :class:`sfml.system.Time` microseconds ^^^^^^^^^^^^ .. py:function:: microseconds(amount) Construct a time value from a number of microseconds. :param int amount: Number of microseconds :return: Time value constructed from the amount of microseconds :rtype: :class:`sfml.system.Time` Time ^^^^ .. class:: Time Represents a time value. :class:`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. :class:`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)) See also: :class:`.Clock` .. method:: Time() Construct a :class:`Time` equivalent to :const:`ZERO` .. data:: ZERO Predefined "zero" time value. Copy this value with the **copy** module. .. attribute:: seconds Return the time value as a number of seconds. .. attribute:: milliseconds Return the time value as a number of milliseconds. .. attribute:: microseconds Return the time value as a number of microseconds. Clock ^^^^^ .. class:: Clock Utility class that measures the elapsed time. :class:`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 :class:`Time` value returned by the clock can then be converted to a number of seconds, milliseconds or even microseconds. See also: :class:`.Time` .. method:: Clock() Construct a :class:`Clock` The clock starts automatically after being constructed. .. attribute:: elapsed_time Get the elapsed time. This attribute returns the time elapsed since the last call to :func:`restart()` (or the construction of the instance if :func:`restart()` has not been called). :return: :class:`.Time` elapsed :rtype: :class:`sfml.system.Time` .. method:: restart() Restart the clock. This function puts the time counter back to zero. It also returns the time elapsed since the clock was started. :return: :class:`.Time` elapsed :rtype: :class:`sfml.system.Time` sleep ^^^^^ .. function:: sleep(duration) Make the current thread sleep for a given duration. :func:`sleep` is the best way to block a program or one of its threads, as it doesn't consume any CPU power. :param sfml.system.Time duration: Time to sleep Thread ^^^^^^ .. class:: 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 :class:`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 :meth:`wait`) Usage example:: def functor(a, b, c): # do something in parallel mythread = sf.Thread(functor, 16.8, 24, -8) mythread.launch() .. method:: Thread(functor, *args, **kwargs) Construct the thread from a callable object with optional arguments. .. note:: This does **not** run the thread, use :meth:`launch`. .. method:: 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. .. method:: 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. .. method:: 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:: 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 :meth:`lock` behaves as usual, and the following ones have no effect. However, you must call `meth:`unlock` exactly as many times as you called :meth:`lock`. If you don't, the mutex won't be released. .. method:: Mutex() Construct a mutex. .. method:: lock() Lock the mutex. If the mutex is already locked in another thread, this call will block the execution until the mutex is released. .. method:: unlock() Unlock the mutex. Lock ^^^^ .. class:: Lock Automatic wrapper for locking and unlocking mutexes. :class:`Lock` is a RAII wrapper for :class:`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, :class:`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. .. method:: Lock(mutex) Construct the lock with a target mutex. The mutex passed to :class:`Lock` is automatically locked.