olegpz
/
ericw-tools
mirror of https://github.com/ericwa/ericw-tools.git
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: format other manuals

This commit is contained in:
Eric Wasylishen 2022-01-26 23:02:08 -07:00
parent 31cd6fe2f2
commit 2ab779556a
6 changed files with 128 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
docs/bspinfo.rst
View File

@ -1,14 +1,15 @@
NAME =======
==== bspinfo
=======
bspinfo - print basic information about a Quake BSP file bspinfo - print basic information about a Quake BSP file
SYNOPSIS Synopsis
======== ========
**bspinfo** BSPFILE **bspinfo** BSPFILE
DESCRIPTION Description
=========== ===========
**bspinfo** will print a very basic summary of the internal data in **bspinfo** will print a very basic summary of the internal data in
@ -20,21 +21,21 @@ If the filename *BSPFILE* does not have a .bsp extension, **bsputil**
will look for a .bsp file by stripping the file extension from BSPFILE will look for a .bsp file by stripping the file extension from BSPFILE
(if any) and appending ".bsp". (if any) and appending ".bsp".
AUTHOR Author
====== ======
| Kevin Shanahan (aka Tyrann) - http://disenchant.net | Kevin Shanahan (aka Tyrann) - http://disenchant.net
| Eric Wasylishen | Eric Wasylishen
| Based on source provided by id Software | Based on source provided by id Software
REPORTING BUGS Reporting Bugs
============== ==============
| Please post bug reports at | Please post bug reports at
https://github.com/ericwa/ericw-tools/issues. https://github.com/ericwa/ericw-tools/issues.
| Improvements to the documentation are welcome and encouraged. | Improvements to the documentation are welcome and encouraged.
COPYRIGHT Copyright
========= =========
| Copyright (C) 2017 Eric Wasylishen | Copyright (C) 2017 Eric Wasylishen
@ -46,7 +47,7 @@ COPYRIGHT
This is free software: you are free to change and redistribute it. There This is free software: you are free to change and redistribute it. There
is NO WARRANTY, to the extent permitted by law. is NO WARRANTY, to the extent permitted by law.
SEE ALSO See Also
======== ========
**qbsp**\ (1) **light**\ (1) **vis**\ (1) **bsputil**\ (1) **qbsp**\ (1) **light**\ (1) **vis**\ (1) **bsputil**\ (1)

30
docs/bsputil.rst
View File

@ -1,33 +1,39 @@
NAME =======
==== bsputil
=======
bsputil - utiltiy for working with Quake BSP files bsputil - utiltiy for working with Quake BSP files
SYNOPSIS Synopsis
======== ========
**bsputil** [OPTION]... BSPFILE **bsputil** [OPTION]... BSPFILE
DESCRIPTION Description
=========== ===========
**bsputil is a small utility for basic manipulation of Quake BSP **bsputil is a small utility for basic manipulation of Quake BSP
files.** files.**
OPTIONS Options
======= =======
--extract-textures .. program:: bsputil
.. option:: --extract-textures
Extract the texture data from *BSPFILE*\ **and create a Quake WAD** Extract the texture data from *BSPFILE*\ **and create a Quake WAD**
file. The output filename is generated from *BSPFILE*\ **by** file. The output filename is generated from *BSPFILE*\ **by**
stripping the .bsp extension and adding the .wad extension. stripping the .bsp extension and adding the .wad extension.
--extract-entities .. option:: --extract-entities
Extract the entity data from *BSPFILE*\ **and create a plain** text Extract the entity data from *BSPFILE*\ **and create a plain** text
.ent file. The output filename is generated from *BSPFILE* by .ent file. The output filename is generated from *BSPFILE* by
stripping the .bsp extension and adding the .ent extension. stripping the .bsp extension and adding the .ent extension.
--check .. option:: --check
Load *BSPFILE*\ **into memory and run a set of tests to check that** Load *BSPFILE*\ **into memory and run a set of tests to check that**
all internal data structures are self-consistent. Currently the tests all internal data structures are self-consistent. Currently the tests
are very basic and not all warnings will result in errors from all are very basic and not all warnings will result in errors from all
@ -35,21 +41,21 @@ OPTIONS
designers, but is intended to assist with development of the **qbsp designers, but is intended to assist with development of the **qbsp
tool and check that a "clean" bsp file is generated.** tool and check that a "clean" bsp file is generated.**
AUTHOR Author
====== ======
| Kevin Shanahan (aka Tyrann) - http://disenchant.net | Kevin Shanahan (aka Tyrann) - http://disenchant.net
| Eric Wasylishen | Eric Wasylishen
| Based on source provided by id Software | Based on source provided by id Software
REPORTING BUGS Reporting Bugs
============== ==============
| Please post bug reports at | Please post bug reports at
https://github.com/ericwa/ericw-tools/issues. https://github.com/ericwa/ericw-tools/issues.
| Improvements to the documentation are welcome and encouraged. | Improvements to the documentation are welcome and encouraged.
COPYRIGHT Copyright
========= =========
| Copyright (C) 2017 Eric Wasylishen | Copyright (C) 2017 Eric Wasylishen
@ -61,7 +67,7 @@ COPYRIGHT
This is free software: you are free to change and redistribute it. There This is free software: you are free to change and redistribute it. There
is NO WARRANTY, to the extent permitted by law. is NO WARRANTY, to the extent permitted by law.
SEE ALSO See Also
======== ========
**qbsp(1)** **light(1)** **vis(1)** **bspinfo(1)** **quake(6)** **qbsp(1)** **light(1)** **vis(1)** **bspinfo(1)** **quake(6)**

