Added document for program overview and reflex map format

docs/doc-map-parsing.txt

@@ -0,0 +1,82 @@
+
+oopless-parser.hpp / oopless-parser.cpp
+    Parses Reflex's .map file, both version 6 and version 8.
+
+Reflex Map Format
+    Reflex maps are plain text files featuring keywords and indentation levels.
+
+    Reflex map keywords:
+    Ordered by indentation level (outer to inner).
+        "global"
+        "prefab"
+        "entity"
+        "brush"
+        "vertices"
+        "faces"
+
+    "vertices" and "faces", sharing the level, are contained in brushes.
+    "brush" and "entity", sharing the level are contained in prefabs.
+    "global" largely behaves the same as prefabs.
+
+    There are two distinct map formats from Reflex- V6 and V8. 
+    V6 was the map format before the addition of prefabs (V8 feature).
+
+    As far as the conversion process is concerned:
+
+        'global' and 'prefab' are containers for map objects.
+
+        'entity' and 'brush' are map objects (but entity may contain a brush).
+
+        'vertices' and 'faces' are details of brushes.
+
+Brush Data
+    Brushes contain faces and vertices. 
+    A brush's faces and vertices are listed in its "faces" and "vertices".
+
+Vertex Data
+    A vertex contains 3 floats representing a coordinate. 
+    Reflex uses a right-handed coordinate system while idTech engine uses left.
+
+Face Data
+    Faces contain the texture definition, indices, & the texture to be applied.
+    Each field in the line, being the entire face, is separated by space.
+
+    The first 5 fields are always data for the texture definition.
+    In order, 
+        * texture x offset
+        * texture y offset
+        * texture x scale
+        * texture y scale
+        * texture rotation
+        
+    The next fields are integers being indices for the list of vertices for 
+    the brush.
+
+    Followed by an hex digit for the color code in sRGB to apply to the face.
+
+    Then followed by the path to the texture asset.
+
+Parsing States
+        GLOBAL or PREFAB -> {BRUSH, ENTITY}
+        BRUSH    -> {FACES, VERTICES}
+        VERTICES -> {FACES, BRUSH, ENTITY}
+        FACES    -> {VERTICES, BRUSH, ENTITY, PREFAB}
+        ENTITY   -> {ENTITY, BRUSH, PREFAB}
+
+    In all observations, VERTICES are defined before FACES.
+
+    Entities may contain brushes as a part of its data; however it is not
+    reflected in indentation levels in Reflex. Thus for the conversion, 
+    brushes must be contained in the entity string, and converted in a 
+    different phase (because the worldspawn entity in idTech excludes 
+    entity-brushes). The parser transitions out of handling the entity when
+    it hits the brush keyword and the entity's type does not match is not of 
+    a specific set of types.
+
+Implementation Overview
+    Each parsing function:
+        - assumes by the time it is called, the respective keyword has already
+        been advanced past.
+        - retrieves the next line from the input stream
+        - detects next possible parsing states
+        - will output its respective data structure

docs/doc-overview.txt

