More documentation

BansheeEngine/Include/BsCamera.h

@@ -329,14 +329,19 @@ namespace BansheeEngine
 		 *			that the core thread has all the necessary data, while avoiding the need
 		 *			to manage Camera itself on the core thread.
 		 *
-		 * @note	Sim thread only. 
-		 *			You generally need to update the core thread with a new proxy whenever core 
+		 * @note	You generally need to update the core thread with a new proxy whenever core 
 		 *			dirty flag is set.
 		 */
 		CameraProxyPtr _createProxy() const;
 
-		// TODO UNDOCUMENTED
+		/**
+		 * @brief	Returns the currently active proxy object, if any.
+		 */
 		CameraProxyPtr _getActiveProxy() const { return mActiveProxy; }
+
+		/**
+		 * @brief	Changes the currently active proxy object. 
+		 */
 		void _setActiveProxy(const CameraProxyPtr& proxy) { mActiveProxy = proxy; }
 
 	protected:

BansheeEngine/Include/BsInputConfiguration.h

@@ -5,6 +5,9 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Modifiers used with virtual buttons.
+	 */
 	enum class VButtonModifier
 	{
 		None = 0x00,
@@ -17,9 +20,22 @@ namespace BansheeEngine
 		ShiftCtrlAlt = 0x07
 	};
 
+	/**
+	 * @brief	Describes a virtual button. Virtual buttons allow you to
+	 *			map custom actions without needing to know about what 
+	 *			physical buttons trigger those actions.
+	 */
 	struct BS_EXPORT VIRTUAL_BUTTON_DESC
 	{
 		VIRTUAL_BUTTON_DESC();
+
+		/**
+		 * @brief	Constructs a virtual button descriptor.
+		 *
+		 * @param	buttonCode	Physical button the virtual button is triggered by.
+		 * @param	modifiers	Modifiers required to be pressed with the physical button to trigger the virtual button.
+		 * @param	repeatable	If true, the virtual button events will be sent continually while the physical button is being held.
+		 */
 		VIRTUAL_BUTTON_DESC(ButtonCode buttonCode, VButtonModifier modifiers = VButtonModifier::None, bool repeatable = false);
 
 		ButtonCode buttonCode;
@@ -27,9 +43,23 @@ namespace BansheeEngine
 		bool repeatable;
 	};
 