1
docs/index.rst
View File

@ -19,5 +19,4 @@ Indices and tables
================== ==================
* :ref:`genindex` * :ref:`genindex`
* :ref:`modindex`
* :ref:`search` * :ref:`search`

99
docs/light.rst
View File

@ -1,14 +1,15 @@
NAME =====
==== light
=====
light - Caclulate lightmap data for a Quake BSP file light - Caclulate lightmap data for a Quake BSP file
SYNOPSIS Synopsis
======== ========
**light** [OPTION]... BSPFILE **light** [OPTION]... BSPFILE
DESCRIPTION Description
=========== ===========
**light** reads a Quake .bsp file and calculates light and shadow **light** reads a Quake .bsp file and calculates light and shadow
@ -16,9 +17,11 @@ information based on the entity definitions contained in the .bsp. The
.bsp file is updated with the new light data upon completion, .bsp file is updated with the new light data upon completion,
overwriting any existing lighting data. overwriting any existing lighting data.
OPTIONS Options
======= =======
.. program:: light
| Note, any of the Worldspawn Keys listed in the next section can be | Note, any of the Worldspawn Keys listed in the next section can be
supplied as command-line options, which will override any setting in supplied as command-line options, which will override any setting in
worldspawn. worldspawn.
@ -26,31 +29,37 @@ OPTIONS
Performance options: Performance options:
-------------------- --------------------
-threads n .. option:: -threads n
Set number of threads explicitly. By default light will attempt to Set number of threads explicitly. By default light will attempt to
detect the number of CPUs/cores available. detect the number of CPUs/cores available.
-extra .. option:: -extra
Calculate extra samples (2x2) and average the results for smoother Calculate extra samples (2x2) and average the results for smoother
shadows. shadows.
-extra4 .. option:: -extra4
Calculate even more samples (4x4) and average the results for Calculate even more samples (4x4) and average the results for
smoother shadows. smoother shadows.
-gate n .. option:: -gate n
Set a minimum light level, below which can be considered zero Set a minimum light level, below which can be considered zero
brightness. This can dramatically speed up processing when there are brightness. This can dramatically speed up processing when there are
large numbers of lights with inverse or inverse square falloff. In large numbers of lights with inverse or inverse square falloff. In
most cases, values less than 1.0 will cause no discernible visual most cases, values less than 1.0 will cause no discernible visual
differences. Default 0.001. differences. Default 0.001.
-sunsamples [n] .. option:: -sunsamples [n]
Set the number of samples to use for "_sunlight_penumbra" and Set the number of samples to use for "_sunlight_penumbra" and
"_sunlight2" (sunlight2 may use more or less because of how the suns "_sunlight2" (sunlight2 may use more or less because of how the suns
are set up in a sphere). Default 100. are set up in a sphere). Default 100.
-surflight_subdivide [n] .. option:: -surflight_subdivide [n]
| Configure spacing of all surface lights. Default 128 units. Minimum | Configure spacing of all surface lights. Default 128 units. Minimum
setting: 64 / max 2048. In the future I'd like to make this setting: 64 / max 2048. In the future I'd like to make this
configurable per-surface-light. configurable per-surface-light.
@ -58,17 +67,20 @@ Performance options:
Output format options: Output format options:
---------------------- ----------------------
-lit .. option:: -lit
Force generation of a .lit file, even if your map does not have any Force generation of a .lit file, even if your map does not have any
coloured lights. By default, light will automatically generate the coloured lights. By default, light will automatically generate the
.lit file when needed. .lit file when needed.
-onlyents .. option:: -onlyents
Updates the entities lump in the bsp. You should run this after Updates the entities lump in the bsp. You should run this after
running qbsp with -onlyents, if your map uses any switchable lights. running qbsp with -onlyents, if your map uses any switchable lights.
All this does is assign style numbers to each switchable light. All this does is assign style numbers to each switchable light.
-litonly .. option:: -litonly
Generate a .lit file that is compatible with the .bsp without Generate a .lit file that is compatible with the .bsp without
modifying the .bsp. This is meant for tweaking lighting or adding modifying the .bsp. This is meant for tweaking lighting or adding
colored lights when you can't modify an existing .bsp (e.g. for colored lights when you can't modify an existing .bsp (e.g. for
@ -80,7 +92,8 @@ Output format options:
(flickering/switchable) can't be added in new areas or have their (flickering/switchable) can't be added in new areas or have their
styles changed. styles changed.
-nolighting .. option:: -nolighting
Do all of the stuff required for lighting to work without actually Do all of the stuff required for lighting to work without actually
performing any lighting calculations. This is mainly for engines that performing any lighting calculations. This is mainly for engines that
don't use the light data, but still need switchable lights, etc. don't use the light data, but still need switchable lights, etc.
@ -90,7 +103,8 @@ Output format options:
Postprocessing options: Postprocessing options:
----------------------- -----------------------
-soft [n] .. option:: -soft [n]
| Perform post-processing on the lightmap which averages adjacent | Perform post-processing on the lightmap which averages adjacent
samples to smooth shadow edges. If n is specified, the algorithm samples to smooth shadow edges. If n is specified, the algorithm
will take 'n' samples on each side of the sample point and replace will take 'n' samples on each side of the sample point and replace
@ -104,61 +118,74 @@ Postprocessing options:
Debug modes: Debug modes:
------------ ------------
-dirtdebug .. option:: -dirtdebug
Implies "-dirt", and renders just the dirtmap against a fullbright Implies "-dirt", and renders just the dirtmap against a fullbright
background, ignoring all lights in the map. Useful for previewing and background, ignoring all lights in the map. Useful for previewing and
turning the dirt settings. turning the dirt settings.
-phongdebug .. option:: -phongdebug
Write normals to lit file for debugging phong shading. Write normals to lit file for debugging phong shading.
-bouncedebug .. option:: -bouncedebug
Write bounced lighting only to the lightmap for debugging / Write bounced lighting only to the lightmap for debugging /
previewing -bounce. previewing -bounce.
-surflight_dump .. option:: -surflight_dump
Saves the lights generated by surfacelights to a Saves the lights generated by surfacelights to a
"mapname-surflights.map" file. "mapname-surflights.map" file.
-novisapprox .. option:: -novisapprox
| Disable approximate visibility culling of lights, which has a small | Disable approximate visibility culling of lights, which has a small
chance of introducing artifacts where lights cut off too soon. chance of introducing artifacts where lights cut off too soon.
Experimental options: Experimental options:
--------------------- ---------------------
-addmin .. option:: -addmin
Changes the behaviour of *minlight*. Instead of increasing low light Changes the behaviour of *minlight*. Instead of increasing low light
levels to the global minimum, add the global minimum light level to levels to the global minimum, add the global minimum light level to
all style 0 lightmaps. This may help reducing the sometimes uniform all style 0 lightmaps. This may help reducing the sometimes uniform
minlight effect. minlight effect.
-lit2 .. option:: -lit2
Force generation of a .lit2 file, even if your map does not have any Force generation of a .lit2 file, even if your map does not have any
coloured lights. coloured lights.
-lux .. option:: -lux
Generate a .lux file storing average incoming light directions for Generate a .lux file storing average incoming light directions for
surfaces. Usable by FTEQW with "r_deluxemapping 1" surfaces. Usable by FTEQW with "r_deluxemapping 1"
-lmscale n .. option:: -lmscale n
Equivalent to "_lightmap_scale" worldspawn key. Equivalent to "_lightmap_scale" worldspawn key.
-bspxlit .. option:: -bspxlit
Writes rgb data into the bsp itself. Writes rgb data into the bsp itself.
-bspx .. option:: -bspx
Writes both rgb and directions data into the bsp itself. Writes both rgb and directions data into the bsp itself.
"-novanilla .. option:: -novanilla
Fallback scaled lighting will be omitted. Standard grey lighting will Fallback scaled lighting will be omitted. Standard grey lighting will
be omitted if there are coloured lights. Implies "-bspxlit". "-lit" be omitted if there are coloured lights. Implies "-bspxlit". "-lit"
will no longer be implied by the presence of coloured lights. will no longer be implied by the presence of coloured lights.
"-wrnormals .. option:: -wrnormals
Writes normal data into the bsp itself. Writes normal data into the bsp itself.
MODEL ENTITY KEYS Model Entity Keys
================= =================
Worldspawn Keys Worldspawn Keys
@ -391,7 +418,7 @@ is off or on.
its brushes from emitting bounced light they receive from elsewhere.) its brushes from emitting bounced light they receive from elsewhere.)
Only has an effect if "_bounce" is enabled in worldspawn. Only has an effect if "_bounce" is enabled in worldspawn.
LIGHT ENTITY KEYS Light Entity Keys
================= =================
Light entity keys can be used in any entity with a classname starting Light entity keys can be used in any entity with a classname starting
@ -572,14 +599,14 @@ The following light properties correspond to these sunlight settings:
Set to 1 to make the light compiler ignore this entity (prevents it Set to 1 to make the light compiler ignore this entity (prevents it
from casting any light). e.g. could be useful with rtlights. from casting any light). e.g. could be useful with rtlights.
OTHER INFORMATION Other Information
================= =================
The "\b" escape sequence toggles red text on/off, you can use this in The "\b" escape sequence toggles red text on/off, you can use this in
any strings in the map file. e.g. "message" "Here is \\bsome red any strings in the map file. e.g. "message" "Here is \\bsome red
text\b..." text\b..."
AUTHOR Author
====== ======
| Eric Wasylishen | Eric Wasylishen
@ -587,14 +614,14 @@ AUTHOR
| David Walton (aka spike) | David Walton (aka spike)
| Based on source provided by id Software | Based on source provided by id Software
REPORTING BUGS Reporting Bugs
============== ==============
| Please post bug reports at | Please post bug reports at
https://github.com/ericwa/ericw-tools/issues. https://github.com/ericwa/ericw-tools/issues.
| Improvements to the documentation are welcome and encouraged. | Improvements to the documentation are welcome and encouraged.
COPYRIGHT Copyright
========= =========
| Copyright (C) 2017 Eric Wasylishen | Copyright (C) 2017 Eric Wasylishen
@ -606,7 +633,7 @@ COPYRIGHT
This is free software: you are free to change and redistribute it. There This is free software: you are free to change and redistribute it. There
is NO WARRANTY, to the extent permitted by law. is NO WARRANTY, to the extent permitted by law.
SEE ALSO See Also
======== ========
**qbsp**\ (1) **vis**\ (1) **bspinfo**\ (1) **bsputil**\ (1) **qbsp**\ (1) **vis**\ (1) **bspinfo**\ (1) **bsputil**\ (1)

