From 6b62b9d00f581e0833fd147a3f2b8e24d0ff6eb1 Mon Sep 17 00:00:00 2001 From: Josh Holtrop Date: Mon, 23 Nov 2009 02:24:30 +0000 Subject: [PATCH] added initial documentation (in progress), renamed ag:: functions with "Static" in the middle to have "Static" at the end git-svn-id: svn://anubis/anaglym/trunk@191 99a6e188-d820-4881-8870-2d33a10e2619 --- .todo | 3 +- Engine.cc | 64 ++++++- ag.cc | 77 ++++----- ag.h | 62 +++---- doc/index.html | 346 ++++++++++++++++++++++++++++++++++++++ tests/ballstairs.lua | 2 +- tests/bowling.lua | 3 +- tests/cannon.lua | 2 +- tests/cratestack.lua | 2 +- tests/managed_objects.lua | 2 +- 10 files changed, 476 insertions(+), 87 deletions(-) create mode 100644 doc/index.html diff --git a/.todo b/.todo index cb1ddaa..271309f 100644 --- a/.todo +++ b/.todo @@ -1 +1,2 @@ -- fix bug with wfobj objects changing appearance of managed objects +- finish bowling demo +- finish ag and std documentation diff --git a/Engine.cc b/Engine.cc index 599ba17..fe797d5 100644 --- a/Engine.cc +++ b/Engine.cc @@ -165,6 +165,7 @@ bool Engine::load(const char * program) if (path == "") { cerr << "Couldn't locate " FONT_NAME << endl; + return false; } else { @@ -387,23 +388,23 @@ int Engine::getCamera(lua_State * L) int Engine::registerEventHandler(lua_State * L) { int argc = lua_gettop(L); - if (argc == 2 && lua_isfunction(L, 1) && lua_isstring(L, 2)) + if (argc == 2 && lua_isstring(L, 1) && lua_isfunction(L, 2)) { - string event = lua_tostring(L, 2); + string event = lua_tostring(L, 1); if (event == "update") - doRegisterHandler(1, update); + doRegisterHandler(2, update); else if (event == "update_overlay") - doRegisterHandler(1, update_overlay); + doRegisterHandler(2, update_overlay); else if (event == "key_down") - doRegisterHandler(1, key_down); + doRegisterHandler(2, key_down); else if (event == "key_up") - doRegisterHandler(1, key_up); + doRegisterHandler(2, key_up); else if (event == "mousebutton_down") - doRegisterHandler(1, mousebutton_down); + doRegisterHandler(2, mousebutton_down); else if (event == "mousebutton_up") - doRegisterHandler(1, mousebutton_up); + doRegisterHandler(2, mousebutton_up); else if (event == "mouse_motion") - doRegisterHandler(1, mouse_motion); + doRegisterHandler(2, mouse_motion); } return 0; } @@ -527,6 +528,51 @@ void Engine::getScreenSize(int * width, int * height) void Engine::drawText(const char * text, GLfloat r, GLfloat g, GLfloat b, int ptsize, float x, float y) { +{ // sanity check framebuffer and env info +printf("GL err was %04x\n", glGetError()); + +GLint r, g, b, a, depth, sten, aux, dbl; +glGetIntegerv(GL_RED_BITS, &r); +glGetIntegerv(GL_GREEN_BITS, &g); +glGetIntegerv(GL_BLUE_BITS, &b); +glGetIntegerv(GL_ALPHA_BITS, &a); +glGetIntegerv(GL_DEPTH_BITS, &depth); +glGetIntegerv(GL_STENCIL_BITS, &sten); +glGetIntegerv(GL_AUX_BUFFERS, &aux); +glGetIntegerv(GL_DOUBLEBUFFER, &dbl); +printf("framebuffer: rgba %d %d %d %d, depth %d, stencil %d, aux bfr %d, double bfr %d\n", + r, g, b, a, depth, sten, aux, dbl); + +GLint a_test, a_func; float a_ref; +glGetIntegerv(GL_ALPHA_TEST, &a_test); +glGetIntegerv(GL_ALPHA_TEST_FUNC, &a_func); +glGetFloatv(GL_ALPHA_TEST_REF, &a_ref); +printf("alpha testing: %d, func %04x ref %f\n", a_test, a_func, a_ref); + +GLint blend, b_src, b_equ, b_dst; +GLfloat b_c[4]; +glGetIntegerv(GL_BLEND, &blend); +glGetIntegerv(GL_BLEND_SRC, &b_src); +glGetIntegerv(GL_BLEND_EQUATION, &b_equ); +glGetIntegerv(GL_BLEND_DST, &b_dst); +glGetFloatv(GL_BLEND_COLOR, b_c); +printf("blending: %d, src %04x equ %04x dst %04x color %.2f %.2f %.2f %.2f\n", + blend, b_src, b_equ, b_dst, b_c[0], b_c[1], b_c[2], b_c[3]); + +GLint logic, logmode, mask[4], cull, cullmode, front, draw; +glGetIntegerv(GL_COLOR_LOGIC_OP, &logic); +glGetIntegerv(GL_LOGIC_OP_MODE, &logmode); +glGetIntegerv(GL_COLOR_WRITEMASK, mask); +glGetIntegerv(GL_CULL_FACE, &cull); +glGetIntegerv(GL_CULL_FACE_MODE, &cullmode); +glGetIntegerv(GL_FRONT_FACE, &front); +glGetIntegerv(GL_DRAW_BUFFER, &draw); +printf("draw env: logic %d logmode %04x, mask %d %d %d %d, cull %d cullmode %04x frontface %04x, drawbuffer %04x\n", + logic, logmode, mask[0], mask[1], mask[2], mask[3], cull, cullmode, front, draw); + +printf("GL err was %04x\n", glGetError()); +printf("***\n"); +} checkGLError(); m_font->FaceSize(ptsize); glPushAttrib(GL_ENABLE_BIT | GL_TEXTURE_BIT); diff --git a/ag.cc b/ag.cc index f8c493d..9702303 100644 --- a/ag.cc +++ b/ag.cc @@ -21,46 +21,41 @@ namespace ag void register_functions(lua_State * L) { static const luaL_Reg functions[] = { - { "print", print }, - { "println", println }, - { "loadModel", loadModel }, - { "loadStaticModel", loadStaticModel }, - { "sleep", sleep }, - { "startFrame", startFrame }, - { "endFrame", endFrame }, - { "setCamera", setCamera }, - { "getCamera", getCamera }, - { "elapsedTime", elapsedTime }, + { "clearEventHandler", clearEventHandler }, { "doPhysics", doPhysics }, { "drawObjects", drawObjects }, + { "elapsedTime", elapsedTime }, + { "endFrame", endFrame }, + { "exit", exit }, + { "getCamera", getCamera }, + { "getScreenSize", getScreenSize }, + { "import", import }, + { "isKeyDown", isKeyDown }, + { "loadModel", loadModel }, + { "loadModelStatic", loadModelStatic }, + { "loadTexture", loadTexture }, + { "print", print }, + { "println", println }, + { "registerEventHandler", registerEventHandler }, + { "setAutoDrawObjects", setAutoDrawObjects }, + { "setAutoEndFrame", setAutoEndFrame }, { "setAutoPhysics", setAutoPhysics }, { "setAutoStartFrame", setAutoStartFrame }, - { "setAutoEndFrame", setAutoEndFrame }, - { "setAutoDrawObjects", setAutoDrawObjects }, - { "isKeyDown", isKeyDown }, - { "registerEventHandler", registerEventHandler }, - { "clearEventHandler", clearEventHandler }, - { "exit", exit }, - { "import", import }, - { "loadTexture", loadTexture }, - { "getScreenSize", getScreenSize }, - { "drawText", drawText}, - { "getTextSize", getTextSize}, - { "drawLine", drawLine}, - { "drawRect", drawRect}, - { "fillRect", fillRect}, - { "drawImage", drawImage}, + { "setCamera", setCamera }, +// { "sleep", sleep }, + { "startFrame", startFrame }, - { "createBox", createBox}, - { "createStaticBox", createStaticBox}, - { "createSphere", createSphere}, - { "createStaticSphere", createStaticSphere}, - { "createPlane", createPlane}, - { "createStaticPlane", createStaticPlane}, - { "createCylinder", createCylinder}, - { "createStaticCylinder", createStaticCylinder}, - { "createCapsule", createCapsule}, - { "createStaticCapsule", createStaticCapsule}, + /* managed object functions */ + { "createBox", createBox }, + { "createBoxStatic", createBoxStatic }, + { "createCapsule", createCapsule }, + { "createCapsuleStatic", createCapsuleStatic }, + { "createCylinder", createCylinder }, + { "createCylinderStatic", createCylinderStatic }, + { "createPlane", createPlane }, + { "createPlaneStatic", createPlaneStatic }, + { "createSphere", createSphere }, + { "createSphereStatic", createSphereStatic }, { NULL, NULL } }; @@ -197,7 +192,7 @@ namespace ag return loadModelSpecify(L, false); } - int loadStaticModel(lua_State * L) + int loadModelStatic(lua_State * L) { return loadModelSpecify(L, true); } @@ -543,7 +538,7 @@ namespace ag return createBoxSpecify(L, false); } - int createStaticBox(lua_State * L) + int createBoxStatic(lua_State * L) { return createBoxSpecify(L, true); } @@ -567,7 +562,7 @@ namespace ag return createSphereSpecify(L, false); } - int createStaticSphere(lua_State * L) + int createSphereStatic(lua_State * L) { return createSphereSpecify(L, true); } @@ -604,7 +599,7 @@ namespace ag return createPlaneSpecify(L, false); } - int createStaticPlane(lua_State * L) + int createPlaneStatic(lua_State * L) { return createPlaneSpecify(L, true); } @@ -629,7 +624,7 @@ namespace ag return createCylinderSpecify(L, false); } - int createStaticCylinder(lua_State * L) + int createCylinderStatic(lua_State * L) { return createCylinderSpecify(L, true); } @@ -654,7 +649,7 @@ namespace ag return createCapsuleSpecify(L, false); } - int createStaticCapsule(lua_State * L) + int createCapsuleStatic(lua_State * L) { return createCapsuleSpecify(L, true); } diff --git a/ag.h b/ag.h index e3dee28..dc2f696 100644 --- a/ag.h +++ b/ag.h @@ -7,49 +7,51 @@ namespace ag { void register_functions(lua_State * L); - int print(lua_State * L); - int println(lua_State * L); - int loadModel(lua_State * L); - int loadStaticModel(lua_State * L); - int sleep(lua_State * L); - int startFrame(lua_State * L); - int endFrame(lua_State * L); - int setCamera(lua_State * L); - int getCamera(lua_State * L); - int elapsedTime(lua_State * L); + + /* Lua interfaces */ + int clearEventHandler(lua_State * L); int doPhysics(lua_State * L); int drawObjects(lua_State * L); + int elapsedTime(lua_State * L); + int endFrame(lua_State * L); + int exit(lua_State * L); + int getCamera(lua_State * L); + int getScreenSize(lua_State * L); + int import(lua_State * L); + int isKeyDown(lua_State * L); + int loadModel(lua_State * L); + int loadModelStatic(lua_State * L); + int loadTexture(lua_State * L); + int print(lua_State * L); + int println(lua_State * L); + int registerEventHandler(lua_State * L); + int setAutoDrawObjects(lua_State * L); + int setAutoEndFrame(lua_State * L); int setAutoPhysics(lua_State * L); int setAutoStartFrame(lua_State * L); - int setAutoEndFrame(lua_State * L); - int setAutoDrawObjects(lua_State * L); - int isKeyDown(lua_State * L); - int registerEventHandler(lua_State * L); - int clearEventHandler(lua_State * L); - int exit(lua_State * L); - int import(lua_State * L); - int loadTexture(lua_State * L); - int getScreenSize(lua_State * L); + int setCamera(lua_State * L); + int sleep(lua_State * L); + int startFrame(lua_State * L); /* 2D overlay functions */ - int drawText(lua_State * L); - int getTextSize(lua_State * L); + int drawImage(lua_State * L); int drawLine(lua_State * L); int drawRect(lua_State * L); + int drawText(lua_State * L); int fillRect(lua_State * L); - int drawImage(lua_State * L); + int getTextSize(lua_State * L); /* managed object creation functions */ int createBox(lua_State * L); - int createStaticBox(lua_State * L); - int createSphere(lua_State * L); - int createStaticSphere(lua_State * L); - int createPlane(lua_State * L); - int createStaticPlane(lua_State * L); - int createCylinder(lua_State * L); - int createStaticCylinder(lua_State * L); + int createBoxStatic(lua_State * L); int createCapsule(lua_State * L); - int createStaticCapsule(lua_State * L); + int createCapsuleStatic(lua_State * L); + int createCylinder(lua_State * L); + int createCylinderStatic(lua_State * L); + int createPlane(lua_State * L); + int createPlaneStatic(lua_State * L); + int createSphere(lua_State * L); + int createSphereStatic(lua_State * L); namespace object { diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..8793301 --- /dev/null +++ b/doc/index.html @@ -0,0 +1,346 @@ + + + + + Anaglym Documentation + + + + +