@@ -0,0 +1,118 @@
+reflex2q3
+A tool to convert Reflex Arena maps to idTech .maps for use in map editors.
+Forked from chronokun's ReflexToQ3.
+
+Features, and Responsibilities of the Program: For Mappers
+    The converter is equipped with the following features:
+        - Converts map geometry from Reflex
+        - Converts entities such as, but not limited to
+            - player spawn points
+            - item pickups
+            - teleporters and respective targets
+            - race checkpoints
+
+    During the conversion process, face related data (texture & color) are 
+    preserved. This is both because of the differences between engines and the
+    numerous games built in idTech engines. Meaning the map converter does not
+    attempt to retexture the map with generic idTech engine equivalents or 
+    per-game equivalents. It is the individual mappers' responsibility to 
+    appropriately adapt the map for the target game. Some of the following 
+    tasks for mappers remain:
+
+        - Redesigning specific map geometry so meta/gameplay tricks work.
+        - Sealing leaks allowed by Reflex Arena, but illegal in idTech.
+        - Texturing the map.
+            * Extends to applying lava and slime effects to brushes.
+        - Providing light to the map.
+            * The converter handles Point Lights; however some entities and 
+            textures in Reflex emit light while target game equivalents
+            do not.
+
+Program Design: For Programmers
+    The program can be summarized as two distinct phases:
+        1. Converting worldspawn (map geometry).
+        2. Converting entities.
+
+    These are split into two distinct phases because of the difference between
+    engines. While it is acceptable for worldspawn brushes and game entites to
+    be in which ever order in Reflex, worldspawn in IdTech engines must not have
+    entities with in it. Entities must be handled separately after worldspawn.
+
+    Both phases will write to the output file, the format determined by a 
+    function pointer to the outputting function- the function to call being a
+    "variable" determined in main. Both phases convert and write to file single 
+    instance of a game object (brush or entity) at a time.
+
+    Converting Worldspawn
+        This is the phase that passes through the input file, parses Reflex's 
+        .map format, and converts brushes for the idTech format.
+
+        Functions pertaining to this phase are written to be easily changed to
+        deal with either from-memory or from-file operations. For example, 
+        functions for parsing brushes for the first phase will deal with input 
+        and output file streams, but later in the next phase they are used to 
+        deal with stringstream. If for any reason, the entire contents of the 
+        input file should be stored in memory, no major rewrites are needed.
+
+        The parsing functions for each game object (brush, faces, vertices) 
+        expect and operate on the contents underneath the respective keywords.
+
+        As the two engines are very different, entities must be converted and
+        written to file at a different phase. The converter will store the 
+        strings of an entity to a vector of vector of strings (STL). A vector
+        was chosen because the entity converter needs to prescan the container
+        for teleporters and targets. The vector permitting multiple passes FIFO
+        and pass by reference; where instead STL queue is either destructive or
+        requires copying the queue. 
+
+    Converting Entities
+        This is the phase that operates on the container of entity strings, 
+        converts, and writes them to file. Entity names for pick up items will
+        vary per target game; to easily adapt to multiple games, a plain text 
+        file is used, containing Reflex map entity id's corresponding to the 
+        target game entity names.
+
+        In order to determine the teleporters and the corresponding target 
+        locations, the entity container is prescanned.
+
+Major Code Changes in Forking
+    - Can be compiled for g++ and by extension mingw, and Linux systems.
+        The original project was for Microsoft Visual Studio; however even
+        manually compiling the source resulted in errors from syntax acceptable
+        by Visual Studio, but rejected by g++.
+
+    - Removal of ckmath, original author's custom C++ library for linear 
+    algebra
+        This was because the attempt to compile ckmath results in several 
+        warnings and errors. Addressing the compilation errors would have 
+        warranted its own tests to see if the output is unchanged. 
+        This was scrapped for Eigen.
+
+    - Addition of Reflex version 8 map parsing
+        The original code had a reported Issue where it did not parse V8, the
+        current format of map files for the game.
+
+    - Addition of output to Net Radiant's brush definition
+        The original code's output was the legacy brush definition used by GTK
+        Radiant or older map editors.
+
+    - Addition of converting map entities.
+
+    - Addition of translating texture definitions.
+        Previously these were kept as placeholder values.
+
+    - Severe bug fixes
+        The old converter crashed on converting Pocket Infinity, and had 
+        distorted geometry for certain maps e.g Sky Temples. The main cause
+        for such issues have been addressed and will not occur on maps 
+        featuring similar cases.
+
+Minor Code Changes
+    - Improved memory usage
+
+    - Added new command line arguments and robust handling of.
+        -h, --help, displays help
+        -gtk        switch to output to GTK's map format
+        -e <FILE>   entity conversion
+
+    - Added test cases to verify correctness of operations pre-commit.