7
docs/qbsp.rst
View File

@ -1,3 +1,4 @@
====
qbsp qbsp
==== ====
@ -206,7 +207,7 @@ All faces of a brush must have textures which indicate the same
contents. Mixed content types will cause qbsp to print an error and contents. Mixed content types will cause qbsp to print an error and
exit. exit.
SKIP skip
^^^^ ^^^^
Any surfaces assigned a texture name of *skip* will be compiled into the Any surfaces assigned a texture name of *skip* will be compiled into the
@ -215,7 +216,7 @@ play can't walk or shoot through them) but they will not be drawn.
Water, slime and lava surfaces can be made invisible using the texture Water, slime and lava surfaces can be made invisible using the texture
names *\*waterskip*, *\*slimeskip* and *\*lavaskip* respectively. names *\*waterskip*, *\*slimeskip* and *\*lavaskip* respectively.
HINT hint
^^^^ ^^^^
Hint surfaces cause a bsp split and portal to be generated the on the Hint surfaces cause a bsp split and portal to be generated the on the
@ -228,7 +229,7 @@ Use a texture with the name *hintskip* on any surfaces of a hint brush
which you don't want to generate bsp splits or portals. All surfaces of which you don't want to generate bsp splits or portals. All surfaces of
a hint brush must use either the *hint* or *hintskip* texture name. a hint brush must use either the *hint* or *hintskip* texture name.
ORIGIN origin
^^^^^^ ^^^^^^
An origin brush (all faces textured with "origin") can be added to a An origin brush (all faces textured with "origin") can be added to a

