# Programmers' Manual - IRIT

## Introduction

This manual describes the different libraries of the IRIT solid modeling environment. Quite a few libraries can be found to manipulate geometry in general, freeform curves and surfaces, symbolic computation, trimmed surfaces, triangular patches, freeform trivariate functions, Boolean operations, input output data file parsing, and miscelleneous.
All interface to the libraries should be made via the appropriate header files that can be found in the include subdirectory. Most libraries have a single header file that is named the same as the library. Functions and constants that are visible to the users of the libraries are prefixed with a unique prefix, usually derived from the library name itself. External definitions that start with an underscore should not be used, even if found in header files.
The header file include/irit_sm.h must be sourced by every source file in the solid modeller. In most cases, this file is sourced indirectly via local header files.
The following libraries are avaliable in IRIT:

Name of Library | Tasks
--- | ---
bool | Boolean operations on polygonal models.
cagd | Low level freeform curves and surfaces.
geom | General geometry functions.
mdl | Model's processing functions.
misc | Memory allocation, configuration files, attributes, etc.
mvar | Multi variate functions.
prsr | Input and output for file/sockets of objects of IRIT.
rndr | Scan conversion rendering functions.
symb | Symbolic manipulation of curves and surfaces.
trim | Trimmed surfaces support.
triv | Freeform trivariate functions.
trng | Triangular patches support.
user | General high level user inteface functions.
xtra | Public domain code that is not part of IRIT.

### Tools and Programs

The IRIT package includes several complete programs such as poly3d-h (hidden line removal), irender (scan conversion tool), and irit2ps (a filter to Postscript). Somewhat different than most other programs is the kernel interpreter, also called irit. The irit program is nothing more than an interpreter (written in C) that invokes numerous functions in the several libraries provided. In order to add a new function to the irit interpreter, the following sequence of operations must be followed:

Write a C function that accepts only one or more of the following type of parameters. All parameters, including the RealType, must be transferred by address:
RealType (see irit_sm.h).
VectorType (see irit_sm.h).
PointType (see irit_sm.h).
CagdCtlPtStruct (see cagd_lib.h).
PlaneType (see irit_sm.h).
StringType (char *).
IPObjectStruct (see iritprsr.h). This includes all object types in IPObjectStruct other than the above.
The written C function can return one of:
RealType by value.
IPObjectStruct by address.
Nothing (a procedure).
According to the returned type by the new C function, go to file inptprsl.h , and add a new enum NEW_FUNC for the new function in enum RealValueFuncType (for RealType returned value), in enum ObjValueFuncType (for IPObjectStruct * returned value), or in enum GenValueFuncType (for no returned value).
In inptevl1.c , add one new line in one of NumFuncTable, ObjFuncTable, or GenFuncTable (depends upon the return value). The line will have the form of:
                { ``FuncName'', NEW_FUNC, CFunctionName,  N, { Param1Type,
                                                  Param2Type, ... ParamNType } }
for procedures with no return values, and of the form of:
                { ``FuncName'', NEW_FUNC, CFunctionName,  N, { Param1Type,
                                        Param2Type, ... ParamNType }, RetValType }
otherwise. N is the number of parameters, ``FuncName'' is the (unique) name that will be used in the interpreter, CFunctionName is the name of the C function you have written. This C function must be declared in one of the header files that inptevl1.c includes. ParamIType, for I between 1 and N, and RetValType are of type IritExprType (see inptprsl.h).
Thats it!

For example, to add the C function declared as

        IPObjectStruct *PolyhedraMoments(IPObjectStruct *IPObjectStruct, RealType *m);

one has to add the following line to ObjFuncTable in iritevl1.c

        { ``PMOMENT'', PMOMENT, { POLY_EXPR, REAL_EXPR }, VECTOR_EXPR },

where PMOMENT needs to be added to ObjValueFuncType in iritprsl.h. While all objects in the interpreted space are of type IPObjectStruct, the functions' interface unfolds many types to simplify matter. RealType, VectorType, Strings, etc. are all extracted from the given (IPObjectStruct) parameters and passed directly by address. For returned values, only numeric real data is allowed where everything else must be returned wrapped in an IPObjectStruct. The following chapters reference the different function of different libraries. Chapter~ref{chap-examples} provides several examples of writing C code using the IRIT libraries.

