@@ -8,9 +8,8 @@ Introduction
88The :py:class: `arcade.Texture ` type is how Arcade normally interacts with
99images either loaded from disk or created manually. This is basically a
1010wrapper 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
1514There is another texture type in Arcade in the lower level
1615OpenGL API: :py:class: `arcade.gl.Texture2D `. This represents an
@@ -20,29 +19,62 @@ with the low level rendering API.
2019Textures can be created/loaded before or after the window is created
2120because 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+
2339Texture 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
4172Texture 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
6092texture 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