# System

## 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))

  See also: `Clock`

  Time()

    Construct a `Time` equivalent to `ZERO`

  ZERO

    Predefined “zero” time value. Copy this value with the copy module.

  seconds

    Return the time value as a number of seconds.

  milliseconds

    Return the time value as a number of milliseconds.

  microseconds

    Return the time value as a number of microseconds.

## 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.

  See also: `Time`

  Clock()

    Construct a `Clock`

    The clock starts automatically after being constructed.

  elapsed_time

    Get the elapsed time.

    This attribute returns the time elapsed since the last call to `restart()` (or the construction of the instance if `restart()` has not been called).

    Returns:

      `Time` elapsed

    Return type:

      `sfml.system.Time`

  restart()

    Restart the clock.

    This function puts the time counter back to zero. It also returns the time elapsed since the clock was started.

    Returns:

      `Time` elapsed

    Return type:

      `sfml.system.Time`

## 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.