## Boolean Library, bool_lib

### General Information

On of the crucial operation in any solid modeling environment is the ability to perform Boolean operations among different geometric objects. The interface of the library is defined in include/bool_lib.h. This library supports only Boolean operations of polygonal objects. The Boolean operations of OR, AND, SUBtract, NEGate, CUT, and MERGE are supported via the BoolOperType typedef:

BoolOperType | Meaning
--- | ---
BOOL_OPER_OR | Union of two geometrical objects
BOOL_OPER_AND | Intersection of two geometrical objects
BOOL_OPER_SUB | The difference of two geometrical objects
BOOL_OPER_NEG | Unary Inside-out of one geometrical object
BOOL_OPER_CUT | Boundary of one object outside the other
BOOL_OPER_MERGE | Simple merge without any computation

The BoolOperType typedef is used in two dimensional Boolean operations invoked via Boolean2D . Three dimensional Boolean operations are invoked via BooleanXXX where XXX is one of OR, AND, SUB, NEG, CUT or MERGE, denoting the same as in the table above. In addition several state functions are available to control the way the Boolean operations are conducted. Functions to enable the dump of (only) the intersection curves, to handle coplanar polygons, and to set the axis along which the sweep is performed are provided.

### Library Functions

Click Here for the list of functions of this library.

## CAGD Library, cagd_lib

### General Information

This library provides a rich set of function to create, convert, display and process freeform Bezier and NURBs curves and surfaces. The interface of the library is defined in include/cagd_lib.h . This library mainly supports low level freeform curve and surface operations. Supported are curves and surfaces from scalars to five dimensions as E1/P1 to E5/P5 using the CagdPointType . Pi is a rational (projective) version of Ei, with an additional W coefficient. Polynomial in the power basis have some very limited support as well. Different data structures to hold UV parameter values, control points, vectors, planes, bounding boxes, polylines and polygons are defined as well as the data strcutures to hold the curves and surfaces themselves,

    typedef struct CagdCrvStruct {
        struct CagdCrvStruct *Pnext;
        struct IPAttributeStruct *Attr;
        CagdGeomType GType;
        CagdPointType PType;
        int Length;            /* Number of control points (== order in Bezier). */
        int Order;	    /* Order of curve (only for Bspline, ignored in Bezier). */
        CagdBType Periodic;			   /* Valid only for Bspline curves. */
        CagdRType *Points[CAGD_MAX_PT_SIZE];     /* Pointer on each axis vector. */
        CagdRType *KnotVector;
    } CagdCrvStruct;

    typedef struct CagdSrfStruct {
        struct CagdSrfStruct *Pnext;
        struct IPAttributeStruct *Attr;
        CagdGeomType GType;
        CagdPointType PType;
        int ULength, VLength;	 /* Mesh size in the tensor product surface. */
        int UOrder, VOrder;   /* Order in tensor product surface (Bspline only). */
        CagdBType UPeriodic, VPeriodic;      /* Valid only for Bspline surfaces. */
        CagdRType *Points[CAGD_MAX_PT_SIZE];     /* Pointer on each axis vector. */
        CagdRType *UKnotVector, *VKnotVector;
    } CagdSrfStruct;

