create tremded branch

7 files changed, 969 insertions, 0 deletions

diff --git a/docs/Features.md b/docs/Features.md
new file mode 100644
index 0000000..1c228da
--- /dev/null
+++ b/docs/Features.md
@@ -0,0 +1,93 @@
+# Windows, Linux and OSX
+
+The GrangerHub Tremulous engine is supported on Windows, Linux and OSX. Builds
+are automaticly produced by our CI/CD system.
+
+# CI/CD 
+
+The Tremulous engine is supported by a CI/CD (Continuous Integration/Continous
+Delivery) using TravisCI and Github. Each time commits are pushed to the github
+repository, TravisCI will verify that each of the MacOSX, Linux and Windows builds
+are successful. Releases are generated automatically anytime a tag is pushed to
+the repository; TravisCI will then package the build with the assets and push
+the build artifacts to the Github releases page. Upon completion a notification
+is sent to the GrangerHub Slack.
+
+Hilights:
+* TravisCI
+* Automated builds
+* Automated release generation
+
+TODO: 
+* Add Appveyor
+* Reenable Coverity scans
+
+# CMake support
+
+A CMake system exists to build Tremulous on Linux and OSX. The CMake setup also
+supports building QVM's using the in-tree QVM toolchain.
+
+TODO: 
+* Windows
+* Appveyor Windows builds
+
+
+# C++14
+
+The engine has been modernized to compile at the C++14 standard. This was originally
+done to simplify supporting Lua using the SOL2 Library, however this conversion has 
+also resulted in a significantly improved stability due to better memory initialization.
+It's worth noting that the renderer's have not been converted to C++14 as we currently
+piggyback off ioquake3's renderer's (maintained by SmileTheory).
+
+# Lua
+
+The engine has an embedded Lua runtime and several API's are exposed from the engine,
+including:
+
+* Cvars
+* Binds
+* Passing commands to server
+* Nettle (Crypto library)
+* HTTP Client/Restful
+* JSON (rapidjson)
+
+# Multi-protocol
+
+Support for Tremulous 1.1.0, Tremulous 1.2.0 (GPP) and the never released version from
+DarkLegion's master branch are supported. A client can connect to any of those protocols. 
+A server can simultaneously serve to all those protocols. QVM version detection on the client
+which magically determines the correct interface required for a QVM.
+
+This work is thanks to `/dev/humancontroller`.
+
+# Auto-update 
+
+Autoupdates are not fully functional, problems with the minizip implementation require additional
+work to work.
+
+Users can however check the latests updates from the main menu in the client, which queries the 
+GrangerHub github for the latest release.
+
+TODO: 
+    * Lua library for ZIP files that preserves executable permissions 
+
+# Restful HTTP Client
+
+An HTTP Rest API is provided to both C++ and Lua interfaces.
+
+
+# JSON Support
+
+JSON support is provided via the lovely RapidJSON project. An interfaces is provided for both
+C++ and Lua.
+
+# Filesystem Stability
+
+The filesystem has been refactored to be stable from startup. It is not possible for a server to
+clobber the default QVM/UI.
+
+FIXME:
+    * Currently breaks mod loading support from the client main menu.
+
+
diff --git a/docs/LuaScripting.md b/docs/LuaScripting.md
new file mode 100644
index 0000000..4bde0d8
--- /dev/null
+++ b/docs/LuaScripting.md
@@ -0,0 +1,13 @@
+# Lua Scripting
+
+Purpose:
+Documentation regarding the Lua API's in depth. lua/README.md is for jumpping
+in _head first!_. What is possible, and maybe some "Shipping" scripts that might be
+released.
+
+This file should be the reference/bible to the Lua runtime API. More boring, answers
+questions, doesn't tell many jokes etc..
+
+
+TODO:  All of it
+
diff --git a/docs/ParticleSystem.md b/docs/ParticleSystem.md
new file mode 100644
index 0000000..e93843f
--- /dev/null
+++ b/docs/ParticleSystem.md
@@ -0,0 +1,160 @@
+
+# Tremulous Particle System
+
+Files matching the pattern `scripts/*.particle` are loaded as particle system description files.
+Each `.particle` file can contain an arbitrary number of discrete particle systems, much like a `.shader` file can house many shaders.
+A particle system is declared by a name followed by curly braces within which the functionality of the particle system is defined.
+
+For example:
+
+```
+aShinyNewParticleSystem { }
+```
+
+Inside the particle system declaration are placed UP TO *four* particle ejectors.
+Ejectors are identified by the keyword ejector and curly braces:
+
+```
+aShinyNewParticleSystem
+{
+     ejector { }
+
+     ejector { }
+
+     thirdPersonOnly
+}
+```
+
+The `thirdPersonOnly` keyword may be used to specify that the particle system is not visible from the first person if it relates to that client.
+
+The role of the particle ejector is to create some number of new particles at a defined rate.
+ These attributes are controlled by the following parameters:
+
+- count `<number>|infinite` - the number of particles this ejector will spawn.
+- delay `<msec>` - the delay in msec before the ejector starts spawning.
+- period `<initial> <final> <variance>` - the period between particle ejections.
+
+It is perfectly acceptable to have an initial period of zero.
+In this case the number of particles specified by the count keyword will be ejected at once.
+It is not permissible to have count infinite and a period of zero for obvious reasons.
+
+At ejection time each ejector creates up to four new particles based on templates.
+These are specified in the ejector section using the particle keyword:
+
+```
+aShinyNewParticleSystem
+{
+  ejector
+  {
+    particle { }
+
+    particle { }
+
+    count 50
+    delay 0
+    period 0 - 0
+  }
+}
+```
+
+Each particle template has a number of attributes:
+
+- `shader <fps>|sync <shader1 <shader2> ... <shaderN>` - this specifies the shaders to use for the particle. The frame rate can be set to a static rate or the sync parameter can be used in which case the frame rate will be synchronised to the lifetime of the particle such that the first frame is displayed on birth and the last frame is displayed immediately before death.
+- `model <model1> <model2> ... <modelN>` - use one of the specified models as the particle. This cannot be used in conjunction with the shader keyword.
+- `modelAnmation <firstFrame> <numFrames> <loopFrames> <fps>|sync` - animation parameters to use when model particles are employed.
+- `displacement <x> <y> <z> <variance>` - a static displacement about the attachment point. The variance parameter specifies a random displacement in all axes.
+- `normalDisplacement <displacement>` - for particle systems that have their normal set (impact particle systems for example) this specifies the magnitude of a displacement along the normal.
+- `velocityType static|static_transform|tag|cent|normal` - this specifies how the particle will compute its initial velocity. `static` means it is specified statically in the `.particle` file, `static_transform` means the same, except that it is transformed by the orientation matrix of what it is attached to, `tag` means the velocity is in the direction of the tag it is attached to, `cent` means the velocity is in the direction of the cent it is attached to and `normal` means the velocity is in the direction of the particle system normal.
+- `velocityDir linear|point` - this specifies whether the initial velocity is computed as a simple direction or as the direction towards a secondary point (defined by `velocityPoint` or dynamically through `velocityType cent`).
+- `velocity <x> <y> <z> <variance>` - for when `velocityType static` is present this specifies the direction. The variance here is specified in degrees e.g. `~5` - up to 5 degrees deviation.
+- `velocityMagnitude <magnitude>` - the magnitude of the velocity.
+- `velocityPoint <x> <y> <z> <variance>` - for when `velocityType static` and `velocityDir point` are present this specifies the point to move towards.
+- `parentVelocityFraction <fraction>` - for when the particle system is attached to a cent this specifies the fraction of the cent’s velocity that is added to the particle’s velocity.
+- `accelerationType static|static_transform|tag|cent|normal` - this specifies how the particle will compute its acceleration. `static` means it is specified statically in the `.particle` file, `static_transform` means the same, except that it is transformed by the orientation matrix of what it is attached to, `tag` means the acceleration is in the direction of the tag it is attached to, `cent` means the acceleration is in the direction of the cent it is attached to and `normal` means the acceleration is in the direction of the particle system normal.
+- `accelerationDir linear|point` - this specifies whether the acceleration is computed as a simple direction or as the direction towards a secondary point (defined by `accelerationPoint` or dynamically through `accelerationType cent`).
+- `acceleration <x> <y> <z> <variance>` - for when accelerationType static is present this specifies the direction. The variance here is specified in degrees e.g. `~5` - up to 5 degrees deviation.
+- `accelerationMagnitude <magnitude>` - the magnitude of the acceleration.
+- `accelerationPoint <x> <y> <z> <variance>` - for when accelerationType static and accelerationDir point are present this specifies the point to move towards.
+- `bounce <fraction>|cull` - the fraction of velocity that is refiected when a particle collides. If this is set to `0.0` the particle won't collide. When cull is used particles are culled as soon as they collide with objects.
+- `bounceMark <count> <radius> <shader>` - make a mark at each bounce point for up to `<count>` bounces.
+- `bounceSound <count> <sound>` - make a sound at each bounce point for up to `<count>` bounces.
+- `dynamicLight <delayRadius> <initialRadius> <finalRadius> { <r> <g> <b> }` - attach a dynamic light to this particle.
+- `color <delay> { <ir> <ig> <ib> } { <fr> <fg> <fb> }` - color the particle where `<i.>` refers to the initial color component and `<f.>` refers to the final color component.
+- `overdrawProtection` - cull particles that occupy a large amount of screen space.
+- `realLight` - light particles using the lightgrid instead of fullbright.
+- `cullOnStartSolid` - cull particles that are spawned inside brushes.
+- `radius <delay> <initial> <final>` - the radius of the particle throughout its lifetime. The delay parameter specifies the time in msec before radius scaling begins. The initial and final parameters specify the radii of the particle in quake units.
+- `alpha <delay> <initial> <final>` - the alpha of the particle throughout its lifetime. The delay parameter specifies the time in msec before alpha scaling begins. The initial and final parameters specify the alpha of the particle where `1.0` is totally opaque and `0.0` is totally transparent.
+- `rotation <delay> <initial> <final>` - the rotation of the particle throughout its lifetime. The delay parameter specifies the time in msec before the rotation begins. The initial and final parameters specify the rotation of the particle in degrees.
+- `lifeTime <time>` - the lifetime of the particle.
+- `childSystem <particle system>` - specifies a particle system to attach to this particle.
+- `childTrailSystem <trail system>` - specifies a trail system to attach to this particle.
+- `onDeathSystem <particle system>` - specifies a particle system to spawn at the point where this particle died.
+- `physicsRadius` - ???
+- `scaleWithCharge` - ???
+
+Except for vector components, shader fps ... and `period <initial><final> <variance>`, every value can be specified with a random variance.
+The syntax for this is as follows:
+
+```
+ [value][variance[%]]
+```
+So the following forms are possible, where random is a random number between `0.0` and `1.0` inclusive:
+
+```
+   5.0      // 5.0
+
+   5.0~8.0  // 5.0 + ( random * 8.0 )
+
+   5.0~200% // 5.0 + ( random * 5.0 * 200% )
+
+   ~7.0     // random * 7.0
+```
+
+This allows for relatively fiexible randomisation of most of the particle’s parameters. For parameters taking an initial and final value, specifying the final value as '`-`' will result in a final value the same as the initial value.
+
+For the purposes of map based particle systems using `misc_particle_system` it is safe to ignore `velocityType` and `accelerationType tag|cent|normal`, `normalDisplacement` and `parentVelocityFraction` altogether.
+
+Of course, it is not necessary to specify every parameter documented here for every particle system.
+If a parameter is not included it will usually default to zero.
+C/C++ style comments can be used throughout.
+There are an enormous number of possible combinations of particle systems parameters and as such it is impractical to test them all.
+For this reason it is possible that certain permutations do not behave as expected or wrongly.
+In this case you may have discovered a bug - let us know.
+Having said this when you’re having problems with a particle system make sure you scroll up the console and check that it compiled OK, I’ve written the parser to be very intolerant of error.
+
+Here is an example particle system:
+
+```
+aShinyNewParticleSystem
+{
+  ejector
+  {
+    particle
+    {
+      shader sync shader1 shader2
+
+      velocityType static
+      velocityDir linear
+      velocityMagnitude 200
+      velocity 0 0 1 ~30
+
+      accelerationType static
+      accelerationDir linear
+      accelerationMagnitude 50
+      acceleration 0 0 1 ~0
+
+      radius 0 10.0 50.0
+      alpha 0 1.0 1.0
+      rotation 0 ~360 -
+      bounce 0.4
+
+      lifeTime 1500
+    }
+
+    count 50
+    delay 0
+    period 0 - 0
+  }
+}
+```
diff --git a/docs/PlayerVars.md b/docs/PlayerVars.md
new file mode 100644
index 0000000..b2ec8d2
--- /dev/null
+++ b/docs/PlayerVars.md
@@ -0,0 +1,15 @@
+## Player Vars
+
+* `player_hp` - Your current HP
+* `player_maxhp` - The maximum HP for your class
+* `player_credits` - The number of credits/evos you currently hold
+* `player_score` - Your current score on the board
+* `player_attackername` - Name of the player who last attacked you
+* `player_crosshairname` - Name of the player in your crosshairs
+
+## Team Vars
+
+* `team_bp` - Your teams remaining available build points
+* `team_kns` - Number of kills till your team advances to the next stage
+* `team_teamname` - Human readable of your team name (i.e., "humans", "aliens" or "spectator")
+* `team_stage` - Your teams current stage (1, 2 or 3. 0 for spectators)
diff --git a/docs/TrailSystem.md b/docs/TrailSystem.md
new file mode 100644
index 0000000..a8b0257
--- /dev/null
+++ b/docs/TrailSystem.md
@@ -0,0 +1,44 @@
+# Trail System
+ 
+Note that as of Tremulous 1.1.0 there is no way to trigger a trail system with map entities.
+However, a trail system can be attached to a Particle System with the `childTrailSystem` key.
+ 
+Files matching the pattern `scripts/*.trail` are loaded as trail system description files.
+Each `.trail` file can contain an arbitrary number of discrete trail systems, much like a `.shader` file can house many shaders.
+A trail system is declared by a name followed by curly braces within which the functionality of the trail system is defined. For example:
+ 
+```
+   aShinyNewTrailSystem { } 
+```
+ 
+Inside the particle system declaration are placed up to four trail beams. Beams are identified by the keyword beam and curly braces:
+ 
+```
+   aShinyNewTrailSystem
+   {
+ 
+     beam { }
+ 
+     beam { }
+ 
+     thirdPersonOnly
+   } 
+```
+
+The `thirdPersonOnly` keyword may be used to specify that the trail system is not visible from the first person if it relates to that client.
+
+A trail beam describes the appearance of one element of the trail system:
+ 
+- `shader <shader>` - the shader to use to texture this beam.
+- `segments <number>` - the number of quads that make up the beam.
+- `width <frontWidth> <backWidth>` - the width of the beam at the front and back.
+- `alpha <frontAlpha> <backAlpha>` - the alpha of the beam at the front and back.
+- `color { <fr> <fg> <fb> } { <br> <bg> <bb> }` - the color of the beam at the front and back.
+- `segmentTime <time>` - how long a single segment lasts when the trail is only attached at one end.
+- `fadeOutTime <time>` - how long this beam takes to fade away.
+- `textureType [stretch <frontTC> <backTC>][repeat [front|back] <repeatLength>]` - how to texture the beam. `stretch` causes the texture to be stretched from the front to the back using the specified texture coordinates. `repeat` causes the texture to be repeated over a specified length either from the front or the back.
+- `model <model1> <model2> ... <modelN>` - use one of the specified models as the particle. This cannot be used in conjunction with the shader keyword.
+- `modelAnmation <firstFrame> <numFrames> <loopFrames> <fps>sync` - animation parameters to use when model particles are employed.
+- `realLight` - light particles using the lightgrid instead of fullbright.
+- `jitter <magnitude> <period>` - this specifies a random jitter of the position of each beam node by magnitude every period.
+- `jitterAttachments` - if this is specified the end points of the beam are jittered as well as the intervening nodes.
diff --git a/docs/VoiceCommands.md b/docs/VoiceCommands.md
new file mode 100644
index 0000000..71aac37
--- /dev/null
+++ b/docs/VoiceCommands.md
@@ -0,0 +1,40 @@
+# Tremulous Voice Commands
+
+Files matching the pattern `voice/*.voice` are loaded automatically as "voices". 
+Each `.voice` file can contain an arbitrary number of voice commands.
+
+The most important voice is the `default` or `default.voice`.
+Every player by default is assigned the `default` voice. 
+
+A player can change they're voice by setting the `voice` userinfo cvar. 
+
+```
+/setu voice bender
+```
+
+## Voice File Format 
+
+```
+hailking
+{
+  "sound/player/ash/voice/aod-hailking.wav"
+  {
+    team 2
+    class 1
+    weapon 1
+    text "Hail to the king"
+    enthusiasm 0
+  }
+}
+```
+
+- "hailking" is the voice command. (i.e., `/vsay "hailking"`). Note that the maximum command length is 16 characters.
+- "sound/player/ash/voice/aod-hailking.wav" is the 1st "track".
+- "team" corresponds to the `team_t` enum in `bg_public.h`.
+- "class" corresponds to the `class_t` enum in `bg_public.h`.
+- "weapon" corresponds to the `weapon_t` enum in `bg_public.h`.
+- "text" is the text that will appear in chat when the voice command is issued.
+- "enthusiasm" needs to be tested
+
+
+I think "text" is the only *required* field.
diff --git a/docs/opengl2-readme.md b/docs/opengl2-readme.md
new file mode 100644
index 0000000..1b1db20
--- /dev/null
+++ b/docs/opengl2-readme.md
@@ -0,0 +1,604 @@
+# OpenGL2
+<insert ascii art here>
+
+OpenGL2 is an alternate renderer for ioquake3.  It aims to implement modern
+features and technologies into the id tech 3 engine, but without sacrificing
+compatibility with existing Quake 3 mods.
+
+
+-------------------------------------------------------------------------------
+  FEATURES
+-------------------------------------------------------------------------------
+
+  - Compatible with most vanilla Quake 3 mods.
+  - HDR Rendering, and support for HDR lightmaps
+  - Tone mapping and auto-exposure.
+  - Cascaded shadow maps.
+  - Multisample anti-aliasing.
+  - Texture upsampling.
+  - Advanced materials support.
+  - Advanced shading and specular methods.
+  - RGTC and BPTC texture compression support.
+  - Screen-space ambient occlusion.
+
+
+-------------------------------------------------------------------------------
+  INSTALLATION
+-------------------------------------------------------------------------------
+
+For *nix:
+
+1. This should be identical to installing ioq3.  Check their README for more
+   details.
+
+   
+For Win32:
+
+1. Have a Quake 3 install, fully patched.
+
+2. Copy the following files into Quake 3's install directory: 
+     
+     ioquake3.x86.exe
+     renderer_opengl1_x86.dll
+     renderer_opengl2_x86.dll
+     
+   These can be found in build/release-mingw32-x86 after compiling, or bug
+   someone to release binaries.
+  
+
+-------------------------------------------------------------------------------
+  RUNNING
+-------------------------------------------------------------------------------
+
+1. Start ioquake3. (ioquake3.x86.exe on Win32)
+ 
+2. Open the console (the default key is tilde ~) and type 
+`/cl_renderer opengl2` and press enter
+`/vid_restart` then press enter again.
+
+3. Enjoy.
+
+
+-------------------------------------------------------------------------------
+  CVARS
+-------------------------------------------------------------------------------
+
+Cvars for simple rendering features:
+
+* `r_ext_compressed_textures`       - Automatically compress textures.
+                                     0 - No texture compression. (default)
+                                     1 - DXT/RGTC texture compression if
+                                         supported.
+                                     2 - BPTC texture compression if supported.
+
+*  `r_ext_framebuffer_multisample`  - Multisample Anti-aliasing.
+                                     0    - None. (default)
+                                     1-16 - Some.
+                                     17+  - Too much!
+
+*  `r_ssao`                         - Enable screen-space ambient occlusion.
+                                   Currently eats framerate and has some
+                                   visible artifacts.
+                                     0 - No. (default)
+                                     1 - Yes.
+
+Cvars for HDR and tonemapping:
+
+ * `r_hdr`                          - Do scene rendering in a framebuffer with
+                                   high dynamic range.  (Less banding, and
+                                   exposure changes look much better)
+                                     0 - No.
+                                     1 - Yes. (default)
+
+*  `r_cameraExposure`               - Cheat.  Alter brightness, in powers of two.
+                                     -2  - 4x as dark.
+                                     0   - Normal. (default)
+                                     0.5 - Sqrt(2)x as bright.
+                                     2   - 4x as bright.
+
+*  `r_postProcess`                  - Enable post-processing.
+                                     0 - No.
+                                     1 - Yes. (default)
+
+*  `r_toneMap`                      - Enable tone mapping.  Requires 
+                                   r_hdr and r_postProcess.
+                                     0 - No.
+                                     1 - Yes. (default)
+
+*  `r_forceToneMap`                 - Cheat. Override built-in and map tonemap settings and use cvars r_forceToneMapAvg, r_forceToneMapMin, and r_forceToneMapMax.
+                                     0 - No. (default)
+                                     1 - Yes.
+
+*  `r_forceToneMapAvg`              - Cheat.  Map average scene luminance to this
+                                   value, in powers of two.  Requires 
+                                   r_forceToneMap.
+                                    -2.0 - Dark.
+                                    -1.0 - Kinda dark. (default).
+                                     2.0 - Too bright.
+
+*  `r_forceToneMapMin`              - Cheat.  After mapping average, luminance
+                                   below this level is mapped to black.
+                                   Requires r_forceToneMap.
+                                    -5    - Not noticeable.
+                                    -3.25 - Normal. (default)
+                                     0.0  - Too dark.
+
+*  `r_forceToneMapMin`              - Cheat.  After mapping average, luminance
+                                   above this level is mapped to white.
+                                   Requires r_forceToneMap.
+                                    0.0 - Too bright.
+                                    1.0 - Normal. (default).
+                                    2.0 - Washed out.
+
+*  `r_autoExposure`                 - Do automatic exposure based on scene
+                                   brightness.  Hardcoded to -2 to 2 on maps
+                                   that don't specify otherwise.  Requires
+                                   r_hdr, r_postprocess, and r_toneMap.
+                                     0 - No.
+                                     1 - Yes. (default)
+
+*  `r_forceAutoExposure`            - Cheat.  Override built-in and map auto
+                                   exposure settings and use cvars
+                                   r_forceAutoExposureMin and 
+                                   r_forceAutoExposureMax.
+                                     0 - No. (default)
+                                     1 - Yes.
+
+*  `r_forceAutoExposureMin`         - Cheat.  Set minimum exposure to this value,
+                                   in powers of two.  Requires
+                                   r_forceAutoExpsure.
+                                    -3.0 - Dimmer.
+                                    -2.0 - Normal. (default)
+                                    -1.0 - Brighter.
+
+*  `r_forceAutoExposureMax`         - Cheat.  Set maximum exposure to this value,
+                                   in powers of two.  Requires
+                                   r_forceAutoExpsure.
+                                     1.0 - Dimmer.
+                                     2.0 - Normal. (default)
+                                     3.0 - Brighter.
+
+Cvars for advanced material usage:
+
+*  `r_normalMapping`                - Enable normal maps for materials that
+                                   support it.
+                                     0 - No.
+                                     1 - Yes. (default)
+
+*  `r_specularMapping`              - Enable specular maps for materials that
+                                   support it.
+                                     0 - No.
+                                     1 - Yes. (default)
+
+*  `r_deluxeMapping`                - Enable deluxe mapping.  (Map is compiled
+                                   with light directions.)  Even if the map 
+                                   doesn't have deluxe mapping compiled in,
+                                   an approximation based on the lightgrid
+                                   will be used.
+                                     0 - No.
+                                     1 - Yes. (default)
+
+*  `r_parallaxMapping`              - Enable parallax mapping for materials that
+                                   support it.
+                                     0 - No. (default)
+                                     1 - Use parallax occlusion mapping.
+                                     2 - Use relief mapping. (slower)
+
+*  `r_baseSpecular`                 - Set the specular reflectance of materials
+                                   which don't include a specular map or
+                                   use the specularReflectance keyword.
+                                     0    - No.
+                                     0.04 - Realistic. (default)
+                                     1.0  - Ack.
+
+*  `r_baseGloss`                    - Set the glossiness of materials which don't
+                                   include a specular map or use the
+                                   specularExponent keyword.
+                                     0   - Rough.
+                                     0.3 - Default.
+                                     1.0 - Shiny.
+
+*  `r_baseNormalX`                  - Set the scale of the X values from normal
+                                   maps when the normalScale keyword is not
+                                   used.
+                                     -1  - Flip X.
+                                     0   - Ignore X.
+                                     1   - Normal X. (default)
+                                     2   - Double X.
+
+*  `r_baseNormalY`                  - Set the scale of the Y values from normal
+                                   maps when the normalScale keyword is not
+                                   used.
+                                     -1  - Flip Y.
+                                     0   - Ignore Y.
+                                     1   - Normal Y. (default)
+                                     2   - Double Y.
+
+*  `r_baseParallax`                 - Sets the scale of the parallax effect for
+                                   materials when the parallaxDepth keyword
+                                   is not used.
+                                     0    - No depth.
+                                     0.01 - Pretty smooth.
+                                     0.05 - Standard depth. (default)
+                                     0.1  - Looks broken.
+
+*  `r_pbr`                          - Enable physically based rendering.
+                                   Experimental, will not look correct without
+                                   assets meant for it.
+                                     0 - No. (default)
+                                     1 - Yes.
+
+Cvars for image interpolation and generation:
+
+*  `r_imageUpsample`                - Use interpolation to artifically increase
+                                   the resolution of all textures.  Looks good
+                                   in certain circumstances.
+                                     0 - No. (default)
+                                     1 - 2x size.
+                                     2 - 4x size.
+                                     3 - 8x size, etc
+
+*  `r_imageUpsampleMaxSize`         - Maximum texture size when upsampling
+                                   textures.
+                                     1024 - Default.
+                                     2048 - Really nice.
+                                     4096 - Really slow.
+                                     8192 - Crash.
+
+*  `r_imageUpsampleType`            - Type of interpolation when upsampling
+                                   textures.
+                                     0 - None. (probably broken)
+                                     1 - Bad but fast (default,
+                                         FCBI without second derivatives)
+                                     2 - Okay but slow (normal FCBI)
+
+*  `r_genNormalMaps`                - Naively generate normal maps for all
+                                   textures.
+                                     0 - Don't. (default)
+                                     1 - Do.
+
+Cvars for the sunlight and cascaded shadow maps:
+
+*  `r_forceSun`                     - Cheat. Force sunlight and shadows, using sun position from sky material.
+                                     0 - Don't. (default)
+                                     1 - Do.
+                                     2 - Sunrise, sunset.
+
+*  `r_forceSunLightScale`           - Cheat. Scale sun brightness by this factor
+                                   when r_forceSun 1.
+                                     1.0 - Default
+
+*  `r_forceSunAmbientScale`         - Cheat. Scale sun ambient brightness by this factor when r_forceSun 1. 0.5 - Default
+
+*  `r_sunShadows`                   - Enable sunlight and cascaded shadow maps for
+                                   it on maps that support it.
+                                     0 - No.
+                                     1 - Yes. (default)
+
+*  `r_sunlightMode`                 - Specify the method used to add sunlight to
+                                   the scene.
+                                     0 - No.
+                                     1 - Multiply lit areas by light scale, and
+                                         shadowed areas by ambient scale.
+                                         (default)
+                                     2 - Add light.  Looks better, but is slower
+                                         and doesn't integrate well with existing
+                                         maps.
+
+*  `r_shadowFilter`                 - Enable filtering shadows for a smoother
+                                   look.
+                                     0 - No.
+                                     1 - Some. (default)
+                                     2 - Much.
+
+*  `r_shadowMapSize`                - Size of each cascaded shadow map.
+                                     256  - 256x256, ugly, probably shouldn't
+                                             go below this.
+                                     512  - 512x512, passable.
+                                     1024 - 1024x1024, good. (default)
+                                     2048 - 2048x2048, extreme.
+                                     4096 - 4096x4096, indistinguishable from
+                                            2048.
+
+Cvars that you probably don't care about or shouldn't mess with:
+
+*  `r_depthPrepass`                 - Do a depth-only pass before rendering.
+                                   Speeds up rendering in cases where advanced
+                                   features are used.  Required for
+                                   r_sunShadows.
+                                     0 - No.
+                                     1 - Yes. (default)
+
+*  `r_mergeLightmaps`               - Merge the small (128x128) lightmaps into 
+                                   2 or fewer giant (4096x4096) lightmaps.
+                                   Easy speedup.
+                                     0 - Don't.
+                                     1 - Do. (default)
+
+*  `r_shadowCascadeZNear`           - Near plane for shadow cascade frustums.
+                                     4 - Default.
+
+*  `r_shadowCascadeZFar`            - Far plane for shadow cascade frustums.
+                                     3072 - Default.
+
+*  `r_shadowCascadeZBias`           - Z-bias for shadow cascade frustums.
+                                     -256 - Default.
+
+Cvars that have broken bits:
+
+*  `r_dlightMode`                   - Change how dynamic lights look.
+                                     0 - Quake 3 style dlights, fake
+                                         brightening. (default)
+                                     1 - Actual lighting, no shadows.
+                                     2 - Light and shadows. (broken)
+
+*  `r_pshadowDist`                  - Virtual camera distance when creating shadowmaps for projected shadows.  Deprecated.
+
+*  `cg_shadows`                     - Old shadow code.  Deprecated.
+
+
+-------------------------------------------------------------------------------
+  MATERIALS
+-------------------------------------------------------------------------------
+
+OpenGL2 supports .mtr files, which are basically the same as .shader files, and
+are located in the same place, but override existing .shader files if they 
+exist.  This is to allow maps and mods to use the new material features without
+breaking the map when using the old renderer.
+
+Here's an example of a material stored in one, showing off some new features:
+
+    textures/abandon/grass
+    {
+        qer_editorimage textures/abandon/grass.jpg
+        {
+            map textures/abandon/grass3_256_d.jpg
+            rgbgen identity
+        }
+        {
+            stage normalparallaxmap
+            map textures/abandon/grass3_1024_n.png
+            normalScale 1 1
+            parallaxDepth 0.05
+        }
+        {
+            stage specularmap
+            map textures/abandon/grass3_256_s.png
+            specularReflectance 0.12
+            specularExponent 16
+        }
+        {
+            map $lightmap
+            blendfunc GL_DST_COLOR GL_ZERO
+        }
+    }
+
+The first thing to notice is that this is basically the same as old Quake 3 
+shader files.  The next thing to notice are the new keywords.  Here is what 
+they mean:
+
+  `stage <type>`
+    - State how this imagemap will be used by OpenGL2:
+        diffuseMap        - Standard, same as no stage entry
+        normalMap         - Image will be used as a normal map
+        normalParallaxMap - Image will be used as a normal map with 
+                            alpha treated as height for parallax mapping
+        specularMap       - Image will be used as a specular map with
+                            alpha treated as shininess.
+
+  `specularReflectance <value>`
+    - State how metallic this material is.  Metals typically have a high 
+      specular and a low diffuse, so this is typically high for them, and low
+      for other materials, such as plastic.  For typical values for various
+      materials, see http://refractiveindex.info , pick a material, then scroll
+      down to the reflection calculator and look up its reflectance.  Default
+      is 0.04, since most materials aren't metallic.
+  
+  `specularExponent <value>`
+    - State how shiny this material is.  Note that this is modulated by the 
+      alpha channel of the specular map, so if it were set to 16, and the alpha
+      channel of the specular map was set to 0.5, then the shininess would be
+      set to 8.  Default 256.
+
+  `normalScale <x> <y>`
+    - State the X and Y scales of the normal map.  This is useful for increasing
+      or decreasing the "strength" of the normal map, or entering negative values
+      to flip the X and/or Y values.  Default 1 1.
+
+  `parallaxDepth <value>`
+    - State the maximum depth of the parallax map.  This is a fairly sensitive
+      value, and I recommend the default or lower.  Default 0.05.
+
+An important note is that normal and specular maps influence the diffuse map
+declared before them, so materials like this are possible:
+
+    textures/terrain/grass
+    {
+        qer_editorimage textures/terrain/grass.jpg
+
+        {
+            map textures/terrain/rock.jpg
+        }
+        {
+            stage normalparallaxmap
+            map textures/terrain/rock_n.png
+        }
+        {
+            stage specularmap
+            map textures/terrain/rock_s.jpg
+        }
+        {
+            map textures/terrain/grass.jpg
+            blendFunc GL_SRC_ALPHA GL_ONE_MINUS_SRC_ALPHA
+            alphaGen vertex
+        }
+        {
+            stage normalparallaxmap
+            map textures/terrain/grass_n.png
+        }
+        {
+            stage specularmap
+            map textures/terrain/grass_s.png
+            specularReflectance 0.12
+        }
+        {
+            map $lightmap
+            blendfunc GL_DST_COLOR GL_ZERO
+        }
+    }
+    
+Though note due to the complexity of lighting, dynamic light (including
+sunlight with cascaded shadow maps) currently only works 100% on materials like
+this, where the second diffuse map doesn't have its own alpha, and only
+uses vertex alpha.  YMMV.
+
+Another addition to materials is working normal/specular maps on vertex lit
+surfaces.  To enable this, make your material look like this:
+
+    textures/vehicles/car
+    {
+        qer_editorimage textures/vehicles/car.jpg
+
+        {
+            map textures/vehicles/car.jpg
+            rgbGen vertexLit
+        }
+        {
+            stage normalparallaxmap
+            map textures/vehicles/car_n.jpg
+        }
+        {
+            stage specularmap
+            map textures/vehicles/car_s.jpg
+        }
+    }
+
+Note the new keyword, 'vertexLit' after rgbGen.  This is analogous to 
+'rgbGen vertex', except a light direction will be determined from the lightgrid
+and used with the normal and specular maps.  'exactVertexLit' exists as well,
+and is the equivalent for 'exactVertex'.
+
+
+-------------------------------------------------------------------------------
+  DYNAMIC SUNLIGHT AND CASCADED SHADOW MAPS
+-------------------------------------------------------------------------------
+
+This adds a new keyword to sky materials, q3gl2_sun.  The syntax is:
+
+    q3gl2_sun <red> <green> <blue> <intensity> <degrees> <elevation> <shadowScale>
+  
+Note the first six parameters are the same as in q3map_sun or q3map_sunExt,
+and the last two indicate scaling factors for the map brightness and an ambient
+light of the same color as the sun.
+
+There are currently two ways to use this in your own (and other people's) maps.
+
+  1. Create your map as normal, set r_sunlightMode to 1, and add a 
+     'q3gl2_sun' line after your 'q3map_sun' line in your sky material, like
+     so:
+     
+        textures/skies/bluesky
+        {
+          qer_editorimage textures/skies/bluesky.jpg
+
+          surfaceparm nomarks
+          surfaceparm noimpact
+          surfaceparm nolightmap
+          surfaceparm sky
+          q3map_sunExt 240 238 200 100 195 35 3 16
+          q3gl2_sun 240 238 200 50 195 35 0.2
+          q3map_skylight 50 16
+          q3map_lightimage $whiteimage
+
+          skyparms env/bluesky - -
+        }
+
+     The advantages with this method are that your map will continue to work
+     with the old renderer with the sunlight baked into the lightmap, and it
+     can be used with existing maps without recompilation.  The downside is
+     artifacts like doubled shadows and uneven shadow edges.
+     
+  2. Set r_sunlightMode to 2 and use 'q3gl2_sun' instead of 'q3map_sun' or
+     'q3map_sunExt', like so:
+  
+        textures/skies/bluesky
+        {
+          qer_editorimage textures/skies/bluesky.jpg
+
+          surfaceparm nomarks
+          surfaceparm noimpact
+          surfaceparm nolightmap
+          surfaceparm sky
+          q3gl2_sun 240 238 200 50 195 35 0.2
+          q3map_skylight 50 16
+          q3map_lightimage $whiteimage
+
+          skyparms env/bluesky - -
+        }
+
+     The advantages with this method are that you don't get the artifacts that
+     characterize the other method, and your map compiles a lot faster without
+     the sunlight bouncing calculations.  The downsides are that your map will
+     not display properly with the old renderer, and you lose the bounced light
+     that compiling the map with q3map_sun* in it would have.
+
+     
+-------------------------------------------------------------------------------
+  TONE MAPPING AND AUTO EXPOSURE
+-------------------------------------------------------------------------------
+
+This adds a new keyword to sky materials, q3gl2_tonemap.  The syntax is:
+
+    q3gl2_tonemap <toneMapMin> <toneMapAvg> <toneMapMax> <autoExposureMin> <autoExposureMax>
+  
+Each of these settings corresponds to a matching cvar, so you can view and
+adjust the effect before settling on fixed settings.
+
+
+-------------------------------------------------------------------------------
+  THANKS
+-------------------------------------------------------------------------------
+
+I'd like to take this part of the readme to thank the numerous people who
+contributed thoughts, ideas, and whole swaths of code to this project.
+
+  - Id Software, for creating Quake 3 and releasing its source code under a
+    GPL license, without which this project would not be possible.
+
+  - Zachary 'Zakk' Slater, Thilo Schulz, Tim Angus, and the rest of the
+    ioquake3 team and contributors, for improving massively upon the raw Quake
+    3 source, and accepting my and gimhael's modular renderer patch.
+
+  - Robert 'Tr3B' Beckebans and the other contributors to XReaL, for letting me
+    liberally copy code from you. :)
+  
+  - Andrew 'Black Monk' Prosnik, Andrei 'Makro' Drexler, Tomi 'T.T.I.' Isoaho,
+    Richard 'JBravo' Allen, Walter 'Johnny Rocket' Somol, and the rest of the
+    Boomstick Studios, for contributing code, feature requests, and testing.
+    
+  - Yoshiharu Gotanda, Tatsuya Shoji, and the rest of tri-Ace's R&D Department,
+    for creating the tri-Ace shading equations and posting their derivations in
+    simple English.
+    
+  - Matthias 'gimhael' Bentrup, for random ideas and bits of code.
+  
+  - Evan 'megatog615' Goers, for testing, ideas, and bugging me just enough
+    that I'd write documentation. :)
+
+  - The folks at #ioquake3, who don't seem to mind when I suddenly drop a
+    screenshot and insist on talking about it. :)
+
+  - And lots of various other random people, who posted on forums, blogs, and
+    Wikipedia, who helped in small but numerous ways.
+
+If I missed you in this section, feel free to drop me a line and I'll add you.
+
+
+-------------------------------------------------------------------------------
+  CONTACT
+-------------------------------------------------------------------------------
+
+My name is James Canete, and I wrote most of this readme.  Also, a renderer.
+
+If you wish to get in touch with me, try my GMail at use.less01 (you should be
+able to solve this), or look for SmileTheory in #ioquake3 on irc.freenode.net.