Add comments in the example program.

Update readme.
Add tap.ogg.

3 files changed, 83 insertions, 3 deletions

diff --git a/README.md b/README.md
index 99af39d..66763a1 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,33 @@
 # SMELT
 _SMELT -- The engine behind BLR3+._
+
 _Now has its own repo._
 
 A bad, bad reference is now in the doc folder.
+
 Currently only the SDL version is available.
+
 A D3D version will be put into construction _soon_.
 
+Building
+--------
+Building the SDL version of SMELT is only officially tested
+on debian sid and debian jessie.
+
+Theoretically the SDL version should work on Windows
+with little modification :)
+
+Building dependencies on debian-based systems:
+
+>libfreetype6-dev libopenal-dev libsdl2-dev libpng12-dev
+>libjpeg62-turbo-dev libvorbis-dev libogg-dev
+
+To build a module, just run make in the corresponding folder.
+
+The example must be built last.
+
 TODOs:
+------
 * Example code.
 * Better documentation.
 * D3D version.
diff --git a/examples/smelt_test.cpp b/examples/smelt_test.cpp
index 915321a..99a9aa9 100644
--- a/examples/smelt_test.cpp
+++ b/examples/smelt_test.cpp
@@ -1,3 +1,20 @@
+/*
+ * The smelt testing/example program.
+ * Resources required:
+ * SpriteSheet.png lcdfont.anm
+ * tap.ogg
+ * 稲田姫樣に叱られるから.ogg(not included, just the original track in TH10)
+ * A truetype font is also required.
+ *
+ * Expected result:
+ * "bitmap font test" on the top in a 5*8 LCD font.
+ * A fixed display of SpriteSheet.png.
+ * A 3D-rotating SpriteSheet.png.
+ * A rotating part of SpriteSheet.png with the
+ * vertices color changed.
+ * A circular indicator with its value changing.
+ * Two lines of text in a truetype font.
+ */
 #include "smelt.hpp"
 #include "smentity.hpp"
 #include "smindicator.hpp"
@@ -22,6 +39,7 @@ smBMFont fonttest;
 smTTFont ttftest;
 SMSFX sfx,bgm;
 void sigHandler(int pm)
+//This function handles the SIGSEGV signal, just ignore it.
 {
 	sm->smLog("Oops, the application ate a piece of DEAD BEEF!\n");
 #if defined(__GNUC__) && !defined(MINGW_BUILD)
@@ -35,17 +53,26 @@ void sigHandler(int pm)
 	exit(1);
 }
 bool doingNothing()