54
docs/vis.rst
View File

@ -1,14 +1,15 @@
NAME ===
==== vis
===
vis - Compute visibility (PVS) for a Quake BSP file vis - Compute visibility (PVS) for a Quake BSP file
SYNOPSIS Synopsis
======== ========
**vis** [OPTION]... BSPFILE **vis** [OPTION]... BSPFILE
DESCRIPTION Description
=========== ===========
**vis** is a tool used in the creation of maps for the game Quake. vis **vis** is a tool used in the creation of maps for the game Quake. vis
@ -25,66 +26,79 @@ days or weeks in extreme cases. Vis will attempt to write a state file
every five minutes so that progress will not be lost in case the every five minutes so that progress will not be lost in case the
computer needs to be rebooted or an unexpected power outage occurs. computer needs to be rebooted or an unexpected power outage occurs.
OPTIONS Options
======= =======
-threads n .. program:: vis
.. option:: -threads n
Set number of threads explicitly. By default vis will attempt to Set number of threads explicitly. By default vis will attempt to
detect the number of CPUs/cores available. detect the number of CPUs/cores available.
-fast .. option:: -fast
Skip detailed calculations and calculate a very loose set of PVS Skip detailed calculations and calculate a very loose set of PVS
data. Sometimes useful for a quick test while developing a map. data. Sometimes useful for a quick test while developing a map.
-level n .. option:: -level n
Select a test level from 0 to 4 for detailed visibility calculations. Select a test level from 0 to 4 for detailed visibility calculations.
Lower levels are not necessarily faster in in all cases. It is not Lower levels are not necessarily faster in in all cases. It is not
recommended that you change the default level unless you are recommended that you change the default level unless you are
experiencing problems. Default 4. experiencing problems. Default 4.
-v .. option:: -v
Verbose output. Verbose output.
-vv .. option:: -vv
Very verbose output. Very verbose output.
-noambientsky .. option:: -noambientsky
Disable ambient sound generation for textures with names beginning Disable ambient sound generation for textures with names beginning
with 'SKY'. with 'SKY'.
-noambientwater .. option:: -noambientwater
Disable ambient sound generation for textures with names beginning Disable ambient sound generation for textures with names beginning
with '*WATER' or '*04WATER'. with '*WATER' or '*04WATER'.
-noambientslime .. option:: -noambientslime
Disable ambient sound generation for textures with names beginning Disable ambient sound generation for textures with names beginning
with '*SLIME'. with '*SLIME'.
-noambientlava .. option:: -noambientlava
Disable ambient sound generation for textures with names beginning Disable ambient sound generation for textures with names beginning
with '*LAVA'. with '*LAVA'.
-noambient .. option:: -noambient
Disable all ambient sound generation. Disable all ambient sound generation.
-visdist n .. option:: -visdist n
Allow culling of areas further than n units. Allow culling of areas further than n units.
AUTHOR Author
====== ======
| Kevin Shanahan (aka Tyrann) - http://disenchant.net | Kevin Shanahan (aka Tyrann) - http://disenchant.net
| Eric Wasylishen | Eric Wasylishen
| Based on source provided by id Software | Based on source provided by id Software
REPORTING BUGS Reporting Bugs
============== ==============
| Please post bug reports at | Please post bug reports at
https://github.com/ericwa/tyrutils-ericw/issues. https://github.com/ericwa/tyrutils-ericw/issues.
| Improvements to the documentation are welcome and encouraged. | Improvements to the documentation are welcome and encouraged.
COPYRIGHT Copyright
========= =========
| Copyright (C) 2017 Eric Wasylishen | Copyright (C) 2017 Eric Wasylishen
@ -96,7 +110,7 @@ COPYRIGHT
This is free software: you are free to change and redistribute it. There This is free software: you are free to change and redistribute it. There
is NO WARRANTY, to the extent permitted by law. is NO WARRANTY, to the extent permitted by law.
SEE ALSO See Also
======== ========
**qbsp**\ (1) **light**\ (1) **bspinfo**\ (1) **bsputil**\ (1) **qbsp**\ (1) **light**\ (1) **bspinfo**\ (1) **bsputil**\ (1)