Curves and surfaces have a geometric type GType to prescribe the type of entity (such as CAGD_SBEZIER_TYPE for Bezier surface) and a point type PType to prescribe the point type of the entity (such as CAGD_PT_E3_TYPE for three dimensional Euclidean control points). Length and Order slots are used to hold the number of control points in the mesh and or control polygon and the order(s) of the basis functions. Periodic flag(s) are used to denote periodic end conditions. In addition, KnotVector slot(s) are used if the entity exploits Bspline basis functions, or NULL otherwise. The control polygon and/or mesh itself is organized in the Points slot as a vector of size CAGD_MAX_PT_SIZE of vectors of CagdRType s. For surfaces, the mesh is ordered U first and the macros of CAGD_NEXT_U CAGD_NEXT_V , and CAGD_MESH_UV can be used to determine indices in the mesh. All structures in the cagd library can be allocated using New constrcutures (i.e. CagdUVNew or CagdCrfNew , freed using Free destructores (i.e. CagdSrfFree or {CagdBBoxFree}, linked list free using FreeList destructores (i.e. CagdPolylineFreeList ), and copied using copy constructores {i.e. CagdPtCopy or CagdCtlPtCopyList ). This library has its own error handler, which by default prints an error message and exit the program called CagdFatalError . Most globals in this library have a prefix of Cagd for general cagd routines. Prefix of Bzr is used for Bezier routines, prefix of Bsp for Bspline specific routines, prefix of Cnvrt for conversion routines, and Afd for adaptive forward differencing routines.

### Library Functions

Click Here for the list of functions of this library.

## Geometry Library, geom_lib

### General Information

This library handles general computational geometry algorithms and geometric queries such as a distance between two lines, bounding boxes, convexity and convex hull of polygons, polygonal constructors of primitives (cylinders, spheres, etc.), basic scan conversion routines, etc.

### Library Functions

Click Here for the list of functions of this library.

## Model, mdl_lib

### General Information

This library provides the necessary tools to represent and process models. Models are sets of trimmed surfaces forming a closed 2-manifold shell. Models are typically the result of Boolean operations over freeform (trimmed) NURBs geometry but can also be constructed directly or via other schemes.

### Library Functions

Click Here for the list of functions of this library.

## Miscelleneous Library, misc_lib

### General Information

This library holds general miscelleneous functions such as reading configuration files, low level homogeneous matrices computation, low level attributes and general machine specific low level routines. Several header files can be found for this library:

Header (include/*.h) | Functionality
--- | ---
config.h | Manipulation of configuration files (*.cfg files)
dist_pts.h | Enegry based distribution of points.
gen_mat.h | Homogeneous matrices manipulation
getarg.h | Command line parsing for application tools
imalloc.h | Low level dynamic memory functions for IRIT
miscattr.h | Low level attribute related functions
priorque.h | An implementation of a priority queue
xgeneral.h | Low level, machine specific, routines

### Library Functions

Click Here for the list of functions of this library.

## Multi variate functions, prsr_lib

### General Information

This library holds functions to handle functions of arbitrary number of variables. In this context curves (univariate), surfaces (bivariate) and trivariates are special cases. This library provides a rich set of functions to manipulate freeform Bezier and/or NURBs multivariates. This library heavily depends on the cagd an symb libraries. Functions are provided to create, copy, and destruct multivariates, to extract isoparametric lower degree multivariates, to evaluate, refine and subdivide, to read and write multivariates, to differentiate, degree raise, make compatible and convert back and forth to/from curves, surfaces, and trivariates. A multivariate has m orders, m Length prescriptions and, possibly, m knot vectors (if Bspline). In addition it contains an m dimensional volume of control points,

    typedef struct MvarMVStruct {
        struct MvarMVStruct *Pnext;
        struct IPAttributeStruct *Attr;
        MvarGeomType GType;
        CagdPointType PType;
        int Dim;		      /* Number of dimensions in this multi variate. */
        int *Lengths;               /* Dimensions of mesh size in multi-variate. */
        int *SubSpaces;	   /* SubSpaces[i] = Prod(i = 0, i-1) of Lengths[i]. */
        int *Orders;                /* Orders of multi varariate (Bspline only). */
        CagdBType *Periodic;            /* Periodicity - valid only for Bspline. */
        CagdRType *Points[CAGD_MAX_PT_SIZE];     /* Pointer on each axis vector. */
        CagdRType **KnotVectors;
    } MvarMVStruct;

The interface of the library is defined in include/mvar_lib.h . This library has its own error handler, which by default prints an error message and exit the program called MvarFatalError . All globals in this library have a prefix of Mva r.

### Library Functions

Click Here for the list of functions of this library.

## Prsr Library, prsr_lib

### General Information

This library provides the data file interface for IRIT. Functions are provided to read and write data files, both compressed (on unix only, using compress ), and uncompressed, in binary and/or ascii text modes. This library is also used to exchange data between the IRIT server and the display devices' clients. Several header files can be found for this library:

Header (include/*.h) | Functionality
--- | ---
allocate.h | High level dynamic allocation of objects
attribut.h | High level attributes for objects
ip_cnvrt.h | Freeform to polygon and polyline high level conversion
iritprsr.h | Main interface to reading and writing data
irit_soc.h | Socket communication for data exchange

### Library Functions

Click Here for the list of functions of this library.

## Render Library, rndr_lib

### General Information

This library provides a powerful full screen scan conversion Z-buffer tool to process IRIT geometry and convert it into images. This library allows one to scan convert any IRIT geometry including polylines and curves that are converted to skinny polygons on the fly. The library offers regular scan conversion with flat, Gouraud, and Phong shading and several antialiasing filters along with advanced features such as transparency and animation support, and width depth cueing on polyline/curves rendering. The library also provide direct access to the depth Z-buffer as well as a stencil buffer.

### Library Functions

Click Here for the list of functions of this library.

## Symbolic Library, symb_lib

### General Information

This library provides a rich set of functions to symbolically manipulate freeform curves and surfaces. This library heavily depends on the cagd library. Functions are provided to low level add, subtract, and multiply freeform curves and surfaces, to compute fields such as curvature, and to extract singular points such as extremums, zeros, and inflections. High level tools to metamorph curves and surfaces, to compute layout (prisa) of freeform surfaces, to compute offset approximations of curves and surfaces, and to compose curves and surfaces are also provided. The interface of the library is defined in include/symb_lib.h . This library has its own error handler, which by default prints an error message and exit the program called SymbFatalError . Globals in this library have a prefix of Symb for general symbolic routines. Prefix of Bzr is used for Bezier routines, and prefix of Bsp for Bspline specific routines.

### Library Functions

Click Here for the list of functions of this library.

## Trimmed surfaces Library, trim_lib

### General Information

This library provides a set of functions to manipulate freeform trimmed Bezier and/or NURBs surfaces. This library heavily depends on the cagd library. Functions are provided to create, copy, and destruct trimmed surfaces to extract isoparametric curves, to evaluate, refine and subdivide, to read and write trimmed surfaces, degree raise, and approximate using polygonal representations. A trimming surface is defined out of a tensor product surface and a set of trimming loops that trims out portions of the parametric space of the surface,

    typedef struct TrimSrfStruct {
        struct TrimSrfStruct *Pnext;
        IPAttributeStruct *Attr;
        int Tags;
        CagdSrfStruct *Srf;			  /* Surface trimmed by TrimCrvList. */
        TrimCrvStruct *TrimCrvList;		         /* List of trimming curves. */
    } TrimSrfStruct;

Each trimming loop consists of a set of trimming curve segments:

    typedef struct TrimCrvStruct {
        struct TrimCrvStruct *Pnext;
        IPAttributeStruct *Attr;
        TrimCrvSegStruct *TrimCrvSegList;    /* List of trimming curve segments. */
    } TrimCrvStruct;

Each trimming curve segment contains a representation for the curve in the UV space of the surface as well as a representation in the Euclidean space,

    typedef struct TrimCrvSegStruct {
        struct TrimCrvSegStruct *Pnext;
        IPAttributeStruct *Attr;
        CagdCrvStruct *UVCrv;    /* Trimming crv segment in srf's param. domain. */
        CagdCrvStruct *EucCrv;       /* Trimming curve as an E3 Euclidean curve. */
    } TrimCrvSegStruct;

The interface of the library is defined in include/trim_lib.h . This library has its own error handler, which by default prints an error message and exit the program called TrimFatalError . All globals in this library have a prefix of Trim .

### Library Functions

Click Here for the list of functions of this library.

## Trivariate Library, triv_lib

### General Information

This library provides a rich set of functions to manipulate freeform Bezier and/or NURBs trivariate. This library heavily depends on the cagd library. Functions are provided to create, copy, and destruct trivariates, to extract isoparametric surfaces, to evaluate, refine and subdivide, to read and write trivariates, to differentiate, degree raise, make compatible and approximate iso-surface at iso values using polygonal representations. A trivariate has three orders, three Length prescriptions and, possibly, three knot vectors (if Bspline). In addition it contains a three dimensional volume of control points,

    typedef struct TrivTVStruct {
        struct TrivTVStruct *Pnext;
        struct IPAttributeStruct *Attr;
        TrivGeomType GType;
        CagdPointType PType;
        int ULength, VLength, WLength;/* Mesh size in tri-variate tensor product.*/
        int UVPlane;	  /* Should equal ULength * VLength for fast access. */
        int UOrder, VOrder, WOrder;       /* Order in trivariate (Bspline only). */
        CagdBType UPeriodic, VPeriodic, WPeriodic;    /* Valid only for Bspline. */
        CagdRType *Points[CAGD_MAX_PT_SIZE];     /* Pointer on each axis vector. */
        CagdRType *UKnotVector, *VKnotVector, *WKnotVector;
    } TrivTVStruct;

The interface of the library is defined in include/triv_lib.h . This library has its own error handler, which by default prints an error message and exit the program called TrivFatalError . All globals in this library have a prefix of Triv .

### Library Functions

Click Here for the list of functions of this library.

## Triangular Library, trng_lib

### General Information

This library provides a subset of functions to manipulate freeform triangular Bezier and Bspline patches. This library heavily depends on the cagd library. Functions are provided to create, copy, and destruct triangular patches, to extract isoparametric curves, to evaluate, refine and subdivide, to read and write triangular patches, to differentiate, and approximate using polygonal representations. A triangular patch has one prescription of Length and one prescription of Order, the total Order and the length of an edge of the triangle. The control mesh mesh has Length * (Length + 1) / 2 control points,

    typedef struct TrngTriangSrfStruct {
        struct TrngTriangSrfStruct *Pnext;
        struct IPAttributeStruct *Attr;
        TrngGeomType GType;
        CagdPointType PType;
        int Length;		    /* Mesh size (length of edge of triangular mesh. */
        int Order;		      /* Order of triangular surface (Bspline only). */
        CagdRType *Points[CAGD_MAX_PT_SIZE];     /* Pointer on each axis vector. */
        CagdRType *KnotVector;
    } TrngTriangSrfStruct;

The interface of the library is defined in include/trng_lib.h . This library has its own error handler, which by default prints an error message and exit the program called TrngFatalError . All globals in this library have a prefix of Trng .

### Library Functions

Click Here for the list of functions of this library.

## User Library, xtra_lib

### General Information

This library includes user interface related geometrical functions such as ray surface intersection (for mouse click/select operations), etc. The interface of the library is defined in include/user_lib.h .

### Library Functions

Click Here for the list of functions of this library.

## Extra Library, xtra_lib

### General Information

This library is not an official part of IRIT and contains public domain code that is used by routines in IRIT. The interface of the library is defined in include/extra_fn.h .

### Library Functions

Click Here for the list of functions of this library.

## Programming Examples

This chapter describes several simple examples of C programs that exploits the libraries of IRIT. All external function are defined in the include subdirectory of IRIT and one can 'grep' there for the exact include file that contains a certain function name. All C programs in all C files should include 'irit_sm.h' as their first include file of IRIT, before any other include file of IRIT. Header files are set so C++ code can compile and link to it without any special treatment.

### Setting up the Compilation Environment

In order to compile programs that uses the libraries of IRIT, a makefile has to be constructed. Assuming IRIT is installed in /usr/local/irit , here is a simple makefile that can be used (for a unix environment):

    IRIT_DIR = /usr/local/irit

    include $(IRIT_DIR)/makeflag.unx

    OBJS	= program.o

    program: $(OBJS)
    	$(CC) $(CFLAGS) -o program $(OBJS) $(LIBS) -lm $(MORELIBS)

The simplicity of this makefile is drawn from the complexity of makeflag.unx. The file makeflag.unx sets the CC, CFLAGS, LIBS, and MORELIBS for the machined using among other things. Furthermore, makeflag.unx also sets the default compilation rules from C sources to object files. The file makeflag.unx had to be modified once, when IRIT was installed on this system. If the used system is not a unix environment, then the file makefile.unx will have to be replaced with the proper makeflag file. In an OS2 environment, using the emx gcc compiler, the makefile is even simpler since the linking rule is also defined in makeflag.os2:

    IRIT_DIR = /usr/local/irit

    include $(IRIT_DIR)/makeflag.os2

    OBJS	= program.o

    program.exe: $(OBJS)

Finally, here is a proper makefile for Windows NT/ Win 95:

    IRIT_DIR = /usr/local/irit

    include $(IRIT_DIR)/makeflag.wnt

    OBJS	= program.obj

    program.exe: $(OBJS)
            $(IRITCONLINK) -out:program.exe $(OBJS) $(LIBS) $(W32CONLIBS)