SGI Developer Toolbox 6.1/SGI Developer Toolbox 6.1 - Disc 4.iso/src/exampleCode/opengl/xlib/README

Text File | 1994-08-02 | 23.5 KB | 675 lines

             ~4Dgifts/toolbox/src/exampleCode/opengl/xlib README


                THIS CODE RUNS/COMPILES ON 5.1 Irix OR LATER
                THIS CODE WILL NOT RUN ON LESS THAN 5.1 Irix



    This is a collection of sample OpenGL programs for those who prefer
    going the stone-knives-and-bearskins route with only Xlib rather than
    working with toolkits like Xt, Motif or the OpenGL's own libGLw.a (the
    motif widget) libtk.a and/or libaux.a.

    Note that in the siggraphCD subtree there are libtk/libaux versions of
    some of the straight Xlib-based programs living here, located in
    ../siggraphCD/src/examples/samples.  There are people who prefer or
    need to work from the ground up.  Thus the justification for the
    existence of this, perhaps somewhat paltry, but better-than-nothing,
    "ground-floor" examples directory.

    Of special note in v4.1 are tprim_pup and zrgb_pup both of which implement
    a pure-Xlib version of the "IrisGL-type" pup menu capability making use of
    the {pup.c,pup.h} files.  This code was ripped out of the IrixGL-X
    implementation and munged around a little, so it is exactly dopup,
    addtopup, etc. (however there *is* an extra screen & display argument to
    make it work with X).  The code is not pretty, but it does work and now
    can offer people an alternative to having to go with a toolbox on top of
    Xlib just to get popup menus included.  See README.pup for a refresher set
    of descriptions lifted from the pup menu man pages on
       long newpup(Display *dpy, int screen)
       void addtopup(long pup, char *str, ...)
       long defpup(Display *dpy, int screen, char *str, ...)
       long dopup(long menu)
       void freepup(long menu)
       void setpup(long menu, long item, unsigned long arg)
    as they now can be used in OpenGL-Xlib programs.

    ++> indicates new as of version 4.1
    =+> indicates enhanced as of version 4.1



++> aaline:     demonstrates anti-aliaed line, aliasing can be toggled, the
        line can be rotated, its width can be increased/decreased,
        and stippling can be toggled.
        RGBA, singlebuffer
      cmd line options:
       -c       color index mode
      keys:
        O/o     rotate counter-clockwise
        P/p     rotate clockwise
    Q/q     decrement line's width
    W/w     increment line's width
    A/a     toggle anti-aliasing on/off (initial state: anti-aliasing ON)
    L/l     toggle line stipple on/off (initial state: line-stippling OFF)
    Esc     quit


==> bufferogl:  demonstrates switching between single and double -buffer
        mode.  A useful technique for bitplane-limited machines like
        Indigo starter or the 8-bit Personal IRIS or Indy.  employs
        materials/lighting, zbuffer, single/double -buffer, drawing
        spheres.
    RGBA, singlebuffer, doublebuffer, depthbuffer
      keys:
    LEFTMOUSE    switch to single buffer
    MIDDLEMOUSE  switch to double buffer
    RIGHTMOUSE   animate to visualize the current buffer mode
        Esx     quit


==> cull: shows the effect of culling on an ordered set of triangles
      representing all the permutations of vertex ordering for both
      smooth and flat shading
    RGBA, singlebuffer
      keys:
        0          select front face
    1          select back face
    2          select both front and back faces
    p/P        display polygon using points
    l/L        display polygon using lines
    f/F        display pologon as filled
    d/D        toggle cw/ccw interpretation of front face
    c/C        cull current face
    e/E    toggle enable/disable culling
    Esc    quit


==> cylinder2:  demonstrates creating a GL window with an overlay window
        on top of it occupying the same position.
    RGBA, doublebuffer, alphablending, depthbuffer
      keys:
    LEFTMOUSE  drag/move cylinder
    w       toggles an overlay wire frame on cylinder
    t       toggles scene transparency
    KeyBd   quit


==> dnbogl: imitation of the Dial Button Box Confidence Test in the "System"
        toolchest.  two windows, 1 single 1 double -buffered, side-by-side.
    CI, singlebuffer and doublebuffer
      keys:
    Dial Buttons  press to highlight representation in GL window
        Dial Dials    turn to highlight representation in GL window
    LEFTMOUSE     quit


