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);

        input: 
            pointer to array of Coordinates.
            Can not be NULL.
            
            unsigned int, for quantity of coordinates to be printed.


    bool getmeshheader(struct MeshHeader**, 
                       unsigned int, 
                       const char * const);
        Retrives 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);
        Retrives 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);
    Retrives 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);
            }
    }