diff --git a/.gitignore b/.gitignore index 6339c13a..01ebe438 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ build/ +documentation/ *.kdev4 *~ *.swp diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 00000000..7ec13048 --- /dev/null +++ b/Doxyfile @@ -0,0 +1,8 @@ +PROJECT_NAME=OpenRW +OUTPUT_DIRECTORY=documentation/ +INPUT=. +RECURSIVE=YES +EXCLUDE=tests +GENERATE_LATEX=NO +GENERATE_HTML=YES +HTML_OUTPUT= diff --git a/README.markdown b/README.markdown index ab2b21f7..e947bdc8 100644 --- a/README.markdown +++ b/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) diff --git a/rwengine/include/WorkContext.hpp b/rwengine/include/WorkContext.hpp index 5555b39e..f1a2de16 100644 --- a/rwengine/include/WorkContext.hpp +++ b/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 _workQueue; diff --git a/rwengine/include/ai/CharacterController.hpp b/rwengine/include/ai/CharacterController.hpp index b1e5da34..d02a4f76 100644 --- a/rwengine/include/ai/CharacterController.hpp +++ b/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 ) diff --git a/rwengine/include/data/ObjectData.hpp b/rwengine/include/data/ObjectData.hpp index 67dd9fea..bf6f04fc 100644 --- a/rwengine/include/data/ObjectData.hpp +++ b/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 { diff --git a/rwengine/include/data/WeaponData.hpp b/rwengine/include/data/WeaponData.hpp index ef3e7ce9..b1f548ee 100644 --- a/rwengine/include/data/WeaponData.hpp +++ b/rwengine/include/data/WeaponData.hpp @@ -41,14 +41,16 @@ struct WeaponData }; /** - * @brief The WeaponScan struct - * Represents a scene query against a ray - * or shape used to determine what to damage. + * @brief simple object for performing weapon checks against the world + * + * @todo RADIUS hitscans */ struct WeaponScan { enum ScanType { + /** Instant-hit ray weapons */ HITSCAN, + /** Area of effect attack */ RADIUS, }; diff --git a/rwengine/include/engine/Animator.hpp b/rwengine/include/engine/Animator.hpp index 6f08891f..68bb9e8d 100644 --- a/rwengine/include/engine/Animator.hpp +++ b/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; diff --git a/rwengine/include/engine/GameData.hpp b/rwengine/include/engine/GameData.hpp index 5c525766..d96ca0cb 100644 --- a/rwengine/include/engine/GameData.hpp +++ b/rwengine/include/engine/GameData.hpp @@ -20,8 +20,9 @@ class GameWorld; class TextureAtlas; /** - * @brief The TextureInfo struct - * Contains metadata about where a texture can be found. + * @brief Stores simple data about Textures such as transparency flags. + * + * @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 { diff --git a/rwengine/include/engine/GameObject.hpp b/rwengine/include/engine/GameObject.hpp index b2b45958..2f6b4511 100644 --- a/rwengine/include/engine/GameObject.hpp +++ b/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; } diff --git a/rwengine/include/engine/GameWorld.hpp b/rwengine/include/engine/GameWorld.hpp index 25fbef3a..e3381633 100644 --- a/rwengine/include/engine/GameWorld.hpp +++ b/rwengine/include/engine/GameWorld.hpp @@ -28,8 +28,7 @@ class WeaponScan; #include /** - * @class GameWorld - * Represents a single instance of the game world, and all of the data required. + * @brief Handles all data relating to object instances and other "worldly" state. */ class GameWorld { @@ -151,24 +150,26 @@ public: std::map> objectTypes; /** - * Paths associated with each object definition. - */ + * Paths associated with each object definition. + */ std::map>> objectNodes; /** - * Vehicle definitions + * Vehicle type definitions + * @todo move this non-instance data to GameData */ std::map> vehicleTypes; /** - * Ped definitions - */ + * Ped definitions + * @todo move this non-instance data to GameData + */ std::map> pedestrianTypes; /** * @brief objects All active GameObjects in the world. - * @TODO add some mechanism to allow objects to be "locked" preventing deletion. - * @TODO add deletion queue to allow objects to self delete. + * @todo add some mechanism to allow objects to be "locked" preventing deletion. + * @todo add deletion queue to allow objects to self delete. */ std::set 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); /** diff --git a/rwengine/include/loaders/LoaderIFP.hpp b/rwengine/include/loaders/LoaderIFP.hpp index ebce7972..771d381c 100644 --- a/rwengine/include/loaders/LoaderIFP.hpp +++ b/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; diff --git a/rwengine/include/objects/VehicleInfo.hpp b/rwengine/include/objects/VehicleInfo.hpp index d562a871..abed2736 100644 --- a/rwengine/include/objects/VehicleInfo.hpp +++ b/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 */ diff --git a/rwengine/include/render/GameRenderer.hpp b/rwengine/include/render/GameRenderer.hpp index b59be617..ababdfad 100644 --- a/rwengine/include/render/GameRenderer.hpp +++ b/rwengine/include/render/GameRenderer.hpp @@ -22,15 +22,17 @@ class Animator; class InventoryItem; /** - * Renderer - * - * Handles low level rendering of Models, as well as high level rendering of - * objects in the world. + * @brief Implements high level drawing logic and low level draw commands + * + * Rendering of object types is handled by drawWorld, calling the respective + * render function for each object. */ class GameRenderer { - GameWorld* engine; + /** 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 - /// With a faster occulusion culling stage - /// This could be replaced with a 2nd draw pass. + /** Transparent objects are queued into this list */ std::vector 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, - Camera, - UpCamera + Free, /** faces direction using up */ + Camera, /** Faces towards the camera @todo implement */ + 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 _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); - /** - * Debug method renders all AI paths - */ + /** method for rendering AI debug information */ 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 void uploadUBO(GLuint buffer, const T& data) { if( currentUBO != buffer ) { diff --git a/rwengine/include/render/GameShaders.hpp b/rwengine/include/render/GameShaders.hpp index 8352dfd9..6639e935 100644 --- a/rwengine/include/render/GameShaders.hpp +++ b/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; }; diff --git a/rwengine/src/render/GameRenderer.cpp b/rwengine/src/render/GameRenderer.cpp index 5907f5b9..0736757d 100644 --- a/rwengine/src/render/GameRenderer.cpp +++ b/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 {