Ygl Version 4.2 Description

©opyright 1993-2007 by Fred Hucht (fred(AT)thp.Uni-Duisburg.DE)

Ygl is distributed in terms of the GNU LIBRARY GENERAL PUBLIC LICENSE. Please see the file LICENSE for further details. You may not distribute this project without this file (ReadMe.html) and the LICENSE file included.

Here you can read the Changes history and the Ygl FAQ.

Description

• On our RS/6000 GT4 hardware, 2D Ygl is up to twenty times faster (circf()) than GL (strange, isn't it?...)
• 2D (and 3D using OpenGL) graphics runs on non GL hardware and even on remote X-Servers.

3D stuff was added with version 4.0 using OpenGL calls.

Since Version 2.8, all Ygl functions do have a FORTRAN interface. The FORTRAN versions of all functions have an underscore appended, so the FORTRAN compiler must append a '_' to all function names. f2c does this, xlf (under AIX 3.2) requires the option -qextname. See smile_f77.f for an example program. Set FortranBindings to 0 in Imakefile or change Makefile.std if you don't want these bindings. FORTRAN bindings are not tested because I have no programs.f to test. If you find bugs, feel free to report them to me.

You can always find the latest version of Ygl in the directory ftp.thp.Uni-Duisburg.de/pub/source/X11/.

Note that perl, python and tcl bindings for Ygl are available here thanks to Prabhu Ramachandran.

Details

Environment variables:

• The environment variable YGL_PRIVATECOLORMAP or YGL_PCM can be set to 1 to force Ygl to use a private colormap. While GL always uses a private colormap, Ygl uses the global map by default to avoid technicolor effects on X-Servers not capable of more than one colormap at a time. Note that you can only redefine the color of already drawn objects when you use a private colormap.
• The environment variable YGL_FLUSHTIME or YGL_FT (default value: 0.1) can be used to adjust the time in seconds between flushes of the graphics pipeline. It can be set to 0 to disable the automatic update via interval timer. Setting YGL_FLUSHTIME to -1 will put the X-Server into synchronous mode (see XSynchronize). This mode seems to be veeeryyy slooow, but is good for debugging...
• The environment variable YGL_BACKINGSTORE or YGL_BS can be set to 1 to enable BackingStore support for all Ygl windows. With BackingStore, the X-Server remembers the contents of a window when it gets obscured or iconified. You must start your X-Server with the option "-bs" ("+bs" on some systems) to use this feature.
• The environment variables YGL_CMAPVISUAL or YGL_CV and YGL_RGBVISUAL or YGL_RV control the selection of visuals for cmapmode and RGBmode. Set these variables to the visual id of the desired visual as returned by xdpyinfo (both hex and decimal is ok). Setting one of these variables to -1 forces Ygl to use the default visual of the screen instead of the best visual.
• The environment variable YGL_SINGLEGC or YGL_GC can be set to 1 to force Ygl to use a single graphics context for colormap windows. Per default Ygl uses one GC for each color, i.e. 256 GCs for a 8 bit colormap window, because this speeds up drawing with many color changes by a factor of 2 or so on many systems. Using a single GC may be faster if you use many mapcolor calls as in colormap animation. Note that if the used colormap visual has more than 256 colors YGL_GC defaults to 1.
• The environment variable YGL_PARENTWID or YGL_PWID controls the parent window of Ygl. Per default the root window of the default screen of the given display is the parent window of windows opened with winopen(). Set this variable to the window id of the desired window as returned by xwininfo (both hex and decimal is ok).
• The environment variable YGL_DITHERSIZE or YGL_DSZ controls dithering in RGB mode.With this variable you can specify the size of the dither matrix. The default value is 4, leading to a 4x4 dither matrix. Valid values range from 0 to 6. On a normal 8 bit TrueColor visual ({3,3,2} bits {red,green,blue}) you obtain 113x113x49 = 625681 different "colors" with YGL_DSZ=4, leading to an effective screen depth of approx. 19 bits. The other values and the effective screendepth are:

           |  8 bit (3-3-2)  | 12 bit (4-4-4)  |  16 bit (6-5-5)
    YGL_DSZ| # colors (bits) | # colors (bits) |  # colors (bits)
    -------------------------------------------------------------
      0,1  |      256 ( 8  ) |     4096 (12  ) |     65536 (16  )
       2   |    10933 (13.4) |   226981 (17.8) |   3953125 (21.9)
       3   |   114688 (16.8) |  2515456 (21.3) |  44531200 (25.4)
       4   |   625681 (19.3) | 13997521 (23.7) | 249232081 (27.9)
       5   |  2354176 (21.2) | 53157376 (25.7) | 949029376 (29.8)
       6   |  6976981 (22.7) |158340421 (27.2) |2831006341 (31.4)
  

  Note that dithering costs speed. You may set YGL_DSZ=0 to disable dithering. If you are lucky and have a 24 bit TrueColor visual, YGL_DSZ is automatically set to zero.

Doublebuffering:

Notes:

OpenGL:

You can use the routine gsync() to wait for the next vertical retrace. If you use doublebuffering, it might help to set the environment variable __GL_SYNC_TO_VBLANK to 1 to swap buffers at a vertical retrace.

X11R6.1:

If you have X11R6.1 or later, set DoubleBuffer to 1 in Imakefile.

AIX < 3.2.5:

The extension "Multi-Buffering" is new in X11R5 and is included in the lpp X11dev.src under AIX. To use doublebuffering you have to link the "Multi-Buffering" extension into your X-Server (under AIX, see /usr/lpp/X11/Xamples/README, "Linking the Sample Extensions into the Server").

AIX >= 3.2.5:

You don't need to recompile the X-Server anymore to use doublebuffering under AIX 3.2.5 (AIXWindows 1.2.3). You simply have to add the option "-x mbx" to the X-Servers command line on startup.

AIX >= 4.1:

You need the LPP X11.adt.ext to compile Ygl with doublebuffering enabled.

RGB mode:

 Colormap mode <-> PseudoColor, StaticColor,
                   GrayScale, StaticGray,
                   TrueColor or DirectColor visual

 RGB mode      <-> TrueColor or DirectColor visual

Multiple Expose events (REDRAW) in qread:

Automatic flushing of the graphics pipeline:

Note that sleep() and usleep() always return 0.

You can use "sleep(0)" to flush the graphics pipeline explicitly. If you have problems with sleep() and usleep(), undefine COVERSLEEP in header.h.

Supported routines

Window related routines:

Color related routines:

Device related routines:

• Currently supported devices are: REDRAW, KEYBD, INPUTCHANGE, LEFTMOUSE, MIDDLEMOUSE, RIGHTMOUSE (MENUBUTTON), MOUSEX, MOUSEY, WINQUIT, and all individual keys as F1KEY, ESCKEY, UPARROWKEY, and so on.
• qenter does only support the REDRAW device.

Menu routines:

int callback(Int32 m, Int32 s) {
  sleep(s);
  switch(m) {
  case 1: explode(); break;
  case 2: implode(); break;
  }
  return(m << 8 + s);
}

main() {
  ...
  sub  = defpup("Seconds%t|1|2|3|4|5");
  menu = defpup("Menu%t%F|Explode%M|Implode%M",	callback, sub, sub);
  ...
}

Font routines:

Doublebuffer routines:

Misc routines:

Coordinate transformation routines:

Drawing routines:

3D routines

Drawing:

Coordinate Systems:

Polygon specs:

z-Buffer:

Display lists:

Misc:

Picking/Names:

NOPs:

Routines not in SGI's GL:

• GC getXgc(void)
  return current graphics context. You can for example use it to draw lines xor'ed with the background:

  #include <X11/X.h>
  ...
  XSetFunction(getXdpy(), getXgc(), GXxor);
  

  Note: Since version 3.1, getXgc() is not supported anymore, as you can use the routine logicop() to set the drawing function.

• Window getXdid()
  return window id of the current drawable. This id differs from the window id returned by getXwid() when in RGB mode or when using doublebuffering.

• Int32 crectread(Screencoord x1, Screencoord y1, Screencoord x2, Screencoord y2, Uint8 *data)
  read screen data to unsigned char array data

• void crectwrite(Screencoord x1, Screencoord y1, Screencoord x2, Screencoord y2, Uint8 *data)
  write unsigned char array data to screen

• void arcxs(Scoord x,Scoord y,Scoord rx,Scoord ry,Angle s,Angle e)
  void arcxi(Icoord x,Icoord y,Icoord rx,Icoord ry,Angle s,Angle e)
  void arcx(Coord x,Coord y,Coord rx,Coord ry,Angle s,Angle e)
  draw ellipses

• void arcxfs(Scoord x,Scoord y,Scoord rx,Scoord ry,Angle s,Angle e)
  void arcxfi(Icoord x,Icoord y,Icoord rx,Icoord ry,Angle s,Angle e)
  void arcxf(Coord x,Coord y,Coord rx,Coord ry,Angle s,Angle e)
  draw filled ellipses

• int gl2ppm(char *filename)
  write out active Ygl window to portable pixmap file 'filename'. When filename[0] == '|', uses popen() instead of fopen(). Note that gl2ppm() can also be used in a GL application. Just add gl2ppm.o to the list of object files.

Acknowledgements

GL is a registered trademark of Silicon Graphics, Inc.