Previous Next Table of Contents

4. Using the Library

This section contains a programmers guide to "libshelly". If you do not plan to program with "libshelly" you may want to skip over to section Using shelly.

It would be handy if you would print a copy of "shellyl.h" or just open it for browsing.

4.1 General Usage

If you want to use "libshelly" to create a shell, you have to fill an argument structure that contains all necessary parameters of the generator ("SLarguments") first.

Then, one of the generating functions ("SLCalcShell", "SLCalcShellNodule", "SLCalcShellGC") may be called. These functions will allocate memory for all points of the shell, fill the memory with coordinates and give you a pointer to it.

The generated points are collected in lists. The lists of points are collected in another list (a list of lines). There is no additional information available now, just the coordinates of the points. For shells generated with "SLCalcShellNodule" (or for easier writing of some triangle based file formats) you might want to call functions that generate additional information.

"SLTriangulate", for instance, assigns points of two lines to triangles. This seems easy for two lines containing the same amount of points, but it is more complex if the points may be unevenly distributed and the numbers of points do not equal. "SLTriangulate" uses the s-values stored in the points structures. Since "SLCalcShellGC" does not store this information into the points, calling "SLTriangulate" on lists created with "SLCalcShellGC" is not possible. This means that not every output format is possible within the "GenCurve" mode.

"SLCreateIndex" creates all index information for writing a file in a format that needs numbered points, lines and triangles, like T3D. You may want to take a look at "WriteT3DFile" in the file "src/rdwrt.c" for an example of how to use the indices.

After writing the shell to hard-disk or displaying it you may free the occupied memory, using the various "SLFree"-functions.

4.2 Structures

"SLarguments" is the structure that contains all parameters and some status information.

"SLgcpoint" is a single point of a generating curve, used by the "GenCurve"-mode.

"SLshell" is the basic structure of the shell. Each shell is split into several lists (lines) of points. Each "SLshell" structure points to such a list.

"SLpoint" is the structure that forms a list of coordinates.

"SLpindex", "SLlindex", "SLtindex" contain index information.

"SLtriangle" contains pointers to the three points of a triangle.

4.3 Functions

"SLCalcShell", "SLCalcShellNodule" and "SLCalcShellGC" create a shell in the according mode ("Normal", "Nodule" or "GenCurve").

"SLTriangulate" and "SLCreateIndex" create index information.

The "SLFree"-functions free the associated items.

For more in depth use of the library you might want to call "SLCalcLine", "SLCalcPoint" and their nodule-mode counterparts. (If you want to change parameters randomly between the points to achieve a more realistically looking shell, for instance.) These functions do not create shells, but lines or single points of a shell, according to the parameters. They will not be explained more deeply here. Take a look at the source.


Previous Next Table of Contents