Improve documentation of the GL port

gl/README.md

@@ -8,8 +8,27 @@ SDL2 port, but uses OpenGL for character drawing.
 Building
 --------
 
-- Currently, this port requires using the included CMakeLists.txt for building.
-- Depends on SDL2 and SDL2_ttf
+- Depends on both SDL2 and SDL2_ttf, always.
+
+- On \*nix (including Linux and Mac OS X), run "make" in the gl
+  directory. There is no configure script (yet?) for this port. This
+  assumes a working sdl-config, and GNU make. It builds the library
+  pdcurses.a (or pdcurses.so/pdcurses.dylib with DLL=Y).
+
+- With MinGW, edit the Makefile to point to the appropriate include and
+  library paths, and then run "mingw32-make".
+
+- With MSVC, edit Makefile.vc if needed, and do "nmake -f Makefile.vc".
+
+- The makefile recognizes the optional PDCURSES_SRCDIR environment variable,
+  and the option "DEBUG=Y", as with the console ports. "WIDE=Y" builds a
+  version that uses 32-bit Unicode characters. "UTF8=Y" makes PDCurses ignore
+  the system locale, and treat all narrow-character strings as UTF-8; this
+  option has no effect unless WIDE=Y is also set. You can specify "DLL=Y" to
+  build a dynamic rather than static library. The dynamic library is called
+  pdcurses.dll, pdcurses.so, or pdcurses.dylib on Windows, Linux, or Mac OS X
+  respectively.  And on all platforms, add the target "demos" to build the
+  sample programs.
 
 
 Usage
@@ -23,6 +42,14 @@ or OpenGL stuff behind it's back, as that would break our assumptions of the
 OpenGL state machine. However, you can change the SDL window parameters safely
 (size, fullscreen).
 
+The font can be set via the environment variable PDC_FONT. If defined, it must
+point to a TrueType font. Only true monospaced fonts work well. The font can be
+set at compile time via PDC_FONT_PATH, and/or at runtime via pdc_ttffont. The
+environment variable PDC_FONT_SIZE is also available to control the font size
+(also as a compile-time define, and at runtime as pdc_font_size.) The character
+mapping for chtypes is UTF-32. However, with SDL2_ttf versions older than
+2.0.18, only the Basic Multilingual Plane characters are available.
+
 The default font (if not redefined) is based on the OS:
 
 - Windows: C:/Windows/Fonts/consola.ttf
@@ -49,6 +76,37 @@ The default screen size is 80x25 characters (whatever size they may be),
 but you can override this via the environment variables PDC_COLS and/or
 PDC_LINES.
 
+You can change what the window scaling does with these two variables:
+```
+PDCEX int pdc_resize_mode;
+PDCEX int pdc_interpolation_mode;
+```
+
+`pdc_resize_mode` has four options: `PDC_GL_RESIZE_NORMAL` makes resizing change
+the number of visible characters on screen. `PDC_GL_RESIZE_STRETCH` stretches
+the existing LINES & COLS to fit the window size. `PDC_GL_RESIZE_SCALE` does
+the same, but keeps aspect ratio by adding black bars. `PDC_GL_RESIZE_INTEGER`
+changes scaling in integer steps.
+
+`pdc_interpolation_mode` can be used to change between nearest-neighbor
+(`PDC_GL_INTERPOLATE_NEAREST`) and bilinear filtering
+(`PDC_GL_INTERPOLATE_BILINEAR`) when the frame is scaled larger than its native
+size. Bilinear filtering is slightly slower and appears soft, while
+nearest-neighbor is faster and "pixelated".
+
+Integration with SDL
+--------------------
+
+Unlike the SDL port, you shouldn't muck around too much with SDL functions.
+SDL_Surfaces can't be used for rendering here. But there's a couple of things
+you can still safely do.
+
+```
+PDCEX SDL_Window *pdc_window;
+```
+
+You can programmatically change the size of the window with
+`SDL_SetWindowSize()` and `SDL_SetWindowFullscreen()`.
 
 Interaction with stdio
 ----------------------
@@ -62,7 +120,7 @@ and stderr may be redirected to files.
 Distribution Status
 -------------------
 
-All files in this directory are released to the public domain.
+The files in this directory are released to the public domain.
 
 
 Acknowledgements

gl/glfuncs.h

@@ -1,9 +1,17 @@
-/* This header declares the internally-used OpenGL stuff.
+/* This header declares the internally-used OpenGL stuff. OpenGL is a bit
+ * annoying in that its functions have to be loaded during runtime; we use
+ * SDL_GL_GetProcAddress for that. GLEW or Glad could be used for this as well,
+ * but it's hard to justify adding such large dependencies for this kind of
+ * minimal OpenGL usage.
  */
 #include "pdcgl.h"
 #include <SDL_opengl.h>
 #include <SDL_opengl_glext.h>
 
+/* We can't just declare our own function pointers with the real function
+ * names, since those prototypes already come from SDL_opengl.h :/ But what we
+ * can do, is use defines to make the OpenGL functions look like they should :)
+ */
 #define glCreateProgram pdc_glCreateProgram
 #define glGenVertexArrays pdc_glGenVertexArrays
 #define glBindVertexArray pdc_glBindVertexArray