anki-3d-engine/docs/manual

**AnKi 3D Engine**

Copyright (C) 2009, 2010 Panagiotis Christopoulos-Charitos

http://www.ancient-ritual.com

[email protected]

.. contents:: Table of Contents


=======
License
=======

Anki is dual licensed. The first option is GLPv3 and the second commercial
license. If you want to use* AnKi to make opensource software (licensed under
GLPv3) then AnKi is provited to you for free but if you want to use it* for
non-GPLv3 licensed software then you have to apply for a commercial license.

\*: as a whole or parts of the source


========
Building
========

AnKi build system is very Linux specific (GNU make only) at the moment. It
also requires a few extra development libraries.

To download the latest release from the SVN repository type:

$ svn checkout http://anki-3d-engine.googlecode.com/svn/trunk/ anki


Required libraries
------------------

AnKi requires a few up to date versions of some libraries. The libraries are:
  
- Bullet Physics
- SDL ver 1.3
- SDL_image
- GLEW
- boost

So before generating makefiles and building AnKi you have to download (from
the revision control repositories) and build some of the above libraries.
Instructions follow. You can alternately use the script
*download-and-build-externals.sh*
  

Bullet Physics
~~~~~~~~~~~~~~

From now on the AnKi requires the Bullet physics library. You need CMake and
SVN installed.

#) $ cd <path to anki>
#) $ cd ..
#) $ svn checkout http://bullet.googlecode.com/svn/trunk/ bullet
#) $ cd bullet
#) $ cmake -DBUILD_SHARED_LIBS=OFF -DCMAKE_BUILD_TYPE=Release
#) $ make


SDL ver 1.3
~~~~~~~~~~~

We need SDL ver 1.3 for creating OpenGL 3.x context. You need to have the
Mercurial and autoconf installed.

#) $ cd <path to anki>
#) $ cd ..
#) $ hg clone http://hg.libsdl.org/SDL SDL
#) $ cd SDL
#) $ ./autogen.sh
#) $ ./configure
#) $ make
 

SDL_image
~~~~~~~~~

SDL_image automates the loading of images (png, jpeg etc). Just like SDL,
SDL_image needs Mercurial and autoconf installed.

#) $ cd <path to anki>
#) $ cd ..
#) $ hg clone http://hg.libsdl.org/SDL_image SDL_image
#) $ cd SDL_image
#) $ ./autogen.sh
#) $ ./configure
#) $ make


GLEW
~~~~

The latest GLEW provides us with OpenGL 3 and 4 extensions. Needs SVN and a 
Unix environment (for step 5).

#) $ cd <path to anki>
#) $ cd ..
#) $ svn co https://glew.svn.sourceforge.net/svnroot/glew/trunk/glew glew
#) $ cd glew
#) $ make extensions
#) $ make


boost
~~~~~

Boost is pretty big to download and build from SVN, also it doesnt need to be in
the lattest version. The Linux distribution's version will do the trick so
install it using the packet manager of your choice.

In Ubuntu type: $ sudo apt-get install libboost<version>-dev-all


Building AnKi and optionally generating makefiles
-------------------------------------------------

Inside the build directory you can find 4 build targets containing GNU
makefiles. If you want to build AnKi just type "make".

**WARNING**: Sometimes I forget to update all the targets. The debug is always 
updated though.

AnKi uses a build system that generates the above makefiles. This build system
is no longer part of AnKi and its located in a different repository. This tool
is called gBuildSystem and you can find it in
http://godlike-projects.googlecode.com/svn/trunk/gBuildSystem. Downloaded it
using SVN:

$ svn checkout http://godlike-projects.googlecode.com/svn/trunk/gBuildSystem