Anaglym Documentation

+ +

+Anaglym exposes a Lua library named ag which contains functions +for interfacing with the Engine. +In addition to the ag library, there is a std library +which contains a "standard library" of Lua functions that do not directly +interface with the Anaglym engine. +The library functions are documented below. +

+ + + +
+ + +

ag library

+ + +

clearEventHandler

+

ag.clearEventHandler(event_name)

+

+This function removes a Lua callback function from being associated +with the engine event specified. +event_name should be one of the following strings: +

+

+ + +

doPhysics

+

ag.doPhysics()

+

+This function invokes the physics processing part of the engine. +It is invoked automatically every update step if the "AutoPhysics" +mode is enabled; this mode is enabled by default. +See setAutoPhysics for more information. +

+ + +

drawObjects

+

ag.drawObjects()

+

+This function instructs the engine to draw all visible objects. +It is invoked automatically every update step if the "AutoDrawObjects" +mode is enabled; this mode is enabled by default. +See setAutoDrawObjects +for more information. +

+ + +

elapsedTime

+

elapsed_msec = ag.elapsedTime()

+

+This function returns the number of milliseconds that have elapsed +since the beginning of the program. +

+ + +

endFrame

+

ag.endFrame()

+

+This function signals the engine that all drawing is complete for the +current update frame. +It is invoked automatically if the "AutoEndFrame" mode is enabled; +this mode is enabled by default. +See setAutoEndFrame for more +information. +

