OpenGL-Backend.md

@@ -6,11 +6,11 @@ OpenGL backend functions:
 
 - `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.
+`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.
 
 - `void UpdateTexture (GLMipmap_t *TexInfo)`
 
-Updated data from `TexInfo` is uploaded to the GPU. (`TexInfo` is left as the current texture?)
+Updated data from `TexInfo` is uploaded to the GPU. (`TexInfo` is left as the current texture?) The texture will be converted to a format usable by the GPU if required.
 
 - `void DeleteTexture (GLMipmap_t *TexInfo)`
 
@@ -27,36 +27,88 @@ Returns the number of bytes used by the textures uploaded to the GPU.
 ***
 
 - `void SetPalette (RGBA_t *ppal)`
+
+Sets the palette used in textures. All textures are also deleted from the GPU since they still have the old colors.
+
 - `void SetSpecialState (hwdspecialstate_t IdState, INT32 Value)`
+
+Some states are set through this function: model lighting, shader/fixed-function toggle and texture filtering.
+
 - `void GClipRect (INT32 minx, INT32 miny, INT32 maxx, INT32 maxy, float nearclip)`
+
+Sets the viewport coordinates on the screen and also the depth of the near clipping plane.
+
 - `void SetTransform (FTransform *ptransform)`
 
-**
+Sets the current projection and modelview matrices according to the parameters in `ptransform`. (If NULL then some simple UI drawing matrices are set?)
+
+***
 
 - `void SetBlend (FBITFIELD PolyFlags)`
 
+The current rendering state is set according to `PolyFlags`. (Most of the time the state is included into the Draw* calls instead)
+
 ***
 
 - `void ClearBuffer (FBOOLEAN ColorMask, FBOOLEAN DepthMask, FRGBAFloat *ClearColor)`
+
+Clears the color buffer with `ClearColor` if `ColorMask` is set. Clears the depth buffer if `DepthMask` is set. (The PF_Occlude flag is set to `DepthMask`?)
+
 - `void Draw2DLine (F2DCoord *v1, F2DCoord *v2, RGBA_t Color)`
+
+Draws a 2D line to the screen. (Used for drawing the devmode map?)
+
 - `void DrawPolygon (FSurfaceInfo *pSurf, FOutVector *pOutVerts, FUINT iNumPts, FBITFIELD PolyFlags)`
+
+Draws a 3D triangle fan to the screen with properties from `PolyFlags`. The vertex data is in `pOutVerts` and `iNumPts` contains the number of vertices.
+
 - `void DrawIndexedTriangles (FSurfaceInfo *pSurf, FOutVector *pOutVerts, FUINT iNumPts, FBITFIELD PolyFlags, UINT32 *IndexArray)`
 
+Draws 3D triangles to the screen with properties from `PolyFlags`. The vertex data is in `pOutVerts` and `iNumPts` contains the number of vertices. `IndexArray` contains indices into `pOutVerts` that define the triangles. (Used by batched rendering)
+
 ***
 
 - `void RenderSkyDome (gl_sky_t *sky)`
 
+Renders the "Sky dome" using the current texture.
+
 ***
 
 - `void FlushScreenTextures (void)`
+
+Deletes the screen textures.
+
 - `void StartScreenWipe (void)`
+
+Saves the screen used for the starting point of screen wipes.
+
 - `void EndScreenWipe (void)`
+
+Saves the screen used for the destination of screen wipes.
+
 - `void DoScreenWipe (void)`
-- `void DrawIntermissionBG (void)`
+
+Renders one frame of a screen wipe, using the current texture as the fade mask.
+
 - `void MakeScreenTexture (void)`
+
+Saves the screen into a screen texture that can be used with `DrawIntermissionBG` and `PostImgRedraw`.
+
+- `void DrawIntermissionBG (void)`
+
+Draws the saved screen texture on the screen.
+
+- `void PostImgRedraw (float points[SCREENVERTS][SCREENVERTS][2])`
+
+Draws the saved screen texture on the screen with distortion defined by `points`.
+
 - `void MakeScreenFinalTexture (void)`
+
+Saves the screen into a "final" screen texture that can be used with `DrawScreenFinalTexture`.
+
 - `void DrawScreenFinalTexture (int width, int height)`
-- `void PostImgRedraw (float points[SCREENVERTS][SCREENVERTS][2])`
+
+Renders the "final" screen texture on the screen, stretched into dimensions defined by `width` and `height`. (Used for stretching a low resolution to the screen without changing the display resolution)
 
 ***