Merge branch 'feature/documentation' of scuti/lib3ddevil1 into master

docs/doc-geo.txt

@@ -0,0 +1,132 @@
+
+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 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);
+            }
+    }
+

docs/doc-overview.txt

@@ -0,0 +1,23 @@
+
+lib3ddevil1
+A C library for handling Devil May Cry 1 HD Collection PC file formats.
+These formats are little endian.
+
+Design/Restrictions
+    Library functions do not: 
+        - allocate memory on the heap 
+        - operate on files
+        - convert endianness
+
+Pseudo-Namespaces
+    Library functions are callable through a struct of function pointers.
+    For example:
+        // Print header of a .pld file.
+        DEVIL1PLD.printheader(...);
+
+        // Print header of a texture pack.
+        DEVIL1TEX.printheader(...);
+
+        // Print header of a mesh pack.
+        DEVIL1GEO.printheader(...);
+

docs/doc-pld.txt

@@ -0,0 +1,56 @@
+
+devil1pld.h / devil1pld.c
+    Handles .pld files.
+
+File Format
+    PLDs are simple packages of different files, and do not contain a table
+    of contents. The header consists only of the number of files packaged
+    and the offsets from the beginning of the .pld that marks the starting
+    location of the file.    
+
+Functions
+    All functions are static but exposed by a function pointer in a constant
+    struct called DEVIL1PLD. For example, clients call functions using
+        DEVIL1PLD.getheader(..., ...);
+
+    bool getheader(struct PldHeader*, const char*);
+        Places file header into the struct pointed at by the first parameter
+        from the information given in by the second parameter.
+
+        inputs: pointer to a struct, pointer to file data
+                Neither parameter should be NULL.
+
+        output: true or false, whether or not operation succeeds or fails.
+                Will return false if one or both of the parameters are NULL
+                pointers.
+                Will return false if the attribute numOffset is less than 0-
+                i.e file is not valid.
+
+    int sizeofsector(struct PldHeader*, unsigned int i, unsigned int max);
+        Returns the size of the i-th file packed in the pld.
+
+        inputs: pointer to a struct, i-th element in pld, file size
+
+        output: (-1), [0, maximum value of int)
+                -1 indicates an invalid input.
+
+    void printheader(struct PldHeader*);
+        Shows contents of a PLD header in standard output.
+
+        inputs: pointer of a struct
+
+Example logic to iterate through a .pld
+    {
+        ...
+        // Get information about the file
+        struct PldHeader h;
+        DEVIL1PLD.getheader(&h, data);
+        
+        unsigned int i;
+        for (i = 0; i < h.numOffset; i++) {
+            const char *currentfile = filedata + h.offset[i];
+            ...
+        }
+        ...
+    
+    }

docs/doc-tex.txt

@@ -0,0 +1,132 @@
+
+devil1tex.h / devil1tex.c
+    Handles texture packages.
+
+File Format
+    Texture packags can be identified with a string "\0 2 3 T" as a starting 
+    tag.
+
+Functions
+    All functions are static but exposed by a function pointer in a constant
+    struct called DEVIL1TEX. For example, clients call functions using
+    DEVIL1TEX.printheader(...);
+
+    
+    void printheader(struct TexturePack*);
+        Prints the attributes and values of a header to standard output.
+
+        input: pointer to a TexturePack struct.
+
+    void printbatchdesc(struct TextureBatchDescriptor*);
+        Prints the attributes and values if a TextureBatchDescriptor to
+        standard output.
+
+    bool getbatchdesc(struct TextureBatchDescriptor**, 
+                      unsigned int, 
+                      const char *, 
+                      unsigned int);
+        Retrieves the i-th TextureBatchDescriptor from a buffer.
+
+        input:
+            Pointer to a pointer of TextureBatchDescriptor. 
+            This is pass by reference of a pointer to the function. 
+            The pointer to TextureBatchDescriptor can be NULL and will be 
+            set to point to a region in the const char*.
+
+            unsigned int, the i-th instance of a TextureBatchDescriptor in
+            the const char*.
+
+            const char*, the buffer containing the whole texture pack file.
+
+            unsigned int, the size of the buffer.
+
+        output:
+            true when successfully retrieving a pointer to 
+            TextureBatchDescriptor.
+
+            false when unsuccesful in retrieving a pointer to 
+            TextureBatchDescriptor; failed checks against segmentation 
+            faults.
+                When const char* (buffer) is NULL.
+
+                When the location of the TextureBatchDescriptor will exceed
+                the size of a buffer.
+
+    bool getbatch(struct TextureBatch**,
+                  unsigned int,
+                  const char*
+                  unsigned int);
+        Retrieves i-th instance of a TextureBatch from a buffer.
+
+        input:
+            Pointer to a pointer of TextureBatch.
+            This is pass by reference of a pointer to the function.
+            The pointer to a TextureBatch can be NULL and will be set to
+            point to a region in the const char*.
+
+            unsigned int, the i-th instance of a TextureBatch in the 
+            const char*.
+
+            const char*, the buffer containing the whole texture pack file.
+
+            unsigned int, the size of the buffer.
+
+        output:
+            true on success.
+
+            false when failing checks against segmentation faults.
+                When const char* is NULL.
+
+                When the location of the Texture Batch will exceed the size
+                of the buffer.
+
+    bool gettextures(struct Texture*,
+                     unsigned int,
+                     const char*,
+                     unsigned int);
+        Retrieves textures of the i-th batch from a buffer.
+
+        input:
+            Pointer to Texture. This can be an array of Textures.
+            This parameter can not be NULL.
+
+            unsigned int, the i-th instance the TextureBatch containing
+            the files.
+
+            const char*, the buffer containing the whole texture pack file.
+
+            unsigned int, size of the buffer.
+
+        output:
+            true on success.
+
+            false when failing checks against segmentation faults.
+
+Example logic to interact with all textures:
+    {
+        // After reading the file in...
+        // Need to know how many batches are in the package.
+        struct TexturePack *p = (struct TexturePack*)filedata;
+        
+        // Need to know about each batch in the package.
+        struct TextureBatchDescriptor *d = NULL;
+
+        struct Texture *t = NULL;
+
+        unsigned int i;
+        for (i = 0; i < p -> batchNumber; i++) {
+            DEVIL1TEX.getbatchdesc(&d, i, filedata, filesize);
+
+            // Batch descriptor tells how many textures are in the batch.
+            t = (struct Texture*)
+                malloc(sizeof(struct Texture) * (d -> texNumber));
+            DEVIL1TEX.gettextures(t, i, filedata, filesize);
+
+            // There are now textures in 't'.
+            for (j = 0; j < d -> texNumber; j++) {
+                // Do whatever you want with however many textures there are.
+            }
+            free(t);
+        }
+    }
+