+ + +

exit

+

ag.exit()

+

+This function instructs the engine to exit. +Internally, this function enqueues an "exit" event on the event +queue to be processed by the engine. +This means that Lua code following the call to exit() +will be executed and callbacks to other events may still be called. +The engine should exit within one update step. +

+ + +

getCamera

+

eye_x, eye_y, eye_z, center_x, center_y, center_z, up_x, up_y, up_z = ag.getCamera()

+

+This function returns the camera position (eye coordinates), +focus position (center coordinates), and up vector for the current +camera settings. +

+ + +

getScreenSize

+

width, height = ag.getScreenSize()

+

+This function returns the dimensions of the engine window, in pixels. +

+ + +

import

+

ag.import(lua_source_name)

+

+This function instructs the engine to import a Lua source file named +lua_source_name, which should be a string specifying the +name of the Lua library without the ".lua" extension. +Source files are searched for relative to the folder containing the +hosted script first, then relative to the engine library folder. +The import() function can be used to load Lua code that +is broken into separate source files. +

+ + +

isKeyDown

+

result = ag.isKeyDown(key)

+

+This function returns a boolean value for whether or not the key +given by key is currently pressed or not. +key should be a string corresponding to a key name. +See keys for key names. +

+ + +

loadModel

+

object = ag.loadModel(model_name [, scale])

