CShape Library

Summary

a C library enabling C and C++ applications to use the ShapeToolsLibrary file readers instead of writing their own. Use of this tool will greatly expand the range of mesh files that may be read by a C, or C++, application.

Table of Contents

Compilation Requirements

• a gnu c compiler
• A JNI implementation
• the Make program (to use the supplied example makefiles)

C API

Revision 1

getCShapeMajorMinorVersion(): float

returns the version of the CShape library (current version is 1.0).

addJar(char *pathToJarFile)

Adds a jar file to the java JVM class path.

getVersion() : char *

Returns the version of the shape tools library used, as a character string.

getMajorMinorVersion(): float

Returns version of shape tools libary as a float, encoding the Major and Minor version numbers into the decimal and fractional parts of the number, respectively. Example version 1.2.5 would return the float number 1.2 .

canRead(char *filePath) : int

Returns 1 if the file referred to by filePath can be read, 0 if not.

readCoordinates(char *filePath, float ***coordinates, int *numVertices, int *numDimensions) : int

Reads vertex coordinates of filePath into a 2d array of floats. Returns 1 if the read was successful, 0 if not. On return, the coordinates point points to a 2d array of floats, the value of numVertices value is set to the number of vertcies, and the value of numDimensions is set to the number of vertex dimensions (typically, 3).

readFaces(char *filePath, int ***faceIndices, int *numFaces): int

Read face indices of a surface into an int array. Returns 1 if the read was successful, 0 if not. The first number of each set of face indices is the number of indices that follow. Example faceIndices[0] points to an array containing a triangle consisting of vertices (0,10,5). This array contains these integer elements: [3,0,10,5].

readCoordinatesAndFaces(char *filePath, float ***coordinates, int *numVertices, int *vertexDimension, int ***faceIndices, int *numFaces): int

Reads vertex coordinates and face vertex indices of a surface into an int array. Returns 1 if the read was successful, 0 if not.

Planned for revision 2

readCoordinatesAndAttributes(char *filePath, float **coordinates, float **attributes, char **attributeNames) : int - reads coordiantes, attribute and attribute identifieres into float arrays. Returns 1 if the read was successful, 0 if not.

Examples

Illustrates version 1.0 interface

#include 
#include 
#include 

#include "CShape.h"

int main(int, char **);
void printFloat2dArray(float **, int ,int );
void printInt2dArray(int **, int);
void usage();

int main(int argc, char **argv)
  {
     char * fn = "cube.obj";
     float majorMinorVersion;
     float cShapeVersion;
     float minAllowedCShapeVersion;
     int readable ;
     // set default path to Jar file.
     char *shapeToolsJarPath = 
         "/Users/craig/Documents/Eclipse_Projects/Shape/Libraries/CShape/lib/ShapeTools.jar";

     // test for compatible version of CShape library

     cShapeVersion = getCShapeMajorMinorVersion();
     minAllowedCShapeVersion = 1.0;
     if (cShapeVersion < minAllowedCShapeVersion) {
       printf("CShape version (%f) must exceed version %f\n", cShapeVersion, minAllowedCShapeVersion);
       exit(1);
     }

     if (argc < 2) {
       usage();
       exit(0);
     }
     // get name of shape file to examine
     fn = argv[1]; 

     // set location of Jar containing ShapeTools classes
     if (argc>2) {
       shapeToolsJarPath = argv[2];
     }
     addJar(shapeToolsJarPath);

     // get version of ShapeTools library as float number
     majorMinorVersion = getMajorMinorVersion();
     printf("ShapeTools version number = %f\n",majorMinorVersion);

     // get version of ShapeTools library as string 
     char *stringVersion;
     stringVersion = getVersion();
     printf("ShapeTools version string: %s\n",stringVersion);

     readable = canRead(fn);
     if (readable == 0 ) {
       printf("Cannot read file: %s\n",fn);
       exit(0);
     }


     float **coords;
     int numVertices, numDimensions, numFaces;

     // read coodinates of a shape file
     if (readCoordinates(fn, &coords, &numVertices, &numDimensions)==1) {
       printFloat2dArray(coords, numVertices, numDimensions);
      } else {
       printf("Unable to read coordinates from file %s\n",fn);
      }

     int **faceIndices;

     // read coodinates of a shape file
     if (readFaces(fn, &faceIndices, &numFaces)==1) {
        printInt2dArray(faceIndices, numFaces);
      } else {
       printf("Unable to read indices from file %s\n",fn);
      }

     // read coordinates and faces with one call
     if (readCoordinatesAndFaces(fn, &coords, &numVertices, &numDimensions,
        &faceIndices, &numFaces)==1) {
       printFloat2dArray(coords, numVertices, numDimensions);
       printInt2dArray(faceIndices, numFaces);
      } else {
       printf("Unable to read coordinates and faces from file %s\n",fn);
      }
  }



/**
 * prints a 2 dimensional array of floats
 * if the input array is NULL, nothing is printed.
 *
 * a - the pointer to the data array.
 * dim0Count number of elements in dimension 0.
 * dim1Count number of elements in dimension 1.
*/
void printFloat2dArray(float **a, int dim0Count,int dim1Count)
  {
   int index, dim;

   if (a==NULL) return;

   for (index=0;index