==> font:  demonstrates a replaced for the IRIS GL charstr() function
       RGBA, singlebuffer
      keys:
    KeyBd   quit


++> fonts:  demonstrates rendering multiple fonts, one-at-a-time.
       RGBA, doublebuffer
      keys:
    f       step thru 4 different fonts
    KeyBd   quit


==> glxvis: provide text of visuals information for machine being run on


==> intro:  standalone program listing from the glXintro man page
    RGBA, singlebuffer


==> iobouce:  animated ball speeds up by pressing the mouse buttons
    CI, doublebuffer
      keys:
        RIGHTMOUSE   stops disk
    MIDDLEMOUSE  increases y velocity
    LEFTMOUSE    increases x velocity
    Esc    quit


++> jackobox: This program creates a nest of seven single-buffered RGB windows.
              A single OpenGL rendering context is bound to each window in turn
          and a clear is done to the window (each window cleared to a
          different color).  Finally, this message is drawn using X.  If
          you can't read the message, the program didn't work.
       RGBA, singlebuffer
      keys:
     SPACEBAR:  steps thru a "colorbase" scheme that changes each time
            in/for each window
     Esc  quit


++> multcx:  creates two GLX contexts, and alternately draws into the same
         window with them.  written to test functioning of multiple
         contexts drawing to same window w/depth buffer
       RGBA, depthbuffer
      keys:
     c/C  copy contexts
     r/R  force "redraw" of the window
     Esc  quit


==> overlay:  draws boxes in the overlay planes with a bouncing ball
              underneath in the GL window.
        CI, doublebuffer, overlay
      keys:
     b    toggles bell
     Esc  quit


++> pixmap:   draws a pixmap
        RGBA or CI, singlebuffer
      cmd line options:
       -c    Run in color index mode
      keys:
     c
     p
     w
     Esc  quit


++> pixtest:  takes an image file as input as performs MANY pixel operations
          via keyboard keys.
        RGB, doublebuffer, depthbuffer, stencilbuffer
      cmd line options:
       pixtest [-s] [-geometry WxH+X+Y] <filename>
       -c    Run in color index mode
       -s       Run in singlebuffer mode [default is doublebuffer]
       -geometry WxH+X+Y   Specify window size and location
      keys:
     i/I  initialize window to white background
     x    increment x size of image
     X    decrement x size of image
     y    increment y size of image
     Y    decrement y size of image
     LEFTARROW  move entire image left
     RIGHTARROW move entire image right
     UPARROW    move entire image up
     DOWNARROW  move entire image down
     b/B  toggle pixel transfer mode bias with
          GL_RED/GREEN/BLUE_SCALE/BIAS for glPixelTransferf
     m/M  toggle pixel transfer mode mapping with
          GL_MAP_COLOR for glPixelTransferf
              (from the man page:  each color component is scaled by the size
           of the corresponding color-to-color map, then replaced by the
           contents of that map indexed by the scaled component.)
     s/S  toggle glScissor mode to just encompass the image size and then
          back to the full window size
         r/R  change "Test" being performed: DRAW, COPY, or READ pixels, which
          consequently invokes glDrawPixels, glCopyPixels, or glReadPixels
          respectively.
         t/T  change "Type" of data being defined for glDraw/ReadPixels, or
          glStencilFunc to run thru the cycle GL_UNSIGNED_BYTE, GL_BYTE,
          GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, GL_FLOAT,
          GL_BITMAP, GL_UNSIGNED_BYTE.
     f/F  change "Format" of data being defined for a MASS of functions
              to run thru the cycle of GL_RGB, GL_RGBA, GL_DEPTH_COMPONENT,
          GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_RED, GL_GREEN, GL_BLUE,
          GL_ALPHA, GL_LUMINANCE, GL_LUMINANCE_ALPHA, GL_RGB.
     a/A  toggle alpha test on/off for glAlphaFunc(GL_GREATER, 0.5).
     e/E  swap bytes from
        glPixelStorei(GL_UNPACK_SWAP_BYTES, GL_TRUE);
        glPixelStorei(GL_UNPACK_LSB_FIRST, GL_FALSE);
        glPixelStorei(GL_PACK_SWAP_BYTES, GL_TRUE);
        glPixelStorei(GL_PACK_LSB_FIRST, GL_FALSE);
              to
        glPixelStorei(GL_UNPACK_SWAP_BYTES, GL_FALSE);
        glPixelStorei(GL_UNPACK_LSB_FIRST, GL_TRUE);
        glPixelStorei(GL_PACK_SWAP_BYTES, GL_FALSE);
        glPixelStorei(GL_PACK_LSB_FIRST, GL_TRUE);
     w/W  modify the alignment shift from 1 to 2 to 3 bytes back to
          default 4-byte alignment with stdout messages of
            (1*), Type: GL_UNSIGNED_BYTE, Format: GL_RGBA
            (2*), Type: GL_UNSIGNED_BYTE, Format: GL_RGBA
            (3*), Type: GL_UNSIGNED_BYTE, Format: GL_RGBA
            Type: GL_UNSIGNED_BYTE, Format: GL_RGBA
     d/D  toggle between immediate or display list modes
     Esc  quit


