4
.. py:module:: sfml.system
12
Utility class for manipulating 2-dimensional vectors.
14
:class:`Vector2` is a simple class that defines a mathematical vector with
15
two coordinates (:attr:`x` and :attr:`y`).
17
It can be used to represent anything that has two dimensions: a size, a
18
point, a velocity, etc.
20
:class:`Vector2` supports arithmetic operations (+, -, /, \*), unary
21
operations and comparisons (==, !=).
23
It contains no mathematical function like dot product, cross product,
28
v1 = sf.Vector2(16.5, 24)
38
Note: for 3-dimensional vectors, see :class:`.Vector3`
40
.. method:: Vector2(x=0, y=0)
42
Construct an :class:`sfml.system.Vector2`
46
X coordinate of the vector.
50
Y coordinate of the vector.
57
Utility class for manipulating 3-dimensional vectors.
59
:class:`Vector3` is a simple class that defines a mathematical vector with
60
three coordinates (:attr:`x`, :attr:`y` and :attr:`z`).
62
It can be used to represent anything that has three dimensions: a size, a
63
point, a velocity, etc.
65
:class:`Vector3` supports arithmetic operations (+, -, /, \*), unary
66
operations and comparisons (==, !=).
68
It contains no mathematical function like dot product, cross product,
73
v1 = sf.Vector3(16.5, 24, -8.2)
84
Note: for 2-dimensional vectors, see :class:`.Vector2`
86
.. method:: Vector3(x=0, y=0, z=0)
88
Construct an :class:`sfml.system.Vector3`
92
X coordinate of the vector.
96
Y coordinate of the vector.
100
Z coordinate of the vector.
105
.. py:function:: seconds(amount)
107
Construct a time value from a number of seconds.
109
:param float amount: Number of seconds
110
:return: Time value constructed from the amount of seconds
111
:rtype: :class:`sfml.system.Time`
117
.. py:function:: milliseconds(amount)
119
Construct a time value from a number of milliseconds.
121
:param int amount: Number of milliseconds
122
:return: Time value constructed from the amount of milliseconds
123
:rtype: :class:`sfml.system.Time`
129
.. py:function:: microseconds(amount)
131
Construct a time value from a number of microseconds.
133
:param int amount: Number of microseconds
134
:return: Time value constructed from the amount of microseconds
135
:rtype: :class:`sfml.system.Time`
142
Represents a time value.
144
:class:`Time` encapsulates a time value in a flexible way.
146
It allows to define a time value either as a number of seconds, milliseconds
147
or microseconds. It also works the other way round: you can read a time
148
value as either a number of seconds, milliseconds or microseconds.
150
By using such a flexible interface, the API doesn't impose any fixed type or
151
resolution for time values, and let the user choose its own favorite
154
:class:`Time` values support the usual mathematical operations: you can add
155
or subtract two times, multiply or divide a time by a number, compare two
158
Since they represent a time span and not an absolute time value, times can
164
milli = t1.milliseconds
166
t2 = sf.milliseconds(30)
167
micro = t2.microseconds
169
t3 = sf.microseconds(-800000)
175
position += speed * elapsed.seconds
177
update(sf.milliseconds(100))
179
See also: :class:`.Clock`
183
Construct a :class:`Time` equivalent to :const:`ZERO`
187
Predefined "zero" time value. Copy this value with the **copy** module.
189
.. attribute:: seconds
191
Return the time value as a number of seconds.
193
.. attribute:: milliseconds
195
Return the time value as a number of milliseconds.
197
.. attribute:: microseconds
199
Return the time value as a number of microseconds.
206
Utility class that measures the elapsed time.
208
:class:`Clock` is a lightweight class for measuring time.
210
It provides the most precise time that the underlying OS can achieve
211
(generally microseconds or nanoseconds). It also ensures monotonicity, which
212
means that the returned time can never go backward, even if the system time
219
time1 = clock.elapsed_time
221
time2 = clock.restart()
223
The :class:`Time` value returned by the clock can then be converted to a
224
number of seconds, milliseconds or even microseconds.
226
See also: :class:`.Time`
230
Construct a :class:`Clock`
232
The clock starts automatically after being constructed.
234
.. attribute:: elapsed_time
236
Get the elapsed time.
238
This attribute returns the time elapsed since the last call to
239
:func:`restart()` (or the construction of the instance if
240
:func:`restart()` has not been called).
242
:return: :class:`.Time` elapsed
243
:rtype: :class:`sfml.system.Time`
245
.. method:: restart()
249
This function puts the time counter back to zero. It also returns the
250
time elapsed since the clock was started.
252
:return: :class:`.Time` elapsed
253
:rtype: :class:`sfml.system.Time`
258
.. function:: sleep(duration)
260
Make the current thread sleep for a given duration.
262
:func:`sleep` is the best way to block a program or one of its threads, as
263
it doesn't consume any CPU power.
265
:param sfml.system.Time duration: Time to sleep
272
Utility class to manipulate threads.
274
Threads provide a way to run multiple parts of the code in parallel.
276
When you launch a new thread, the execution is split and both the new thread
277
and the caller run in parallel.
279
To use a :class:`Thread`, you construct it directly with the function to
280
execute as the entry point of the thread.
282
The thread ends when its function is terminated. If the owner sf.Thread
283
instance is destroyed before the thread is finished, the destructor will
284
wait (see :meth:`wait`)
288
def functor(a, b, c):
289
# do something in parallel
291
mythread = sf.Thread(functor, 16.8, 24, -8)
294
.. method:: Thread(functor, *args, **kwargs)
296
Construct the thread from a callable object with optional arguments.
300
This does **not** run the thread, use :meth:`launch`.
306
This function starts the entry point passed to the thread's constructor,
307
and returns immediately. After this function returns, the thread's
308
function is running in parallel to the calling code.
310
.. method:: terminate()
312
Terminate the thread.
314
This function immediately stops the thread, without waiting for its
315
function to finish. Terminating a thread with this function is not safe,
316
and can lead to local variables not being destroyed on some operating
317
systems. You should rather try to make the thread function terminate by
322
Wait until the thread finishes.
324
This function will block the execution until the thread's function ends.
328
If the thread function never ends, the calling thread will block
329
forever. If this function is called from its owner thread, it returns
330
without doing anything.
338
Blocks concurrent access to shared resources from multiple threads.
340
Mutex stands for "MUTual EXclusion".
342
A mutex is a synchronization object, used when multiple threads are involved.
344
When you want to protect a part of the code from being accessed
345
simultaneously by multiple threads, you typically use a mutex. When a thread
346
is locked by a mutex, any other thread trying to lock it will be blocked
347
until the mutex is released by the thread that locked it. This way, you can
348
allow only one thread at a time to access a critical region of your code.
352
database = Database() # this is a critical resoruce that needs some protection
357
mutex.lock() # this call will block the thread if the mutex is already locked by thread2
359
mutex.unlock() # if thread2 was waiting, it will now be unblocked
362
mutex.lock() # this call will block the thread if the mutex is already locked by thread1
364
mutex.unlock() # if thread1 was waiting, it will now be unblocked
366
Be very careful with mutexes. A bad usage can lead to bad problems, like
367
deadlocks (two threads are waiting for each other and the application is
370
To make the usage of mutexes more robust, particularly in environments where
371
exceptions can be thrown, you should use the helper class `class:`Lock` to
374
pySFML mutexes are recursive, which means that you can lock a mutex multiple
375
times in the same thread without creating a deadlock. In this case, the
376
first call to :meth:`lock` behaves as usual, and the following ones have no
377
effect. However, you must call `meth:`unlock` exactly as many times as you
378
called :meth:`lock`. If you don't, the mutex won't be released.
388
If the mutex is already locked in another thread, this call will block
389
the execution until the mutex is released.
402
Automatic wrapper for locking and unlocking mutexes.
404
:class:`Lock` is a RAII wrapper for :class:`Mutex`.
406
By unlocking it in its destructor, it ensures that the mutex will always be
407
released when the current scope (most likely a function) ends. This is even
408
more important when an exception or an early return statement can interrupt
409
the execution flow of the function.
411
For maximum robustness, :class:`Lock` should always be used to lock/unlock a
419
lock = sf.Lock(mutex) # mutex is now locked
421
function_that_may_throw_an_exception() # mutex is unlocked if this function throws
424
return # mutex is unlocked
428
Because the mutex is not explicitely unlocked in the code, it may remain
429
locked longer than needed. If the region of the code that needs to be
430
protected by the mutex is not the entire function, just delete the lock via
436
lock = sf.Lock(mutex)
437
code_that_requires_protection()
439
code_that_doesnt_care_about_the_mutex()
441
Having a mutex locked longer than required is a bad practice which can lead
442
to bad performances. Don't forget that when a mutex is locked, other threads
443
may be waiting doing nothing until it is released.
445
.. method:: Lock(mutex)
447
Construct the lock with a target mutex.
449
The mutex passed to :class:`Lock` is automatically locked.
added
removed
doc/source/api/system.rst
