From: yakui-lover <yakui-lover@yandex.ru>
Date: Thu, 21 Jul 2016 19:01:14 +0000 (+0100)
Subject: Documented 16_vrs files
X-Git-Url: http://4ch.mooo.com/gitweb/?a=commitdiff_plain;h=848c772e64209441c696de3d8101f7b3b81f1354;p=16.git

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 d5457ae5..abd43c43 100755
--- 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 38b8132d..a0f30620 100755
--- 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