Skip to content

Commit 7e8d566

Browse files
committed
Fixes pythonarcade#2821: Improve Textures guide wording, layers, uniqueness, and cache
1 parent f032c52 commit 7e8d566

1 file changed

Lines changed: 56 additions & 18 deletions

File tree

‎doc/programming_guide/textures.rst‎

Lines changed: 56 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,8 @@ Introduction
88
The :py:class:`arcade.Texture` type is how Arcade normally interacts with
99
images either loaded from disk or created manually. This is basically a
1010
wrapper for PIL/Pillow images including detection for hit box data
11-
using pymunk depending on the selected hit box algorithm. These texture
12-
objects are in other words responsible to provide raw RGBA pixel
13-
data to OpenGL and hit box geometry to the sprite engine.
11+
using pymunk depending on the selected hit box algorithm. These texture objects are responsible for providing raw RGBA pixel
12+
data to OpenGL and hit box geometry used when rendering sprites.
1413

1514
There is another texture type in Arcade in the lower level
1615
OpenGL API: :py:class:`arcade.gl.Texture2D`. This represents an
@@ -20,29 +19,62 @@ with the low level rendering API.
2019
Textures can be created/loaded before or after the window is created
2120
because they don't interact with OpenGL directly.
2221

22+
Texture Layers
23+
--------------
24+
25+
Textures in Arcade interact with several layers of the rendering system:
26+
27+
* **Arcade (Python / RAM)**
28+
The :py:class:`arcade.Texture` object stores image data and metadata
29+
in system memory, including raw pixel data and hit box information.
30+
31+
* **pyglet**
32+
Arcade relies on pyglet to manage the window and communicate with the
33+
graphics system.
34+
35+
* **OpenGL / GPU**
36+
When rendering occurs, the texture data is uploaded to the GPU so it
37+
can be used efficiently when drawing sprites.
38+
2339
Texture Uniqueness
2440
------------------
2541

26-
When a texture is created a ``hash/name`` is required. This should be a unique
27-
string. If two more more textures have the same name we will run into
28-
trouble. When loading textures the absolute path to the file is used
29-
as part of the name including vertical/horizontal/diagonal, size and
30-
other parameter for a truly unique name.
42+
Each texture in Arcade has a ``name`` (sometimes referred to as a hash)
43+
that uniquely identifies it in the texture cache. This value is used as
44+
the cache key when textures are loaded or created.
45+
46+
A *unique* name means that no two textures should share the same
47+
identifier. If multiple textures use the same name, the cache may return
48+
the wrong texture instance. This can lead to incorrect sprite rendering
49+
or invalid hit box data.
3150

32-
When loading texture through Arcade the name of the texture will be
33-
the absolute path to the image and various parameters such as size,
34-
flipping, xy position etc.
51+
When textures are loaded from files using functions such as
52+
:py:func:`arcade.load_texture`, Arcade automatically generates a unique
53+
name based on several pieces of information, including:
3554

36-
Also remember that the texture class do hit box detection with pymunk
37-
by looking at the raw pixel data. This means for example a texture with
38-
different flipping will be loaded multiple times (or fetched from cache)
39-
because we rely in the transformed pixel data to get the hit box.
55+
* The absolute path to the image file
56+
* The selected image region or size
57+
* Flipping options (horizontal, vertical, or diagonal)
58+
* Other transformation parameters
59+
60+
Using the absolute file path ensures that textures loaded from
61+
different relative paths still resolve to the same cached texture.
62+
63+
Flipping options also affect the generated name. For example,
64+
loading a texture with ``flipped_vertically=True`` produces a different
65+
texture instance because the underlying pixel data changes. This is
66+
important because hit box detection relies on the transformed pixel
67+
data.
68+
69+
For implementation details, see the texture loading logic in
70+
``arcade/cache/texture.py``.
4071

4172
Texture Cache
4273
-------------
4374

44-
Arcade is caching texture instances based on the ``name/hash`` attribute
45-
to significantly speed up loading times.
75+
Each :py:class:`arcade.Texture` has a ``name`` attribute that uniquely
76+
identifies it. Arcade uses this attribute in the
77+
:py:class:`arcade.cache.TextureCache` to speed up texture loading.
4678

4779
.. code:: python
4880
@@ -59,7 +91,13 @@ to significantly speed up loading times.
5991
The above also applies when using :py:func:`arcade.load_texture` or other
6092
texture loading functions.
6193

62-
Arcade's default texture cache can be cleared using ``arcade.texture.default_texture_cache.flush()``
94+
Arcade stores texture instances in the default texture cache
95+
(:py:class:`arcade.cache.TextureCache`). To clear all cached textures,
96+
use the :py:meth:`arcade.cache.TextureCache.flush` method:
97+
98+
.. code:: python
99+
100+
arcade.texture.default_texture_cache.flush()
63101
64102
Custom Textures
65103
---------------

0 commit comments

Comments
 (0)