Documentation

BansheeEditor/Include/BsHandleSlider.h

@@ -7,49 +7,158 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Base class for all handle sliders. A handle slider is geometry that the user
+	 *			can interact with by selecting or dragging (i.e. sliding) it. Sliders generally
+	 *			output a one- or multi-dimensional delta value that signals the drag amount 
+	 *			(and/or direction).
+	 */
 	class BS_ED_EXPORT HandleSlider
 	{
 	public:
+		/**
+		 * @brief	Possible states the slider can be in.
+		 */
 		enum class State
 		{
-			Inactive,
-			Active,
-			Hover
+			Inactive, /**< Slider is not being interacted with. */
+			Active, /**< Slider is clicked on and being dragged. */
+			Hover /**< Slider is being hovered over but isn't clicked on. */
 		};
 
+		/**
+		 * @brief	Constructs a new handle slider.
+		 *
+		 * @param	fixedScale	If true the handle slider will always try to maintain the same visible
+		 *						area in the viewport regardless of distance from camera. 
+		 */
 		HandleSlider(bool fixedScale);
 		virtual ~HandleSlider() { }
 
+		/**
+		 * @brief	Attempts to find an intersection between the provided ray and the slider geometry.
+		 *
+		 * @param	ray	Ray in world space to try to interect with geometry.
+		 * @param	t	Position of the intersection along the ray. Only if intersection happened.
+		 *
+		 * @return	Whether an intersection was detected.
+		 */
 		virtual bool intersects(const Ray& ray, float& t) const = 0;
+
+		/**
+		 * @brief	Updates a slider that is currently active (being dragged).
+		 *
+		 * @param	camera		Camera through which we're interacting with the slider.
+		 * @param	inputDelta	Pointer movement since the last time this method was called.
+		 */
 		virtual void handleInput(const CameraHandlerPtr& camera, const Vector2I& inputDelta) = 0;
+
+		/**
+		 * @brief	Updates the state of the slider. Must be called every frame.
+		 *
+		 * @param	camera	Camera through which we're interacting with the slider.
+		 */
 		void update(const CameraHandlerPtr& camera);
 
+		/**
+		 * @brief	Returns the state the slider is currently in.
+		 */
 		State getState() const { return mState; }
+		
+		/**
+		 * @brief	Returns if fixed scale is enabled. If enabled the handle slider will 
+		 *			always try to maintain the same visible area in the viewport regardless 
+		 *			of distance from camera.
+		 */
 		bool getFixedScale() const { return mFixedScale; }
 
+		/**
+		 * @brief	Sets the world position of the slider.
+		 */
 		void setPosition(const Vector3& position);
+
+		/**
+		 * @brief	Sets the world rotation of the slider.
+		 */
 		void setRotation(const Quaternion& rotation);
+
+		/**
+		 * @brief	Sets the scale of the slider.
+		 */
 		void setScale(const Vector3& scale);
 
+
+		/**
+		 * @brief	Gets the world position of the slider.
+		 */
 		const Vector3& getPosition() const { return mPosition; }
+
+		/**
+		 * @brief	Gets the world rotation of the slider.
+		 */
 		const Quaternion& getRotation() const { return mRotation; }
+
+		/**
+		 * @brief	Gets the scale of the slider.
+		 */
 		const Vector3& getScale() const { return mScale; }
 
 	protected:
 		friend class HandleSliderManager;
 
+		/**
+		 * @brief	Toggles the slider state to inactive.
+		 */
 		void setInactive();
+
+		/**
+		 * @brief	Toggles the slider state to active.
+		 *
+		 * @param	camera		Camera through which the slider was activated.
+		 * @param	pointerPos	Position of the pointer when the slider was activated.
+		 */
 		void setActive(const CameraHandlerPtr& camera, const Vector2I& pointerPos);
+
+		/**
+		 * @brief	Toggles the slider state to hovered.
+		 */
 		void setHover();
 
+		/**
+		 * @brief	Gets the slider transform depending on set position, rotation and scale values.
+		 */
 		const Matrix4& getTransform() const;
+
+		/**
+		 * @brief	Gets the inverse of the slider transform depending on 
+		 *			set position, rotation and scale values.
+		 */
 		const Matrix4& getTransformInv() const;
 
+		/**
+		 * @brief	Triggered when the slider state is changed to active.
+		 */
 		virtual void activate(const CameraHandlerPtr& camera, const Vector2I& pointerPos) { }
+
+		/**
+		 * @brief	Triggered when the slider state is changed from active to some other state.
+		 */
 		virtual void reset() { }
 
+		/**
+		 * @brief	Updates the internal transform from the stored position, rotation and scale values.
+		 */
 		void updateCachedTransform() const;
 
+		/**
+		 * @brief	Calculates amount of movement along the provided ray depending on pointer movement.
+		 *
+		 * @param	camera			Camera on which the pointer movement is occurring.
+		 * @param	position		Position of the ray to calculate movement on.
+		 * @param	direction		Direction of the ray to calculate movement on. Must be normalized.
+		 * @param	pointerStart	Starting position of the pointer when movement started, in pixels relative to provided camera.
+		 * @param	pointerEnd		Current position of the pointer, in pixels relative to provided camera.
+		 */
 		float calcDelta(const CameraHandlerPtr& camera, const Vector3& position, const Vector3& direction,
 			const Vector2I& pointerStart, const Vector2I& pointerEnd);
 

BansheeEditor/Include/BsHandleSliderDisc.h

@@ -6,26 +6,95 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Handle slider that returns a delta value as you drag the pointer
+	 *			along a disc. For intersection purposes the disc is internally 
+	 *			represented by a torus.
+	 */
 	class BS_ED_EXPORT HandleSliderDisc : public HandleSlider
 	{
 	public:
+		/**
+		 * @brief	Constructs a new disc slider.
+		 *
+		 * @param	normal		Normal that determines the orientation of the disc.
+		 * @param	radius		Radius of the disc.
+		 * @param	fixedScale	If true the handle slider will always try to maintain the same visible
+		 *						area in the viewport regardless of distance from camera.
+		 */
 		HandleSliderDisc(const Vector3& normal, float radius, bool fixedScale);
 		~HandleSliderDisc();
 
-		bool intersects(const Ray& ray, float& t) const;
-		void handleInput(const CameraHandlerPtr& camera, const Vector2I& inputDelta);
+		/**
+		 * @copydoc	HandleSlider::intersects
+		 */
+		bool intersects(const Ray& ray, float& t) const override;
+
+		/**
+		 * @copydoc	HandleSlider::handleInput
+		 */
+		void handleInput(const CameraHandlerPtr& camera, const Vector2I& inputDelta) override;
+
+		/**
+		 * @brief	Enables or disables a cut-off plane that can allow the disc to be intersected
+		 *			with only in an 180 degree arc.
+		 *
+		 * @param	angle	Angle at which to start the cut-off. (i.e. the plane will contain points
+		 *					on the disc at angle and (angle + pi) and anything between those two angles
+		 *					wont be interactable.
+		 *					
+		 */
 		void setCutoffPlane(Degree angle, bool enabled);
 
+		/**
+		 * @brief	Returns a delta value that is the result of dragging/sliding the pointer 
+		 *			along the disc. This changes every frame and will be zero unless the slider is active.
+		 */
 		Radian getDelta() const { return mDelta; }
+
+		/**
+		 * @brief	Gets the initial angle at which the drag/slide operation started. This is only
+		 *			valid when the slider is active.
+		 */
 		Radian getStartAngle() const { return mStartAngle; }
 
 	protected:
-		void activate(const CameraHandlerPtr& camera, const Vector2I& pointerPos);
-		void reset() { mDelta = 0.0f; }
 
+		/**
+		 * @copydoc	HandleSlider::activate
+		 */
+		void activate(const CameraHandlerPtr& camera, const Vector2I& pointerPos) override;
+
+		/**
+		 * @copydoc	HandleSlider::reset
+		 */
+		void reset() override { mDelta = 0.0f; }
+
+		/**
+		 * @brief	Calculates the closest point on an arc from a ray.
+		 *
+		 * @param	inputRay	Ray to use for determining the point.
+		 * @param	center		Center of the arc.
+		 * @param	up			Normal vector of the arc. Must be normalized.
+		 * @param	radius		Radius of the arc.
+		 * @param	startAngle	Starting angle of the arc.
+		 * @param	angleAmount	Length of the arc.
+		 *
+		 * @return	A point on the arc closest to the provided ray.
+		 */
 		Vector3 calculateClosestPointOnArc(const Ray& inputRay, const Vector3& center, const Vector3& up,
 			float radius, Degree startAngle, Degree angleAmount);
 
+		/**
+		 * @brief	Determines an angle of a point on a circle.
+		 *
+		 * @param	up		Normal vector of the circle. Must be normalized.
+		 * @param	point	Point to try to find the angle for. Caller must ensure the
+		 *					point is actually somewhere on the circle otherwise the result
+		 *					is undefined.
+		 *
+		 * @return	Angle at which the provided point lies on the circle.
+		 */
 		Degree pointOnCircleToAngle(Vector3 up, Vector3 point);
 
 		static const float TORUS_RADIUS;

BansheeEditor/Include/BsHandleSliderLine.h

@@ -7,20 +7,52 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Handle slider that returns a delta value as you drag the pointer
+	 *			along a line. For intersection purposes the line is internally 
+	 *			by a capsule and a sphere at its cap (assuming we'll use this for
+	 *			arrow-like handles).
+	 */
 	class BS_ED_EXPORT HandleSliderLine : public HandleSlider
 	{
 	public:
+		/**
+		 * @brief	Constructs a new line slider.
+		 *
+		 * @param	direction	Direction of the line.
+		 * @param	length		Length of the slider (i.e. the line).
+		 * @param	fixedScale	If true the handle slider will always try to maintain the same visible
+		 *						area in the viewport regardless of distance from camera.
+		 */
 		HandleSliderLine(const Vector3& direction, float length, bool fixedScale);
 		~HandleSliderLine();
 
-		bool intersects(const Ray& ray, float& t) const;
-		void handleInput(const CameraHandlerPtr& camera, const Vector2I& inputDelta);
+		/**
+		 * @copydoc	HandleSlider::intersects
+		 */
+		bool intersects(const Ray& ray, float& t) const override;
 
+		/**
+		 * @copydoc	HandleSlider::handleInput
+		 */
+		void handleInput(const CameraHandlerPtr& camera, const Vector2I& inputDelta) override;
+
+		/**
+		 * @brief	Returns a delta value that is the result of dragging/sliding the pointer 
+		 *			along the line. This changes every frame and will be zero unless the slider is active.
+		 */
 		float getDelta() const { return mDelta; }
 
 	protected:
-		void activate(const CameraHandlerPtr& camera, const Vector2I& pointerPos) { mStartPosition = getPosition(); }
-		void reset() { mDelta = 0.0f; }
+		/**
+		 * @copydoc	HandleSlider::activate
+		 */
+		void activate(const CameraHandlerPtr& camera, const Vector2I& pointerPos) override { mStartPosition = getPosition(); }
+
+		/**
+		 * @copydoc	HandleSlider::reset
+		 */
+		void reset() override { mDelta = 0.0f; }
 
 		static const float CAPSULE_RADIUS;
 		static const float SPHERE_RADIUS;

BansheeEditor/Include/BsHandleSliderManager.h

@@ -4,21 +4,63 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Controls all instantiated HandleSlider%s.
+	 */
 	class BS_ED_EXPORT HandleSliderManager
 	{
 	public:
 		HandleSliderManager();
 		~HandleSliderManager();
 
+		/**
+		 * @brief	Updates all underlying sliders, changing their state and dragging them depending
+		 *			on their state and pointer movement.
+		 *
+		 * @param	camera		Camera through which we're interacting with sliders.
+		 * @param	inputPos	Position of the pointer.
+		 * @param	inputDelta	Movement of the pointer since last frame.
+		 */
 		void update(const CameraHandlerPtr& camera, const Vector2I& inputPos, const Vector2I& inputDelta);
+
+		/**
+		 * @brief	Attempts to select (activate) a slider at the specified position (if there is any).
+		 *
+		 * @param	camera		Camera through which we're interacting with sliders.
+		 * @param	inputPos	Position of the pointer.
+		 */
 		void trySelect(const CameraHandlerPtr& camera, const Vector2I& inputPos);
+
+		/**
+		 * @brief	Clears the 0active slider (deactivates it).
+		 */
 		void clearSelection();
+
+		/**
+		 * @brief	Checks is any slider active.
+		 */
 		bool isSliderActive() const { return mActiveSlider != nullptr; }
 
+		/**
+		 * @brief	Registers a new instantiated slider.
+		 */
 		void _registerSlider(HandleSlider* slider);
+
+		/**
+		 * @brief	Unregisters a previously instantiated slider.
+		 */
 		void _unregisterSlider(HandleSlider* slider);
 
 	private:
+
+		/**
+		 * @brief	Attempts to find slider at the specified position.
+		 *
+		 * @param	camera		Camera through which we're interacting with sliders.
+		 * @param	inputPos	Position of the pointer.
+		 *
+		 * @return	Slider if we're intersecting with one, or null otherwise.
+		 */
 		HandleSlider* findUnderCursor(const CameraHandlerPtr& camera, const Vector2I& inputPos) const;
 
 		HandleSlider* mActiveSlider;

BansheeEditor/Include/BsHandleSliderPlane.h

@@ -7,21 +7,64 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Handle slider that returns a delta value as you drag the pointer
+	 *			along a plane. For intersection purposes the line is internally
+	 *			by a quadrilateral (a bounded plane).
+	 */
 	class BS_ED_EXPORT HandleSliderPlane : public HandleSlider
 	{
 	public:
+		/**
+		 * @brief	Constructs a new plane slider. The plane is constructed from two
+		 *			direction vectors.
+		 *
+		 * @param	dir1		First direction of the plane. The x component of returned delta value will be in 
+		 *						this direction.
+		 * @param	dir2		Second direction of the plane. The y component of returned delta value will be in 
+		 *						this direction.
+		 * @param	length		Determines size of the plane. 
+		 * @param	fixedScale	If true the handle slider will always try to maintain the same visible
+		 *						area in the viewport regardless of distance from camera.
+		 */
 		HandleSliderPlane(const Vector3& dir1, const Vector3& dir2, float length, bool fixedScale);
 		~HandleSliderPlane();
 
+		/**
+		 * @copydoc	HandleSlider::intersects
+		 */
 		bool intersects(const Ray& ray, float& t) const override;
+
+		/**
+		 * @copydoc	HandleSlider::handleInput
+		 */
 		void handleInput(const CameraHandlerPtr& camera, const Vector2I& inputDelta) override;
 
+		/**
+		 * @brief	Returns a delta value that is the result of dragging/sliding the pointer 
+		 *			along the plane. Returned movement is in terms of the two directions originally provided
+		 *			when constructing the slider. This changes every frame and will be zero unless the slider 
+		 *			is active.
+		 */
 		Vector2 getDelta() const { return mDelta; }
 	protected:
+		/**
+		 * @copydoc	HandleSlider::activate
+		 */
 		void activate(const CameraHandlerPtr& camera, const Vector2I& pointerPos) override;
+
+		/**
+		 * @copydoc	HandleSlider::reset
+		 */
 		void reset() override { mDelta = Vector2::ZERO; }
 
-		Vector3 getClickPosition(const CameraHandlerPtr& camera, const Vector2I& pointerPos) const;
+		/**
+		 * @brief	Returns the position on plane based on pointer position.
+		 *
+		 * @param	camera		Camera we're interacting through.
+		 * @param	pointerPos	Position of the pointer in pixels relative to the provided camera's viewport.
+		 */
+		Vector3 getPositionOnPlane(const CameraHandlerPtr& camera, const Vector2I& pointerPos) const;
 
 		Vector3 mDirection1;
 		Vector3 mDirection2;

BansheeEditor/Source/BsHandleSliderPlane.cpp

@@ -6,9 +6,6 @@
 #include "BsPlane.h"
 #include "BsCameraHandler.h"
 
-// DEBUG ONLY
-#include "BsDebug.h"
-
 namespace BansheeEngine
 {
 	HandleSliderPlane::HandleSliderPlane(const Vector3& dir1, const Vector3& dir2, float length, bool fixedScale)
@@ -54,7 +51,7 @@ namespace BansheeEngine
 	void HandleSliderPlane::activate(const CameraHandlerPtr& camera, const Vector2I& pointerPos)
 	{
 		mStartPlanePosition = getPosition();
-		mStartClickPosition = getClickPosition(camera, pointerPos);
+		mStartClickPosition = getPositionOnPlane(camera, pointerPos);
 	}
 
 	void HandleSliderPlane::handleInput(const CameraHandlerPtr& camera, const Vector2I& inputDelta)
@@ -66,14 +63,14 @@ namespace BansheeEngine
 		Vector3 worldDir1 = getRotation().rotate(mDirection1);
 		Vector3 worldDir2 = getRotation().rotate(mDirection2);
 
-		Vector3 intersectPosition = getClickPosition(camera, mCurrentPointerPos);
+		Vector3 intersectPosition = getPositionOnPlane(camera, mCurrentPointerPos);
 		Vector3 positionDelta = intersectPosition - mStartClickPosition;
 
 		mDelta.x = positionDelta.dot(worldDir1);
 		mDelta.y = positionDelta.dot(worldDir2);
 	}
 
-	Vector3 HandleSliderPlane::getClickPosition(const CameraHandlerPtr& camera, const Vector2I& pointerPos) const
+	Vector3 HandleSliderPlane::getPositionOnPlane(const CameraHandlerPtr& camera, const Vector2I& pointerPos) const
 	{
 		Vector3 worldDir1 = getRotation().rotate(mDirection1);
 		Vector3 worldDir2 = getRotation().rotate(mDirection2);

BansheeUtility/Include/BsEvent.h

@@ -34,6 +34,9 @@ namespace BansheeEngine
 		bool hasHandleLink;
 	};
 
+	/**
+	 * @brief	Internal data for an Event, storing all connections.
+	 */
 	struct EventInternalData
 	{
 		EventInternalData()
@@ -61,6 +64,12 @@ namespace BansheeEngine
 			}
 		}
 
+		/**
+		 * @brief	Disconnects the connection with the specified data,
+		 *			ensuring the event doesn't call its callback again.
+		 *
+		 * @note	Only call this once.
+		 */
 		void disconnect(BaseConnectionData* conn)
 		{
 			BS_LOCK_RECURSIVE_MUTEX(mMutex);
@@ -71,6 +80,9 @@ namespace BansheeEngine
 			free(conn);
 		}
 
+		/**
+		 * @brief	Disconnects all connections in the event.
+		 */
 		void clear()
 		{
 			BS_LOCK_RECURSIVE_MUTEX(mMutex);
@@ -88,6 +100,12 @@ namespace BansheeEngine
 			}
 		}
 
+		/**
+		 * @brief	Called when the event handle no longer keeps
+		 *			a reference to the connection data. This means
+		 *			we might be able to free (and reuse) its memory
+		 *			if the event is done with it too.
+		 */
 		void freeHandle(BaseConnectionData* conn)
 		{
 			BS_LOCK_RECURSIVE_MUTEX(mMutex);
@@ -98,6 +116,11 @@ namespace BansheeEngine
 				free(conn);
 		}
 
+		/**
+		 * @brief	Releases connection data and makes it
+		 *			available for re-use when next connection
+		 *			is formed.
+		 */
 		void free(BaseConnectionData* conn)
 		{
 			if (conn->prev != nullptr)
@@ -186,6 +209,8 @@ namespace BansheeEngine
 	 *
 	 * @note	Callback method return value is ignored.
 	 */
+	// Note: I could create a policy template argument that allows creation of 
+	// lockable and non-lockable events in the case mutex is causing too much overhead.
 	template <class RetType, class... Args>
 	class TEvent
 	{

TODO.txt

@@ -59,9 +59,6 @@ Code quality improvements:
 Polish stage 1
 
 Handle seems to lag behind the selected mesh
-
-Track down the large performance spike
- - Seems to be caused by something on core thread
 ProjectLibrary seems to import some files on every start-up
 Crash on shutdown in mono_gchandle_free
 
@@ -78,13 +75,6 @@ First screenshot work:
 - Status bar with last console message
 - (Optionally) Console window
 
-Optimization:
- - Remove profiling calls in GUIWidget and text sprite
- - Remove pause mechanic from profiler overlay
- - HResource.isLoaded checks are using up a lot of allocations in GUI updates
-  - getResourceDependencies AND getCoreDependencies need to use frame alloc
- - There are more issues with GUI allocations
-
 -----------
 
 SceneTreeView