+

+This function loads an object file and returns the object loaded. +If the returned value is nil, loading of the object failed. +model_name should be a string specifying the base name of +the model file, without the ".obj" extension. +Models are searched for relative to the folder containing the +hosted script first, then relative to the engine library folder. +scale is an optional parameter that defaults to 1.0. +

+ + +

loadModelStatic

+

object = ag.loadModelStatic(model_name [, scale])

+

+loadModelStatic() is the same as loadModel(), with +the exception that the object loaded is created as a static object. +A static object can still be placed with +setPosition() and +setRotation(). +A static object will participate in collision detection when +physics computations are performed, however a static object will not +be moved by any colliding objects. +

+ + +

loadTexture

+

texture = ag.loadTexture(texture_name)

+

+This function loads a texture file from the file system and returns +a Lua reference to the loaded texture. +nil is returned if loading the texture fails. +The texture_name should contain the file extension, since +multiple formats are supported (.jpg, .png, .bmp, etc...). +Textures are searched for relative to the folder containing the +hosted script first, then relative to the engine library folder. +

+ + +

print

+

ag.print(args...)

+

+This function prints its arguments to the standard output. +On Windows, this output stream may be redirected to a file (stdout.txt). +Example usage: +

local x, y, z = my_obj:getPosition()
+ag.print("my_obj position: (", x, ", ", y, ", ", z, ")")
+
+

