I’ll comment on other issues later as I just fried my brain and knocked this out in a couple of hours. This is kind of what I was talking about. It’s a start and we could hash out the organization and other administration at everyones leisure.
This link to v1.17BL_KetsjiEmbedStart.cpp. is where you can view the CVS log for this file and also view the source code. This is good if you don’t want to download the complete source and it is suitable for a start. Click on some of the links to get familiar with what they do, it’s all pretty simple.
Note, I only cover the load_game_data() function here there is so much more to do with this file though. There are 670 lines of code and I only covered 20.
BL_KetsjiEmbedStart.cpp =
BL_KetsjiEmbedStart.cpp contains two functions, load_game_data() and
StartKetsjiShell().
== Blender Load Game Data ==
1) Reads a .blend file and loads data into BlendFileData structure
Line # 86
static BlendFileData *load_game_data(char *filename)
"BlendFileData" is a type of data called a Structure. All data is of a certain
type, it could be an number or a character among others types. A type identifies
what you data you are working with. A structure is a colletction of data types that
are related. Think of a character in your game, each character has a name, age,
weight, eye color and so on. Now think of a structure like a drivers license or a
identification card and call it "ID" this is what "BlendFileData" is a, collection
of data that, drum roll, contains the stuff in your .blend file.
"load_game_data" and "filename" are pointers. A pointer is also a type of data
and what this type does is point to the location of the address of a variable or
other data in memory. This doesn't contain the data, just the address where the
data lives or resides. We give it names so it is easier to read and understand.
One last thing, we use "*" in front of the pointer name to find the value stored in
the pointer. If you didn't use the "*" you would get the address of the pointer not
the address to the data that the pointer contains. Make sense?
So what happens is we have the address to where the load_game_data() function is and
the address to where the "filename" is and a nice structure "BlendFileData" to store
it in a nice neat package for use. Cool.
Line #87
BlendReadError error;
So you know what a structure is. What this does is create an instance of the
structure "BlendReadError". We give it a name called error so that if there is an
error reading the file we can find it with "error". So now "error" is a variable
which holds error information.
Line #90
FILE* file = fopen(filename,"rb");
We talked a little bit about pointer so here we have a nice exmple of how to create
one. "FILE" is a data type and and the "*" immediately after the data type means we
are creating a pointer named "file". Do not confuse this with accessing the address
of the data stored in "file" as noted above where the "*" asterisk is placed in
front of the pointer name. So to keep things moving along we assign the address
where the results of the fopen() function are stored to the "file" pointer.
Rember the "*filename" pointer above, well this is where we use the actual data to
open the file for reading "r", and that it is a binary file "b". Remember your
.blend file is a binary file.
Line #91
BlendFileData *bfd = 0;
HELP: I guess here we are clearing any old address stored in "bfd".
Line #92
if (file)
Check to see if there is a pointer called "file".
Line #93
fseek(file, 0L, SEEK_END)
The fseek() function allows you to read a file beginning at any point in the file.
We can see that it takes three parameters. "file" is the pointer to the file being
searched. "0L" is the offset or how far along move from the start. The letrer "L"
after the number means that this number is of type long. What this means is that a
normal number of type "int" can only store values betwee -32767 and 32767. If you
need bigger numbers one thing to do is use "long" or other number types that have
more storage space. You have to use "long" here. An finally "SEEK_END" means
measure the offset from the end of the file. So this just sets the position to the
end of the file.
Line #95
int len= ftell(file)
ftell() tells how many bytes there are from the fseek() location to the beginning
of the file. Above we set "SEEK_END" as the file position and the offset to 0 and
now "len" convieniently holds the length of bytes in the file as a "long". Again
we know how fast the .blend file can grow so we need lots of space for the length.
Line #96
fseek(file, 0L, SEEK_SET)
Simple enough, this sets the seek position to the start of the file.
Line #97
char* filebuffer= new char[len]
Guess what this does. It creates a pointer of type char named "filebuffer" and
assigns the memory location of the array "char" to it. We havent touched on arrays
yet and many would say that they need discussion before pointers, but we need some
progress here. An array is a series of emements of one data type. The key here is
the word "series" because arrays have an index where you can find your data stored.
Our array "char" has as many spaces to hold data as there are bytes in our .blend
file. The brackets identify "char" as and array and "len" is the number of
elements in the array. Let's not forget that this array holds data of type "new".
HELP: WHAT IS THE "NEW" DATA TYPE. THE COMMENT MIGHT TELL? We access the elements in the array by the
index of the element. Our array "char" starts with char[0] and goes all the way to
char[len] where "len" is the size of our .blend file in bytes. If I want the 2473th
item in array we would use char[2473]. Easy enough.
Line #98
int sizeread = fread(filebuffer, len, 1, file);
fread() is used to read binary data. Binary dats is what we have ben using with
our .blend file all along. Notice a pattern here, I do. The parameters that fread()
take are "filebuffer" which is the pointer to the address where the binary data is
o be written in memory. "len", AGAIN, is the size of the data in bytes, "1"
represents the number of chunks to be written, and file is the file to be read.
We now read one chenk of data with a length of "len" from the "file" into the
"filebuffer". We also store the number of items sucessfully read in the variable
"sizeread".
Line #99
if (sizeread == 1)
This checks to see that we acutally read 1 chunk of data ad like we wanted in line
# 98.
Line # 101
bfd = BLO_read_from_memory(filebuffer, len, &error);
Were getting close to the end of the function here. What we are doing here is
checking that the data was actually read from the file into memory. I haven't found
the "BLO_read_from_memory() but I am guessing that it reads a chunk of binary data
from memory starting at the address in "filebuffer" and if there are any errors it
grabbs the address where it can store the location of the error data.
Here is a bit more on pointers. "error" is a pointer that holds the address of
data it points to. To find the address of "error" we use "&" before the pointer
name. Lets rephrase that. *error is the address where the error data is stored.
&error is the address where we store the address to the error data.
Think of it this way. I live in a huge appartment complex. You need to know
where I live so I tell you to check mailbox #386. Inside this mailbox you will find
the address to my appartment. Mailbox #386 is like &error, it is only the address
to my mailbox. My apartment #9876 is stored in this mailbox and this is just like
*error. Hopefully that makes sense.
In summary we read the data from memory and store it in the structure "bfd" for
use.
Line #103
fclose(file)
If you open something, close it when you are done. Not doing this is like leaving
the cap of the milk jug, things go sour.
Line #106
if (!bfd)
Something happened and there is no "bfd" we didn't read the data from memory.
What do we do?
Line # 107
printf("Loading %s failed: %s
", filename, BLO_bre_as_string(error));
Crash and burn, baby! Loading "filename" failed: ERROR. Just to be complete, the
printf() function prints data to the screen of console. In this case ir prints some
text as well as data. %s tells the function that the data is a string and we tell
it what string by the use of "filemane". The second %s is string data and that is
the error message. I can only geuss right how that the error is stored as binary
data and that the function BLO_bre_as_string() makes it human readable.
Line#110
return bfd;
We have now read the .blend file by using this function. This line tells the
function to make the data available for use outside the function.
I wont post any more text here but I do plan so see if I can find my Wiki username and password so I can add it there. Please proof this and give comments on layout and style. Of course everything can change when we get going but we just need to get going, and now.
Kind Regards,
honeycomb
