.SET TITLE Æsthe +PAGE +LAYOUT +WINDOW .TITLE;$(TITLE) +TEXT .HEADER 1;Description .IMAGE image/aesthe_2_s.png;Typical aesthe screen .STRONG;Aesthe is 3D scripting development environment controlled by command line with built-in 3D modeller, allowing you to create interactive script-driven 3D simulations or animations. .HEADER 1;License Copyleft (ↄ) 2008 by Tomáš Darmovzal This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see .REF http://www.gnu.org/licenses/; . .HEADER 1;Download +STRONG You can download sources of Aesthe from .REF http://sourceforge.net/projects/aesthe;SourceForge.Net -STRONG .RAW html;SourceForge.net Logo .HEADER 1;Running Aesthe .CODE;Usage: ./aesthe [-h] [-v] [-dx] [-s] +LIST .ITEM; -h --- prints usage help .ITEM; -v --- prints version .ITEM; -dx --- specifies initial console window dimensions .ITEM; -s --- specifies script name to run after aesthe starts -LIST +CODE cd bin ./aesthe -d1024x768 -sexample1 -CODE Command shown above runs demo application - robot arm simulation. .IMAGE image/example1_s.png;Robot arm simulation .HEADER 1;Default control bindings By default mouse and keyboard events are bounded as follows (see script/event.lua for more precise description): .HEADER 2;Mouse events +LIST .ITEM;left button drag - rotates camera around camera point .ITEM;middle button drag - shifts Y coordinate of camera point (moves camera vertically) .ITEM;right button drag - shifts X-Z coordinates of camera points (moves camera in horizontal plane) .ITEM;wheel up/down - increments/decrements distance of camera from camera point .ITEM;CTRL + left button drag - (un)marks vertices and faces of current object .ITEM;CTRL + left button pointed - places new vertex in plane parallel to camera view vector and intersecting camera point .ITEM;SHIFT + left button drag - rotates marked vertices around camera view vector .ITEM;SHIFT + middle button drag - scales uniformly marked vertices with respect to current camera point .ITEM;SHIFT + right button drag - moves marked vertices in plane parallel to camera view vector -LIST .HEADER 2;Keyboard events +LIST .ITEM;F1 - change camera to top orthographic projection .ITEM;F2 - change camera to front orthographic projection .ITEM;F3 - change camera to side orthographic projection .ITEM;F4 - change camera to last used perspective projection .ITEM;F5 - switches between solid and wireframe render .ITEM;F6 - switches between mark view (current object gray, others green, marked elements colored) and material view (shows textures and materials) .ITEM;F11 - loads scene from model file named "checkpoint" .ITEM;F12 - saves whole scene into model file named "checkpoint" -LIST #.HEADER 1;Tutorial .IMAGE image/terrain_s.png;Terrain flood simulation .HEADER 1;Architecture Aesthe is assembled of several modules: +LIST .ITEM;kernel - lightweight interface for all kinds of scene graph operations including creating/destroying basic scene elements, reading/changing their attributes or traversing them. This module is written in ANSI C and does not depends on any other library (excluding stdlib for malloc) and thus can be used separately. .ITEM;render - its primary function is to render kernel scene graph. Current implementation uses OpenGL. +ITEM engine - scripting language engine bound to all other modules allowing full control over their functionality. Currently is used Lua language v. 5.1 ( .REF http://www.lua.org;www.lua.org ) -ITEM .ITEM;console - serves as graphical interface for other modules with user. Creates graphical window which combines command line console for command execution with 3D scene rendered at background. Current implementation depends on SDL library. .ITEM;eximport - module used as (de)serializer of selected branch of scene tree into persistent state (export/import scene to/from file). -LIST .HEADER 2;Kernel Kernel is aesthe module, which holds scene graph and exports simple interface for its manipulation. Kernel interface is designed to allow only primitive-type values passing, thus application developer cannot break scene content with invalid pointer. This interface allows developer to create and destroy basic elements of scene (vertices, faces, objects and textures), set or read element's attributes, traversal through scene graph and some more. Kernel module is written with respect to keep no dependency to any external library (excluding libc, of course), thus you can use it separately in any other 3D GPL project. Kernel is designed as finite automaton, which has set of variables - one for each basic element type - which can be used to store reference to current basic elements passed as parameters to other operations (eg. setting/getting attributes). This set of variables is furthermore provided as stack - that means, you can save current state of variables by .STRONG;push() operation (which duplicates top of the stack) and then again restore previously saved state by calling .STRONG;pop() . Furthermore, you can use concept of .STRONG;registry (similar to processor registry), which serves as array of basic scene elements with user-defined length. You can use this registry as temporary array of elements, which are accessible by numerical index. Registry are bounded to current state, that means if you call pop(), you lose along with current variables also current registry. In C, .STRONG;struct AeKernel is the most important kernel data structure - it holds root of scene graph as well as current variable state stack and registry. This structure has several methods for scene manipulation: .STRONG;CREATE +CODE .STRONG;C: void aekCreate(AeKernel * kernel, AeType type); .STRONG;Lua: kernel.create(kernel.AET_*) -CODE .STRONG;enum AeType +LIST .ITEM;AET_VERTEX - vertex .ITEM;AET_FACE - polygon .ITEM;AET_TEXTURE - texture .ITEM;AET_OBJECT - node of scene tree containing its own faces, vertices and transformation matrix -LIST Creates new element of provided type and sets it as current. All attribute values are reset to its default values. AeType enumeration parameter is provided for chosing type of created element. .STRONG;DESTROY +CODE .STRONG;C: void aekDestroy(AeKernel * kernel, AeType type); .STRONG;Lua: kernel.destroy(kernel.AET_*) -CODE Destroys element set as current value of provided element type. .STRONG;SET / GET +CODE .STRONG;C: void aekSet(AeKernel * kernel, AeType type, AeAttribute attribute, void * value); void aekGet(AeKernel * kernel, AeType type, AeAttribute attribute, void * value, int maxlength); .STRONG;Lua: kernel.set(kernel.AET_*, kernel.AEA_*, value) value = kernel.get(kernel.AET_*, kernel.AEA_*) -CODE Methods for setting/reading attribute values of elements which are set as current. In C, parameter value must reference to value of correct data type (see following list of attribute types). Parameter maxlength states maximal length of read attribute value. It has sense only while reading attribute of variable length (currently only char */string). In other cases is value of this parameter ignored. .STRONG;enum AeAttribute: +LIST .ITEM;AEA_ID - int/number - unique identifier of element .ITEM;AEA_MARK - int/number - mark of element .ITEM;AEA_TEMP - int/number - temporary value of element .ITEM;AEA_POSITION - V3/ae.v3 - position of vertex .ITEM;AEA_NORMAL - V3/ae.v3 - normal vector of surface at vertex (only applicable for already bound vertex) .ITEM;AEA_TEXUV - V2/ae.v2 - texture coordinate for vertex (only applicable for already bound vertex) .ITEM;AEA_SHININESS - float/number - material shininess coefficient (only applicable for already bound vertex) .ITEM;AEA_COLOR - V3/ae.v3 - material color (only applicable for already bound vertex) .ITEM;AEA_AMBIENT - V3/ae.v3 - material ambient RGB reflection (only applicable for already bound vertex) .ITEM;AEA_DIFFUSE - V3/ae.v3 - material diffuse RGB reflection (only applicable for already bound vertex) .ITEM;AEA_SPECULAR - V3/ae.v3 - material specular RGB reflection (only applicable for already bound vertex) .ITEM;AEA_EMISSION - V3/ae.v3 - material emission color (only applicable for already bound vertex) .ITEM;AEA_FILE - char */string - texture file name (applicable for texture only) .ITEM;AEA_TRANSFORM - Matrix/ae.matrix - object transformation (applicable for object only) .ITEM;AEA_NAME - char */string - object name (applicable for object only) .ITEM;AEA_VISIBLE - int/boolean - object visibility flag (applicable for object only) -LIST .STRONG;FIND +CODE .STRONG;C: typedef int (* AeFindCallback)(AeKernel * kernel, int index, void * userdata); int aekFind(AeKernel * kernel, AeType type, AeRule rule, int param, AeFindCallback callback, void * userdata); .STRONG;Lua: count = kernel.find(kernel.AET_*, kernel.AER_*, param, [callback(index)], [userdata]) -CODE Find() is multi-purpose method for any kind of scene elements traversal. First parameter specifies type of basic element for traversal, second and third specifies traversal rule and its optional integer parameter (see AeRule table below). Fourth parameter is optional, if set specifies callback which will be called for every found element. Found element is before invoking callback set as current, so it is often useful to surround find() call with push() and pop() brackets. Optional last parameter is userdata used for callback. Callback prototype takes integer parameter index, which represents index of each found element incremented from zero. Callback returns integer flag used as indicator of premature stop of search loop (zero means continue, nonzero means stop search immediately). Find method returns number of found elements. If callback is not specified (is set to NULL in C), this method can be used to count number of searched elements and/or set last (sometimes only) searched element as current. .STRONG;enum AeRule +LIST .ITEM;AER_ALL - traverse all elements .ITEM;AER_BY_ID - traverse only element with ID attribute equal to param .ITEM;AER_BY_MARK - traverse only elements with MARK attribute equal to param .ITEM;AER_BY_MARK_MASK_ALL - traverse only elements for which MARK attribute value has set ALL bits specified by bitmask param .ITEM;AER_BY_MARK_MASK_ANY - traverse only elements for which MARK attribute value has set ANY bits specified by bitmask param .ITEM;AER_BY_TEMP - traverse only elements with TEMP attribute equal to param .ITEM;AER_BY_TEMP_MASK_ALL - traverse only elements for which TEMP attribute value has set ALL bits specified by bitmask param .ITEM;AER_BY_TEMP_MASK_ANY - traverse only elements for which TEMP attribute value has set ANY bits specified by bitmask param .ITEM;AER_BY_PARENT - traverse objects whose parent is current object (traverse all childs of current object) .ITEM;AER_BY_CHILD - traverse object whose child is current object (traverse parent of current object) .ITEM;AER_BY_FACE - traverse textures or vertices which are bound to current face .ITEM;AER_BY_VERTEX - traverse faces which are bound to current vertex .ITEM;AER_BY_TEXTURE - traverse faces which are bound to current texture -LIST .STRONG;BIND / UNBIND +CODE .STRONG;C: void aekBind(AeKernel * kernel, AeType type1, AeType type2, int order1, int order2); void aekUnbind(AeKernel * kernel, AeType type1, AeType type2); .STRONG;Lua: kernel.bind(kernel.AET_*, kernel.AET_*, [order1], [order2]) kernel.unbind(kernel.AET_*, kernel.AET_*) -CODE These functions are used to (un)bind vertices with faces and faces with textures. Faces-vertices as well as faces-textures has many-to-many relationship, so if you wish to eg. add vertex to 3rd index in face, you must set desired face and vertex as current and call bind(AET_VERTEX, AET_FACE, 3, 0). .STRONG;PUSH / POP +CODE .STRONG;C: void aekPush(AeKernel * kernel); void aekPop(AeKernel * kernel); .STRONG;Lua: kernel.push() kernel.pop() -CODE Function push() duplicates current state at the top of state stack excluding registry values. Function pop() removes top of the state stack (call is successfull only if stack size is > 1). .STRONG;CLEAR +CODE .STRONG;C: void aekClear(AeKernel * kernel, AeType type); .STRONG;Lua: kernel.clear(kernel.AET_*) -CODE This method clears current element of chosen type in top of state stack. It does not destroy the element, only clears its reference in current state. .STRONG;REGISTRY / LOAD / STORE +CODE .STRONG;C: void aekRegistry(AeKernel * kernel, AeType type, int size); void aekLoad(AeKernel * kernel, AeType type, int index); void aekStore(AeKernel * kernel, AeType type, int index); .STRONG;Lua: kernel.registry(kernel.AET_*, size) kernel.load(kernel.AET_*, index) kernel.store(kernel.AET_*, index) -CODE Call registry(type, size) allocates in current state registry array of specified type and size. If size is 0, registry are cleared, if size is larger then previous registry size, then all previous items are preserved. Call load(type, index) replaces current state element of specified type by item in registry array at specified index. Calling of store(type, index) sets current state element reference of specified type into registry at specified index. Indices parameters in load() and store() are boundary-checked. .IMAGE image/aesthe_s.png;Modelling in aesthe .HEADER 1;Documentation .INCLUDE help.dpp -TEXT -WINDOW -LAYOUT +LAYOUT +WINDOW +TEXT Author: .STRONG;Tomáš Darmovzal tomas dot darmovzal at gmail dot you-know-what Generated by DocumentPreProcessor (dpp) - .REF index.dpp;DPP source -TEXT -WINDOW -LAYOUT -PAGE