|
| 1 | +"""Pygame module for monitoring time. |
| 2 | +
|
| 3 | +Times in pygame are represented in milliseconds (1/1000 seconds). Most |
| 4 | +platforms have a limited time resolution of around 10 milliseconds. This |
| 5 | +resolution, in milliseconds, is given in the ``TIMER_RESOLUTION`` constant. |
| 6 | +""" |
| 7 | + |
1 | 8 | from typing import Union, final |
2 | 9 |
|
3 | 10 | from pygame.event import Event |
4 | 11 |
|
5 | | -def get_ticks() -> int: ... |
6 | | -def wait(milliseconds: int, /) -> int: ... |
7 | | -def delay(milliseconds: int, /) -> int: ... |
8 | | -def set_timer(event: Union[int, Event], millis: int, loops: int = 0) -> None: ... |
| 12 | +def get_ticks() -> int: |
| 13 | + """Get the time in milliseconds. |
| 14 | +
|
| 15 | + Return the number of milliseconds since ``pygame.init()`` was called. Before |
| 16 | + pygame is initialized this will always be 0. |
| 17 | + """ |
| 18 | + |
| 19 | +def wait(milliseconds: int, /) -> int: |
| 20 | + """Pause the program for an amount of time. |
| 21 | +
|
| 22 | + Will pause for a given number of milliseconds. This function sleeps the |
| 23 | + process to share the processor with other programs. A program that waits for |
| 24 | + even a few milliseconds will consume very little processor time. It is |
| 25 | + slightly less accurate than the ``pygame.time.delay()`` function. |
| 26 | +
|
| 27 | + This returns the actual number of milliseconds used. |
| 28 | + """ |
| 29 | + |
| 30 | +def delay(milliseconds: int, /) -> int: |
| 31 | + """Pause the program for an amount of time. |
| 32 | +
|
| 33 | + Will pause for a given number of milliseconds. This function will use the |
| 34 | + processor (rather than sleeping) in order to make the delay more accurate |
| 35 | + than ``pygame.time.wait()``. |
| 36 | +
|
| 37 | + This returns the actual number of milliseconds used. |
| 38 | + """ |
| 39 | + |
| 40 | +def set_timer(event: Union[int, Event], millis: int, loops: int = 0) -> None: |
| 41 | + """Repeatedly create an event on the event queue. |
| 42 | +
|
| 43 | + Set an event to appear on the event queue every given number of milliseconds. |
| 44 | + The first event will not appear until the amount of time has passed. |
| 45 | +
|
| 46 | + The ``event`` attribute can be a ``pygame.event.Event`` object or an integer |
| 47 | + type that denotes an event. |
| 48 | +
|
| 49 | + ``loops`` is an integer that denotes the number of events posted. If 0 (default) |
| 50 | + then the events will keep getting posted, unless explicitly stopped. |
| 51 | +
|
| 52 | + To disable the timer for such an event, call the function again with the same |
| 53 | + event argument with ``millis`` argument set to 0. |
| 54 | +
|
| 55 | + It is also worth mentioning that a particular event type can only be put on a |
| 56 | + timer once. In other words, there cannot be two timers for the same event type. |
| 57 | + Setting an event timer for a particular event discards the old one for that |
| 58 | + event type. |
| 59 | +
|
| 60 | + When this function is called with an ``Event`` object, the event(s) received |
| 61 | + on the event queue will be a shallow copy; the dict attribute of the event |
| 62 | + object passed as an argument and the dict attributes of the event objects |
| 63 | + received on timer will be references to the same dict object in memory. |
| 64 | + Modifications on one dict can affect another, use deepcopy operations on the |
| 65 | + dict object if you don't want this behaviour. |
| 66 | + However, calling this function with an integer event type would place event objects |
| 67 | + on the queue that don't have a common dict reference. |
| 68 | +
|
| 69 | + ``loops`` replaces the ``once`` argument, and this does not break backward |
| 70 | + compatibility. |
| 71 | +
|
| 72 | + .. versionaddedold:: 2.0.0.dev3 once argument added. |
| 73 | + .. versionchangedold:: 2.0.1 event argument supports ``pygame.event.Event`` object |
| 74 | + .. versionaddedold:: 2.0.1 added loops argument to replace once argument |
| 75 | + """ |
| 76 | + |
9 | 77 | @final |
10 | 78 | class Clock: |
11 | | - def tick(self, framerate: float = 0, /) -> int: ... |
12 | | - def tick_busy_loop(self, framerate: float = 0, /) -> int: ... |
13 | | - def get_time(self) -> int: ... |
14 | | - def get_rawtime(self) -> int: ... |
15 | | - def get_fps(self) -> float: ... |
| 79 | + """Create an object to help track time. |
| 80 | +
|
| 81 | + Creates a new Clock object that can be used to track an amount of time. The |
| 82 | + clock also provides several functions to help control a game's framerate. |
| 83 | +
|
| 84 | + .. versionchanged:: 2.1.4 This class is also available through the ``pygame.Clock`` |
| 85 | + alias. |
| 86 | + """ |
| 87 | + |
| 88 | + def __new__(cls) -> Clock: ... |
| 89 | + def tick(self, framerate: float = 0, /) -> int: |
| 90 | + """Update the clock. |
| 91 | +
|
| 92 | + This method should be called once per frame. It will compute how many |
| 93 | + milliseconds have passed since the previous call. |
| 94 | +
|
| 95 | + If you pass the optional framerate argument the function will delay to |
| 96 | + keep the game running slower than the given ticks per second. This can be |
| 97 | + used to help limit the runtime speed of a game. By calling |
| 98 | + ``Clock.tick(40)`` once per frame, the program will never run at more |
| 99 | + than 40 frames per second. |
| 100 | +
|
| 101 | + Note that this function uses SDL_Delay function which is not accurate on |
| 102 | + every platform, but does not use much CPU. Use tick_busy_loop if you want |
| 103 | + an accurate timer, and don't mind chewing CPU. |
| 104 | + """ |
| 105 | + |
| 106 | + def tick_busy_loop(self, framerate: float = 0, /) -> int: |
| 107 | + """Update the clock. |
| 108 | +
|
| 109 | + This method should be called once per frame. It will compute how many |
| 110 | + milliseconds have passed since the previous call. |
| 111 | +
|
| 112 | + If you pass the optional framerate argument the function will delay to |
| 113 | + keep the game running slower than the given ticks per second. This can be |
| 114 | + used to help limit the runtime speed of a game. By calling |
| 115 | + ``Clock.tick_busy_loop(40)`` once per frame, the program will never run at |
| 116 | + more than 40 frames per second. |
| 117 | +
|
| 118 | + Note that this function uses :func:`pygame.time.delay`, which uses lots |
| 119 | + of CPU in a busy loop to make sure that timing is more accurate. |
| 120 | +
|
| 121 | + .. versionaddedold:: 1.8 |
| 122 | + """ |
| 123 | + |
| 124 | + def get_time(self) -> int: |
| 125 | + """Time used in the previous tick. |
| 126 | +
|
| 127 | + The number of milliseconds that passed between the previous two calls to |
| 128 | + ``Clock.tick()``. |
| 129 | + """ |
| 130 | + |
| 131 | + def get_rawtime(self) -> int: |
| 132 | + """Actual time used in the previous tick. |
| 133 | +
|
| 134 | + Similar to ``Clock.get_time()``, but does not include any time used |
| 135 | + while ``Clock.tick()`` was delaying to limit the framerate. |
| 136 | + """ |
| 137 | + |
| 138 | + def get_fps(self) -> float: |
| 139 | + """Compute the clock framerate. |
| 140 | +
|
| 141 | + Compute your game's framerate (in frames per second). It is computed by |
| 142 | + averaging the last ten calls to ``Clock.tick()``. |
| 143 | + """ |
0 commit comments