Initial documentation pass

Add a nice doxygen file.

.gitignore

@@ -1,4 +1,5 @@
 build/
+documentation/
 *.kdev4
 *~
 *.swp

Doxyfile

@@ -0,0 +1,8 @@
+PROJECT_NAME=OpenRW
+OUTPUT_DIRECTORY=documentation/
+INPUT=.
+RECURSIVE=YES
+EXCLUDE=tests
+GENERATE_LATEX=NO
+GENERATE_HTML=YES
+HTML_OUTPUT=

README.markdown

@@ -32,6 +32,10 @@ File viewer for game data, open the folder containing "gta3.exe" and it will loa
 
 Currently only supports viewing instance data, pending some rewriting.
 
+## Documentation
+
+Run Doxygen on the included Doxyfile to generate documentation.
+
 ## Things to do
 
 * Make it work on Windows (shouldn't be too difficult for anyone with CMake and C++ experience)

rwengine/include/WorkContext.hpp

@@ -31,6 +31,9 @@ public:
 	}
 };
 
+/**
+ * @brief Interface for background work
+ */
 class WorkJob
 {
 	WorkContext* _context;
@@ -55,6 +58,12 @@ public:
 // TODO: refactor everything to remove this.
 class GameWorld;
 
+/**
+ * @brief A worker queue that runs work in the background.
+ *
+ * Work is added with queueJob, once it completes the job is added
+ * to the _completeQueue to be finalised on the "main" thread.
+ */
 class WorkContext
 {
 	std::queue<WorkJob*> _workQueue;

rwengine/include/ai/CharacterController.hpp

@@ -84,6 +84,11 @@ public:
 // TODO: Refactor this with an ugly macro to reduce code dup.
 class WeaponItem;
 
+/**
+ * @brief Activities for CharacterController behaviour
+ *
+ * @todo Move into ControllerActivities.hpp or equivelant
+ */
 namespace Activities {
 	struct GoTo : public CharacterController::Activity {
 		DECL_ACTIVITY( GoTo )

rwengine/include/data/ObjectData.hpp

@@ -57,7 +57,7 @@ struct CharacterData
 };
 
 /**
- * Data shared by vehicles types.
+ * @brief Stores vehicle data loaded from item definition files.
  */
 struct VehicleData
 {

rwengine/include/data/WeaponData.hpp

@@ -41,14 +41,16 @@ struct WeaponData
 };
 
 /**
- * @brief The WeaponScan struct
+ * @brief simple object for performing weapon checks against the world
- * Represents a scene query against a ray
+ *
- * or shape used to determine what to damage.
+ * @todo RADIUS hitscans
  */
 struct WeaponScan
 {
 	enum ScanType {
+		/** Instant-hit ray weapons */
 		HITSCAN,
+		/** Area of effect attack */
 		RADIUS,
 	};
 

rwengine/include/engine/Animator.hpp

@@ -13,7 +13,8 @@ class Model;
 class ModelFrame;
 
 /**
- * @brief The Animator class handles updating frame matricies for animations.
+ * @brief calculates animation frame matrices, as well as procedural frame
+ * animation.
  */
 class Animator
 {
@@ -27,6 +28,9 @@ class Animator
 	 */
 	Model* model;
 
+	/**
+	 * @brief Stores data required to animate a model frame
+	 */
 	struct FrameInstanceData {
 		bool visible;
 		AnimationBone* bone;

rwengine/include/engine/GameData.hpp

@@ -20,8 +20,9 @@ class GameWorld;
 class TextureAtlas;
 
 /**
- * @brief The TextureInfo struct
+ * @brief Stores simple data about Textures such as transparency flags.
- * Contains metadata about where a texture can be found.
+ *
+ * @todo Covert usage to TextureHandles or something for streaming.
  */
 struct TextureInfo
 {
@@ -38,7 +39,12 @@ struct TextureInfo
 };
 
 /**
- * Handles loading and management of the Game's DAT
+ * @brief Loads and stores all "static" data such as loaded models, handling
+ * information, weather etc.
+ *
+ * @todo Move parsing of one-off data files from this class.
+ * @todo Improve how Loaders and written and used
+ * @todo Considering implementation of streaming data and object handles.
  */
 class GameData
 {

rwengine/include/engine/GameObject.hpp

@@ -15,7 +15,10 @@ class Animator;
 class GameWorld;
 
 /**
- * Stores data used by call types of object instances.
+ * @brief Base data and interface for all world "objects" like vehicles, peds.
+ *
+ * Contains handle to the world, and other useful properties like water level
+ * tracking used to make tunnels work.
  */
 struct GameObject
 {
@@ -35,7 +38,9 @@ struct GameObject
 
 	bool _inWater;
 
-	// Used to determine in water status
+	/**
+	 * @brief stores the height of water at the last tick
+	 */
 	float _lastHeight;
 
 	GameObject(GameWorld* engine, const glm::vec3& pos, const glm::quat& rot, ModelHandle* model)
@@ -45,6 +50,9 @@ struct GameObject
 		
 	virtual ~GameObject() {}
 
+	/**
+	 * @brief Enumeration of possible object types.
+	 */
     enum Type
     {
 		Instance,
@@ -54,6 +62,10 @@ struct GameObject
 		Unknown
     };
 
+	/**
+	 * @brief determines what type of object this is.
+	 * @return one of Type
+	 */
 	virtual Type type() { return Unknown; }
 	
 	virtual void setPosition(const glm::vec3& pos);
@@ -98,7 +110,7 @@ struct GameObject
 		float impulse;
 	};
 	
-	virtual bool takeDamage(const DamageInfo& damage) { return false; }
+	virtual bool takeDamage(const DamageInfo& /*damage*/) { return false; }
 
 	virtual bool isAnimationFixed() const { return true; }
 

rwengine/include/engine/GameWorld.hpp

@@ -28,8 +28,7 @@ class WeaponScan;
 #include <random>
 
 /**
- * @class GameWorld
+ * @brief Handles all data relating to object instances and other "worldly" state.
- *  Represents a single instance of the game world, and all of the data required.
  */
 class GameWorld
 {
@@ -156,19 +155,21 @@ public:
 	std::map<uint16_t, std::vector<std::shared_ptr<PathData>>> objectNodes;
 
 	/**
-	 * Vehicle definitions
+	 * Vehicle type definitions
+	 * @todo move this non-instance data to GameData
 	 */
 	std::map<uint16_t, std::shared_ptr<VehicleData>> vehicleTypes;
 
 	/**
 	* Ped definitions
+	* @todo move this non-instance data to GameData
 	*/
 	std::map<uint16_t, std::shared_ptr<CharacterData>> pedestrianTypes;
 
 	/**
 	 * @brief objects All active GameObjects in the world.
-	 * @TODO add some mechanism to allow objects to be "locked" preventing deletion.
+	 * @todo add some mechanism to allow objects to be "locked" preventing deletion.
-	 * @TODO add deletion queue to allow objects to self delete.
+	 * @todo add deletion queue to allow objects to self delete.
 	 */
 	std::set<GameObject*> objects;
 
@@ -201,6 +202,12 @@ public:
 	 * Used to implement uprooting and other physics oddities.
 	 */
 	static bool ContactProcessedCallback(btManifoldPoint& mp, void* body0, void* body1);
+
+	/**
+	 * @brief PhysicsTickCallback updates object each physics tick.
+	 * @param physWorld
+	 * @param timeStep
+	 */
 	static void PhysicsTickCallback(btDynamicsWorld* physWorld, btScalar timeStep);
 
 	/**

rwengine/include/loaders/LoaderIFP.hpp

@@ -37,6 +37,11 @@ struct AnimationBone
 	AnimationKeyframe getKeyframe(float time);
 };
 
+/**
+ * @brief Animation data object, stores bones.
+ *
+ * @todo break out into Animation.hpp
+ */
 struct Animation
 {
     std::string name;

rwengine/include/objects/VehicleInfo.hpp

@@ -9,7 +9,7 @@
 class VehicleData;
 
 /**
- * Vehicle handling data
+ * @brief Stores data loaded from handling.cfg
  */
 struct VehicleHandlingInfo
 {
@@ -84,7 +84,7 @@ struct SeatInfo {
 };
 
 /**
- * Vehicle Handling and runtime data.
+ * @brief Vehicle Handling and runtime-derrived information about wheel and seat positions.
  */
 struct VehicleInfo {
 	/** Handling data */

rwengine/include/render/GameRenderer.hpp

@@ -22,15 +22,17 @@ class Animator;
 class InventoryItem;
 
 /**
- * Renderer 
+ * @brief Implements high level drawing logic and low level draw commands
  *
- * Handles low level rendering of Models, as well as high level rendering of
+ * Rendering of object types is handled by drawWorld, calling the respective
- * objects in the world.
+ * render function for each object.
  */
 class GameRenderer
 {
+	/** Pointer to the world instance */
 	GameWorld* engine;
 	
+	/** Data required to queue transparent objects for delayed rendering */
 	struct RQueueEntry {
 		Model* model;
 		size_t g;
@@ -39,44 +41,75 @@ class GameRenderer
 		GameObject* object;
 	};
 	
+	/**
+	 * @brief renders a model's frame.
+	 * @param m
+	 * @param f
+	 * @param matrix
+	 * @param object
+	 * @param queueTransparent abort the draw if the frame contains transparent materials
+	 * @return True if the frame was drawn, false if it should be queued
+	 */
 	bool renderFrame(Model* m, ModelFrame* f, const glm::mat4& matrix, GameObject* object, bool queueTransparent = true);
 	
-	// Internal method for processing sub-geometry
+	/**
+	 * @brief renders a model's subgeometry
+	 * @param model
+	 * @param g
+	 * @param sg
+	 * @param matrix
+	 * @param object
+	 * @param queueTransparent
+	 * @return @see renderFrame(
+	 */
 	bool renderSubgeometry(Model* model, size_t g, size_t sg, const glm::mat4& matrix, GameObject* object, bool queueTransparent = true);
 	
-	/// Queue of sub-geometry to post-render 
+	/** Transparent objects are queued into this list */
-	/// With a faster occulusion culling stage
-	/// This could be replaced with a 2nd draw pass.
 	std::vector<RQueueEntry> transparentDrawQueue;
 
 	float _renderAlpha;
 
 public:
 
+	/**
+	 * @brief Stores particle effect instance data
+	 */
 	struct FXParticle {
+
+		/** Initial world position */
 		glm::vec3 position;
+
+		/** Direction of particle */
 		glm::vec3 direction;
+
+		/** Velocity of particle */
 		float velocity;
 
+		/** Particle orientation modes */
 		enum Orientation {
-			Free,
+			Free, /** faces direction using up */
-			Camera,
+			Camera, /** Faces towards the camera @todo implement */
-			UpCamera
+			UpCamera /** Face closes point in camera's look direction */
 		};
 		Orientation orientation;
 
+		/** Game time at particle instantiation */
 		float starttime;
 		float lifetime;
 
-		/// @TODO convert use of TextureInfo to a pointer so it can be used here
+		/** Texture name */
 		GLuint texture;
 
+		/** Size of particle */
 		glm::vec2 size;
 
+		/** Up direction (only used in Free mode) */
 		glm::vec3 up;
 
+		/** Internal cache value */
 		glm::vec3 _currentPosition;
 
+		/** Constructs a particle */
 		FXParticle(const glm::vec3& p, const glm::vec3& d, float v,
 				   Orientation o, float st, float lt, GLuint texture,
 				   const glm::vec2& size, const glm::vec3& up = {0.f, 0.f, 1.f})
@@ -86,6 +119,8 @@ public:
 	};
 
 private:
+
+	/** Particles in flight */
 	std::vector<FXParticle> _particles;
 
 public:
@@ -94,11 +129,12 @@ public:
 	
 	ViewCamera camera;
 	
-	/// The numer of things rendered by the last renderWorld
+	/** Number of issued draw calls */
 	size_t rendered;
+	/** Number of culling events */
 	size_t culled;
 
-	/* TODO clean up all these variables */
+	/** @todo Clean up all these shader program and location variables */
 	GLuint worldProgram;
 	GLint uniTexture;
 	GLuint ubiScene, ubiObject;
@@ -109,21 +145,44 @@ public:
 	GLint skyUniView, skyUniProj, skyUniTop, skyUniBottom;
 	GLuint particleProgram;
 	
-	/// Internal VAO to avoid clobbering global state.
+	/** Internal non-descript VAOs */
     GLuint vao, debugVAO;
 
 	GLuint skydomeVBO, skydomeIBO, debugVBO;
     GLuint debugTex;
 	
     /**
-     * Renders the current World. 
+	 * Draws the world:
+	 *
+	 *  - draws all objects (instances, vehicles etc.)
+	 *  - draws particles
+	 *  - draws water surfaces
+	 *  - draws the skybox
      */
     void renderWorld(float alpha);
 
-	// Object rendering methods.
+	/**
+	 * @brief draws a CharacterObject and any item they are holding.
+	 * @param pedestrian the character to render
+	 */
 	void renderPedestrian(CharacterObject* pedestrian);
+
+	/**
+	 * @brief draws a VehicleObject and it's wheels.
+	 * @param vehicle vehicle to render
+	 */
 	void renderVehicle(VehicleObject* vehicle);
+
+	/**
+	 * @brief draw part of the world.
+	 */
 	void renderInstance(InstanceObject* instance);
+
+	/**
+	 * @brief draws a pickup with it's model
+	 * @param pickup
+	 * @todo corona rendering, with tint.
+	 */
 	void renderPickup(PickupObject* pickup);
 
 	void renderWheel(Model*, const glm::mat4& matrix, const std::string& name);
@@ -132,22 +191,26 @@ public:
 
 	void renderGeometry(Model*, size_t geom, const glm::mat4& modelMatrix, GameObject* = nullptr);
 
+	/**
+	 * @brief renders all visible particles and removes expired
+	 */
 	void renderParticles();
 
-
 	/** 
 	 * Renders a model (who'd have thought)
 	 */
 	void renderModel(Model*, const glm::mat4& modelMatrix, GameObject* = nullptr, Animator* animator = nullptr);
 
-	/**
+	/** method for rendering AI debug information */
-	 * Debug method renders all AI paths
-	 */
     void renderPaths();
 
+	/** Adds a particle to the rendering */
 	void addParticle(const FXParticle& particle);
 
 	static GLuint currentUBO;
+	/**
+	 * Uploads data from T into the specified UBO
+	 */
 	template<class T> void uploadUBO(GLuint buffer, const T& data)
 	{
 		if( currentUBO != buffer ) {

rwengine/include/render/GameShaders.hpp

@@ -2,6 +2,9 @@
 #ifndef _GAMESHADERS_HPP_
 #define _GAMESHADERS_HPP_
 
+/**
+ * @brief collection of shaders to make managing them a little easier.
+ */
 namespace GameShaders {
 
 struct WaterHQ {
@@ -19,8 +22,8 @@ struct WorldObject {
 	static const char* FragmentShader;
 };
 
+/** @brief Particle effect shaders, uses WorldObject::VertexShader */
 struct Particle {
-	/* Shares vertex with WorldObject */
 	static const char* FragmentShader;
 };
 

rwengine/src/render/GameRenderer.cpp

@@ -47,7 +47,7 @@ DrawBuffer waterLQDraw;
 GeometryBuffer waterHQBuffer;
 DrawBuffer waterHQDraw;
 
-/// @TODO collapse all of these into "VertPNC" etc.
+/// @todo collapse all of these into "VertPNC" etc.
 struct ParticleVert {
 	static const AttributeList vertex_attributes() {
 		return {