SYNOPSIS
         # Play some recorded 3D graphics
         bzcat graphics.txt.bz2 | CmdlineGL >/dev/null

         # Experiment from Bash
         source CmdlineGL.lib
         glClearColor '#00FF00'
         glClear GL_COLOR_BUFFER_BIT
         cglSwapBuffers

DESCRIPTION
       CmdlineGL is an interpreter for parsing and executing OpenGL functions, which also simplifies the OpenGL API in several ways to make it more user-friendly.  It comes with
       shell bindings for bash, allowing for experiments right from the terminal (if you have a graphical desktop).  It only covers the functions a beginner would need, and doesn't
       aspire to anything newer than the 1.4 API.  It also provides some basic access to the GLU, SDL_image, and FTGL libraries, for the ability to make useful demos that the raw
       OpenGL API can't provide on its own.

OPTIONS
       -t  Terminate after a zero-length read (EOF)

       --manual-viewport
           Don't automatically reinitialize glViewport after the window has changed size.  This allows the application to control the viewport area.

       --manual-projection
           Don't automatically set up a projection matrix or rescale it after the window changes size.

       -f FIFO
           Create a named pipe at this path, and read from it.  This option is not available on Windows.

       --title TEXT
           Set the title of the window.

       --noevents
           Don't report user input activity on stdout.  (other messages and events will still be printed)

       --showcmds
           Dump a list of all available commands on stdout.

       --showconsts
           Dump a list of all symbolic constants on stdout.  These constants may be given to any command which takes an integer argument.

       -v
       --version
           Print the version and exit.

       -h  Print a brief usage summary

