This is geomview, produced by Makeinfo version 3.12h from geomview.texi.

INFO-DIR-SECTION Graphics Applications
START-INFO-DIR-ENTRY
* Geomview: (geomview).         The interactive 3D viewing program.
END-INFO-DIR-ENTRY


File: geomview,  Node: Example3,  Next: Example4,  Prev: Forms,  Up: Modules

Example 3: External Module with Bi-Directional Communication
============================================================

   The previous two example modules simply send commands to Geomview
and do not receive anything from Geomview.  This section describes a
module that communicates in both directions.  There are two types of
communication that can go from Geomview to an external module.  This
example shows _asynchronous_ communication -- the module needs to be
able to respond at any moment to expressions that Geomview may emit
which inform the module of some change of state within Geomview.

   (The other type of communication is _synchronous_, where a module
sends a request to Geomview for some piece of information and waits for
a response to come back before doing anything else.  The main gcl
command for requesting information of this type is `write'.  This
module does not do any synchronous communication.)

   In ansynchronous communication, Geomview sends expressions that are
essentially echoes of gcl commands.  The external module sends Geomview
a command expressing interest in a certain command, and then every time
Geomview executes that command, the module receives a copy of it.  This
happens regardless of who sent the command to Geomview; it can be the
result of the user doing something with a Geomview panel, or it may
have come from another module or from a file that Geomview reads.  This
is how a module can find out about and act on things that happen in
Geomview.

   This example uses the OOGL lisp library to parse and act on the
expressions that Geomview writes to the module's standard input.  This
library is actually part of Geomview itself -- we wrote the library in
the process of implementing gcl.  It is also convenient to use it in
external modules that must understand a of subset of gcl --
specifically, those commands that the module has expressed interest in.

   This example shows how a module can receive user pick events, i.e.
when the user clicks the right mouse button with the cursor over a geom
in a Geomview camera window.  When this happens Geomview generates an
internal call to a procedure called `pick'; the arguments to the
procedure give information about the pick, such as what object was
picked, the coordinates of the picked point, etc.  If an external module
has expressed interest in calls to `pick', then whenever `pick' is
called Geomview will echo the call to the module's standard input.  The
module can then do whatever it wants with the pick information.

   This module is the same as the _Nose_ module that comes with
Geomview.  Its purpose is to illustrate picking.  Whenever you pick on a
geom by clicking the right mouse button on it, the module draws a little
box at the spot where you clicked.  Usually the box is yellow.  If you
pick a vertex, the box is colored magenta.  If you pick a point on an
edge of an object, the module will also highlight the edge by drawing
cyan boxes at its endpoints and drawing a yellow line along the edge.

   Note that in order for this module to actually do anything you must
have a geom loaded into Geomview and you must click the right mouse
button with the cursor over a part of the geom.

     /*
      * example3.c: external module with bi-directional communication
      *
      * This example module is distributed with the Geomview manual.
      * If you are not reading this in the manual, see the "External
      * Modules" chapter of the manual for an explanation.
      *
      * This module is the same as the "Nose" program that is distributed
      * with Geomview.  It illustrates how a module can find out about
      * and respond to user pick events in Geomview.  It draws a little box
      * at the point where a pick occurrs.  The box is yellow if it is not
      * at a vertex, and magenta if it is on a vertex.  If it is on an edge,
      * the program also marks the edge.
      *
      * To compile:
      *
      *   cc -I/u/gcg/ngrap/include -g -o example3 example3.c \
      *      -L/u/gcg/ngrap/lib/sgi -loogl -lm
      *
      * You should replace "/u/gcg/ngrap" above with the pathname of the
      * Geomview distribution directory on your system.
      */
     
     #include <stdio.h>
     #include "lisp.h"               /* We use the OOGL lisp library */
     #include "pickfunc.h"           /* for PICKFUNC below */
     #include "3d.h"                 /* for 3d geometry library */
     
     /* boxstring gives the OOGL data to define the little box that
      * we draw at the pick point.  NOTE:  It is very important to
      * have a newline at the end of the OFF object in this string.
      */
     char boxstring[] = "\
     INST\n\
     transform\n\
     .04 0 0 0\n\
     0 .04 0 0\n\
     0 0 .04 0\n\
     0 0 0 1\n\
     geom\n\
     OFF\n\
     8 6 12\n\
     \n\
     -.5 -.5 -.5     # 0   \n\
     .5 -.5 -.5      # 1   \n\
     .5  .5 -.5      # 2   \n\
     -.5  .5 -.5     # 3   \n\
     -.5 -.5  .5     # 4   \n\
     .5 -.5  .5      # 5   \n\
     .5  .5  .5      # 6   \n\
     -.5  .5  .5     # 7   \n\
     \n\
     4 0 1 2 3\n\
     4 4 5 6 7\n\
     4 2 3 7 6\n\
     4 0 1 5 4\n\
     4 0 4 7 3\n\
     4 1 2 6 5\n";
     
     progn()
     {
       printf("(progn\n");
     }
     
     endprogn()
     {
       printf(")\n");
       fflush(stdout);
     }
     
     Initialize()
     {
       extern LObject *Lpick();  /* This is defined by PICKFUNC below but must */
       			    /* be used in the following LDefun() call */
       LInit();
       LDefun("pick", Lpick, NULL);
     
       progn(); {
         /* Define handle "littlebox" for use later
          */
         printf("(read geometry { define littlebox { %s }})\n", boxstring);
     
         /* Express interest in pick events; see Geomview manual for explanation.
          */
         printf("(interest (pick world * * * * nil nil nil nil nil))\n");
     
         /* Define "pick" object, initially the empty list (= null object).
          * We replace this later upon receiving a pick event.
          */
         printf("(geometry \"pick\" { LIST } )\n");
     
         /* Make the "pick" object be non-pickable.
          */
         printf("(pickable \"pick\" no)\n");
     
         /* Turn off normalization, so that our pick object will appear in the
          * right place.
          */
         printf("(normalization \"pick\" none)\n");
     
         /* Don't draw the pick object's bounding box.
          */
         printf("(bbox-draw \"pick\" off)\n");
     
       } endprogn();
     }
     
     /* The following is a macro call that defines a procedure called
      * Lpick().  The reason for doing this in a macro is that that macro
      * encapsulates a lot of necessary stuff that would be the same for
      * this procedure in any program.  If you write a Geomview module that
      * wants to know about user pick events you can just copy this macro
      * call and change the body to suit your needs; the body is the last
      * argument to the macro and is delimited by curly braces.
      *
      * The first argument to the macro is the name of the procedure to
      * be defined, "Lpick".
      *
      * The next two arguments are numbers which specify the sizes that
      * certain arrays inside the body of the procedure should have.
      * These arrays are used for storing the face and path information
      * of the picked object.  In this module we don't care about this
      * information so we declare them to have length 1, the minimum
      * allowed.
      *
      * The last argument is a block of code to be executed when the module
      * receives a pick event.  In this body you can refer to certain local
      * variables that hold information about the pick.  For details see
      * Example 3 in the Extenal Modules chapter of the Geomview manual.
      */
     PICKFUNC(Lpick, 1, 1,
     {
       handle_pick(pn>0, &point, vn>0, &vertex, en>0, edge);
     })
     
     handle_pick(picked, p, vert, v, edge, e)
          int picked;                /* was something actually picked?     */
          int vert;                  /* was the pick near a vertex?        */
          int edge;                  /* was the pick near an edge?         */
          HPoint3 *p;                /* coords of pick point               */
          HPoint3 *v;                /* coords of picked vertex            */
          HPoint3 e[2];              /* coords of endpoints of picked edge */
     {
       Normalize(&e[0]);             /* Normalize makes 4th coord 1.0 */
       Normalize(&e[1]);
       Normalize(p);
       progn(); {
         if (!picked) {
           printf("(geometry \"pick\" { LIST } )\n");
         } else {
           /*
            * Put the box in place, and color it magenta if it's on a vertex,
            * yellow if not.
            */
           printf("(xform-set pick { 1 0 0 0  0 1 0 0  0 0 1 0  %g %g %g 1 })\n",
                  p->x, p->y, p->z);
           printf("(geometry \"pick\"\n");
           if (vert) printf("{ appearance { material { diffuse 1 0 1 } }\n");
           else printf("{ appearance { material { diffuse 1 1 0 } }\n");
           printf("  { LIST { :littlebox }\n");
     
           /*
            * If it's on an edge and not a vertex, mark the edge
            * with cyan boxes at the endpoins and a black line
            * along the edge.
            */
           if (edge && !vert) {
             e[0].x -= p->x; e[0].y -= p->y; e[0].z -= p->z;
             e[1].x -= p->x; e[1].y -= p->y; e[1].z -= p->z;
             printf("{ appearance { material { diffuse 0 1 1 } }\n\
       LIST\n\
        { INST transform 1 0 0 0 0 1 0 0 0 0 1 0 %f %f %f 1 geom :littlebox }\n\
        { INST transform 1 0 0 0 0 1 0 0 0 0 1 0 %f %f %f 1 geom :littlebox }\n\
        { VECT\n\
               1 2 1\n\
               2\n\
               1\n\
               %f %f %f\n\
               %f %f %f\n\
               1 1 0 1\n\
        }\n\
       }\n",
                    e[0].x, e[0].y, e[0].z,
                    e[1].x, e[1].y, e[1].z,
                    e[0].x, e[0].y, e[0].z,
                    e[1].x, e[1].y, e[1].z);
           }
           printf("    }\n  }\n)\n");
         }
     
       } endprogn();
     
     }
     
     Normalize(HPoint3 *p)
     {
       if (p->w != 0) {
         p->x /= p->w;
         p->y /= p->w;
         p->z /= p->w;
         p->w = 1;
       }
     }
     
     main()
     {
       Lake *lake;
       LObject *lit, *val;
       extern char *getenv();
     
       Initialize();
     
       lake = LakeDefine(stdin, stdout, NULL);
       while (!feof(stdin)) {
     
         /* Parse next lisp expression from stdin.
          */
         lit = LSexpr(lake);
     
         /* Evaluate that expression; this is where Lpick() gets called.
          */
         val = LEval(lit);
     
         /* Free the two expressions from above.
          */
         LFree(lit);
         LFree(val);
       }
     }

   The code begins by defining procedures `progn()' and `endprogn()'
which begin and end a Geomview `progn' group.  The purpose of the
Geomview `progn' command is to group commands together and cause
Geomview to execute them all at once, without refreshing any graphics
windows until the end.  It is a good idea to group blocks of commands
that a module sends to Geomview like this so that the user sees their
cumulative effect all at once.

   Procedure `Initialize()' does various things needed at program
startup time.  It initializes the lisp library by calling `LInit()'.
Any program that uses the lisp library should call this once before
calling any other lisp library functions.  It then calls `LDefun' to
tell the library about our `pick' procedure, which is defined further
down with a call to the `DEFPICKFUNC' macro.  Then it sends a bunch of
setup commands to Geomview, grouped in a `progn' block.  This includes
defining a handle called `littlebox' that stores the geometry of the
little box.  Next it sends the command

     (interest (pick world * * * * nil nil nil nil nil))

which tells Geomview to notify us when a pick event happens.

   The syntax of this `interest' statement merits some explanation.  In
general `interest' takes one argument which is a (parenthesized)
expression representing a Geomview function call.  It specifies a type
of call that the module is interested in knowing about.  The arguments
can be any particular argument values, or the special symbols `*' or
`nil'.  For example, the first argument in the `pick' expression above
is `world'.  This means that the module is interested in calls to
`pick' where the first argument, which specifies the coordinate system,
is `world'.  A `*' is like a wild-card; it means that the module is
interested in calls where the corresponding argument has any value.
The word `nil' is like `*', except that the argument's value is not
reported to the module.  This is useful for cutting down on the amount
of data that must be transmitted in cases where there are arguments
that the module doesn't care about.

   The second, third, fourth, and fifth arguments to the `pick' command
give the name, pick point coordinates, vertex coordinates, and edge
coordinates of a pick event.  We specify these by `*''s above.  The
remaining five arguments to the `pick' command give other information
about the pick event that we do not care about in this module, so we
specify these with `nil''s.  For the details of the arguments to
`pick', *Note GCL::.

   The `geometry' statement defines a geom called `pick' that is
initially an empty list, specified as ` { LIST } '; this is the best
way of specifying a null geom.  The module will replace this with
something useful by sending Geomview another `geometry' command when
the user picks something.  Next we arrange for the `pick' object to be
non-pickable, and turn normalization off for it so that Geomview will
display it in the size and location where we put it, rather than
resizing and relocating it to fit into the unit cube.

   The next function in the file, `Lpick', is defined with a strange
looking call to a macro called `PICKFUNC', defined in the header file
`pickfunc.h'.  This is the function for handling pick events.  The
reason we provide a macro for this is that that macro encapsulates a
lot of necessary stuff that would be the same for the pick-handling
function in any program.  If you write a Geomview module that wants to
know about user pick events you can just copy this macro call and change
it to suit yours needs.

   In general the syntax for `PICKFUNC' is
     PICKFUNC(NAME, MAXFACEVERTS, MAXPATHLEN, BLOCK)

where NAME is the name of the procedure to be defined, in this case
`Lpick'.  The next two arguments, MAXFACEVERTS and MAXPATHLEN, give the
sizes to be used for declaring two local variable arrays in the body of
the procedure.  These arrays are for storing information about the
picked face and the picked primitive's path.  In this module we don't
care about this information (it corresponds to some of the things
masked out by the `nil''s in the `interest' call above) so we specify
1, the minimum allowable, for both of these.  The last argument, BLOCK,
is a block of code to be executed when a pick event occurs.  The BLOCK
should be delimited by curly braces.  The code in your BLOCK should not
include any `return' statements.

   `PICKFUNC' declares certain local variables in the body of the
procedure.  When the module receives a `(pick ...)' statement from
Geomview, the procedure assigns values to these variables based on the
information in the `pick' call.  (Variables corresponding to `nil''s in
the `(interest (pick ...))' are not given values.)  These variables are:
`char *coordsys;'
     A string specifying the coordinate system in which coordinates are
     given.  In this example, this will always be `world' because of
     the `interest' call above.

`char *id;'
     A string specifying the name of the picked geom.

`HPoint3 point; int pn;'
     `point' is an `HPoint3' structure giving the coordinates of the
     picked point.  `HPoint3' is a homogeneous point coordinate
     representation equivalent to an array of 4 floats.  `pn' tells how
     many coordinates have been written into this array; it will always
     be either 0 or 4.  A value of zero means no point was picked, i.e.
     the user clicked the right mouse button while the cursor was not
     pointing at a geom.

`HPoint3 vertex; int vn;'
     `vertex' is an `HPoint3' structure giving the coordinates of the
     picked vertex, if the pick point was near a vertex.  `vn' tells
     how many coordinates have been written into this array; it will
     always be either 0 or 4.  A value of zero means the pick point was
     not near a vertex.

`HPoint3 edge[2]; int en;'
     `edge' is an array of two `HPoint3' structures giving the
     coordinates of the endpoints of the picked edge, if the pick point
     was near an edge.  `en' tells how many coordinates have been
     written into this array; it will always be either 0 or 8.  A value
     of zero means the pick point was not near an edge.

   In this example module, the remaining variables will never be given
values because their values in the `interest' statement were specified
as `nil'.

`HPoint3 face[MAXFACEVERTS]; int fn;'
     `face' is an array of MAXFACEVERTS `HPoint3''s; MAXFACEVERTS is
     the value specified in the `PICKFUNC' call.  `face' gives the
     coordinates of the vertices of the picked face.  `fn' tells how
     many coordinates have been written into this array; it will always
     be a multiple of 4 and will be at most 4*MAXFACEVERTS.  A value of
     zero means the pick point was not near a face.

`HPoint3 ppath[MAXPATHLEN; int ppn;'
     `ppath' is an array of MAXPATHLEN `int''s; MAXPATHLEN is the value
     specified in the `PICKFUNC' call.  `ppath' gives the path through
     the OOGL heirarchy to the picked primitive.  `pn' tells how many
     integers have been written into this array; it will be at most
     MAXPATHLEN.  A path of {3,1,2}, for example, means that the picked
     primitive is "subobject number 2 of subobject number 1 of object 3
     in the world".

`int vi;'
     `vi' gives the index of the picked vertex in the picked primitive,
     if the pick point was near a vertex.

`int ei[2]; int ein'
     The `ei' array gives the indices of the endpoints of the picked
     edge, if the pick point was near a vertex.  `ein' tells how many
     integers were written into this array.  It will always be either 0
     or 2; a value of 0 means the pick point was not near an edge.

`int fi;'
     `fi' gives the index of the picked face in the picked primitive, if
     the pick point was near a face.

   The `handle_pick' procedure actually does the work of dealing with
the pick event.  It begins by normalizing the homogeneous coordinates
passed in as arguments so that we can assume the fourth coordinate is 1.
It then sends gcl commands to define the `pick' object to be whatever
is appropriate for the kind of pick recieved.  See *note OOGL File
Formats::., and *note GCL::., for an explanation of the format of the
data in these commands.

   The main program, at the bottom of the file, first calls
`Initialize()'.  Next, the call to `LakeDefine' defines the `Lake' that
the lisp library will use.  A `Lake' is a structure that the lisp
library uses internally as a type of communiation vehicle.  (It is like
a unix stream but more general, hence the name.)  This call to
`LakeDefine' defines a `Lake' structure for doing I/O with `stdin' and
`stdout'.  The third argument to `LakeDefine' should be `NULL' for
external modules (it is used by Geomview).  Finally, the program enters
its main loop which parses and evaluates expressions from standard
input.


File: geomview,  Node: Example4,  Next: Module Installation,  Prev: Example3,  Up: Modules

Example 4: Simple Tcl/Tk Module Demonstrating Picking
=====================================================

   It's not necessary to write a Geomview module in C.  The only
requirement of an external module is that it send GCL commands to its
standard output and expect responses (if any) on its standard input.
An external module can be written in C, perl, tcl/tk, or pretty much
anything.

   As an example, assuming you have Tcl/Tk version 4.0 or later, here's
an external module with a simple GUI which demonstrates interaction with
geomview.  This manual doesn't discuss the Tcl/Tk language; see the
good book on the subject by its originator John Ousterhout, published
by Addison-Wesley, titled _Tcl and the Tk Toolkit_.

   The `#!' on the script's first line causes the system to interpret
the script using the Tcl/Tk `wish' program; you might have to change its
first line if that's in some location other than /usr/local/bin/wish4.0.
Or, you could define it as a module using
       (emodule-define  "Pick Demo"  "wish pickdemo.tcl")
   in which case `wish' could be anywhere on the UNIX search path.

     #! /usr/local/bin/wish4.0
     
     # We use "fileevent" below to have "readsomething" be called whenever
     # data is available from standard input, i.e. when geomview has sent us
     # something.  It promises to include a trailing newline, so we can use
     # "gets" to read the geomview response, then parse its nested parentheses
     # into tcl-friendly {} braces.
     
     proc readsomething {} {
       if {[gets stdin line] < 0} {
             puts stderr "EOF on input, exiting..."
             exit
       }
       regsub -all {\(} $line "\{" line
       regsub -all {\)} $line "\}" line
       # Strip outermost set of braces
       set stuff [lindex $line 0]
       # Invoke handler for whichever command we got.  Could add others here,
       # if we asked geomview for other kinds of data as well.
       switch [lindex $stuff 0] {
             pick     {handlepick $stuff}
             rawevent {handlekey $stuff}
       }
     }
     
     # Fields of a "pick" response, from geomview manual:
     #     (pick COORDSYS GEOMID G V E F P VI EI FI)
     #          The pick command is executed internally in response to pick
     #          events (right mouse double click).
     #
     #          COORDSYS = coordinate system in which coordinates of the following
     #              arguments are specified.   This can be:
     #               world: world coord sys
     #               self:  coord sys of the picked geom (GEOMID)
     #               primitive: coord sys of the actual primitive within
     #                   the picked geom where the pick occurred.
     #          GEOMID = id of picked geom
     #          G = picked point (actual intersection of pick ray with object)
     #          V = picked vertex, if any
     #          E = picked edge, if any
     #          F = picked face
     #          P = path to picked primitive [0 or more]
     #          VI = index of picked vertex in primitive
     #          EI = list of indices of endpoints of picked edge, if any
     #          FI = index of picked face
     
     # Report when user picked something.
     #
     proc handlepick {pick} {
       global nameof selvert seledge order
       set obj [lindex $pick 2]
       set xyzw [lindex $pick 3]
       set fv [lindex $pick 6]
       set vi [lindex $pick 8]
       set ei [lindex $pick 9]
       set fi [lindex $pick 10]
     
       # Report result, converting 4-component homogeneous point into 3-space point.
       set w [lindex $xyzw 3]
       set x [expr [lindex $xyzw 0]/$w]
       set y [expr [lindex $xyzw 1]/$w]
       set z [expr [lindex $xyzw 2]/$w]
       set s "$x $y $z "
       if {$vi >= 0} {
             set s "$s  vertex #$vi"
       }
       if {$ei != {}} {
             set s "$s  edge [lindex $ei 0]-[lindex $ei 1]"
       }
       if {$fi != -1} {
             set s "$s  face #$fi ([expr [llength $fv]/3]-gon)"
       }
       msg $s
     }
     
     
     # Having asked for notification of these raw events, we report when
     # the user pressed these keys in the geomview graphics windows.
     
     proc handlekey {event} {
       global lastincr
       switch [lindex $event 1] {
         32 {msg "Pressed space bar"}
          8 {msg "Pressed backspace key"}
       }
     }
     
     
     #
     # Display a message on the control panel, and on the terminal where geomview
     # was started.  We use ``puts stderr ...'' rather than simply ``puts ...'',
     # since Geomview interprets anything we send to standard output
     # as a GCL command!
     #
     proc msg {str} {
       global msgtext
       puts stderr $str
       set msgtext $str
       update
     }
     
     # Load object from file
     proc loadobject {fname} {
       if {$fname != ""} {
             puts "(geometry thing < $fname)"
             # Be sure to flush output to ensure geomview receives this now!
             flush stdout
       }
     }
     
     
     # Build simple "user interface"
     
     # The message area could be a simple label rather than an entry box,
     # but we want to be able to use X selection to copy text from it.
     # The default mouse bindings do that automatically.
     
     entry .msg -textvariable msgtext -width 45
     pack .msg
     
     frame .f
     
       label .f.l -text "File to load:"
       pack .f.l -side left
     
       entry .f.ent -textvariable fname
       pack .f.ent -side left -expand true -fill x
       bind .f.ent <Return> { loadobject $fname }
     
     pack .f
     
     
     # End UI definition.
     
     
     # Call "readsomething" when data arrives from geomview.
     
     fileevent stdin readable {readsomething}
     
     # Geomview initialization
     
     puts {
             (interest (pick primitive))
             (interest (rawevent 32))	# Be notified when user presses space
             (interest (rawevent 8))		# or backspace keys.
             (geometry thing < hdodec.off)
             (normalization world none)
     }
     # Flush to ensure geomview receives this.
     flush stdout
     
     wm title . {Sample external module}
     
     msg "Click right mouse in graphics window"


File: geomview,  Node: Module Installation,  Next: Private Module Installation,  Prev: Example4,  Up: Modules

Module Installation
===================

   This section tells how to install an external module so you can
invoke it within Geomview.  There are two ways to install a module: you
can install a _private_ module so that the module is available to you
whenever you run Geomview, or you can install a _system_ module so that
the module is available to all users on your system whenever they run
Geomview.

* Menu:

* Private Module Installation::.
* System Module Installation::.


File: geomview,  Node: Private Module Installation,  Next: System Module Installation,  Prev: Module Installation,  Up: Module Installation

Private Module Installation
---------------------------

   The `emodule-define' command arranges for a module to appear in
Geomview's _Modules_ browser.  `emodule-define' takes two string
arguments; the first is the name that will appear in the _Modules_
browser.  The second is the shell command for running the module; it
may include arguments.  Geomview executes this command in a subshell
when you click on the module's entry in the browser.  For example

     (emodule-define "Foo" "/u/home/modules/foo -x")

adds a line labeled "Foo" to the _Modules_ browser which causes the
command "/u/home/modules/foo -x" to be executed when selected.

   You may put `emodule-define' commands in your `~/.geomview' file to
arrange for certain modules to be available every time you run
Geomview; *Note Customization::.  You can also execute `emodule-define'
commands from the _Commands_ panel to add a module to an already
running copy of Geomview.

   There are several other gcl commands for controlling the entries in
the _Modules_ browser; for details, *Note GCL::.


File: geomview,  Node: System Module Installation,  Next: GCL,  Prev: Private Module Installation,  Up: Module Installation

System Module Installation
--------------------------

   To install a module so that it is available to all Geomview users do
the following

1.
     Create a file called `.geomview-MODULE' where `MODULE' is the name
     of the module.  This file should contain a single line which is an
     `emodule-define' command for that module:
          (emodule-define "New Module" "newmodule")
     The first argument, `"New Module"' above, is the string that will
     appear in the _Modules_ browser.  The second string, `"newmodule"'
     above, is the Bourne shell command for invoking the module.  It
     may include arguments, and you may assume that the module is on the
     $path searched by the shell.

2.
     Put a copy of the `.geomview-MODULE' and the module executable
     itself in Geomview's `modules/<CPU>' directory, where `<CPU>' is
     your system type.

   After these steps, the new module should appear, in alphabetical
position, in the _Modules_ browser of Geomview's _Main_ panel next time
Geomview is run.  The reason this works is that when Geomview is
invoked it processes all the `.geomview-*' files in its `modules'
directory.  It also remembers the pathname of this directory and
prepends that path to the $path of the shell in which it invokes such a
module.


File: geomview,  Node: GCL,  Next: Argument Conventions,  Prev: System Module Installation,  Up: Top

gcl: the Geomview Command Language
**********************************

   Gcl has the syntax of lisp - i.e. an expression of the form (f a b
...) means pass the values of a, b, ... to the function f.  Gcl is very
limited and is by no means an implementation of lisp.  It is simply a
language for expressing commands to be executed in the order given,
rather than a programming language.  It does not support variable or
function definition.

   Gcl is the language that Geomview understands for files that it loads
as well as for communication with other programs.  To execute a gcl
command interactively, you can bring up the _Commands_ panel which lets
you type in a command; Geomview executes the command when you hit the
<Enter> key.  Output from such commands is printed to standard output.
Alternately, you can invoke Geomview as `geomview -c -' which causes it
to read gcl commands from standard input.

   Gcl functions return a value, and you can nest function calls in ways
which use this returned value.  For example
     (f (g a b))
   evaluates `(g a b)' and then evaluates `(f x)' where `x' is the
result returned by `(g a b)'.  Geomview maintains these return values
internally but does not normally print them out.  To print out a return
value pass it to the `echo' function.  For example the
`geomview-version' function returns a string representing the version
of Geomview that is running, and
     (echo (geomview-version))
   prints out this string.

   Many functions simply return `t' for success or `nil' for failure;
this is the case if the documentation for the function does not
indicate otherwise.  These are the lisp symbols for true and false,
respectively.  (They correspond to the C variables `Lt' and `Lnil'
which you are likely to see if you look at the source code for Geomview
or some of the external modules.)

   In the descriptions of the commands below several references are
made to "OOGL" formats.  OOGL is the data description language that
Geomview uses for describing geometry, cameras, appearances, and other
basic objects.  For details of the OOGL formats, *Note OOGL File
Formats::.  (Or equivalently, see the oogl(5) manual page, distributed
with Geomview in the file man/cat5/oogl.5.

   The gcl commands and argument types are listed below.  Most of the
documentation in this section of the manual is available within
Geomview via the `?' and `??' commands.  The command `(?  COMMAND)'
causes Geomview to print out a one-line summary of the syntax of
COMMAND, and `(?? COMMAND)' prints out an explanation of what COMMAND
does.  You can include the wild-card character `*' in COMMAND to print
information for a group of commands matching a pattern.  For example,
`(?? *emodule*)' will print all information about all commands
containing the string `emodule'.  `(? *)' will print a short list of
all commands.

* Menu:

* Argument Conventions::  Conventions used in describing argument types.
* Gcl Reference::	  Documentation for each gcl command.


File: geomview,  Node: Argument Conventions,  Next: Gcl Reference,  Prev: GCL,  Up: GCL

Conventions Used In Describing Argument Types
=============================================

   The following symbols are used to describe argument types in the
documentation for gcl functions.

`APPEARANCE'
     is an OOGL appearance specification.

`CAM-ID'
     is an ID that refers to a camera.

`CAMERA'
     is an OOGL camera specification.

`GEOM-ID'
     is an ID that refers to a geometry.

`GEOMETRY'
     is an OOGL geometry specification.

`ID'
     is a string which names a geometry or camera.  Besides those you
     create, valid ones are:

    ``World, world, worldgeom, g0''
          the collection of all geom's

    `target'
          selected target object (cam or geom)

    `center'
          selected center-of-motion object

    `targetcam'
          last selected target camera

    `targetgeom'
          last selected target geom

    `focus'
          camera where cursor is (or most recently was)

    `allgeoms'
          all geom objects

    `allcams'
          all cameras

    ``default, defaultcam, prototype''
          future cameras inherit default's settings

     The following IDs are used to name coordinate systems, e.g. in
     `pick' and `write' commands:

    ``World, world, worldgeom, g0''
          the world, within which all other geoms live.

    `universe'
          the universe, in which the World, lights and cameras live.
          Cameras' world2cam transforms might better be called
          universe2cam, etc.

    `self'
          "this Geomview object".  Transform from an object to `self'
          is the identity; writing its geometry gives the object itself
          with no enclosing transform; picked points appear in the
          object's coordinates.

    `primitive'
          (for `pick' only) Picked points appear in the coordinate
          system of the lowest-level OOGL primitive.

     A name is also an acceptable id.  Given names are made unique by
     appending numbers if necessary (i.e. `foo<2>'). Every geom is also
     named g[n] and every camera is also named c[n] (`g0' is always the
     worldgeom): this name is used as a prefix to keyboard commands and
     can also be used as a gcl id.  Numbers are reused after an object
     is deleted. Both names are shown in the Object browser.

`STATEMENT'
     represents a function call.  Function calls have the form `(func
     arg1 arg2 ... )', where `func' is the name of the function and
     `arg1', `arg2', ... are the arguments.

`TRANSFORM'
     is an OOGL 4x4 transformation matrix.

`WINDOW'
     is an OOGL winddow specification.