+	/**
+	 * @brief	Describes a virtual axis. Virtual axes allow you to map
+	 *			custom axes without needing to know the actual physical device
+	 *			handling those axes.
+	 */
 	struct BS_EXPORT VIRTUAL_AXIS_DESC
 	{
 		VIRTUAL_AXIS_DESC();
+
+		/**
+		 * @brief	Constructs a new virtual axis descriptor.
+		 *
+		 * @param	type		Type of physical axis to map to. See InputAxis type for common types, but you are not limited to those values.
+		 * @param	deadZone	Value below which to ignore axis value and consider it 0.
+		 * @param	sensitivity	Higher sensitivity means the axis will more easily reach its maximum values.
+		 * @param	invert		Should axis values be inverted.
+		 */
 		VIRTUAL_AXIS_DESC(UINT32 type, float deadZone = 0.0001f, float sensitivity = 1.0f, bool invert = false);
 
 		float deadZone;
@@ -46,6 +76,8 @@ namespace BansheeEngine
 	 * 			one of these using the button name, and then store it for later use. 
 	 * 			
 	 *			This class is not thread safe and should only be used on the sim thread.
+	 *
+	 * @see		VIRTUAL_BUTTON_DESC
 	 */
 	class BS_EXPORT VirtualButton 
 	{
@@ -53,13 +85,12 @@ namespace BansheeEngine
 		VirtualButton();
 		VirtualButton(const String& name);
 
-		UINT32 buttonIdentifier;
-
 		bool operator== (const VirtualButton& rhs) const
 		{
 			return (buttonIdentifier == rhs.buttonIdentifier);
 		}
 
+		UINT32 buttonIdentifier;
 	private:
 		static Map<String, UINT32> UniqueButtonIds;
 		static UINT32 NextButtonId;
@@ -73,6 +104,8 @@ namespace BansheeEngine
 	 * 			one of these using the axis name, and then store it for later use. 
 	 * 			
 	 *			This class is not thread safe and should only be used on the sim thread.
+	 *
+	 * @see		VIRTUAL_AXIS_DESC
 	 */
 	class BS_EXPORT VirtualAxis
 	{
@@ -92,11 +125,17 @@ namespace BansheeEngine
 		static UINT32 NextAxisId;
 	};
 
+	/**
+	 * @brief	Contains virtual <-> physical key mappings.
+	 */
 	class BS_EXPORT InputConfiguration
 	{
 		static const int MAX_NUM_DEVICES_PER_TYPE = 8;
 		static const int MAX_NUM_DEVICES = (UINT32)InputDevice::Count * MAX_NUM_DEVICES_PER_TYPE;
 
+		/**
+		 * @brief	Internal virtual button data container.
+		 */
 		struct VirtualButtonData
 		{
 			String name;
@@ -104,6 +143,9 @@ namespace BansheeEngine
 			VIRTUAL_BUTTON_DESC desc;
 		};
 
+		/**
+		 * @brief	Internal virtual axis data container.
+		 */
 		struct VirtualAxisData
 		{
 			String name;
@@ -111,6 +153,9 @@ namespace BansheeEngine
 			VIRTUAL_AXIS_DESC desc;
 		};
 
+		/**
+		 * @brief	Internal container for holding axis data for all devices.
+		 */
 		struct DeviceAxisData
 		{
 			VirtualAxisData axes[(UINT32)InputAxis::Count];
@@ -119,16 +164,53 @@ namespace BansheeEngine
 	public:
 		InputConfiguration();
 
+		/**
+		 * @brief	Registers a new virtual button.
+		 *
+		 * @param	name		Unique name of the virtual button. You will use this to access the button.
+		 * @param	buttonCode	Physical button the virtual button is triggered by.
+		 * @param	modifiers	Modifiers required to be pressed with the physical button to trigger the virtual button.
+		 * @param	repeatable	If true, the virtual button events will be sent continually while the physical button is being held.
+		 */
 		void registerButton(const String& name, ButtonCode buttonCode, VButtonModifier modifiers = VButtonModifier::None, bool repeatable = false);
+
+		/**
+		 * @brief	Unregisters a virtual button with the specified name. Events will no longer be generated for that button.
+		 */
 		void unregisterButton(const String& name);
 
+		/**
+		 * @brief	Registers a new virtual axis.
+		 *
+		 * @param	name	Unique name of the virtual axis. You will use this to access the axis.
+		 * @param	desc	Descriptor structure containing virtual axis creation parameters.
+		 */
 		void registerAxis(const String& name, const VIRTUAL_AXIS_DESC& desc);
+
+		/**
+		 * @brief	Unregisters a virtual axis with the specified name. You will no longer
+		 *			be able to retrieve valid values for that axis.
+		 */
 		void unregisterAxis(const String& name);
 
+		/**
+		 * @brief	Sets repeat interval for held virtual buttons.
+		 */
 		void setRepeatInterval(UINT64 milliseconds) { mRepeatInterval = milliseconds; }
+
+		/**
+		 * @brief	Gets the currently set repeat interval for held virtual buttons.
+		 */
 		UINT64 getRepeatInterval() const { return mRepeatInterval; }
 
+		/**
+		 * @brief	Returns data about a virtual button from a physical button code and modifier flags.
+		 */
 		bool _getButton(ButtonCode code, UINT32 modifiers, VirtualButton& btn, VIRTUAL_BUTTON_DESC& btnDesc) const;
+
+		/**
+		 * @brief	Retrieves virtual axis descriptor for the provided axis.
+		 */
 		bool _getAxis(const VirtualAxis& axis, VIRTUAL_AXIS_DESC& axisDesc) const;
 	private:
 		Vector<VirtualButtonData> mButtons[BC_Count];

BansheeEngine/Include/BsPrerequisites.h

@@ -103,6 +103,9 @@ namespace BansheeEngine
 
 	typedef ResourceHandle<SpriteTexture> HSpriteTexture;
 
+	/**
+	 * @brief	RTTI types.
+	 */
 	enum TypeID_Banshee
 	{
 		TID_Camera = 30000,

BansheeEngine/Include/BsRectOffset.h

@@ -4,6 +4,10 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Rectangle represented in the form of offsets
+	 *			from some parent rectangle.
+	 */
 	struct RectOffset
 	{
 		RectOffset()

BansheeEngine/Include/BsRenderQueue.h

@@ -22,21 +22,30 @@ namespace BansheeEngine
 	};
 
 	/**
-	 * @brief	Render objects determines rendering order of objects contained within it. Normally the rendering
-	 * 			order is determined by object material, and can influence rendering of transparent or opaque objects,
+	 * @brief	Render objects determines rendering order of objects contained within it. Rendering order 
+	 *			is determined by object material, and can influence rendering of transparent or opaque objects,
 	 * 			or be used to improve performance by grouping similar objects together.
-	 * 			
-	 *			You need to provide your own implementation of the render queue sorting method. Likely the sorting method
-	 *			will need to be closely tied to the renderer used.
 	 */
-	// TODO UNDOCUMENTED
 	class BS_EXPORT RenderQueue
 	{
 	public:
 		RenderQueue();
 
+		/**
+		 * @brief	Adds a new entry to the render queue.
+		 *
+		 * @param	element			Renderable element to add to the queue.
+		 * @param	worldPosForSort	World position that will be used for distance sorting of the object.
+		 */
 		void add(RenderableElement* element, const Vector3& worldPosForSort);
 
+		/**
+		 * @brief	Adds a new entry to the render queue.
+		 *
+		 * @param	material	Material that will be used for rendering the object.
+		 * @param	mesh		Mesh representing the geometry of the object.
+		 * @param	worldPosForSort	World position that will be used for distance sorting of the object.
+		 */
 		void add(const MaterialProxyPtr& material, const MeshProxyPtr& mesh, const Vector3& worldPosForSort);
 
 		/**

BansheeEngine/Include/BsRenderable.h

@@ -88,9 +88,24 @@ namespace BansheeEngine
 		 */
 		void _markCoreClean();
 
-		// TODO UNDOCUMENTED
+		/**
+		 * @brief	Creates a new core proxy from the currently set Renderable data. Core proxies ensure
+		 *			that the core thread has all the necessary Renderable data, while avoiding the need
+		 *			to manage Renderable itself on the core thread.
+		 *
+		 * @note	You generally need to update the core thread with a new proxy whenever core 
+		 *			dirty flag is set.
+		 */
 		RenderableProxyPtr _createProxy() const;
+
+		/**
+		 * @brief	Returns the currently active proxy object, if any.
+		 */
 		RenderableProxyPtr _getActiveProxy() const { return mActiveProxy; }
+
+		/**
+		 * @brief	Changes the currently active proxy object. 
+		 */
 		void _setActiveProxy(const RenderableProxyPtr& proxy) { mActiveProxy = proxy; }
 
 	private:

BansheeEngine/Include/BsRenderableHandler.h

@@ -4,13 +4,37 @@
 
 namespace BansheeEngine
 {
-	// TODO UNDOCUMENTED
+	/**
+	 * Abstract class that provides an interface for initializing
+	 * renderable elements of a certain type, along with their GPU
+	 * parameter buffers.
+	 *
+	 * Essentially this class holds all the information that is needed for rendering
+	 * an element of a certain renderable type.
+	 *
+	 * @note	e.g. elements that have shadows would have a RenderableLitShadowHandler
+	 *			and elements that can be animated would have RenderableAnimatedHandler,
+	 *			or a combination of the two.	
+	 */
 	class BS_EXPORT RenderableHandler
 	{
 	public:
+		/**
+		 * @brief	Initializes the specified renderable element, making it ready
+		 *			to be used. Caller must ensure the renderable element actually
+		 *			supports this handler.
+		 */
 		virtual void initializeRenderElem(RenderableElement* element) = 0;
 
+		/**
+		 * @brief	Binds per object GPU parameter buffers to the provided element.
+		 */
 		virtual void bindPerObjectBuffers(const RenderableElement* element) = 0;
+
+		/**
+		 * @brief	Binds global GPU parameter buffers used for this Renderable 
+		 *			type to the provided element.
+		 */
 		virtual void bindGlobalBuffers(const RenderableElement* element);
 	};
 }

BansheeEngine/Include/BsRenderableProxy.h

@@ -8,30 +8,73 @@
 
 namespace BansheeEngine
 {
-	// TODO UNDOCUMENTED
+	/**
+	 * @brief	Contains all information needed for rendering a single
+	 *			sub-mesh. Closely tied with Renderer.
+	 */
 	class BS_EXPORT RenderableElement
 	{
 	public:
 		RenderableElement();
 
+		/**
+		 * @brief	Calculate mesh world bounds.
+		 */
 		Bounds calculateWorldBounds();
 
+		/**
+		 * @brief	Index of the renderable element in the global array
+		 *			managed by the Renderer.
+		 */
 		UINT32 id;
+
+		/**
+		 * @brief	World transform matrix of the element.
+		 */
 		Matrix4 worldTransform;
 
+		/**
+		 * @brief	Proxy of the sub-mesh to render.
+		 */
 		MeshProxyPtr mesh;
+
+		/**
+		 * @brief	Proxy of the material to render the mesh with.
+		 */
 		MaterialProxyPtr material;
 
+		/**
+		 * @brief	Optional layer that may be used for the camera for culling
+		 *			certain elements.
+		 */
 		UINT64 layer;
 
+		/**
+		 * @brief	Custom data that may optionally be set by the RenderableHanbdler.
+		 */
 		Any rendererData;
+
+		/**
+		 * @brief	Handler responsible for initializing and updating this element.
+		 */
 		RenderableHandler* handler;
+
+		/**
+		 * @brief	Type that determines which type of RenderableHandler to use for this element.
+		 */
 		RenderableType renderableType;
 
 	private:
 		bool mBoundsDirty;
 	};
 
+	/**
+	 * @brief	Proxy contains data about a single Renderable object, to
+	 *			be used for rendering by the Renderer on the core thread.
+	 *
+	 * @note	Essentially it is a snapshot of Renderable (We cannot use
+	 *			Renderable itself because this is meant for the core thread).
+	 */
 	class BS_EXPORT RenderableProxy
 	{
 	public:

BansheeEngine/Include/BsSceneManager.h

@@ -5,6 +5,10 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Manages active SceneObjects and provides ways for querying
+	 *			and updating them or their components.
+	 */
 	class BS_EXPORT SceneManager : public CoreSceneManager
 	{
 	public:
@@ -37,5 +41,8 @@ namespace BansheeEngine
 		Event<void(const HCamera&)> onCameraRemoved;
 	};
 
+	/**
+	 * @copydoc	SceneManager
+	 */
 	BS_EXPORT SceneManager& gBsSceneManager();
 }

BansheeEngine/Include/BsVirtualInput.h

@@ -6,8 +6,16 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Handles virtual input that allows you to receive virtual input events that 
+	 *			hide the actual physical input, allowing you to easily change the input keys
+	 *			while being transparent to the external code.
+	 */
 	class BS_EXPORT VirtualInput : public Module<VirtualInput>
 	{
+		/**
+		 * @brief	Possible states of virtual buttons.
+		 */
 		enum class ButtonState
 		{
 			Off,
@@ -16,6 +24,9 @@ namespace BansheeEngine
 			ToggledOff
 		};
 
+		/**
+		 * @brief	Data container for a single virtual button.
+		 */
 		struct ButtonData
 		{
 			VirtualButton button;
@@ -24,11 +35,17 @@ namespace BansheeEngine
 			bool allowRepeat;
 		};
 
+		/**
+		 * @brief	Contains button data for a specific input device.
+		 */
 		struct DeviceData
 		{
 			Map<UINT32, ButtonData> cachedStates;
 		};
 
+		/**
+		 * @brief	Data container for a virtual button event.
+		 */
 		struct VirtualButtonEvent
 		{
 			VirtualButton button;
@@ -39,26 +56,89 @@ namespace BansheeEngine
 	public:
 		VirtualInput();
 
+		/**
+		 * @brief	Creates a new empty input configuration.
+		 */
 		static std::shared_ptr<InputConfiguration> createConfiguration();
 
+		/**
+		 * @brief	Sets an input configuration that determines how physical keys map to virtual buttons.
+		 */
 		void setConfiguration(const std::shared_ptr<InputConfiguration>& input);
+
+		/**
+		 * @brief	Retrieves the active input configuration that determines how physical keys map to virtual buttons.
+		 */
 		std::shared_ptr<InputConfiguration> getConfiguration() const { return mInputConfiguration; }
 
+		/**
+		 * @brief	Check is the virtual button just getting pressed. This state is only
+		 *			active for one frame.
+		 *
+		 * @param	button		Virtual button identifier.
+		 * @param	deviceIdx	Optional device index in case multiple input devices are available.
+		 */
 		bool isButtonDown(const VirtualButton& button, UINT32 deviceIdx = 0) const;
+
+		/**
+		 * @brief	Check is the virtual button just getting released. This state is only
+		 *			active for one frame.
+		 *
+		 * @param	button		Virtual button identifier.
+		 * @param	deviceIdx	Optional device index in case multiple input devices are available.
+		 */
 		bool isButtonUp(const VirtualButton& button, UINT32 deviceIdx = 0) const;
+
+		/**
+		 * @brief	Check is the virtual button is being held. This state is active as long
+		 *			as the button is being held down, i.e. possibly multiple frames.
+		 *
+		 * @param	button		Virtual button identifier.
+		 * @param	deviceIdx	Optional device index in case multiple input devices are available.
+		 */
 		bool isButtonHeld(const VirtualButton& button, UINT32 deviceIdx = 0) const;
 
+		/**
+		 * @brief	Returns normalized value for the specified input axis. 
+		 *			Returned value will be in [-1.0, 1.0] range.
+		 *
+		 * @param	axis		Virtual axis identifier.
+		 * @param	deviceIdx	Optional device index in case multiple input devices are available.
+		 */
 		float getAxisValue(const VirtualAxis& axis, UINT32 deviceIdx = 0) const;
 
-		void update();
+		/**
+		 * @brief	Called once every frame.
+		 *
+		 * @note	Internal method.
+		 */
+		void _update();
 
+		/**
+		 * @brief	Triggered when a virtual button is pressed.
+		 */
 		Event<void(const VirtualButton&, UINT32 deviceIdx)> onButtonDown;
+
+		/**
+		 * @brief	Triggered when a virtual button is released.
+		 */
 		Event<void(const VirtualButton&, UINT32 deviceIdx)> onButtonUp;
+
+		/**
+		 * @brief	Triggered every frame when a virtual button is being held down.
+		 */
 		Event<void(const VirtualButton&, UINT32 deviceIdx)> onButtonHeld;
 	private:
 		friend class VirtualButton;
 
+		/**
+		 * @brief  Performs all logic related to a button press.
+		 */
 		void buttonDown(const ButtonEvent& event);
+
+		/**
+		 * @brief  Performs all logic related to a button release.
+		 */
 		void buttonUp(const ButtonEvent& event);
 
 		std::shared_ptr<InputConfiguration> mInputConfiguration;

BansheeEngine/Source/BsApplication.cpp

@@ -97,7 +97,7 @@ namespace BansheeEngine
 	{
 		CoreApplication::update();
 
-		VirtualInput::instance().update();
+		VirtualInput::instance()._update();
 		PROFILE_CALL(GUIManager::instance().update(), "GUI");
 	}
 

BansheeEngine/Source/BsVirtualInput.cpp

@@ -100,7 +100,7 @@ namespace BansheeEngine
 		return 0.0f;
 	}
 
-	void VirtualInput::update()
+	void VirtualInput::_update()
 	{
 		for (auto& deviceData : mDevices)
 		{