OpenGL-Backend.md

@@ -4,6 +4,10 @@ OpenGL backend functions:
 
 - `void Init (void)`
 
+Loads the OpenGL library. Some of the internal gl function pointers are loaded here and the rest are loaded in `OglSdlSurface`. TODO why?
+
+***
+
 - `void SetTexture (GLMipmap_t *TexInfo)`
 
 `TexInfo` becomes the current texture, used in future draw calls. If NULL, then a white texture is used. The texture will be uploaded to the GPU if it has not been yet. The texture will be converted to a format usable by the GPU if required.
@@ -56,7 +60,7 @@ Clears the color buffer with `ClearColor` if `ColorMask` is set. Clears the dept
 
 - `void Draw2DLine (F2DCoord *v1, F2DCoord *v2, RGBA_t Color)`
 
-Draws a 2D line to the screen. (Used for drawing the devmode map?)
+Draws a 2D line to the screen. (Used for drawing the devmode map)
 
 - `void DrawPolygon (FSurfaceInfo *pSurf, FOutVector *pOutVerts, FUINT iNumPts, FBITFIELD PolyFlags)`
 
@@ -113,17 +117,43 @@ Renders the "final" screen texture on the screen, stretched into dimensions defi
 ***
 
 - `boolean CompileShaders (void)`
+
+Compiles the shaders so they can be used in rendering. Needs to be called before using shaders for the first time. Any custom shaders set with `LoadCustomShader` will be compiled too. The function can be called again to remove old compiled shaders and re-compile them.
+
+If the function returns false, it means that the hardware does not support shaders or that the code has been compiled without shader support. In either case, the user of the backend needs to take the lack of shader capability into account. This is currently the method that will reveal if shaders can be used or not for the user of the backend.
+
 - `void CleanShaders (void)`
+
+Removes custom shader source code from memory. Next call to `CompileShaders` will not have them. Call `CompileShaders` for the changes to come into effect.
+
+- `void LoadCustomShader (int number, char *code, size_t size, boolean isfragment)`
+
+Puts a custom shader into slot `number`. (See SHADER_* in hw_defs.h for slots.) The source code is in `code` and the length of the source code string is defined in `size`. `isfragment` is true for fragment shaders and false for vertex shaders. Call `CompileShaders` for the changes to come into effect.
+
 - `void SetShader (int type)`
+
+If shaders are enabled, the currently used shader is set to `type`.
+
 - `void UnSetShader (void)`
+
+The fixed function pipeline is used for draw calls instead of shaders. (used for most/all non-3d stuff?)
+
 - `void SetShaderInfo (hwdshaderinfo_t info, INT32 value)`
-- `void LoadCustomShader (int number, char *code, size_t size, boolean isfragment)`
+
+Sets certain values that are given to shader uniform variables. (currently only level time)
 
 ***
 
 - `void DrawModel (model_t *model, INT32 frameIndex, INT32 duration, INT32 tics, INT32 nextFrameIndex, FTransform *pos, float scale, UINT8 flipped, UINT8 hflipped, FSurfaceInfo *Surface)`
+
+`CreateModelVBOs` needs to be called for `model` before drawing it for the first time.
+
 - `void CreateModelVBOs (model_t *model)`
 
+Creates vertex buffer objects for `model` so it can be rendered.
+
 ***
 
 - `void ReadRect (INT32 x, INT32 y, INT32 width, INT32 height, INT32 dst_stride, UINT16 *dst_data)`
+
+Reads a rectangle from the framebuffer. TODO: `dst_stride` and output format?