diff --git a/docs/doc-geo.txt b/docs/doc-geo.txt new file mode 100644 index 0000000..7de2fb6 --- /dev/null +++ b/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); + } + } + diff --git a/docs/doc-overview.txt b/docs/doc-overview.txt new file mode 100644 index 0000000..786583b --- /dev/null +++ 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(...); + diff --git a/docs/doc-pld.txt b/docs/doc-pld.txt new file mode 100644 index 0000000..0e53808 --- /dev/null +++ b/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]; + ... + } + ... + + } diff --git a/docs/doc-tex.txt b/docs/doc-tex.txt new file mode 100644 index 0000000..5ce4387 --- /dev/null +++ b/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); + } + } +