1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
The Resource System
===================
Resource types
--------------
The resource system has four different resource
types/categories it can load.
* **Programs** : Shader programs (vertex, geometry, fragment, tessellation,
compute)
* **Textures** : Textures of all different variations
* **Scenes**: Wavefront, GLTF2 and STL scenes/objects
* **Data**: A generic "lane" for everything else
Each of these resource categories have separate search
directories, one or multiple loader classes and a
:py:class:`~moderngl_window.meta.base.ResourceDescription`
class we use to describe the resource we are loading
with all its parameters.
Resource paths
--------------
Resources are loaded using relative paths. These paths
are relative to one or multiple search directories
we register using the :py:mod:`~moderngl_window.resources`
module.
For simple usage were we have one or multiple resource
directories with mixed resource types (programs, textures
etc.) we can use the simplified version,
:py:func:`~moderngl_window.resources.register_dir`.
.. code:: python
from pathlib import Path
from moderngl_window import resources
# pathlib.Path (recommended)
resources.register_dir(Path('absolute/path/using/pathlib'))
# Strings and/or os.path
resources.register_dir('absolute/string/path')
A resource finder system will scan through the registered
directories in the order they were added loading the
first resource found.
For more advanced usage were resources of different types
are separated we can register resource type specific search
directories:
* :py:func:`~moderngl_window.resources.register_program_dir`
* :py:func:`~moderngl_window.resources.register_texture_dir`
* :py:func:`~moderngl_window.resources.register_scene_dir`
* :py:func:`~moderngl_window.resources.register_data_dir`
This can be handy when dealing with larger quantities of
files.
These search directories are stored in the
:py:class:`~moderngl_window.conf.Settings` instance
and can for example be temporarily altered if needed.
This means you can separate local and global resources
in more complex situations. It could even be used to
support themes by promoting a theme directory overriding
global/default resources or some default theme directory.
Resource descriptions
---------------------
Resource descriptions are basically just classes
acting as bags of attributes describing the resource
we are requesting. We have four standard classes.
* :py:class:`~moderngl_window.meta.program.ProgramDescription`
* :py:class:`~moderngl_window.meta.texture.TextureDescription`
* :py:class:`~moderngl_window.meta.scene.SceneDescription`
* :py:class:`~moderngl_window.meta.data.DataDescription`
Example::
from moderngl_window.meta import TextureDescription
# We are aiming to load wood.png horizontally flipped
# with generated mipmaps and high anisotropic filtering.
TextureDescription(
path='wood.png',
flip=True,
mipmap=True,
anisotropy=16.0,
)
New resource description classes can be created
by extending the base
:py:class:`~moderngl_window.meta.base.ResourceDescription` class.
This is not uncommon when for example making a new loader class.
Loading resources
-----------------
Now that we know about the different resource categories,
search paths and resource descriptions, we're ready to
actually load something.
Loading resources can in some situation be a bit verbose,
but you can simplify by wrapping them in your own functions
if needed.
The :py:class:`~moderngl_window.context.base.window.WindowConfig`
class is already doing this and can be used as a reference.
.. code:: python
from moderngl_window.resources import (
textures,
programs,
scenes,
data,
)
from moderngl_window.meta import (
TextureDescription,
ProgramDescription,
SceneDescription,
DataDescription,
)
Textures
~~~~~~~~
.. code:: python
# Load a 2D texture
texture = textures.load(TextureDescription(path='wood.png'))
# Load wood.png horizontally flipped with generated mipmaps and high anisotropic filtering.
textures.load(TextureDescription(path='wood.png', flip=True, mipmap=True, anisotropy=16.0))
# Load a texture array containing 10 vertically stacked tile textures
textures.load(TextureDescription(path='tiles.png', layers=10, mipmap=True, anisotrpy=8.0))
Programs
~~~~~~~~
.. code:: python
# Load a shader program in a single glsl file
program = programs.load(ProgramDescription(path='fun.glsl'))
# Load a shader program from multiple glsl files
program = programs.load(
ProgramDescription(
vertex_shader='sphere_vert.glsl',
geometry_shader='sphere_geo.glsl',
fragment_shader='sphere_fs.glsl',
)
)
Scenes
~~~~~~
.. code:: python
# Load a GLTF2 scene
scene = scenes.load(SceneDescription(path="city.gltf'))
# Load a wavefront scene
scene = scenes.load(SceneDescription(path="earth.obj'))
# Load an STL file
scene = scenes.load(SceneDescription(path="apollo_landing_site_18.stl"))
Data
~~~~
.. code:: python
# Load text file
text = data.load(DataDescription(path='notes.txt'))
# Load config file as a dict
config_dict = data.load(DataDescription(path='config.json'))
# Load binary data
data = data.load(DataDescription(path='data.bin', kind='binary))
For more information about supported parameters see the api documentation.
|
