Documented 16_vrs files

Also, wrapped header file in #ifdef
and added a check for invalid vrl id get_vrl_by_id

diff --git a/src/lib/16_vrs.c b/src/lib/16_vrs.c
index d5457ae5061307542f1eae4bea8ed71dfdfd7eee..abd43c43cfaf231fd4e223b8456761c2bd303e64 100755 (executable)
--- a/src/lib/16_vrs.c
+++ b/src/lib/16_vrs.c
@@ -1,20 +1,21 @@
 #include <stdio.h>
 #include <fcntl.h>
 #include <ctype.h>
-#include <errno.h>
-#include <assert.h>
 #include <stdint.h>
 #include <stdlib.h>
-#include <string.h>
 #include <unistd.h>
 
-#include "stdlib.h"
 #include "16_vrs.h"
 
+// Read .vrs file into memory 
 int read_vrs(char *filename, struct vrs_container *vrs_cont){
+       // Initialise a local copy of becessary variables
+       // so vrs_cont won't be dirty on error
        int fd;
        unsigned long size;
        unsigned char *buffer;
+       // Open filename, get size of file,
+       // populate the vrs_container if all tests pass
        fd = open(filename, O_RDONLY|O_BINARY);
        // Insert sanity cheks later
        size = lseek(fd, 0, SEEK_END);
@@ -23,25 +24,45 @@ int read_vrs(char *filename, struct vrs_container *vrs_cont){
        read(fd, buffer, size);
        vrs_cont->size = size;
        vrs_cont->buffer = buffer;
-
+       // 0 is an invalid value for ids under vrs specifications,
+       // so it is safe to flush ids to this value
+       vrs_cont->anchor_sprite_id = 0;
+       vrs_cont->current_sprite_id = 0;
        return 0;
 }
 
+// Seek and return a specified .vrl blob from .vrs blob in memory 
 struct vrl_container* get_vrl_by_id(struct vrs_container *vrs_cont, uint16_t id){
        uint16_t *ids; 
        uint32_t *vrl_list;
-       int counter = 0;
        struct vrl_container *vrl_cont;
+       int counter = 0;
+       // If id is invalid, return null
        if(id == 0){
+               // Probably add an error message?
                return 0;
        }
+       // Get id list from .vrs blob (base + offset)
        ids = (uint16_t*)vrs_cont->buffer + (unsigned long)vrs_cont->vrs_hdr->offset_table[VRS_HEADER_OFFSET_SPRITE_ID_LIST];
+       // Loop through the id list until we found the right one or hit the end of the list
+       // Counter is keeping track of the offset(in ids/vrl blobs)
        while(ids[counter] != id && ids[counter]){
                counter++;
        }
+       // Return null if we couldn't find the requested id
+       if(!ids[counter]){
+               // Error message?
+               return 0;
+       }
+       // Get vrl list from .vrs blob (base + offset)
        vrl_list = (uint32_t *)(vrs_cont->buffer + vrs_cont->vrs_hdr->offset_table[VRS_HEADER_OFFSET_VRS_LIST]);
+       // Allocate memory for vrl_cont
        vrl_cont = (struct vrl_container*)malloc(sizeof(struct vrl_container));
+       // Get vrl_header from .vrs (base + offset from vrl_list)
+       // Counter is number of vrls to skip (ids and vrls are aligned according to the .vrs specification)
        vrl_cont->vrl_header = (struct vrl1_vgax_header*)(vrs_cont->buffer + vrl_list[counter]);
+       // Get .vrl size by integer arithmetics (next vrl - current vrl)
+       // Untested. May be an incorrect way to do so
        vrl_cont->size = vrl_list[counter+1] - vrl_list[counter];
        return vrl_cont;
 }

diff --git a/src/lib/16_vrs.h b/src/lib/16_vrs.h
index 38b8132ddd0e71488668ad3d3b8ab94bcb166f42..a0f306201855ef5b01109ffe5daeb2b150d2d291 100755 (executable)
--- a/src/lib/16_vrs.h
+++ b/src/lib/16_vrs.h
@@ -1,14 +1,32 @@
+#ifndef __16_VRS__
+#define __16_VRS__
+
+#include <stdint.h>
 #include "hw/vga/vrl.h"
 #include "hw/vga/vrs.h"
 
+// Container for .vrs files loaded in memory with useful info
+// Includes: 
+// + size of the .vrs blob in memory
+// + pointer to the blob/vrs header
+// + id of the curent (shown) animation
+// + id of the first sprite of the curret animation (supplementary)
+// + id of the current (shown) sprite
+
 struct vrs_container{
        unsigned long size;
        union{
                unsigned char *buffer;
                struct vrs_header *vrs_hdr;
        };
+       uint16_t anchor_sprite_id;
+       uint16_t current_sprite_id; 
 };
 
+// Container for .vrl files loaded in memory with useful info
+// Includes:
+// + size of the .vrl blob in memory
+// + pointer to the blob/vrl header
 struct vrl_container{
        unsigned long size;
        union{
@@ -17,5 +35,23 @@ struct vrl_container{
        };
 };
 
+// Read .vrs file into memory
+// In:
+// + char *filename - name of the file to load
+// + struct vrs_container *vrs_cont - pointer to the vrs_container 
+// to load the file into
+// Out:
+// + int - 0 on succes, 1 on failure
 int read_vrs(char *filename, struct vrs_container *vrs_cont);
+
+// Seek and return a specified .vrl blob from .vrs blob in memory
+// In:
+// + struct vrs_container *vrs_cont - pointer to the vrs_container 
+// with a loaded .vrs file
+// + uint16_t id - id of the vrl to retrive
+// Out:
+// struct vrl_container* - a pointer to a vrl_container with a pointer
+// to the requested .vrl blob
 struct vrl_container* get_vrl_by_id(struct vrs_container *vrs_cont, uint16_t id);
+
+#endif