+ + +

println

+

ag.println(args...)

+

+Identical to print() but automatically prints a newline ("\n") +after printing the arguments. +

+ + +

registerEventHandler

+

ag.registerEventHandler(event_name, handler)

+

+This function registers a Lua callback function (handler) +to be called when the engine event specified by event_name +occurs. +There can be only one registered handler per event, so if a previous +Lua function was registered for event_name, it will be +overwritten to call the new handler. +event_name should be one of: +

+

+ + +

setAutoDrawObjects

+

ag.setAutoDrawObjects(enable_flag)

+

+This function sets the "AutoDrawObjects" mode. +enable_flag should be true or false. +If AutoDrawObjects mode is enabled, then all visible objects in the +engine will be drawn automatically every update step. +If it is not enabled, one can call +ag.drawObjects() +to draw all visible objects in the scene. +

+ + +

setAutoEndFrame

+

ag.setAutoEndFrame(enable_flag)

+

+This function sets the "AutoEndFrame" mode. +enable_flag should be true or false. +If AutoEndFrame mode is enabled, then +ag.endFrame() +will be invoked automatically after executing the update +and update_overlay Lua callback functions. +

+ + +

setAutoPhysics

+

ag.setAutoPhysics(enable_flag)

+

+This function sets the "AutoPhysics" mode. +enable_flag should be true or false. +If AutoPhysics mode is enabled, then collision detection and +physics processing is performed automatically on every update step. +If it is not enabled, one can call +ag.doPhysics() +to perform physics updates. +

+ + +

setAutoStartFrame

+

ag.setAutoStartFrame(enable_flag)

+

+This function sets the "AutoStartFrame" mode. +enable_flag should be true or false. +If AutoStartFrame mode is enabled, then +ag.startFrame() +will be invoked automatically prior to executing the update and +update_overlay Lua callback functions. +

+ + +

