babycthulu/README

Baby Cthulu is an abstraction interface and management engine.

Throw the .cpp's in tests into a template devkit working project and you'll have
for one of them you'll need a copy of the data files to serve as test sprites.

The 3D tests show the currently limited functionality of the engine.

Sprite capabilities are pretty solid. Multiple sprites of varying sizes can be:
 *Blitted anywhere on the screen
 *Have Alpha channels and such
 *Be animated
 *Stopped

I will add more functionality as I think of it. Esepcially while adding BG
functionality and such. Trying to make the engine compact but useful for users
in the same way Game Maker was useful in making neat nethack like RPG's. 
(Man I want to learn to play that game so bad now...)

Anywho. Enjoi what I've got so far. Try out what you can. Break it send in bugs.


*************************************************************
*
* CTHULU Basics
*
*
----------------------------


1.1 bcthulu Nodes.
Baby Cthulu is first and foremost an API. Thus you must have an access method.
The functions of the babyCthulu interface can be seen in the source.

To create a handle to babyCthulu use the call "bluCreate()" to return a
reference to the babycthulu interface. This is done as so:

	bcthulu* blu = bluCreate();

After this call blu will have a reference to babyCthulu. And will be able to
make calls to the interface.

blu->GFX_Initiate() or Input will begin to initialize the graphics engines and 
will
be ready to handle input and 2D. 

1.2 Graphics
As of currently babyCthulu only handles sprite memory. One could theoretically 
add lower level code to access bg's until this functionality is added.

Graphics memory can be initiated. It has not been implemented however.

1.2.1 Sprites
Lets first  take a look at the sprite memory. Using previous knowledge from the
DS architecture we know that OMA memory has 128 active spaces to hold sprites
of any shape size or format. (Unlike it's predecessor the gba which did not
have enough memory to full implement OAM). 

Lets look at some specs before diving into cthulu
	*0680:0000 is the VRAM base of a total of 656KB. Libnds breaks this up 
	 into 9 banks. 
		Bank A - B: 128KB
		Bank E: 64KB
		Bank F & G: 16KB
		Bank H: 32KB
		Bank I: 16KB
	This spans all of VRAM @680:0000. One needs to map virtual VRAM pointer 
        addresses to the real VRAM for the 2D engine to operate. This is done
	with setBank(parameters);

	That is not in the scope of this manual and if you have not learned it
	you should not be using cthulu.

Babycthulu will automatically set the memory banks dependning on what you're
going to craft in terms of it's the engines. The default initiate will
set the Bank A to the start of sprite memory, and Bank B to the BG.

So to get ready to make sprites go ahead and call blu->GFX_Inititate(); 
Onto the sprite structures. Baby Cthulu handles all sprite data in memory
using structures that represents a fully animated sprite. (This is an advanced
feature, the animation). Go take a look in the babyCthulu header file about
what data you can set into the sprite:
		
		struct bluSprite{
		int init;
		int frame;
		int framerate;
		int counter;
		int x;
		int y;
		int fps;
		int id;
		int priority;
		unsigned short* gfx;
		const unsigned int* tiles;
		const unsigned short* pal;
		unsigned int tlen;
		unsigned int plen;
		SpriteMapping sm;
		SpriteSize sz;
		SpriteColorFormat sfmt;
		};

All of these should be self explanatory (save init, set init to 0 before 
initializing a sprite and it will be set to 1. Do not mess with it after. Set 
frame the framerate and counter to 0 as well). 

Framerate is not a real FPS. The higher this number the slower the animation 
will play the lower the faster it will play. 

Everything else should be explanatory. 

After you construct a struct, pass a reference to it to LDSprite(); this will 
cause the sprite to go into memory. From here you may BltSpr() it.

So how to use this? First use the grit extensions in devkitpro to configure 
your sprites for your program. See the sample gritfiles, the best learning is 
through code. 

Once you do this your tiles should be named after your image. I like to metatile
so one sheet will have all the tiles like SnakeTiles or SnakePal and the len's
respectively. This is the easiest way to manage 2D resources through the gfx 
tools used by the Makefile. 

So as said include the .h files to get the tiles and palette info. Afterwhich 
pass these values into a babyCthulu sprite structure as described above.

After you have set all that up and then set init=0 you are read to begin with 
your sprite.

Pass a call to  GFX_LDSprite() your sprite object and memory will be assigned to
it and the system will declare it initialized. You can now build animations to 
accesorize the sprite object with. And animation is created in much the same 
fashion using a structure object. However it has two slots for large memory
(assigned to the 4MB heap for optimization reasons), which we assign to tiles.

So step one is describing the amount of frames the animation will be (usually
indicated by the size of the sprite sheet). Then the sizes of each frame which
is almost always the size of the base sprite. You then assign it frames the same
way you assign a sprite a tileset. From here you make a call to play animation
with a reference to the base sprite. This call will determine if enough time has
passed to change frames if so it pulls the current tiles out of the basesprite
then slides in the frame number as indicated by the animation table.
Release when done. Pretty simple system.

---
Under Construction:
Started experimenting with the stuff underneath the input queues, trying to 
buff it up a bit so that events are resolved efficiently. Probably need TODO 
some modifications to the whole iprintf() thing. -- On going part of the below.

Going to build queue resolver for when the thing is spinning the framefunc.
When a message is resolved we'll place time markers to see how fast the
engine is actually running. This will be done first probably due to it's 
simplicity. In essence the queue needs to output the average time between 
resolving consecutive events. - Still working on this built a sort of developers
console to start this one off.

Resource manager for the 2D engine. Given a table of sprites and associated
animations (and soon/eventually backgrounds), the resource manager should 
determine how to load and unload a large amount en masse without disturbing
current program flow.

---

If this manual is out of your scope here are some things to get started before
developing with or for babyCthulu:
*GNU C/C++ - if you know Java, Basic, or any language, this will take at most a
day to get up to speed

*Pointers - this is a part of learning C/C++, but they are a fundamental 
concept in computing that many people misinterperate and henceforth misuse.

If you understand those two things you should be fine, if not people will hate
you as you work on this project. 

-Stevie

Project by: Stevie Frederick and Patrick Jennings