a06e44a04e97ac0bcf311c59af9dac093bac6bc0
[xonotic/netradiant.git] / tools / quake3 / q3map2 / help.c
1 /* -------------------------------------------------------------------------------
2
3    Copyright (C) 1999-2007 id Software, Inc. and contributors.
4    For a list of contributors, see the accompanying CONTRIBUTORS file.
5
6    This file is part of GtkRadiant.
7
8    GtkRadiant is free software; you can redistribute it and/or modify
9    it under the terms of the GNU General Public License as published by
10    the Free Software Foundation; either version 2 of the License, or
11    (at your option) any later version.
12
13    GtkRadiant is distributed in the hope that it will be useful,
14    but WITHOUT ANY WARRANTY; without even the implied warranty of
15    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16    GNU General Public License for more details.
17
18    You should have received a copy of the GNU General Public License
19    along with GtkRadiant; if not, write to the Free Software
20    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
21
22    -------------------------------------------------------------------------------
23
24    This code has been altered significantly from its original form, to support
25    several games based on the Quake III Arena engine, in the form of "Q3Map2."
26
27    ------------------------------------------------------------------------------- */
28
29
30
31 /* dependencies */
32 #include "q3map2.h"
33
34
35
36 struct HelpOption
37 {
38         const char* name;
39         const char* description;
40 };
41
42 void HelpOptions(const char* group_name, int indentation, int width, struct HelpOption* options, int count)
43 {
44         indentation *= 2;
45         char* indent = malloc(indentation+1);
46         memset(indent, ' ', indentation);
47         indent[indentation] = 0;
48         printf("%s%s:\n", indent, group_name);
49         indentation += 2;
50         indent = realloc(indent, indentation+1);
51         memset(indent, ' ', indentation);
52         indent[indentation] = 0;
53
54         int i;
55         for ( i = 0; i < count; i++ )
56         {
57                 int printed = printf("%s%-24s  ", indent, options[i].name);
58                 int descsz = strlen(options[i].description);
59                 int j = 0;
60                 while ( j < descsz && descsz-j > width - printed )
61                 {
62                         if ( j != 0 )
63                                 printf("%s%26c",indent,' ');
64                         int fragment = width - printed;
65                         while ( fragment > 0 && options[i].description[j+fragment-1] != ' ')
66                                         fragment--;
67                         j += fwrite(options[i].description+j, sizeof(char), fragment, stdout);
68                         putchar('\n');
69                         printed = indentation+26;
70                 }
71                 if ( j == 0 )
72                 {
73                         printf("%s\n",options[i].description+j);
74                 }
75                 else if ( j < descsz )
76                 {
77                         printf("%s%26c%s\n",indent,' ',options[i].description+j);
78                 }
79         }
80
81         putchar('\n');
82
83         free(indent);
84 }
85
86 void HelpBsp()
87 {
88         struct HelpOption bsp[] = {
89                 {"-bsp <filename.map>", "Switch that enters this stage"},
90                 {"-altsplit", "Alternate BSP tree splitting weights (should give more fps)"},
91                 {"-bspfile <filename.bsp>", "BSP file to write"},
92                 {"-celshader <shadername>", "Sets a global cel shader name"},
93                 {"-custinfoparms", "Read scripts/custinfoparms.txt"},
94                 {"-debuginset", "Push all triangle vertexes towards the triangle center"},
95                 {"-debugportals", "Make BSP portals visible in the map"},
96                 {"-debugsurfaces", "Color the vertexes according to the index of the surface"},
97                 {"-deep", "Use detail brushes in the BSP tree, but at lowest priority (should give more fps)"},
98                 {"-de <F>", "Distance epsilon for plane snapping etc."},
99                 {"-fakemap", "Write fakemap.map containing all world brushes"},
100                 {"-flares", "Turn on support for flares (TEST?)"},
101                 {"-flat", "Enable flat shading (good for combining with -celshader)"},
102                 {"-fulldetail", "Treat detail brushes as structural ones"},
103                 {"-leaktest", "Abort if a leak was found"},
104                 {"-linefile <filename.lin>", "Line file to write"},
105                 {"-meta", "Combine adjacent triangles of the same texture to surfaces (ALWAYS USE THIS)"},
106                 {"-minsamplesize <N>", "Sets minimum lightmap resolution in luxels/qu"},
107                 {"-mi <N>", "Sets the maximum number of indexes per surface"},
108                 {"-mv <N>", "Sets the maximum number of vertices of a lightmapped surface"},
109                 {"-ne <F>", "Normal epsilon for plane snapping etc."},
110                 {"-nocurves", "Turn off support for patches"},
111                 {"-nodetail", "Leave out detail brushes"},
112                 {"-noflares", "Turn off support for flares"},
113                 {"-nofog", "Turn off support for fog volumes"},
114                 {"-nohint", "Turn off support for hint brushes"},
115                 {"-nosubdivide", "Turn off support for `q3map_tessSize` (breaks water vertex deforms)"},
116                 {"-notjunc", "Do not fix T-junctions (causes cracks between triangles, do not use)"},
117                 {"-nowater", "Turn off support for water, slime or lava (Stef, this is for you)"},
118                 {"-np <A>", "Force all surfaces to be nonplanar with a given shade angle"},
119                 {"-onlyents", "Only update entities in the BSP"},
120                 {"-patchmeta", "Turn patches into triangle meshes for display"},
121                 {"-prtfile <filename.prt>", "Portal file to write"},
122                 {"-rename", "Append suffix to miscmodel shaders (needed for SoF2)"},
123                 {"-samplesize <N>", "Sets default lightmap resolution in luxels/qu"},
124                 {"-skyfix", "Turn sky box into six surfaces to work around ATI problems"},
125                 {"-snap <N>", "Snap brush bevel planes to the given number of units"},
126                 {"-srffile <filename.srf>", "Surface file to write"},
127                 {"-tempname <filename.map>", "Read the MAP file from the given file name"},
128                 {"-texrange <N>", "Limit per-surface texture range to the given number of units, and subdivide surfaces like with `q3map_tessSize` if this is not met"},
129                 {"-tmpout", "Write the BSP file to /tmp"},
130                 {"-verboseentities", "Enable `-v` only for map entities, not for the world"},
131         };
132         HelpOptions("BSP Stage", 0, 80, bsp, sizeof(bsp)/sizeof(struct HelpOption));
133 }
134
135 void HelpVis()
136 {
137         struct HelpOption vis[] = {
138                 {"-vis <filename.map>", "Switch that enters this stage"},
139                 {"-fast", "Very fast and crude vis calculation"},
140                 {"-mergeportals", "The less crude half of `-merge`, makes vis sometimes much faster but doesn't hurt fps usually"},
141                 {"-merge", "Faster but still okay vis calculation"},
142                 {"-nopassage", "Just use PortalFlow vis (usually less fps)"},
143                 {"-nosort", "Do not sort the portals before calculating vis (usually slower)"},
144                 {"-passageOnly", "Just use PassageFlow vis (usually less fps)"},
145                 {"-prtfile <filename.prt>", "Portal file to read"},
146                 {"-saveprt", "Keep the Portal file after running vis (so you can run vis again)"},
147                 {"-tmpin", "Use /tmp folder for input"},
148                 {"-tmpout", "Use /tmp folder for output"},
149         };
150         HelpOptions("VIS Stage", 0, 80, vis, sizeof(vis)/sizeof(struct HelpOption));
151 }
152
153 void HelpLight()
154 {
155         struct HelpOption light[] = {
156                 {"-light <filename.map>", "Switch that enters this stage"},
157                 {"-vlight <filename.map>", "Deprecated alias for `-light -fast` ... filename.map"},
158                 {"-approx <N>", "Vertex light approximation tolerance (never use in conjunction with deluxemapping)"},
159                 {"-areascale <F, `-area` F>", "Scaling factor for area lights (surfacelight)"},
160                 {"-border", "Add a red border to lightmaps for debugging"},
161                 {"-bouncegrid", "Also compute radiosity on the light grid"},
162                 {"-bounceonly", "Only compute radiosity"},
163                 {"-bouncescale <F>", "Scaling factor for radiosity"},
164                 {"-bounce <N>", "Number of bounces for radiosity"},
165                 {"-bspfile <filename.bsp>", "BSP file to write"},
166                 {"-cheapgrid", "Use `-cheap` style lighting for radiosity"},
167                 {"-cheap", "Abort vertex light calculations when white is reached"},
168                 {"-compensate <F>", "Lightmap compensate (darkening factor applied after everything else)"},
169                 {"-cpma", "CPMA vertex lighting mode"},
170                 {"-custinfoparms", "Read scripts/custinfoparms.txt"},
171                 {"-dark", "Darken lightmap seams"},
172                 {"-debugaxis", "Color the lightmaps according to the lightmap axis"},
173                 {"-debugcluster", "Color the lightmaps according to the index of the cluster"},
174                 {"-debugdeluxe", "Show deluxemaps on the lightmap"},
175                 {"-debugnormals", "Color the lightmaps according to the direction of the surface normal"},
176                 {"-debugorigin", "Color the lightmaps according to the origin of the luxels"},
177                 {"-debugsurfaces, -debugsurface", "Color the lightmaps according to the index of the surface"},
178                 {"-debugunused", "This option does nothing"},
179                 {"-debug", "Mark the lightmaps according to the cluster: unmapped clusters get yellow, occluded ones get pink, flooded ones get blue overlay color, otherwise red"},
180                 {"-deluxemode 0", "Use modelspace deluxemaps (DarkPlaces)"},
181                 {"-deluxemode 1", "Use tangentspace deluxemaps"},
182                 {"-deluxe, -deluxemap", "Enable deluxemapping (light direction maps)"},
183                 {"-dirtdebug, -debugdirt", "Store the dirtmaps as lightmaps for debugging"},
184                 {"-dirtdepth", "Dirtmapping depth"},
185                 {"-dirtgain", "Dirtmapping exponent"},
186                 {"-dirtmode 0", "Ordered direction dirtmapping"},
187                 {"-dirtmode 1", "Randomized direction dirtmapping"},
188                 {"-dirtscale", "Dirtmapping scaling factor"},
189                 {"-dirty", "Enable dirtmapping"},
190                 {"-dump", "Dump radiosity from `-bounce` into numbered MAP file prefabs"},
191                 {"-export", "Export lightmaps when compile finished (like `-export` mode)"},
192                 {"-exposure <F>", "Lightmap exposure to better support overbright spots"},
193                 {"-external", "Force external lightmaps even if at size of internal lightmaps"},
194                 {"-extravisnudge", "Broken feature to nudge the luxel origin to a better vis cluster"},
195                 {"-extrawide", "Deprecated alias for `-super 2 -filter`"},
196                 {"-extra", "Deprecated alias for `-super 2`"},
197                 {"-fastbounce", "Use `-fast` style lighting for radiosity"},
198                 {"-faster", "Use a faster falloff curve for lighting; also implies `-fast`"},
199                 {"-fastgrid", "Use `-fast` style lighting for the light grid"},
200                 {"-fast", "Ignore tiny light contributions"},
201                 {"-filter", "Lightmap filtering"},
202                 {"-floodlight", "Enable floodlight (zero-effort somewhat decent lighting)"},
203                 {"-gamma <F>", "Lightmap gamma"},
204                 {"-gridambientscale <F>", "Scaling factor for the light grid ambient components only"},
205                 {"-gridscale <F>", "Scaling factor for the light grid only"},
206                 {"-keeplights", "Keep light entities in the BSP file after compile"},
207                 {"-lightmapdir <directory>", "Directory to store external lightmaps (default: same as map name without extension)"},
208                 {"-lightmapsize <N>", "Size of lightmaps to generate (must be a power of two)"},
209                 {"-lomem", "Low memory but slower lighting mode"},
210                 {"-lowquality", "Low quality floodlight (appears to currently break floodlight)"},
211                 {"-minsamplesize <N>", "Sets minimum lightmap resolution in luxels/qu"},
212                 {"-nocollapse", "Do not collapse identical lightmaps"},
213                 {"-nodeluxe, -nodeluxemap", "Disable deluxemapping"},
214                 {"-nogrid", "Disable grid light calculation (makes all entities fullbright)"},
215                 {"-nolightmapsearch", "Do not optimize lightmap packing for GPU memory usage (as doing so costs fps)"},
216                 {"-normalmap", "Color the lightmaps according to the direction of the surface normal (TODO is this identical to `-debugnormals`?)"},
217                 {"-nostyle, -nostyles", "Disable support for light styles"},
218                 {"-nosurf", "Disable tracing against surfaces (only uses BSP nodes then)"},
219                 {"-notrace", "Disable shadow occlusion"},
220                 {"-novertex", "Disable vertex lighting"},
221                 {"-patchshadows", "Cast shadows from patches"},
222                 {"-pointscale <F, `-point` F>", "Scaling factor for point lights (light entities)"},
223                 {"-q3", "Use nonlinear falloff curve by default (like Q3A)"},
224                 {"-samplescale <F>", "Scales all lightmap resolutions"},
225                 {"-samplesize <N>", "Sets default lightmap resolution in luxels/qu"},
226                 {"-samples <N>", "Adaptive supersampling quality"},
227                 {"-scale <F>", "Scaling factor for all light types"},
228                 {"-shadeangle <A>", "Angle for phong shading"},
229                 {"-shade", "Enable phong shading at default shade angle"},
230                 {"-skyscale <F, `-sky` F>", "Scaling factor for sky and sun light"},
231                 {"-smooth", "Deprecated alias for `-samples 2`"},
232                 {"-srffile <filename.srf>", "Surface file to read"},
233                 {"-style, -styles", "Enable support for light styles"},
234                 {"-sunonly", "Only compute sun light"},
235                 {"-super <N, `-supersample` N>", "Ordered grid supersampling quality"},
236                 {"-thresh <F>", "Triangle subdivision threshold"},
237                 {"-trianglecheck", "Broken check that should ensure luxels apply to the right triangle"},
238                 {"-trisoup", "Convert brush faces to triangle soup"},
239                 {"-wolf", "Use linear falloff curve by default (like W:ET)"},
240         };
241
242         HelpOptions("Light Stage", 0, 80, light, sizeof(light)/sizeof(struct HelpOption));
243 }
244
245 void HelpAnalyze()
246 {
247         struct HelpOption analyze[] = {
248                 {"-analyze <filename.bsp>", "Switch that enters this mode"},
249                 {"-lumpswap", "Swap byte order in the lumps"},
250         };
251
252         HelpOptions("Analyzing BSP-like file structure", 0, 80, analyze, sizeof(analyze)/sizeof(struct HelpOption));
253 }
254
255 void HelpScale()
256 {
257         struct HelpOption scale[] = {
258                 {"-scale <S filename.bsp>", "Scale uniformly"},
259                 {"-scale <SX SY SZ filename.bsp>", "Scale non-uniformly"},
260                 {"-scale -tex <S filename.bsp>", "Scale uniformly without texture lock"},
261                 {"-scale -tex <SX SY SZ filename.bsp>", "Scale non-uniformly without texture lock"},
262         };
263         HelpOptions("Scaling", 0, 80, scale, sizeof(scale)/sizeof(struct HelpOption));
264 }
265
266 void HelpConvert()
267 {
268         struct HelpOption convert[] = {
269                 {"-convert <filename.bsp>", "Switch that enters this mode"},
270                 {"-de <number>", "Distance epsilon for the conversion"},
271                 {"-format <converter>", "Select the converter (available: map, ase, or game names)"},
272                 {"-ne <F>", "Normal epsilon for the conversion"},
273                 {"-shadersasbitmap", "(only for ase) use the shader names as \\*BITMAP key so they work as prefabs"},
274         };
275
276         HelpOptions("Converting & Decompiling", 0, 80, convert, sizeof(convert)/sizeof(struct HelpOption));
277 }
278
279 void HelpExport()
280 {
281         struct HelpOption exportl[] = {
282                 {"-export <filename.bsp>", "Copies lightmaps from the BSP to `filename/lightmap_0000.tga` ff"}
283         };
284
285         HelpOptions("Exporting lightmaps", 0, 80, exportl, sizeof(exportl)/sizeof(struct HelpOption));
286 }
287
288 void HelpFixaas()
289 {
290         struct HelpOption fixaas[] = {
291                 {"-fixaas <filename.bsp>", "Switch that enters this mode"},
292         };
293
294         HelpOptions("Fixing AAS checksum", 0, 80, fixaas, sizeof(fixaas)/sizeof(struct HelpOption));
295 }
296
297 void HelpInfo()
298 {
299         struct HelpOption info[] = {
300                 {"-info <filename.bsp>", "Switch that enters this mode"},
301         };
302
303         HelpOptions("Get info about BSP file", 0, 80, info, sizeof(info)/sizeof(struct HelpOption));
304 }
305
306 void HelpImport()
307 {
308         struct HelpOption import[] = {
309                 {"-import <filename.bsp>", "Copies lightmaps from `filename/lightmap_0000.tga` ff into the BSP"},
310         };
311
312         HelpOptions("Importing lightmaps", 0, 80, import, sizeof(import)/sizeof(struct HelpOption));
313 }
314
315 void HelpMinimap()
316 {
317         struct HelpOption minimap[] = {
318                 {"-minimap <filename.bsp>", "Creates a minimap of the BSP, by default writes to `../gfx/filename_mini.tga`"},
319                 {"-black", "Write the minimap as a black-on-transparency RGBA32 image"},
320                 {"-boost <F>", "Sets the contrast boost value (higher values make a brighter image); contrast boost is somewhat similar to gamma, but continuous even at zero"},
321                 {"-border <F>", "Sets the amount of border pixels relative to the total image size"},
322                 {"-gray", "Write the minimap as a white-on-black GRAY8 image"},
323                 {"-keepaspect", "Ensure the aspect ratio is kept (the minimap is then letterboxed to keep aspect)"},
324                 {"-minmax <xmin ymin zmin xmax ymax zmax>", "Forces specific map dimensions (note: the minimap actually uses these dimensions, scaled to the target size while keeping aspect with centering, and 1/64 of border appended to all sides)"},
325                 {"-nokeepaspect", "Do not ensure the aspect ratio is kept (makes it easier to use the image in your code, but looks bad together with sharpening)"},
326                 {"-o <filename.tga>", "Sets the output file name"},
327                 {"-random <N>", "Sets the randomized supersampling count (cannot be combined with `-samples`)"},
328                 {"-samples <N>", "Sets the ordered supersampling count (cannot be combined with `-random`)"},
329                 {"-sharpen <F>", "Sets the sharpening coefficient"},
330                 {"-size <N>", "Sets the width and height of the output image"},
331                 {"-white", "Write the minimap as a white-on-transparency RGBA32 image"},
332         };
333
334         HelpOptions("MiniMap", 0, 80, minimap, sizeof(minimap)/sizeof(struct HelpOption));
335 }
336
337 void HelpCommon()
338 {
339         struct HelpOption common[] = {
340                 {"-connect <address>", "Talk to a NetRadiant instance using a specific XML based protocol"},
341                 {"-force", "Allow reading some broken/unsupported BSP files e.g. when decompiling, may also crash"},
342                 {"-fs_basepath <path>", "Sets the given path as main directory of the game (can be used more than once to look in multiple paths)"},
343                 {"-fs_game <gamename>", "Sets a different game directory name (default for Q3A: baseq3, can be used more than once)"},
344                 {"-fs_homebase <dir>", "Specifies where the user home directory name is on Linux (default for Q3A: .q3a)"},
345                 {"-fs_pakpath <dir>", "Specify a package directory (can be used more than once to look in multiple paths)"},
346                 {"-game <gamename>", "Load settings for the given game (default: quake3)"},
347                 {"-subdivisions <F>", "multiplier for patch subdivisions quality"},
348                 {"-threads <N>", "number of threads to use"},
349                 {"-v", "Verbose mode"}
350         };
351
352         HelpOptions("Common Options", 0, 80, common, sizeof(common)/sizeof(struct HelpOption));
353
354 }
355
356 void HelpMain(const char* arg)
357 {
358         printf("Usage: q3map2 [stage] [common options...] [stage options...] [stage source file]\n");
359         printf("       q3map2 -help [stage]\n\n");
360
361         HelpCommon();
362
363         struct HelpOption stages[] = {
364                 {"-bsp", "BSP Stage"},
365                 {"-vis", "VIS Stage"},
366                 {"-light", "Light Stage"},
367                 {"-analyze", "Analyzing BSP-like file structure"},
368                 {"-scale", "Scaling"},
369                 {"-convert", "Converting & Decompiling"},
370                 {"-export", "Exporting lightmaps"},
371                 {"-fixaas", "Fixing AAS checksum"},
372                 {"-info", "Get info about BSP file"},
373                 {"-import", "Importing lightmaps"},
374                 {"-minimap", "MiniMap"},
375         };
376         void(*help_funcs[])() = {
377                 HelpBsp,
378                 HelpVis,
379                 HelpLight,
380                 HelpAnalyze,
381                 HelpScale,
382                 HelpConvert,
383                 HelpExport,
384                 HelpFixaas,
385                 HelpInfo,
386                 HelpImport,
387                 HelpMinimap,
388         };
389
390         if ( arg && strlen(arg) > 0 )
391         {
392                 if ( arg[0] == '-' )
393                         arg++;
394
395                 unsigned i;
396                 for ( i = 0; i < sizeof(stages)/sizeof(struct HelpOption); i++ )
397                         if ( strcmp(arg, stages[i].name+1) == 0 )
398                         {
399                                 help_funcs[i]();
400                                 return;
401                         }
402         }
403
404         HelpOptions("Stages", 0, 80, stages, sizeof(stages)/sizeof(struct HelpOption));
405 }