gBuildSystem only purpose is to re-generate these makefiles in case you have
made changes in code structure (renaming/moving/deleting/adding files) or in the
includes (#include) or your have the external libs in different paths.
gBuildSystem requires the gen.cfg.py files (something like CMakeLists.txt).
gen.cfg.py format is pretty straightforward and minimal.

If you want to generate the makefile for the debug target (for example) do the
following:

#) $ cd <path to anki>/build/debug
#) $ <path to gBuildSystem>/gbs.py
#) $ make

And the build process will begin. 
  

======
Assets
======

Currently there are no assets (models, textures, materials etc) so even if you
build it, the application will fail to run.


===================
System requirements
===================

The engine requires:

- GPU with shader model 4
- Linux OS
- Proprietary GPU drivers

Development rig: Ubuntu 10.04, AMD Radeon 4870 w/ Catalyst 10.04. So it should
be working on similar systems.


==============================================
Generating source code documentation (doxygen)
==============================================

The AnKi source code uses doxygen style comments in almost every file. To
generate the documentation you need doxygen (http://www.doxygen.org/). From a
terminal type:

#) $ cd docs
#) $ doxygen doxyfile

Then open doxygen.html to see it.
  

============
Coding style
============

Every project has some rules and here are some things to remember while coding
AnKi.


Types
-----

The classes, structs, typedefs, enums etc must be capitalized eg *ThisIsAClass*


Functions & variables
---------------------

All functions (including class methods) and all variables are mixed case.

All functions should have a verb inside them eg *doSomething()*

All variables should not have verbs eg *oneVariable*


Constants, macros & enumerators
-------------------------------

All constants, macros and enumerators are capital with undercores eg *#define 
MACRO(x)* or *const int ONE_INT = 10;*

All the constants should be defined without using the preprocessor eg dont write
*#define ONE_INT 10*

All enumerators have the first letters of the enum as prefix eg
*enum CarColors { CC_BLUE, CC_GREEN };*


Parenthesis, braces, comas & operators
--------------------------------------

After opening parenthesis and before closing it there is no spaces, same for
square brackets. Before and after an operator there is always a space

eg *((mat1 * 10) + 10)* or *setWidth(100)* or *int arr[100 + 1];*

After a coma there is a space eg *setSize(10, 20)*


Order in class definitions
--------------------------

class 

{

  friends
	
  pre-nested (very rare)
	
  nested
	
  properties
	
  public
	
  protected
	
  private 
	
}

inlines


Material shader program naming
------------------------------

dnspgke:

- diffuse mapping
- normal mapping
- specular mapping
- parallax mapping
- grass like
- hardware skinning
- environment mapping


Naming shortcuts
----------------

This list contains some of the naming shortcuts we use in AnKi. This is because
we are bored to type:

- Array                        : arr
- Animation                    : anim
- Application                  : app
- Buffer                       : buff
- Camera                       : cam
- Color                        : col
- Controller                   : ctrl
- Current                      : crnt
- Feature                      : feat
- Fragment                     : frag
- Framebuffer Attachable Image : fai
- Geometry                     : geom
- Location                     : loc
- Material                     : mtl
- Matrix                       : mat
- Number                       : num
- Physics                      : phy
- Position                     : pos
- Property                     : prop
- Quadrilateral                : quad
- Quaternion                   : quat
- Resource                     : rsrc
- Rotation                     : rot
- Shader                       : shdr
- Shader Program               : shaderProg or sProg
- Skeletal Animation           : sAnim
- Skeleton                     : skel
- Text                         : txt
- Texture                      : tex
- Transformation               : trf
- Transform Feedback           : trffb
- Translation                  : tsl
- Triangle                     : tri
- Utility                      : util
- Variable                     : var
- Vector                       : vec
- Vertex                       : vert

Anything else should be typed full.


Controllers
-----------

The controllers are part of the scene node objects. They control the node's
behaviour. 

They have an input (script, animation, etc) and they control a scene node. The
naming convention of the controllers is:

<what the controller controls><the input of the contoller>Ctrl

For Example:

MeshSkelNodeCtrl A Mesh is controlled by a SkelNode


Submitting patches
------------------

If you want to update/patch a file (for example Main.cpp) do:

- Make the changes on that file
- Save the differences in a file using "svn diff Main.cpp > /tmp/diff"
- E-mail the "diff" file with subject "[PATCH] Main.cpp updates"


=========
ToDo list
=========

- Continue working on the new coding style in shaders
- Changes in the blending objects problem. The BS will become one stage and the
  PPS will be divided in two steps. The first will apply the SSAO and the EdgeAA
  in the IS_FAI and the second will do the rest
- The second Physics demo: Create a box that is geting moved by the user. It has
  to interact with the other boxes
- Set the gravity of a certain body to a lower value and see how it behaves
- In the Ragdoll bullet demo try to change the distances of the bodies
- Ask in the bullet forum:
	- How to make floating particles like smoke. But first try with one body and
	  manualy setting the gravity
	- What the btCollisionObject::setActivationState takes as parameter?
- Re-enable the stencil tex in Ms.cpp and replace all the stencil buffers with
  that (Smo, Bs) to save memory
- See if the restrictions in FBOs (all FAIs same size) still apply
- See what happens if I write *#pragma anki attribute <randName> 10* where
  randName does not exist. Do the same for tranform feedback varyings