Document the algorithm used for generating the 1D shadow maps

src/gl/dynlights/gl_shadowmap.cpp

@@ -32,6 +32,39 @@
 #include "gl/shaders/gl_shadowmapshader.h"
 #include "r_state.h"
 
+/*
+	The 1D shadow maps are stored in a 1024x1024 texture as float depth values (R32F).
+
+	Each line in the texture is assigned to a single light. For example, to grab depth values for light 20
+	the fragment shader (main.fp) needs to sample from row 20. That is, the V texture coordinate needs
+	to be 20.5/1024.
+
+	mLightToShadowmap is a hash map storing which line each ADynamicLight is assigned to. The public
+	ShadowMapIndex function allows the main rendering to find the index and upload that along with the
+	normal light data. From there, the main.fp shader can sample from the shadow map texture, which
+	is currently always bound to texture unit 16.
+
+	The texel row for each light is split into four parts. One for each direction, like a cube texture,
+	but then only in 2D where this reduces itself to a square. When main.fp samples from the shadow map
+	it first decides in which direction the fragment is (relative to the light), like cubemap sampling does
+	for 3D, but once again just for the 2D case.
+	
+	Texels 0-255 is Y positive, 256-511 is X positive, 512-767 is Y negative and 768-1023 is X negative.
+
+	Generating the shadow map itself is done by FShadowMap::Update(). The shadow map texture's FBO is
+	bound and then a screen quad is drawn to make a fragment shader cover all texels. For each fragment
+	it shoots a ray and collects the distance to what it hit.
+	
+	The shadowmap.fp shader knows which light and texel it is processing by mapping gl_FragCoord.y back
+	to the light index, and it knows which direction to ray trace by looking at gl_FragCoord.x. For
+	example, if gl_FragCoord.y is 20.5, then it knows its processing light 20, and if gl_FragCoord.x is
+	127.5, then it knows we are shooting straight ahead for the Y positive direction.
+
+	Ray testing is done by uploading two GPU storage buffers - one holding AABB tree nodes, and one with
+	the line segments at the leaf nodes of the tree. The fragment shader then performs a test same way
+	as on the CPU, except everything uses indexes as pointers are not allowed in GLSL.
+*/
+
 void FShadowMap::Update()
 {
 	UploadAABBTree();