lib3ddevil1/docs/doc-geo.txt

devil1geo.h / devil1geo.c
    Handles files containing geometry.

Functions
    All functions are static but exposed by a function pointer in a constant
    struct called DEVIL1GEO. For example, clients call functions using
    DEVIL1GEO.printheader(...);

    void printheader(struct Header*);
        Show attributes and values of a Header for the package.

        input: pointer to Header, pass by reference of a struct.
               Can not be NULL.

    void printmeshheader(struct MeshHeader*);
        Show attributes and values of a MeshHeader.

        input: pointer to MeshHeader, pass by reference of a struct.
               Can not be NULL.

    void printbatch(struct Batch*);
        Show attribute and values of a Batch and three sample position 
        coordinates.

        input: pointer to Batch, pass by reference of a struct.
               Can not be NULL.

    void printcoordinate(struct Coordinate*, unsigned int);
        Show a specified quantity of Coordinates.
        
        input: 
            pointer to array of Coordinates.
            Can not be NULL.
            
            unsigned int, for quantity of coordinates to be printed.

    bool getheader(struct Header**, const char*);
        Retrieves the header for a geometry package.

            input:
                Pointer of a pointer to struct Header.
                Pass by reference of a pointer to the function.
                The pointer of Header can be NULL and will be set to point to
                a region in the buffer.

                const char*, the buffer containing the whole geometry package.
                Can not be NULL.

    bool getmeshheader(struct MeshHeader**, 
                       unsigned int, 
                       const char * const);
        Retrieves the i-th MeshHeader in a buffer.

        input:
            Pointer of a pointer to MeshHeader.
            Pass by reference of a pointer to the function.
            The pointer of MeshHeader can be NULL and will be set to point to
            a region in the buffer.

            unsigned int, the i-th instance of MeshHeader in the buffer.

            const char*, the buffer containing the whole mesh package.

        output:
            true on success.

            false when failing checks against segmentation faults.
                If parameter 'struct MeshHeader**' is NULL.
                If parameter 'const char*' is NULL.

    bool getbatch(struct Batch*, 
                  unsigned int offset, 
                  const char * const);
        Retrieves the i-th Batch in a buffer.

        input:
            Pointer to a Batch.
            Pass by reference of a struct to the function.
            Can not be NULL.

            unsigned int, the i-th instance of Batch in the buffer.

            const char*, the buffer containing the whole mesh package.

        output:
            true on success.

            false when failing checks against segmentation faults.
                If parameter 'struct Batch*' is NULL.
                If parameter 'const char*' is NULL.

    bool getmesh(struct Mesh*, 
                 unsigned int, 
                 const char*,
                 unsigned int);
    Retrieves the i-th Mesh in a buffer.

        input:
            Pointer to mesh.
            Pass by reference of a struct to the function.

            unsigned int, the i-th instance of Mesh in the buffer.

            const char*, the buffer containing the whole mesh package.

        output:
            true on success.

            false when failing checks against segmentation faults.
                If parameter 'struct Mesh*' is NULL.
                If attribute 'b' of parameter 'struct Mesh' is NULL.
                if parameter 'const char*' is NULL.
                When file size is detected to be too small for a given i-th
                Mesh.

Example logic to interact with all meshes:
    {
        // After the file has been read in.

        // Need to know how many meshes are in the file.
        struct Header *h = (struct Header*)filedata;
        
        // Need to know about a specific mesh (how many batches).
        struct MeshHeader *mh = NULL;
        
        // Need to hold information about mesh.
        struct Mesh m;
        // As a precaution - empty for now.
        m.b = NULL;

        unsigned int i;
        for (i = 0; i < h -> numMesh; i++) {
            DEVIL1GEO.getmeshheader(&mh, i, filedata);
            // Allocate space to hold batch data.
            m.b = (struct Batch*)malloc(sizeof(struct Batch) * (mh -> numBatch));
            if (m.b != NULL) {
                DEVIL1GEO.getmesh(&m, i, filedata, filesize);
                // Do whatever you want with the mesh.
                free(m.b);
            }
    }