Debian Codegraph @

manual.html

raw
1 <html>
2 <style>
3 .tocindent { margin-left: 20px; }
4 </style>
5 <body>
6
7 <h1>Omgifol manual</h1>
8
9 <p><em>Note: this is ridiculously incomplete.</em>
10 </p>
11 <table border="0" id="toc"><tr id="toctitle"><td align="center">
12 <b>Table of contents</b> <script type="text/javascript">showTocToggle("show","hide")</script></td></tr><tr id="tocinside"><td>
13 <div class="tocline"><a href="#Installation">1 Installation</a><br /></div>
14
15 <div class="tocline"><a href="#Using_Omgifol">2 Using Omgifol</a><br /></div>
16 <div class="tocline"><a href="#WAD_objects">3 WAD objects</a><br /></div>
17 <div class="tocindent">
18 <a href="#Loading_from_WAD_files">3.1 Loading from WAD files</a><br />
19 <a href="#Writing_to_WAD_files">3.2 Writing to WAD files</a><br />
20 <a href="#Accessing_lumps">3.3 Accessing lumps</a><br />
21 <div class="tocindent">
22 <a href="#Lump_groups">3.3.1 Lump groups</a><br />
23 </div>
24 <a href="#Merging">3.4 Merging</a><br />
25 </div>
26 <div class="tocline"><a href="#Lumps">4 Lumps</a><br /></div>
27 <div class="tocindent">
28 <a href="#Graphic_lumps">4.1 Graphic lumps</a><br />
29 </div>
30 <div class="tocline"><a href="#Editors">5 Editors</a><br /></div>
31 <div class="tocindent">
32 <a href="#Map_editor">5.1 Map editor</a><br />
33 <a href="#UDMF_map_editor">5.2 UDMF map editor</a><br />
34
35 </div>
36 </td></tr></table>
37 <a name="Installation"></a><h2>Installation</h2>
38 <ol><li> Install Python 3, which can be downloaded from <a href="https://python.org" title="https://python.org">https://python.org</a>
39 </li><li> Use pip to install Omgifol: <tt>pip install omgifol</tt>
40 </li><li> Or, if pip is unavailable, extract the "omg" directory in the Omgifol package into <em>pythondir</em>/Lib/site-packages (replace <em>pythondir</em> with the directory where Python is installed).
41 </li></ol>
42 <p>Optionally:
43
44 </p>
45 <ol><li> Install the <a href="https://python-pillow.github.io" class="external" title="https://python-pillow.github.io">Pillow library</a><span class="urlexpansion"> (<i>https://python-pillow.github.io</i>)</span>. This is required to import or export images.
46 </li>
47 <li> Install the <a href="https://pysoundfile.readthedocs.io" class="external" title="https://pysoundfile.readthedocs.io">PySoundFile library</a><span class="urlexpansion"> (<i>https://pysoundfile.readthedocs.io</i>)</span>. This is required to import or export sound files.
48 </li>
49 </ol>
50
51 <a name="Using_Omgifol"></a><h2>Using Omgifol</h2>
52 <p>At the beginning of an interactive session, or as the first line in a Python script file, enter
53 </p>
54 <pre> from omg import *
55 </pre>
56 <a name="WAD_objects"></a><h2>WAD objects</h2>
57 <p>A <tt>WAD</tt> is an abstract representation of a WAD file. A <tt>WAD</tt> object can load content from a WAD file, or save content to a WAD file, but is entirely memory-resident.
58
59 </p>
60 <a name="Loading_from_WAD_files"></a><h3>Loading from WAD files</h3>
61 <p>The following are all equivalent:
62 </p>
63 <pre> a = WAD('wadfile.wad')
64
65 a = WAD(from_file='wadfile.wad')
66
67 f = open('wadfile.wad', 'rb')
68 a = WAD(from_file=f)
69
70 a = WAD()
71 a.from_file('wadfile.wad')
72
73 f = open('wadfile.wad', 'rb')
74 a = WAD()
75 a.from_file(f)
76 </pre>
77 <p>You can load more than one file to the same object:
78 </p>
79 <pre> a = WAD()
80 a.from_file(file1)
81 a.from_file(file2)
82 a.from_file(file3)
83 </pre>
84 <p>In this case, lumps from <em>file2</em> will overwrite those from <em>file1</em>
85
86 with the same name, etc.
87 </p>
88 <a name="Writing_to_WAD_files"></a><h3>Writing to WAD files</h3>
89 <p>If <em>a</em> is a <tt>WAD</tt> instance:
90 </p>
91 <pre> a.to_file('some_wad.wad')
92 </pre>
93 <a name="Accessing_lumps"></a><h3>Accessing lumps</h3>
94
95 <p>Lumps are stored in <em>groups</em>. Each <tt>WAD</tt> holds a number of groups, representing different categories of lumps. Each group is an ordered dictionary; that is, it works just like a Python <tt>collections.OrderedDict</tt> object.
96 </p><p>All lumps are instances of the <tt>Lump</tt> class; see below for its documentation.
97
98 </p><p>To retrieve the sprite called <tt>CYBR1A</tt> from the <tt>WAD</tt> object <em>a</em>, do:
99 </p>
100 <pre> a.sprites['CYBR1A']
101 </pre>
102 <p>And to replace it with some other lump object called <tt>some_lump</tt>:
103 </p>
104
105 <pre> a.sprites['CYBR1A'] = some_lump
106 </pre>
107 <p>To add a new lump, simply do as above with a lump name that does not yet exist.
108 </p><p>Renaming and deleting is done as follows:
109 </p>
110 <pre> a.sprites.rename('CYBR1A', 'NEW_NAME')
111 del a.sprites['CYBR1A']
112 </pre>
113 <a name="Lump_groups"></a><h4>Lump groups</h4>
114 <p>By default, WADs recognize the following lump groups:
115 </p>
116 <pre> sprites Sprite graphics (between S and SS markers)
117 patches Wall graphics (between P and PP markers)
118 flats Flat graphics (between F and FF markers)
119 colormaps Boom colormaps (between C markers)
120 ztextures ZDoom textures (between TX markers)
121 maps Map data
122 udmfmaps Map data (UDMF)
123 glmaps GL nodes map data
124 music Music (all lumps named D_*)
125 sounds Sound effects (all lumps named DS* or DP*)
126 txdefs TEXTURE1, TEXTURE2 and PNAMES
127 graphics Titlepic, status bar, miscellaneous graphics
128 data Everything else
129 </pre>
130 <p>This scheme can be modified if desired; refer to wad.py for the details.
131
132 </p><p>The <tt>maps</tt> and <tt>glmaps</tt> are special. These do not contain lumps, but additional groups of lumps, one for each map. So if you access E1M1:
133 </p>
134 <pre> a.maps['E1M1']
135 </pre>
136 <p>you will retrieve a group of lumps containing all the map's data. To retrieve
137 the individual lumps, do:
138 </p>
139 <pre> a.maps['E1M1']['SIDEDEFS']
140 </pre>
141 <p>etc.
142
143 </p>
144 <a name="Merging"></a><h3>Merging</h3>
145 <p>To merge two <tt>WAD</tt>s <em>a</em> and <em>b</em>:
146 </p>
147 <pre> c = a + b
148 </pre>
149 <p>Note that (for efficiency reasons) this only copies references to lumps,
150 which means that subsequent changes to lumps in <em>a</em> or <em>b</em> will affect the
151 corresponding lumps in <em>c</em>. To give <em>c</em> its own set of lumps, do:
152
153 </p>
154 <pre> c = (a + b).copy()
155 </pre>
156 <p>When lumps in <em>a</em> and <em>b</em> have the same name,
157 lumps from <em>b</em> will replace those from <em>a</em>.
158 </p><p>It is also possible to merge individual sections:
159
160 </p>
161 <pre> a.sprites += b.sprites
162 </pre>
163 <p>Use with care for sections of different types.
164 </p><p>Note that some sections do more than just copy over the list of lumps
165 when they merge. For example, adding two <em>txdefs</em> sections together
166 will automagically merge the <tt>TEXTURE1</tt>, <tt>TEXTURE2</tt> and <tt>PNAMES</tt> lumps. <tt>txdefs</tt>
167
168 also get merged this way when two <tt>WAD</tt> objects are merged on the top level.
169 </p>
170 <a name="Lumps"></a><h2>Lumps</h2>
171 <p>The <tt>Lump</tt> class holds a single lump. The class provides the following data and methods:
172 </p>
173 <pre> .data The lump's raw data as a string
174 .to_file(<em>filename</em>) Save from a file
175 .from_file(<em>filename</em>) Load from a file
176 .copy() Return a copy
177
178 </pre>
179 <p>Creating a new lump called 'FOOF' containing the text 'Hello!' and inserting it into a <tt>WAD</tt> <em>w</em> would be done as follows:
180 </p>
181 <pre> w.data['FOOF'] = Lump('Hello!')
182 </pre>
183 <a name="Graphic_lumps"></a><h3>Graphic lumps</h3>
184 <p>There are subclasses of <tt>Lump</tt> for different types of lumps. Currently, only these provide special functionality: <tt>Graphic</tt>, <tt>Flat</tt>, and <tt>Sound</tt>.
185
186 </p><p><tt>Graphic</tt>, used to represent Doom format graphics, provides the following settable attributes:
187 </p>
188 <pre> .offsets (x, y) offsets
189 .x_offset x offset
190 .y_offset y offset
191 .dimensions (width, height)
192 .width width in pixels
193 .height height in pixels
194 </pre>
195 <p><tt>Graphic</tt> defines the following methods in adddition to those defined by <tt>Lump</tt>:
196 </p>
197 <pre> .from_raw Load from a raw image
198 .to_raw Return the image converted to raw pixels
199 .from_Image Load from a PIL Image instance
200 .to_Image Return the image converted to a PIL image
201 .translate Translate to another palette
202 </pre>
203 <p>For the argument lists used by these functions, refer to the code and the inline documentation in lump.py.
204 </p><p><tt>Flat</tt> works similarly to <tt>Graphic</tt>, but handles format conversions slightly differently.
205
206 </p><p><tt>Sound</tt>, used to represent Doom format sounds, provides the following settable attributes:
207 </p>
208 <pre> .format Sound effect format (0-3)
209 .length Length of sound in samples
210 .sample_rate Sample rate for digitized sounds (defaults to 11025)
211 .midi_bank MIDI patch bank number (formats 1-2 only)
212 .midi_patch MIDI patch number (formats 1-2 only)
213 </pre>
214 <p><tt>Sound</tt> defines the following methods in adddition to those defined by <tt>Lump</tt>:
215 </p>
216 <pre> .from_raw Load from a raw sound file
217 .to_raw Return the sound file converted to raw samples
218 .from_file Load from a sound file
219 .to_file Save the sound to a file
220 </pre>
221
222
223 </p>
224 <a name="Editors"></a><h2>Editors</h2>
225 <p><em>Editors</em> are used to edit lumps or lump groups. They represent lump data with high-level objects and structures, and provide methods to modify the data. The following editors have been implemented so far:
226 </p>
227 <ul><li> <tt>Colormap</tt> for the COLORMAP lump
228 </li><li> <tt>Playpal</tt> for the PLAYPAL lump
229 </li><li> <tt>Textures</tt> for TEXTURE1/TEXTURE2/PNAMES
230
231 </li><li> <tt>MapEditor</tt> for maps
232 </li><li> <tt>UMapEditor</tt> for maps in UDMF format
233 </li></ul>
234 <p>All editors provide the following methods:
235 </p>
236 <pre> .to_lump
237 .from_lump
238 </pre>
239 <p>or, if the editor represents more than one lump:
240 </p>
241 <pre> .to_lumps
242 .from_lumps
243 </pre>
244 <p>In the latter case, the editor is initialized with a lump group instead of a single lump.
245 </p>
246
247 <a name="Map_editor"></a><h3>Map editor</h3>
248 <p>Example (moving one vertex one unit):
249 </p>
250 <pre> m = MapEditor(wad.maps["E1M1"])
251 m.vertexes[103].x += 1
252 wad.maps["E1M1"] = m.to_lumps()
253 </pre>
254
255 <a name="UDMF_map_editor"></a><h3>UDMF map editor</h3>
256 <p><tt>UMapEditor</tt> works similarly to <tt>MapEditor</tt>, except the attributes of map data are named based on how they appear in the <tt>TEXTMAP</tt> lump itself. See the <a href="https://www.doomworld.com/eternity/engine/stuff/udmf11.txt">UDMF specification</a> for examples.
257 </p>
258 <p><tt>UMapEditor</tt> can also import non-UDMF maps, and line specials will automatically be translated to their UDMF equivalents when necessary:
259 </p>
260 <pre> # Load and automatically convert a Doom-format map
261 m = UMapEditor(wad.maps["E1M1"])
262
263 # Load a UDMF-format map
264 m = UMapEditor(wad.udmfmaps["MAP01"])
265 </pre>
266 <p>Refer to the source code for more information.</p>
267 </body>
268 </html>