setCamera

+

ag.setCamera(eye_x, eye_y, eye_z [, center_x, center_y, center_z [, up_x, up_y, up_z] ])

+

+This function sets the camera position (eye coordinates), focus point +(center coordinates), and up vector. +If the center coordinates or up vector are not specified, their values +are unchanged from the previous invocation of setCamera(). +The default center point is (0, 0, 0). +The default up vector is (0, 0, 1). +

+ + +

startFrame

+

ag.startFrame()

+

+This function instructs the engine to begin drawing a frame. +It is not necessary to call this function if the "AutoStartFrame" +mode is enabled. +See ag.setAutoStartFrame(). +

+ +
+ + +

std library

+ +
+ + +

Object creation functions

+ + +

createBox

+ + +

createBoxStatic

+ + +

createCapsule

+ + +

createCapsuleStatic

+ + +

createCylinder

+ + +

createCylinderStatic

+ + +

createPlane

+ + +

createPlaneStatic

+ + +

createSphere

+ + +

createSphereStatic

+ +
+ + +

Object member functions

+ + +

obj:setPosition(x, y, z)

+ + + diff --git a/tests/ballstairs.lua b/tests/ballstairs.lua index 6486759..b91bcfb 100755 --- a/tests/ballstairs.lua +++ b/tests/ballstairs.lua @@ -1,6 +1,6 @@ function init() - arena = ag.loadStaticModel("boxarena") + arena = ag.loadModelStatic("boxarena") ball = ag.loadModel("checkerball") ball:setPosition(-7, 7.4, 12) ball2 = ball:clone() diff --git a/tests/bowling.lua b/tests/bowling.lua index cd9f224..fe748c9 100644 --- a/tests/bowling.lua +++ b/tests/bowling.lua @@ -13,7 +13,6 @@ function init() end end - --local ground = ag.loadStaticModel("crate", 10) local ground = ag.createPlane(0, 0, 1, 0) ground:setColor(0.8, 0.5, 0.0) ground:setPosition(0, 0, -10) @@ -29,7 +28,7 @@ function init() -- local crate = ag.loadModel("crate") -- crate:setPosition(0, 20, 10) - crate_texture = ag.loadTexture("crate.png") +-- crate_texture = ag.loadTexture("crate.png") end function mousebutton_down_event(button) diff --git a/tests/cannon.lua b/tests/cannon.lua index e9ca10e..de69779 100644 --- a/tests/cannon.lua +++ b/tests/cannon.lua @@ -12,7 +12,7 @@ function init() end end - local ground = ag.loadStaticModel("crate", 10) + local ground = ag.loadModelStatic("crate", 10) ground:setPosition(0, 0, -10) ag.setCamera(levels/2, -2*levels, levels, 0, 0, levels/2, 0, 0, 1) camx, camy, camz, cx, cy, cz = ag.getCamera() diff --git a/tests/cratestack.lua b/tests/cratestack.lua index cb9c323..cbc9772 100644 --- a/tests/cratestack.lua +++ b/tests/cratestack.lua @@ -18,7 +18,7 @@ function init() end end - ground = ag.loadStaticModel("crate", 10) + ground = ag.loadModelStatic("crate", 10) ground:setPosition(0, 0, -10) ag.setCamera(2, -12, 8, 0, 0, 2, 0, 0, 1) end diff --git a/tests/managed_objects.lua b/tests/managed_objects.lua index b7ce070..11971ae 100644 --- a/tests/managed_objects.lua +++ b/tests/managed_objects.lua @@ -1,7 +1,7 @@ function init() local crate_texture = ag.loadTexture("checker.jpg") - local ground = ag.createStaticPlane(0, 0, 1, 0) + local ground = ag.createPlaneStatic(0, 0, 1, 0) ground:setColor(0.2, 1.0, 0.2) ground:setTexture(crate_texture) ag.setCamera(10, -10, 10, 0, 0, 0)