++> readwrite:   perform read/write tests of glDrawPixels
        One should see nothing change with any of these tests if opengl
    is functioning properly (i.e. simply taking a black polygon with an
    alpha value of zero and adding it to the screen should not change).
        RGBA or CI, singlebuffer or doublebuffer, depthbuffer, stencilbuffer
      cmd line options:
       -c      run in color index mode
       -s      run in singlebuffer mode
       -i      turn direct rendering off--go thru the X server
      keys:
     p/P  pixels test
     b/B  blend test
         d/D  enable/disable dithering
     r/R  redraw
     Esc  quit


++> scube:  draw a lit spining cube and its shadow
        RGBA && dblbuffer or RGB && sglbuffer or CI && (dblbuffer||snglbuffer),
        depthbuffer
      cmd line options:
       -geometry  window size and location
       -c      toggle color index mode
       -l      toggle lighting
       -f      toggle fog
       -db     toggle double buffering
       -logo   toggle sgi logo for the shadow pattern
       -quads  toggle use of GL_QUADS to draw the checkerboard
      keys:
     l/L  enable/disable lighting
     f/F  enable/disable fog
     1    when fog is enabled, set glFogf(GL_FOG_MODE, GL_LINEAR)
     2    when fog is enabled, set glFogf(GL_FOG_MODE, GL_EXP)
     3    when fog is enabled, set glFogf(GL_FOG_MODE, GL_EXP2)
     Esc  quit


