min3d Sample Project Study Notes

1. According to the content of "AndroidMainfest.xml", the startup activity is "SplashActivity".

2. The relationships between list items and the activities are:

"Hello, Jupiter" ---> ExampleRotatingPlanets
"Minimal example" ---> ExampleMostMinimal
"Vertex colors" ---> ExampleVertexColors
"Texture" ---> ExampleTextures
"Usage of Vertices class" ---> ExampleVerticesVariations
"Triangles, lines, points" ---> ExampleRenderType
"Camera, frustum (trackball)" ---> ExampleCamera
"Multiple lights" ---> ExampleMultipleLights
"Animating vertices" ---> ExampleAnimatingVertices
"Rendering subset of faces" ---> ExampleSubsetOfFaces
"Assigning textures dynamically" ---> ExampleAssigningTexturesDynamically
"MIP Mapping (on vs. off)" ---> ExampleMipMap
"Texture wrapping" ---> ExampleTextureWrap
"Multiple textures" ---> ExampleMultiTexture
"Texture offset" ---> ExampleTextureOffset
"3D inside layout" --> ExampleInsideLayout
"Load model from .obj file" ---> ExampleLoadObjFile
"Load multiple models from .obj file" ---> ExampleObjFileMultiple
"Load model from .3ds file" ---> ExampleLoad3DSFile
"Load animated .md2 file" ---> ExampleLoadMD2File
"Keyframe animation" ---> ExampleKeyframeAnimation

3. To create a min3d based activity, we have to create a activity class that is derived from RendererActivity class:
public class xxxxx extends RendererActivity.
Then we have to override initScene() and updateScene() functions.

4.1 Library source codes note:

4.1 Functions initScene() and updateScene() are declared in ISceneController interface class (interfaces/ISceneController.java)

4.2 When class RendererActivity (core/RendererActivity.java) is created, it will:
- Save current context to the STATIC class Shared (Shared.java)
- Create a scene object (core/Scene.java) (See 4.3 for more information)
- Create a renderer object (core/Renderer.java) for Android OpenGL surface and save the renderer to the STATIC class Shared.
- Assign the renderer object to the OpenGL surface
- Set render mode to RENDERMODE_CONTINUOUSLY.

4.3 When scene object is created, it will:
- Save the ISceneController Interface class so that it can call the overrided initScene() and updateScene() functions.
- Create a ManagedLightList object (core/ManagedLightList.java) for OpenGL light objects

4.4 The renderer object controls the FINAL output for a OpenGL surface. (More information can be found from Android development documents and other Android OpenGL tutorials) It is a good point to study how min3d displays 3D objects on the screen.
A renderer object has three important functions:
- onSurfaceCreated
- onSurfaceChanged
- onDrawFrame
And onDrawFrame() will be called frequently to update the scrren. (I.e. It is the critical part for performance...)

4.5 When the renderer object is created, it will:
- Save the created scene object to the variable _scene for later use
- Create two scratch buffers (one for Int and another for float (not used yet))
- Create TextureManager (core/TextureManager.java) and save it to the STATIC class Shared (textureManager will delete all existing textures in its list. See reset() of TextureManager class)
- Create other objects for doFps() function. (For statistic)

4.6 When OpenGL surface is created (onSurfaceCreated() is called), it will:
- Make use of a STATIC RenderCaps class (core/RenderCaps.java) to get the OpenGL capability
- save the current GL10 object for internal function use
- Do some initialization (reset())
- Initialize scene object (See 4.7 for more information)

4.7 When init() of scene object is called, it will:
- It will clear all attached Object3d objects (core/Object3d.java)
- Create a CameraVo Object (vos/CameraVo,java)
- Create a background color (vos/Color4Managed.java)
- Enable lighting flag
- Call the override initScene() function (which is defined in your Activity class)

4.8 When a Color4Managed object works as a Color4 object:
- Initialize internal r,g,b,a and float buffer.
- When any r,g,b,a is changed, dirty flag is set
- IDirtyParent parent is not used so onDirty() of scene object is no use

4.9 CameraVo object just setup some Numer3d objects (vos/Number3d.java) and a FrustumManaged object (vos/FrustumManaged.java) for public access.

4.10 Therefore, when the override initScene() function is called,
- You can access the STATIC Shared class to get:
- the scene object to add Object3d objects and/or light objects (vos/Light.java) (see 4.2 and 4.3)
- the TextureManager object (see 4.5) to add textures
- You can access the RenderCaps object (see 4.6) to get OpenGL capability
- Also, some default settings are set (see 4.2, 4.5 and 4.7)

How to build min3d source codes

1. Download source codes from Google code SVN server to your local folder (e.g. min3d)

Suppose Eclipse (Helios Release) and ADT 0.9.7 will be used.

2. In Eclipse, select "File --> Import...", then select "Existing Projects into Workspace", and then click "Next"

3. Set "Select root directory" to your local min3d folder (e.g. min3d) and then you can see "min3dSampleProject1" in the "Project list". Select "Copyprojects into workspace" and click "Finish".

4. Now, we have to change some configurations:
4.1 Under "min3dSampleProject1", select "src_min3d" and select "Properties" from the pop-up menu (Click your left mouse button)
4.2 Under "Resource" item, set the "location" to /src (e.g. min3d/src) and then click "Apply".
4.3 Select "min3dSampleProject1" again and select "Properties" from the pop-up menu. Select "Android" and then select which Android Paltform you want to use and then click "Apply".
4.4 Then select "Java Build Path", select "Libraries" tag and then remove "src...." item, then click "OK".

5. Now Eclipse should build the sample project automatically.