+//This function is called every frame.
 {
+	//we play the tapping sound every 0.37 seconds.
+	//do not ask why 0.37 seconds.
 	d+=sm->smGetDelta();
 	if(d>0.37){sm->smSFXPlay(sfx);d=0;}
+
+	//We render the 3D scene to a render target.
 	sm->smRenderBegin3D(60,testtrg);
+	//camera position and rotation.
 	static float pos[3]={0,0,600};
 	static float rot[3]={0,0,-30};
+	//set the camera transformation.
 	sm->sm3DCamera6f2v(pos,rot);
+	//clear the rendering target
 	sm->smClrscr(0xFF000000);
+	//render the 3d entity.
 	e3d->render9f(0,0,0,theta,0,1,0,1);
-	//printf("%.2f\n",sm->smGetFPS());
 #define pp printf("(%.0f,%.0f,%.0f) (%.0f,%.0f,%.0f)\n",pos[0],pos[1],pos[2],rot[0],rot[1],rot[2]);
+	//camera manipulation key bindings.
 	if(sm->smGetKeyState(SMK_W)==SMKST_HIT)pos[1]+=10,pp;
 	if(sm->smGetKeyState(SMK_S)==SMKST_HIT)pos[1]-=10,pp;
 	if(sm->smGetKeyState(SMK_D)==SMKST_HIT)pos[0]+=10,pp;
@@ -58,34 +85,54 @@ bool doingNothing()
 	if(sm->smGetKeyState(SMK_J)==SMKST_HIT)rot[0]-=5,pp;
 	if(sm->smGetKeyState(SMK_U)==SMKST_HIT)rot[2]+=5,pp;
 	if(sm->smGetKeyState(SMK_O)==SMKST_HIT)rot[2]-=5,pp;
+	//set the rendering target to the screen.
 	sm->smRenderEnd();
 	sm->smRenderBegin2D();
+	//clear the screen.
 	sm->smClrscr(0xFF000000);
+	//render a test string with the bitmap font.
 	fonttest.render(0,0,0,ALIGN_LEFT,NULL,"bitmap font test");
+	//render a test string with the truetype font.
 	ttftest.render(0,500,0xFFFFFFFF,ALIGN_LEFT);
+	//render the content of the previously used rendering
+	//target to the screen.
 	quad.tex=sm->smTargetTexture(testtrg);
 	sm->smRenderQuad(&quad);
+	//render the testing 2d entity.
 	e2d->render(400,300,theta);
 	double t;
+	//set the value of the circular indicator and render it.
 	ictest.setValue(modf(theta,&t));
 	ictest.render(400,300);
 	theta+=0.02;
+	//render a testing quad.
 	quad.tex=tex;
 	sm->smRenderQuad(&quad);
 	sm->smRenderEnd();
+	//screenshot test.
 	if(sm->smGetKeyState(SMK_Y)==SMKST_HIT)sm->smScreenShot("wtf.bmp");
 	return false;
 }
 int main()
 {
+	//set the signal handler.
 	signal(SIGSEGV,sigHandler);
+	//get the pointer to the smelt core.
 	sm=smGetInterface(SMELT_APILEVEL);
+	//set the video mode.
 	sm->smVidMode(800,600,true);
+	//set the update function.
 	sm->smUpdateFunc(doingNothing);
+	//set the window title.
 	sm->smWinTitle("SMELT Example App");
+	//set the FPS policy.
 	sm->smSetFPS(FPS_VSYNC);
+	//now we can initialize the smelt engine.
 	sm->smInit();
 
+	//As anm files are always packed in dtp files, only the
+	//load-from-memory version is implemented.
+	//We load the bitmap font here.
 	FILE *pFile;DWORD size,rsize;char *buff;
 	pFile=fopen("lcdfont.anm","rb");
 	if(!pFile)return 0;
@@ -99,15 +146,19 @@ int main()
 	fonttest.setBlend(BLEND_ALPHABLEND);
 	fonttest.setScale(1.);
 
+	//load the truetype font.
 	if(!ttftest.loadTTF("/usr/share/fonts/truetype/wqy/wqy-microhei.ttc",18))sm->smLog("ttf load error!");
 
+	//load the texture.
 	tex=sm->smTextureLoad("SpriteSheet.png");
+	//load the sound files.
 	sfx=sm->smSFXLoad("tap.ogg");
 	bgm=sm->smSFXLoad("稲田姫樣に叱られるから.ogg");
+	//set loop points of the bgm.
 	sm->smSFXSetLoopPoint(bgm,0xED80,0x1E0400);
-	//sm->smTextureLock(tex,0,0,64,320,false);
-	//sm->smTexutreUnlock(tex);
+	//create the rendering target for the 3d scene.
 	testtrg=sm->smTargetCreate(256,320);
+	//create the entities.
 	e2d=new smEntity2D(tex,0,0,101,101);
 	e2d->setCentre(50,50);
 	e2d->setColor(0xFFFFFFFF,0);
@@ -116,6 +167,7 @@ int main()
 	e2d->setColor(0xFF0000FF,3);
 	e3d=new smEntity3D(tex,0,0,256,320);
 	e3d->setCentre(128,160);
+	//set up the quad.
 	quad.v[0].x=128;quad.v[0].y=128;
 	quad.v[1].x=384;quad.v[1].y=128;
 	quad.v[2].x=384;quad.v[2].y=448;
@@ -127,11 +179,17 @@ int main()
 	for(int i=0;i<4;++i)quad.v[i].col=0xFFFFFFFF;
 	quad.blend=BLEND_ALPHABLEND;
 	quad.tex=tex;
+	//initialize the indicator.
 	ictest.init(100,5,0x80,tex,smTexRect(151,264,2,8));
+	//set the string of the truetype font renderer.
 	ttftest.updateString(L"truetype font test\nNow Playing: 稲田姫樣に叱られるから by ZUN");
+	//play the bgm.
 	sm->smSFXPlay(bgm,100,0,1.,true);
+	//enter the main loop.
 	sm->smMainLoop();
+	//deinitialize the smelt engine
 	sm->smFinale();
+	//free the resources we used.
 	delete e2d;
 	ictest.deinit();
 	fonttest.close();
@@ -142,6 +200,7 @@ int main()
 	sm->smTargetFree(testtrg);
 	sm->smSFXFree(sfx);
 	sm->smSFXFree(bgm);
+	//destroy the smelt interface.
 	sm->smRelease();
 	return 0;
 }
diff --git a/examples/tap.ogg b/examples/tap.ogg
new file mode 100755
index 0000000..1ef00b0
--- /dev/null
+++ b/examples/tap.ogg