mirror of
https://git.code.sf.net/p/quake/quakeforge
synced 2024-12-01 16:42:37 +00:00
605d60167d
So I don't have to keep duplicating file names all over the place, I've decided to use the "dox" extension on text files that are formatted for doxygen processing. This way, doxygen can search for them using wildcards, and unformated text files won't cause any headaches.
86 lines
3.1 KiB
Text
86 lines
3.1 KiB
Text
//unfortunately, have to wrap the docs in a C comment for doxygen
|
|
/**
|
|
\page mapformat Map (.map) File Format
|
|
|
|
"//" marks a comment which extends to the end of the current line
|
|
|
|
Note that () and {} characters require white space around them.
|
|
|
|
A map consists of a series of entities delineated by {}
|
|
|
|
An entity consists of a series of either epairs or brushes, one per "line".
|
|
|
|
An epair is a pair of quoted (via "quotes") strings. The first string of the
|
|
pair is the key, the second string the value. epairs are used to populate the
|
|
dictionary of the entity.
|
|
|
|
A brush is a simple, convex polytope delineated by {}. The format of a brush
|
|
is as follows:
|
|
\verbatim
|
|
{
|
|
[optional vertex list]
|
|
<plane spec> <texture name> <texcoord spec> [optional flags]
|
|
<plane spec> <texture name> <texcoord spec> [optional flags]
|
|
<plane spec> <texture name> <texcoord spec> [optional flags]
|
|
...
|
|
}
|
|
\endverbatim
|
|
That is, an optional vertex list followed by a number of surface specs, one
|
|
per line.
|
|
|
|
The optional vertex list, found in map files produced by Quest3d, is denoted
|
|
by a colon followed by a number indicating the number of vertexes in the list.
|
|
Following this, one per line, come the 3d coordinates of the vertexes, one
|
|
vertex per line. The vertex coordinates are listed in X Y Z order.
|
|
|
|
There are two formats for the plane spec, selected via the presence (vertex
|
|
mode) or absence (plane point mode) of the vertex list.
|
|
|
|
In vertex mode, the plane spec directly describes the shape of the surface
|
|
polygon. It is simply a number indicating the number of vertexes, followed by a
|
|
set of 0 based indexes, enclosed in (). The indexes indicate which of the
|
|
vertexes from the vertex list to use. When compiling the map, only the first 3
|
|
vertexes are significant: they are used as the 3 points for calculating the
|
|
plane.
|
|
|
|
In point plane mode, the plane spec consists of three point vectors, each
|
|
enclosed in ().
|
|
|
|
The three points (from either mode) are then used to calculate the plane
|
|
normal and offset:
|
|
\verbatim
|
|
n = (p0 - p1) x (p2 - p1) # normal
|
|
d = p1 . n # offset
|
|
\endverbatim
|
|
|
|
The texture name is just a simple string (no spaces) that specifies the name
|
|
of the texture within the wadfile.
|
|
|
|
The texcoord spec is black magic. :) It can be either:
|
|
(halflife style)
|
|
\verbatim
|
|
[ sx sy sz s ] [ tx ty tz t ] r s_scale t_scale
|
|
\endverbatim
|
|
or (quake style)
|
|
\verbatim
|
|
s t r s_scale t_scale
|
|
\endverbatim
|
|
In quake style, the basis vectors for s and t (sv and tv) are taken as the
|
|
most appropriate axial plane for the surface plane. In halflife style, they're
|
|
given directly via sv = (sx sy sz), tv = (tx ty tz). sv and tv are then
|
|
transformed by rotating around their perpendicular by r degrees. How this
|
|
interacts with halflife style is currently unknown. When rendering, the texture
|
|
coords (rs, rt) for vertex v are calculated as:
|
|
\verbatim
|
|
rs = v . sv + s
|
|
rt = v . tv + t
|
|
\endverbatim
|
|
|
|
The optional flags indicate various options for the surface. So far, the only
|
|
flag supported is "detail", indicating that the brush is a detail brush and not
|
|
to be used for visibility calculations. If any surface has the detail flag set,
|
|
the whole brush is affected.
|
|
|
|
Example map file (vertex mode):
|
|
\verbinclude cliptest.map
|
|
*/
|