Skip to content

Commit de83534

Browse files
einarfeinarf
authored
Sprite docstrings (#2302)
* init * animated * base * colored * sprite * collision * spatial_hash * sprite_list * Remove dead links in spatial hash documentation * Remove inactive loggers * Misc remaining docstrings
1 parent cf0a5d6 commit de83534

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

58 files changed

+1158
-745
lines changed

‎arcade/__init__.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,9 @@
2020

2121
def configure_logging(level: int | None = None):
2222
"""Set up basic logging.
23-
:param level: The log level. Defaults to DEBUG.
23+
24+
Args:
25+
level: The log level. Defaults to DEBUG.
2426
"""
2527
import logging
2628

‎arcade/camera/camera_2d.py‎

Lines changed: 60 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -55,31 +55,31 @@ class Camera2D:
5555
Replacing the camera data and projection data may break controllers. Their
5656
contents are exposed via properties rather than directly to prevent this.
5757
58-
:param viewport: A 4-int tuple which defines the pixel bounds which the camera
59-
will project to.
60-
:param position: The 2D position of the camera in the XY plane.
61-
:param up: A 2D vector which describes which direction is up
62-
(defines the +Y-axis of the camera space).
63-
:param zoom: A scalar value which is inversely proportional to the size of the
64-
camera projection. i.e. a zoom of 2.0 halves the size of the projection,
65-
doubling the perceived size of objects.
66-
:param projection: A 4-float tuple which defines the world space
67-
bounds which the camera projects to the viewport.
68-
:param near: The near clipping plane of the camera.
69-
:param far: The far clipping plane of the camera.
70-
:param render_target: The FrameBuffer that the camera uses. Defaults to the screen.
71-
If the framebuffer is not the default screen nothing drawn after this camera is used will
72-
show up. The FrameBuffer's internal viewport is ignored.
73-
:param window: The Arcade Window to bind the camera to.
74-
Defaults to the currently active window.
75-
76-
:attributes:
77-
* render_target - An optional framebuffer to activate at the same time as
78-
the projection data, could be the screen, or an offscreen texture
79-
* viewport - A rect which describes how the final projection should be mapped
80-
from unit-space. defaults to the size of the render_target or window
81-
* scissor - An optional rect which describes what pixels of the active render
82-
target should be drawn to when undefined the viewport rect is used.
58+
Args:
59+
viewport:
60+
A 4-int tuple which defines the pixel bounds which the camera will project to.
61+
position:
62+
The 2D position of the camera in the XY plane.
63+
up:
64+
A 2D vector which describes which direction is up
65+
(defines the +Y-axis of the camera space).
66+
zoom:
67+
A scalar value which is inversely proportional to the size of the
68+
camera projection. i.e. a zoom of 2.0 halves the size of the projection,
69+
doubling the perceived size of objects.
70+
projection:
71+
A 4-float tuple which defines the world space
72+
bounds which the camera projects to the viewport.
73+
near:
74+
The near clipping plane of the camera.
75+
far:
76+
The far clipping plane of the camera.
77+
render_target:
78+
The FrameBuffer that the camera uses. Defaults to the screen.
79+
If the framebuffer is not the default screen nothing drawn after this camera
80+
is used will show up. The FrameBuffer's internal viewport is ignored.
81+
window:
82+
The Arcade Window to bind the camera to. Defaults to the currently active window.
8383
"""
8484

8585
def __init__(
@@ -98,6 +98,10 @@ def __init__(
9898
):
9999
self._window: Window = window or get_window()
100100
self.render_target: Framebuffer | None = render_target
101+
"""
102+
An optional framebuffer to activate at the same time as
103+
the projection data, could be the screen, or an offscreen texture
104+
"""
101105

102106
# We don't want to force people to use a render target,
103107
# but we need to have some form of default size.
@@ -140,7 +144,16 @@ def __init__(
140144
)
141145

142146
self.viewport: Rect = viewport or LRBT(0, 0, width, height)
147+
"""
148+
A rect which describes how the final projection should be mapped
149+
from unit-space. defaults to the size of the render_target or window
150+
"""
151+
143152
self.scissor: Rect | None = scissor
153+
"""
154+
An optional rect which describes what pixels of the active render
155+
target should be drawn to when undefined the viewport rect is used.
156+
"""
144157

145158
@classmethod
146159
def from_camera_data(
@@ -178,26 +191,28 @@ def from_camera_data(
178191
* - ``render_target``
179192
- Complex rendering setups
180193
181-
:param camera_data: A :py:class:`~arcade.camera.data.CameraData`
182-
describing the position, up, forward and zoom.
183-
:param projection_data:
184-
A :py:class:`~arcade.camera.data.OrthographicProjectionData`
185-
which describes the left, right, top, bottom, far, near
186-
planes and the viewport for an orthographic projection.
187-
:param render_target: A non-screen
188-
:py:class:`~arcade.gl.framebuffer.Framebuffer` for this
189-
camera to draw into. When specified,
190-
191-
* nothing will draw directly to the screen
192-
* the buffer's internal viewport will be ignored
193-
194-
:param viewport:
195-
A viewport as a :py:class:`~arcade.types.rect.Rect`.
196-
This overrides any viewport the ``render_target`` may have.
197-
:param scissor:
198-
The OpenGL scissor box to use when drawing.
199-
:param window: The Arcade Window to bind the camera to.
200-
Defaults to the currently active window.
194+
Args:
195+
camera_data:
196+
A :py:class:`~arcade.camera.data.CameraData`
197+
describing the position, up, forward and zoom.
198+
projection_data:
199+
A :py:class:`~arcade.camera.data.OrthographicProjectionData`
200+
which describes the left, right, top, bottom, far, near
201+
planes and the viewport for an orthographic projection.
202+
render_target:
203+
A non-screen :py:class:`~arcade.gl.framebuffer.Framebuffer` for this
204+
camera to draw into. When specified,
205+
206+
* nothing will draw directly to the screen
207+
* the buffer's internal viewport will be ignored
208+
209+
viewport:
210+
A viewport as a :py:class:`~arcade.types.rect.Rect`.
211+
This overrides any viewport the ``render_target`` may have.
212+
scissor:
213+
The OpenGL scissor box to use when drawing.
214+
window: The Arcade Window to bind the camera to.
215+
Defaults to the currently active window.
201216
"""
202217

203218
if projection_data:

‎arcade/camera/data_types.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,8 +86,9 @@ def constrain_camera_data(data: CameraData, forward_priority: bool = False):
8686
Ensure that the camera data forward and up vectors are length one,
8787
and are perpendicular
8888
89-
:param data: the camera data to constrain
90-
:param forward_priority: whether up or forward gets constrained
89+
Args:
90+
data: the camera data to constrain
91+
forward_priority: whether up or forward gets constrained
9192
"""
9293
forward_vec = Vec3(*data.forward).normalize()
9394
up_vec = Vec3(*data.up).normalize()

‎arcade/camera/default.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,8 @@ class DefaultProjector(ViewportProjector):
107107
here to act as the default camera used internally by arcade. There should be
108108
no instance where a developer would want to use this class.
109109
110-
:param window: The window to bind the camera to. Defaults to the currently active window.
110+
Args:
111+
window: The window to bind the camera to. Defaults to the currently active window.
111112
"""
112113

113114
def __init__(self, *, context: ArcadeContext | None = None):

‎arcade/camera/grips/rotate.py‎

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,12 @@ def rotate_around_forward(data: CameraData, angle: float) -> tuple[float, float,
1717
If that is not the center of the screen this method may appear erroneous.
1818
Uses arcade.camera.controllers.quaternion_rotation internally.
1919
20-
:param data: The camera data to modify. The data's up vector is rotated around
21-
its forward vector
22-
:param angle: The angle in degrees to rotate clockwise by
20+
Args:
21+
data:
22+
The camera data to modify. The data's up vector is rotated around
23+
its forward vector
24+
angle:
25+
The angle in degrees to rotate clockwise by
2326
"""
2427
return quaternion_rotation(data.forward, data.up, angle)
2528

@@ -30,9 +33,12 @@ def rotate_around_up(data: CameraData, angle: float) -> tuple[float, float, floa
3033
Generally only useful in 3D games.
3134
Uses arcade.camera.controllers.quaternion_rotation internally.
3235
33-
:param data: The camera data to modify. The data's forward vector is rotated
34-
around its up vector
35-
:param angle: The angle in degrees to rotate clockwise by
36+
Args:
37+
data:
38+
The camera data to modify. The data's forward vector is rotated
39+
around its up vector
40+
angle:
41+
The angle in degrees to rotate clockwise by
3642
"""
3743
return quaternion_rotation(data.up, data.forward, angle)
3844

@@ -45,9 +51,12 @@ def rotate_around_right(
4551
right vector. Generally only useful in 3D games.
4652
Uses arcade.camera.controllers.quaternion_rotation internally.
4753
48-
:param data: The camera data to modify. The data's forward vector is rotated
49-
around its up vector
50-
:param angle: The angle in degrees to rotate clockwise by
54+
Args:
55+
data:
56+
The camera data to modify. The data's forward vector is rotated
57+
around its up vector
58+
angle:
59+
The angle in degrees to rotate clockwise by
5160
"""
5261
_forward = Vec3(data.forward[0], data.forward[1], data.forward[2])
5362
_up = Vec3(data.up[0], data.up[1], data.up[2])

‎arcade/camera/grips/screen_shake_2d.py‎

Lines changed: 35 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -25,27 +25,21 @@ class ScreenShake2D:
2525
the equation rises using a inverse exponential equation, before decreasing
2626
using a modified smooth-step sigmoid.
2727
28-
Attributes:
29-
max_amplitude: The largest possible world space offset.
30-
falloff_duration: The length of time in seconds it takes the shaking
31-
to reach 0 after reaching the maximum. Can be set
32-
to a negative number to disable falloff.
33-
shake_frequency: The number of peaks per second. Avoid making it
34-
a multiple of half the target frame-rate.
35-
(e.g. at 60 fps avoid 30, 60, 90, 120, etc.)
36-
37-
:param camera_data: The CameraData PoD that the controller modifies.
38-
Should not be changed once initialized.
39-
:param max_amplitude: The largest possible world space offset.
40-
:param falloff_time: The length of time in seconds it takes the shaking
41-
to reach 0 after reaching the maximum. Can be set
42-
to a negative number to disable falloff.
43-
:param acceleration_duration: The length of time in seconds it takes the
44-
shaking to reach max amplitude. Can be set
45-
to 0.0 to start at max amplitude.
46-
:param shake_frequency: The number of peaks per second. Avoid making it
47-
a multiple of half the target frame-rate.
48-
(e.g. at 60 fps avoid 30, 60, 90, 120, etc.)
28+
Args:
29+
camera_data:
30+
The CameraData PoD that the controller modifies. Should not be
31+
changed once initialized.
32+
max_amplitude:
33+
The largest possible world space offset.
34+
falloff_time:
35+
The length of time in seconds it takes the shaking to reach 0 after
36+
reaching the maximum. Can be set to a negative number to disable falloff.
37+
acceleration_duration:
38+
The length of time in seconds it takes the shaking to reach max
39+
amplitude. Can be set to 0.0 to start at max amplitude.
40+
shake_frequency:
41+
The number of peaks per second. Avoid making it a multiple of half
42+
the target frame-rate. (e.g. at 60 fps avoid 30, 60, 90, 120, etc.)
4943
"""
5044

5145
def __init__(
@@ -60,8 +54,20 @@ def __init__(
6054
self._data: CameraData = camera_data
6155

6256
self.max_amplitude: float = max_amplitude
57+
"""The largest possible world space offset."""
58+
6359
self.falloff_duration: float = falloff_time
60+
"""
61+
The length of time in seconds it takes the shaking to reach 0
62+
after reaching the maximum.
63+
"""
64+
6465
self.shake_frequency: float = shake_frequency
66+
"""
67+
The number of peaks per second. Avoid making it a multiple of
68+
half the target frame-rate.
69+
"""
70+
6571
self._acceleration_duration: float = acceleration_duration
6672

6773
self._shaking: bool = False
@@ -169,7 +175,8 @@ def _acceleration_amp(self, _t: float) -> float:
169175
The equation for the growing half of the amplitude equation.
170176
It uses 1.0001 so that at _t = 1.0 the amplitude equals 1.0.
171177
172-
:param _t: The scaled time. Should be between 0.0 and 1.0
178+
Args:
179+
_t: The scaled time. Should be between 0.0 and 1.0
173180
"""
174181
return 1.0001 - 1.0001 * exp(log(0.0001 / 1.0001) * _t)
175182

@@ -178,7 +185,8 @@ def _falloff_amp(self, _t: float) -> float:
178185
The equation for the falloff half of the amplitude equation.
179186
It is based on the 'smootherstep' function.
180187
181-
:param _t: The scaled time. Should be between 0.0 and 1.0
188+
Args:
189+
_t: The scaled time. Should be between 0.0 and 1.0
182190
"""
183191
return 1 - _t**3 * (_t * (_t * 6.0 - 15.0) + 10.0)
184192

@@ -241,9 +249,10 @@ def update(self, delta_time: float) -> None:
241249
Does not actually set the camera position.
242250
Should not be called more than once an update cycle.
243251
244-
:param delta_time: the length of time in seconds between update calls.
245-
Generally pass in the delta_time provided by the
246-
arcade.Window's on_update method.
252+
Args:
253+
delta_time:
254+
the length of time in seconds between update calls. Generally pass
255+
in the delta_time provided by the arcade.Window's on_update method.
247256
"""
248257
if not self._shaking:
249258
return

‎arcade/camera/orthographic.py‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -42,10 +42,14 @@ class OrthographicProjector(Projector):
4242
Initialize a Projector which produces an orthographic projection matrix using
4343
a CameraData and PerspectiveProjectionData PoDs.
4444
45-
:param window: The window to bind the camera to. Defaults to the currently active camera.
46-
:param view: The CameraData PoD. contains the viewport, position, up, forward, and zoom.
47-
:param projection: The OrthographicProjectionData PoD.
48-
contains the left, right, bottom top, near, and far planes.
45+
Args:
46+
window:
47+
The window to bind the camera to. Defaults to the currently active camera.
48+
view:
49+
The CameraData PoD. contains the viewport, position, up, forward, and zoom.
50+
projection:
51+
The OrthographicProjectionData PoD.
52+
contains the left, right, bottom top, near, and far planes.
4953
"""
5054

5155
def __init__(

‎arcade/camera/perspective.py‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -43,10 +43,14 @@ class PerspectiveProjector(Projector):
4343
Initialize a Projector which produces a perspective projection matrix using
4444
a CameraData and PerspectiveProjectionData PoDs.
4545
46-
:param window: The window to bind the camera to. Defaults to the currently active camera.
47-
:param view: The CameraData PoD. contains the viewport, position, up, forward, and zoom.
48-
:param projection: The PerspectiveProjectionData PoD.
49-
contains the field of view, aspect ratio, and then near and far planes.
46+
Args:
47+
window:
48+
The window to bind the camera to. Defaults to the currently active camera.
49+
view:
50+
The CameraData PoD. contains the viewport, position, up, forward, and zoom.
51+
projection:
52+
The PerspectiveProjectionData PoD. contains the field of view, aspect ratio,
53+
and then near and far planes.
5054
"""
5155

5256
def __init__(

0 commit comments

Comments
 (0)