lib3ddevil1/docs/doc-tex.txt

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 getheader(struct TexturePack**, const char*);
        Retrieves the header for a texture package.

        input:
            Pointer to a pointer of TexturePack.
            This is a pass by reference of a pointer to the function.
            The pointer to TexturePack may be NULL and will be set to point to 
            a region in the buffer.

            const char*, the buffer containing the whole texture pack file.
            Can not be NULL.

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