Next: LIST, Previous: SPHERE, Up: Object File Formats

#### 4.2.9 INST Files

The conventional suffix for a `INST` file is `.inst`.

There is no INST BINARY format.

An `INST` applies a 4x4 (or (N+1)x(N+1) in the context of ND-viewing) transformation to another OOGL object. It begins with `INST` followed by these sections which may appear in any order:

         geom oogl-object

specifies the OOGL object to be instantiated. See References, for the syntax of an oogl-object. The keyword `unit` is a synonym for `geom`.

         transform   ["{"] 4x4 transform ["}"]

specifies a single transformation matrix. Either the matrix may appear literally as 16 numbers, or there may be a reference to a "transform" object, i.e.

             "<" file-containing-4x4-matrix

or

             ":" symbol-representing-transform-object

Another way to specify the transformation is

         transforms
             oogl-object

The oogl-object must be a `TLIST` object (list of transformations) object, or a `LIST` whose members are ultimately `TLIST` objects. In effect, the `transforms` keyword takes a collection of 4x4 matrices and replicates the `geom` object, making one copy for each 4x4 matrix.

If no `transform` nor `transforms` keyword appears, no transformation is applied (actually the identity is applied). You could use this for, e.g., wrapping an appearance around an externally-supplied object, though a single-membered LIST would do this more efficiently.

See Transformation matrices, for the matrix format.

When replicating a single geometry by means of a `TLIST` object (see ‘`transforms`’ above) it may be useful to transform texture co-ordinates by another list of transformations; that list can be specified by

         txtransforms
             TLIST-object

The number of texture transformations must match the number of geometry transformations. The `SPHERE` object (see Sphere Objects) uses this technique to generate an entire textured sphere out of some fraction of a sphere (usually one octant).

A single (N+1)-dimensional transformation can be specified by

         ntransform ["{"] N+1 N+1 (N+1)x(N+1) floats ["}"]

This gives a single N+1-dimensional transformation matrix. Either the matrix may appear literally as (N+1)x(N+1) numbers, or there may be a reference to an ‘`ntransform`’ object, i.e.

             "<" file-containing-(N+1)x(N+1)-matrix

or

             ":" symbol-representing-ntransform-object

See ND Transformation matrices, for the matrix format.

Two more INST fields are accepted: `location` and `origin`.

Note that `location` as well as `origin` are ignored if this `INST` object carries an `ntransform`. Also, if ND-viewing is active (`ND-axes` command, see GCL) then `INST` objects with `origin` unequal to `local` will not be drawn, though the `location` stuff may work (or not).

         location [global or camera or ndc or screen or local]

Normally an INST specifies a position relative to its parent object; the `location` field allows putting an object elsewhere.

- `location global` attaches the object to the global (a.k.a. universe) coordinate system – the same as that in which geomview's World objects, alien geometry, and cameras are placed.
- `location camera` places the object relative to the camera. (Thus if there are multiple views, it may appear in a different spatial position in each view.) The center of the camera's view is along its negative Z axis; positive X is rightward, positive Y upward. Normally the units of camera space are the same as global coordinates. When a camera is reset, the global origin is at (0,0,-3.0).
- `location ndc` places the object relative to the normalized unit cube into which the camera's projection (perspective or orthographic) maps the visible world. X, Y, and Z are each in the range from -1 to +1, with Z = -1 the near and Z = +1 the far clipping plane, and X and Y increasing rightward and upward respectively. Thus something like

                INST  transform  1 0 0 0  0 1 0 0  0 0 1 0  -.9 -.9 -.999 1
                      location ndc
                      geom < label.vect

  pastes `label.vect` onto the lower left corner of each window, and in front of nearly everything else, assuming `label.vect`'s contents lie in the positive quadrant of the X-Y plane. It's tempting to use -1 rather than -.999 as the Z component of the position, but that may put the object just nearer than the near clipping plane and make it (partially) invisible, due to floating-point error.

- `location screen` places the object in screen coordinates. The range of Z is still -1 through +1 as for ndc coordinates; X and Y are measured in pixels, and range from (0,0) at the lower left corner of the window, increasing rightward and upward.

`location local` is the default; the object is positioned relative to its parent.

         origin [global or camera or ndc or screen or local] x y z

The `origin` field translates the contents of the INST to place the origin at the specified point of the given coordinate system. Unlike `location`, it doesn't change the orientation, only the choice of origin. Both `location` and `origin` can be used together.

So for example

         { INST
           location screen
           origin ndc 0 0 -.99
           geom { < xyz.vect }
           transform { 100 0 0 0  0 100 0 0  0 0 -.009 0   0 0 0 1 }
         }

places xyz.vect's origin in the center of the window, just beyond the near clipping plane. The unit-length X and Y edges are scaled to be just 100 screen units – pixels – long, regardless of the size of the window.