COMMANDS
       All commands take arguments separated by whitespace, in much the same way as a shell would break its arguments.  There is also a quoting mechanism that may be used for any
       type of argument.  If the argument begins with "'" or """, then whitespace (other than newlines) will be included in the argument until the matching quote character.
       Literal newline characters always end the command.  Within the string, "\n" will be converted to newline charachers, and any other character preceeded by a backslash will be
       included as-is, allowing you to escape the quote character and the backslash.

       '#RRGGBB' or '#RRGGBBAA' in their place.  The floating point values ARE affected by any implied divisor in effect (see above) but the HTML color codes are NOT.

   Default Divisors
       cglPushDivisor DIVISOR
           All future floating-point numbers receive this implied "/DIVISOR".  This does not replace a divisor that is manually specified.

           For example,

               cglPushDivisor 100
               glRotate 12/1 100 100 100

           becomes

               glRotated(12, 1, 1, 1);

       cglPopDivisor
           Clear the current default  divisor, returning to whatever default was set before that.  The initial default is 1.

   Render Loop Commands
       These commands control CmdlineGL itself, and assist with setting up a render loop.

       cglEcho ANY_TEXT
           Repeat a string of text on stdout (may be confused for user input events, but maybe that's what you want)

       cglExit
           Cause CmdlineGL to terminate (with error code 0)

       cglQuit
           Alias for cglExit

       cglGetTime
           Return the number of milliseconds since start of the program.

       cglSleep DELAY_MS
           Sleep for a number of milliseconds from when the command is received

       cglSync UNTIL_TIME_MS
           Sleep until the specified time, measured as milliseconds from start of program.

       cglSwapBuffers
           Swap front and back buffer, showing the frame you were drawing and beginning a new frame.  (you still need to call glClear yourself) If a window resize is pending, it
           will be performed at this point.

       glClear ENUM [ENUM...]
           Clear one or more aspects of the frame buffer.  Normally the constants are combined as a bit mask, but for this protocol they are just given as multiple arguments.

       glClearColor COLOR | R G B [A]
           Specify what color to use when clearing the frame buffer.  You may use a single HTML-style color code, or individual floating point components.  See "Colors"

       glClearDepth DEPTH
           Select what depth to assign when clearing the depth buffer.

           Control how new pixel colors are blended into the existing frame buffer.  SOURCE_FACTOR and DEST_FACTOR each an enum constant describing the equation used.

       glShadeModel GL_SMOOTH|GL_FLAT
           Control whether lighting is calculated per-pixel or per-vertex.

   GL Lighting Setup Commands
       These settings affect the overall lighting calculation

       glColorMaterial FACE MODE
           Set one or both faces of polygons to use the current color as one or more color components of the "material" in the lighting equation.  FACE is: GL_FRONT, GL_BACK,
           GL_FRONT_AND_BACK, and MODE is: GL_EMISSION, GL_AMBIENT, GL_DIFFUSE, GL_SPECULAR, GL_AMBIENT_AND_DIFFUSE.

       glFog PNAME [PARAMS...]
           Apply a fog setting.  PNAME selects which value to change, and PARAMS depends on PNAME.  If PNAME is a color, you may use HTML color notation.  See "Colors".

       glLightModel PNAME [PARAMS...]
           Apply a lighting setting.  PNAME is the setting to change, and PARAMS depend on PNAME.  If the PARAMS are a color, you may use HTML color notation.  See "Colors".

       glLight LIGHT PNAME [PARAMS...]
           Apply a per-light setting.  LIGHT is the enum or number of the light to be altered, and PNAME selects which parameter to change.  PARAMS depends on PNAME. If PARAMS is a
           color, you may use HTML color notation.  See "Colors".

   Geometry Plotting Commands
       glBegin MODE
           Begin plotting points of geometry type MODE.

       glEnd
           Stop plotting points.

       glVertex X Y [Z] [w]
           Plot a vertex at (X,Y), (X,Y,Z), or (X,Y,Z,W)

       glNormal X Y Z
           Specify the Normal vector for the next Vertex.

       glTexCoord S T [R] [Q]
           Specify texture coordinates to use for the next Vertex.

       glColor COLORCODE | R G B [A]
           Specify a color value to be used in the calculation of the color for the next vertex.  The color may be specified in HTML notation or as separate components.  See
           "Colors".

       glMaterial FACE PNAME [PARAMS...]
           Apply a Material property that affects how future vertices will be affected by various lighting parameters.  See OpenGL documentation for details, but FACE and PNAME
           should be symbolic constants, and PARAMS depends on PNAME.  If PARAMS are a color, you may use HTML notation.  See "Colors".

   Texture Commands
       glBindTextue TARGET TEXTURENAME
           Select the current texture object for purpose TARGET.  (TARGET is usually GL_TEXTURE_2D)

       glTexParameter TARGET PNAME [PARAMS...]
           Change an attribute of the texture object currently bount to TARGET.  PNAME is the name of the attribute, and PARAMS depend on PNAME.  If PARAMS is a color, you may use
           Restore the previous saved matrix.

       glLoadIdentity
           Overwrite the current matrix with a matrix that has no effect on vertices.

       glLoadMatrix I1 I2 I3 I4 J1 J2 J3 J4 K1 K2 K3 K4 L1 L2 L3 L4
           Directly overwrite the matrix with 16 values.

       glMultMatrix I1 I2 I3 I4 J1 J2 J3 J4 K1 K2 K3 K4 L1 L2 L3 L4
           Multiply the current matrix by this specified matrix

       glScale SCALE [SCALE_Y [SCALE_Z]]
           When given one argument, scale the X, Y, and Z axis by the specified value.  When given two arguments, scale X and Y, leaving Z unchanged.  When given three
           arguments,scale X, Y, and Z.

       glTranslate X Y [Z]
           Apply a translation to the matrix.  The Z coordinate is optional and defaults to 0.

       glRotate DEGREES X Y Z
           Rotate DEGREES around the axis defined by (X,Y,Z)

       gluLookAt EYE_X EYE_Y EYE_Z CENTER_X CENTER_Y CENTER_Z UP_X UP_Y UP_Z
           Change the current matrix to "look at" CENTER from EYE.

       glViewport X Y WIDTH HEIGHT
           Define the 2D region of the screen to be rendered by the current matrix.

       glOrtho
           Set up a projection matrix that maps the given coordinate values to the edges of the viewport, and sets the near and far clipping plane.

       glFrustum
           Set up a projection matrix where the given coordinates are the edges of the screen at the near clipping plane, and scale proportionally as the Z coordinate gets farther
           from the near plane.

   Display List Commands
       glNewList LISTNAME MODE
           Begin recording a new display list, either creating or overwriting LISTNAME.  MODE can either be GL_COMPILE or GL_COMPILE_AND_EXECUTE.  LISTNAME can be any string of
           text and is not limited to OpenGL's integer "names".

       glEndList
           End the recording.

       glCallList LISTNAME
           Replay a recorded list.

   Quadric Commands
       gluNewQuadric NAME
           Quadric objects must be created before they can be used.

       gluQuadricDrawStyle NAME DRAW
           Set the DRAW style of the NAMEd quadric: GLU_FILL, GLU_LINE, GLU_SILHOUETTE, GLU_POINT

           Draw a sphere of RADIUS around the origin, composed of n=SLICES polygons radially around the Z axis and n=STACKS polygons along the z axis.

       gluDisk NAME INNER OUTER SLICES LOOPS
           Draw a flat disk ("inner = 0") or donought ("<inner " 0>>) around the Z axis with the given OUTER radius and INNER radius, composed of SLICES polygons radially around Z
           and LOOPS concentric rings.

       gluPartialDisk NAME INNER OUTER SLICES LOOPS START SWEEP
           Same as above, but only from START degrees around Z axis until and SWEEP degrees afterward.

   FTGL Font Functions
       These functions come from the FTGL library.  They can open any font file that the FreeType library can open.  A symbolic name takes the place of FTGL's "FTfont*" pointer.
       You must call one of the Create methods to initialize a symbolic name (and it must succeed).

       ftglCreateBitmapFont NAME "FONT_FILE_PATH"
           Create a 2-color font that renders directly to the framebuffer in 2D.

       ftglCreatePixmapFont NAME "FONT_FILE_PATH"
           Create a 256-color-grayscale font that renders directly to the framebuffer in 2D.

       ftglCreateTextureFont NAME "FONT_FILE_PATH"
           Create a font that renders each glyph into a texture, so that a small set of textures can supply all your rendering needs.

       ftglCreateBufferFont NAME "FONT_FILE_PATH"
           Create a texture-based font that renders each line of text into its own texture, so that common phrases can be drawn as a single polygon.

       ftglCreateExtrudeFont NAME "FONT_FILE_PATH"
           Create 3D models to represent each glyph extruded as a solid object.

       ftglCreateOutlineFont NAME "FONT_FILE_PATH"
           Create 2D model of GL lines that trace the outline of each glyph.

       ftglCreatePolygonFont NAME "FONT_FILE_PATH"
           Create each glyph as a flat 2D mesh of polygons.

       ftglDestroyFont NAME
           Free resources and un-define the symbolic NAME.

       ftglSetFontCharMap NAME CMAP_CODE
           Set the charmap to one of the codes known by the FreeType library.

       ftglSetFontFaceSize NAME SIZE
           For texture and raster fonts, render each glyph at SIZE pixels.  For Vector fonts, render each glyph at SIZE logical units.

       ftglSetFontDepth NAME SIZE
           For extruded fonts, set the depth to SIZE units.

       ftglSetFontOutset NAME FRONT BACK
           For extruded fonts.

       ftglRenderFont NAME TEXT FLAGS[...]
           Renter TEXT using NAMEd font, affected by FLAGS.  In the C API, the flags are combined, but in this command each flag is given as another parameter.  Flags are:
           FTGL_RENDER_FRONT, FTGL_RENDER_BACK, FTGL_RENDER_SIDE, FTGL_RENDER_ALL, FTGL_ALIGN_LEFT, FTGL_ALIGN_RIGHT, FTGL_ALIGN_CENTER, FTGL_ALIGN_JUSTIFY.

           spin_rate=70  # Degree per second
           R=0           # current rotation
           T=0           # "game-time", in milliseconds

           # Initialize CmdlineGL for rendering only (no input or feedback)
           source CmdlineGL.lib
           CmdlineGL_Start ro
           glEnable GL_NORMALIZE GL_DEPTH_TEST GL_CULL_FACE
           glShadeModel GL_SMOOTH

           # Load font file and configure font rendering parameters
           ftglCreateExtrudeFont font1 "$font"
           ftglSetFontFaceSize   font1 72 72
           ftglSetFontDepth      font1 20

           # Prepare the graphics in a display list.  Need to call once first since
           # ftgl creates its own display lists, then again to capture those in the
           # second display list.
           ftglRenderFont font1 "$text" FTGL_ALIGN_CENTER FTGL_RENDER_ALL
           glNewList mytext GL_COMPILE
           glTranslate -$(( ${#text}/2 * 40 )) -36 10  # flaky guess at string mid
           ftglRenderFont font1 "$text" FTGL_RENDER_ALL
           glEndList

           # set up lighting (otherwise no change as it rotates)
           glEnable GL_LIGHTING GL_LIGHT0
           glLight GL_LIGHT0 GL_AMBIENT .8 .8 .8 0
           glLight GL_LIGHT0 GL_DIFFUSE 1 .8 .8 0
           glLight GL_LIGHT0 GL_SPECULAR .8 .8 .8 0
           glLight GL_LIGHT0 GL_POSITION 10 10 10 1

           while true; do
               glClear GL_COLOR_BUFFER_BIT GL_DEPTH_BUFFER_BIT
               glLoadIdentity
               glRotate $((R+=spin_rate))/60 0 1 0  # assuming 60fps
               glScale 10/$((40 * ${#text} / 2))    # flaky guess at window width
               glCallList mytext
               glFlush
               cglSwapBuffers
               cglSync $((T+=16)) # blindly assume we can maintain 60fps
           done

       More advanced timing and handling of user input can be seen in ModelViewer.sh, usage of Quadrics for quick rendering of solids can be seen in Robot.sh, and direct
       manipulation of the modelview matrix as a coordinate system can be seen in FlightSim.sh

BUGS
       Please report bugs in the issue tracker at <http://github.com/nrdvana/CmdlineGL>

SEE ALSO
       Homepage       <http://nrdvana.net/cmdlinegl>