==> skeeter:  illustrates overlay/popup plane usage, display lists, two-sided
              lighting, alpha blending transparency.
        RGBA, doublebuffer, alphablending, depthbuffer
      keys:
         LEFTMOUSE  drags the `skeeter' around in the overlay/popup planes
         SPACEBAR   CD drops from the sky
         Esc        quit


==> sphere:  draws a wire-framed sphere and exits on any keypress
    RGBA, singlebuffer
      keys:
    KeyBd   quit


++> spots:  demonstrate implementation of spotlights "swinging about"
        RGBA, doublebuffer
      cmd line options:
       -geometry Specify size and position WxH+X+Y
       -lm       Toggle lighting(SPECULAR and AMBIENT are/not same
      keys:
         Esc        quit


==> tabletogl: "line drawing" tablet demo
    CI, singlebuffer
      keys:
    tablet pen or puck  draws lines as long as stylus is pressed down
    LEFTMOUSE           quit


++> tcilight:  test color index lighting
        CI, doublebuffer, depthbuffer
      cmd line options:
       -geometry (Specify size and position:) WxH+X+Y
      keys:
         o/O  toggle between checkboard or cylinder object
         l/L  toggle lighting
         t/T  toggle two-sided lighting
         k/K  toggle local light
         v/V  toggle local viewer
         p/P  toggle spotlight
         n/N  toggle attenuation
         a    decrease ambient color by changing ambient index
         A    increase ambient color by changing ambient index
         d    decrease diffuse color by changing diffuse index
         D    increase diffuse color by changing diffuse index
         s    decrease specular color by changing specular index
         S    increase specular color by changing specular index
         MOUSEBUTTON  when pressed rotate object about its center
         Esc        quit


==> tdepth: uses the depth buffer test
    RGBA, singlebuffer, depthbuffer
      keys:
    a/A       toggles aliasing/antialiasing
    s/S       toggles stipple/no stipple
    Esc     quit


++> tesstest:  glu tessellator test
      cmd line options:
       -c      run in color index mode
       -s      run in singlebuffer mode
      keys:
     c  create a new contour.  (see note below)
     d  delete a vertex.
     t  tessellate and draw the polygon.
     s  show the tessellation.
     e  draw the polygon in Polymode(GL_LINE) with edge flags.
     LEFTMOUSE   moves an existent vertex
     MIDDLEMOUSE inserts a vertex into a contour
         Esc        quit
      Note : you can create polygon with holes by creating a new
             contour inside the outer contour. pressing c key
             creates vertices for the new countour which can
             be connected by clicking and dragging the middle mouse.


++> tfog:  test fog functionality
    RGBA or CI, singlebuffer, depthbuffer
      cmd line options:
       -c    Run in color index mode
      keys:
     a/A       toggles aliasing/antialiasing
     e/E    toggles feedback mode
     f/F    toggles fog mode
     s/S       toggles stipple/no stipple
     t/T    toggles enabling/disabling stencil test
     m/M    toggles smooth shading on/off
         Esc    quit


++> tline: line test
    RGBA || CI, singlebuffer || doublebuffer, depthbuffer, stencilbuffer,
      cmd line options:
       -c    color index mode
       -s    single buffer mode
       -geometry  specify window size and location
      keys:
    y/Y     toggle blending
    g/G     toggle rotating "lines as rays of the sun" behind the grid
    q/Q     enable GL_LINE_STIPPLE
    w/W     disable GL_LINE_STIPPLE
    e/E     enable GL_LINE_SMOOTH w/glHint(GL_LINE_SMOOTH_HINT, GL_NICEST)
    r/R      "  GL_LINE_SMOOTH w/glHint(GL_LINE_SMOOTH_HINT, GL_DONT_CARE)
    t/T     disable GL_LINE_SMOOTH
    a/A     if GL_LINE_SMOOTH enabled (e/E || r/R),
            increment line width by 0.25 per keypress
        else if GL_LINE_SMOOTH disabled (t/T),
            increment line width by 1.0 per keypress
    z/Z     if GL_LINE_SMOOTH enabled (e/E || r/R),
            decrement line width by 0.25 per keypress
        else if GL_LINE_SMOOTH disabled (t/T),
            decrement line width by 1.0 per keypress
    d/D     toggle dithering
    f/F     toggle line fragmentation
    s/S     toggle flat/smooth shading
    x/X     toggle stenciling on/off
    c/C     toggle depth testing off/on
    v/V     toggle glDepthFunc(GL_ALWAYS) or glDepthFunc(GL_LESS)
    b/B     toggle "Depth writes masked for horizontal lines"
        or "Depth writes not masked"
    Esc    quit


=+> tlogo: renders the SGI cube logo using a variety of texturing, lighting
       techniques and models.
    RGBA || CI, singlebuffer || doublebuffer, depthbuffer, stencilbuffer,
    RED accumulation buffer
      cmd line options:
       -c    color index mode
       -s    single buffer mode
       -f    choose a new X font name to use
       -geometry  specify window size and location
      keys:
    Esc    quit
    space    anitmation toggle
    ?    show frames/second
        LEFT    rotate to the left
    RIGHT    rotate to the right
    UP      move clipping plane toward viewer
    DOWN    move clipping plane away from viewer
    z    zoom in logo
    Z    zoom out logo
    1    draw filled polygons
    2       draw only the vertices of the polygons
    3       draw only the outline of the polygons
    p/P     cycle current face mode BACK, FRONT, FRONTANDBACK
    4    if highest level of antialiasing is avaialbe, use it
    5    enable alpha test (function is source alpha, destintation is 1)
    6    enable the depth test
    7    stipple the image
    8    disable the stipple
    9    flat shade the polygons
    0    gouraud shade the polygons
    Q    enable culling of front-and-back facing polygons
    q    disable culling
    w/W    cull the front facing polygons
    e/E    cull the back facing polygons
    r/R    use the cw rule to determine front facing
    t/T    use the ccw rule to determine front facing
    y/Y    change the stippling to least significant bit last
    u/U    change the stippling to least significant bit first
    a/A    use a brick like pattern as the texture image
    s/S    use a black and white checkerboard as the texture image
    d/D    disable texturing
    f/F    change the texturing environment function to decal
    g/G    change the texturing environment function to modulate
    h/H    toggle dithering (default is on)
    l/L    toggle lighting
    k/K     toggle twosided lighting
    i/I    toggle fog
    j/J    toggle depth testing
    x/X    toggle clip plane on/off
    c/C     toggle capping algorithm
    v/V     toggle jittering (accumulation buffering anti-aliasing)
    b/B     toggle motion blur
    n/N     toggle feedback mode test
    M       increment viewport decimation
    m       decrement viewport decimation



++> toverlay:  test overlay plane rendering
      cmd line options:
        -nm       just display normal plane window
        -ov       just display overlay plane window
        -m mode   display both windows according to mode:
                   0  overlay is child of normal (default)
                   1  both are children of root
                   2  both are children of a child of root
        -bindov   bind opengl to overlay window first
        -gl       toggle opengl rendering
        -a        toggle animation


=+> tprim: draws all of the primitives ( from left to right, bottom to top )
       points, lines, line strip, a line loop, bitmaps, triangles,
       triangle strips, fanned triangles, a rectangle, a polygon, two
       separate quads, and a quad strip.  Draws them using flat shading,
       Gouraud shading and draws them filled or outlined.
    RGBA || CI, singlebuffer
      cmd line options:
       -c    color index mode
      keys:
    f/F    render using flat shading
    s/S    render using smooth shading
    p/P    render polygon in filled mode
    l/L    render polygon in line mode
    c/C     rotates color mask
    b/B     toggle which buffer is currently drawn to: [GL_NONE,GL_FRONT]
    r/R     toggle drawing the next vertex randomly either using
        glVertex2f(x,y), glVertex3f(x,y,0), or glVertex4f(x,y,0,1).
    q/Q     toggle switching to a constrained clipped area or not
    2       toggle switching to the fastest 2D clipping possible
    Esc    quit


++> tprim_pup:  resuscitated "iris GL-type" pup menu capability added to the
       tprim prog which draws all of the primitives (left to right, bottom
       to top ) points, lines, line strip, a line loop, bitmaps, triangles,
       triangle strips, fanned triangles, a rectangle, a polygon, two
       separate quads, and a quad strip.  Draws them using flat shading,
       Gouraud shading and draws them filled or outlined.
    RGBA || CI, singlebuffer
      cmd line options:
       -c    color index mode
      keys:
    f/F    render using flat shading
    s/S    render using smooth shading
    p/P    render polygon in filled mode
    l/L    render polygon in line mode
    c/C     rotates color mask
    RIGHTMOUSE    invokes "iris GL-type" pop-up menu
    Esc    quit


==> tri: render triangles as points, lines or filled and rotate or translate
     with [keypad] arrow keys.
    RGBA, singlebuffer
      keys:
    p/P    render polygon in point mode
    l/L    render polygon in line mode
    f/F    render polygon in fill mode
    LEFT    translate along -x
    RIGHT    translate along +x
    UP    translate along +y
    DOWN    translate along -y
    KeyPadLEFT    rotate around z
    KeyPadRIGHT    rotate around z
    KeyPadUP    rotate around x
    KeyPadDOWN    rotate around x
    Esc        quit


==> tri2: render triangles as points, lines or filled inside a larger disk
    with a hole in its center that these triangles get drawn into, and
    rotate or translate with [keypad] arrow keys.
    RGBA, singlebuffer
      keys:
        p/P     render polygon in point mode
        l/L     render polygon in line mode
        f/F     render polygon in fill mode
        LEFT    translate along -x
        RIGHT   translate along +x
        UP      translate along +y
        DOWN    translate along -y
        KeyPadLEFT      rotate around z
        KeyPadRIGHT     rotate around z
        KeyPadUP        rotate around x
        KeyPadDOWN      rotate around x
        Esc             quit


==> ttri: examines the clipping of a triangle using clip planes.
    RGBA, doublebuffer
      keys:
    LEFT    rotate 1/2 degree around z-axis ccw
    RIGHT    rotate 1/2 degree around z-axis cw
    UP    scale triangle smaller by a factor of .75
    DOWN    scale triangle larger by a factor of 1.5
    p/P     render polygon in point mode
        l/L     render polygon in line mode
        f/F     render polygon in fill mode
    1    render the vertices as a polygon
    2    render the vertices as a line loop
    3    render the vertices as points
    a/A    0 degree rotation around the z axis (default..original position)
    b/B    90 degrees more rotation cw around the z axis
    c/C    180 degrees more rotation cw around the z axis
    d/D     270 degrees more rotation cw around the z axis
    v/V    toggle show vertices (default is true)
    s/S    render with gouraud shading
    t/T    render with flat shading
    h/H    toggle hide bottom (default is true)
    o/O    toggle outlining
    m/M    toggle dithering
    7    toggle culling (default is false)
    8    toggle winding (default is false)
    9    toggle face (default is false - back face is culled)
    q/Q    enable blending
    w/W    disable blending
    Esc    quit


=+> tvorder:  draw 2-sided lit points, lines or filled polygons--all in quad
          strip mode--and each time read back some pixels from the middle
          of the window.
    RGBA, singlebuffer
      cmd line options:
       -u  Render to unmapped window
      keys:
    p/P     render as points
    l/L     render as lines
    f/F     render as filled
    Esc    quit


=+> twave: wave animation of mesh with control over rendering options
    RGBA, singlebuffer, depthbuffer, stencilbuffer ||
    RGBA, doublebuffer, depthbuffer, stencilbuffer ||
    CI, singlebuffer, depthbuffer, stencilbuffer   ||
    CI, doublebuffer, depthbuffer, stencilbuffer   ||
      cmd line options:
       twave [-g width height] [-f frames] [-c] [-s] [-b checker size]
             [-h height] [-geometry WxH+X+Y] [-a]
       -g    Specify grid size  (default is 10 by 10)
       -f    Specify number of frames in a full cycle (default is 10)
       -c    Run in color index mode
       -s    Run in single buffered mode
       -b    Specify size of checker on checker board (default is 2)
       -h    Specify the height of the wave (default is 0.2)
       -a       Don't start off animating
       -geometry  Specify window size and location
      keys:
    c/C    cycle texturing modes
    s/S    toggle flat/smooth shading
    l/L    toggle lighting on/off
    d/D    toggle depth testing on/off
    o/O     toggle overstrike mode, use of stencil
    f/F     toggle fog (currently not working)
    space    halt motion
    n/N    enable motion
    a/A    enable spinning
    Esc     quit


++> wind2:  simple multi-context abuse program:  drawing with one context
        into two windows
    RGBA || CI, singlebuffer || doublebuffer
      cmd line options:
       -c    color index mode
       -s    single buffer mode
      keys:
    Esc    quit


++> wind3:  simple multi-context abuse program:  drawing with two contexts
        into three windows
    RGBA || CI, singlebuffer || doublebuffer
      cmd line options:
       -c    color index mode
       -s    single buffer mode
      keys:
    Esc    quit


++> xswap:  test buffer swapping mixing X and OpenGL
    RGBA || CI, doublebuffer
      cmd line options:
       -c    color index mode
      keys:
    f       set the draw buffer to be GL_FRONT
    b       set the draw buffer to be GL_BACK
    g       toggle drawing the font in openGL (glCallLists) or not
    x       toggle drawing the font in X (DrawXFont) or not
        r       force a "REDRAW" event of the entire window
    s       swap the colors of the FRONT and BACK buffers
    Esc    quit


==> zrgb:  depthbuffered, intersecting polygons movable with mouse
       (openGL version of ~4Dgifts/examples/grafix/zrgb.c)
    RGBA, doublebuffer, depthbuffer
      keys:
    LEFTMOUSE    rotate polygons
    Esc    quit


++> zrgb_pup:  resuscitated "iris GL-type" pup menu capability added to the
       the zrgb.c prog including  depthbuffered, intersecting polygons
       movable with mouse functionality.
       (openGL version of ~4Dgifts/examples/grafix/zrgbmenu.c)
    RGBA, doublebuffer, depthbuffer
      keys:
    LEFTMOUSE    rotate polygons
    RIGHTMOUSE    invokes "iris GL-type" pop-up menu
    Esc    quit