More documentation

CamelotCore/Include/CmCoreThread.h

@@ -36,9 +36,7 @@ public:
 	CM_EXPORT ~CoreThread();
 
 	/**
-		* @brief	Returns the id of the core thread. If a separate core thread
-		* 			is not used, then it returns the id of the thread RenderSystem
-		* 			was initialized on.
+		* @brief	Returns the id of the core thread. 
 		*/
 	CM_EXPORT CM_THREAD_ID_TYPE getCoreThreadId() { return mCoreThreadId; }
 
@@ -54,8 +52,8 @@ public:
 	/**
 	* @brief	Retrieves an accessor that you can use for executing commands on the core thread from
 	* 			a non-core thread. There is only one synchronized accessor and you may access it from any thread you wish.
-	* 			Note however that it is much more efficient to create a separate non-synchronized accessor using
-	* 			"createCoreAccessor" for each thread you will be using it on.
+	* 			Note however that it is much more efficient to retrieve a separate non-synchronized accessor using
+	* 			"getAccessor" for each thread you will be using it on.
 	* 			
 	* @note		Accessors contain their own command queue and their commands will only start to get executed once that queue is submitted
 	* 			to the core thread via "submitAccessors" method.
@@ -93,7 +91,7 @@ public:
 	/**
 	 * @brief	Called once every frame.
 	 * 			
-	 * @note	Must be called before sim thread schedules any CoreThread operations that frame. 
+	 * @note	Must be called before sim thread schedules any core thread operations for the frame. 
 	 */
 	CM_EXPORT void update();
 
@@ -106,8 +104,10 @@ public:
 	 */
 	CM_EXPORT FrameAlloc* getFrameAlloc() const;
 private:
-	// Double buffered frame allocators - Means sim thread cannot be more than 1 frame ahead of core thread
-	// (If that changes you should be able to easily add more)
+	/**
+	 * @brief	Double buffered frame allocators. Means sim thread cannot be more than 1 frame ahead of core thread
+	 *			(If that changes you should be able to easily add more).
+	 */
 	FrameAlloc* mFrameAllocs[2]; 
 	UINT32 mActiveFrameAlloc;
 
@@ -125,18 +125,18 @@ private:
 
 	CommandQueue<CommandQueueSync>* mCommandQueue;
 
-	UINT32 mMaxCommandNotifyId; // ID that will be assigned to the next command with a notifier callback
-	Vector<UINT32>::type mCommandsCompleted; // Completed commands that have notifier callbacks set up
+	UINT32 mMaxCommandNotifyId; /**< ID that will be assigned to the next command with a notifier callback. */
+	Vector<UINT32>::type mCommandsCompleted; /**< Completed commands that have notifier callbacks set up */
 
 	SyncedCoreAccessor* mSyncedCoreAccessor;
 
 	/**
-		* @brief	Initializes a separate core thread. Should only be called once.
+		* @brief	Starts the core thread worker method. Should only be called once.
 		*/
 	void initCoreThread();
 
 	/**
-		* @brief	Main function of the core thread. Called once thread is started.
+		* @brief	Main worker method of the core thread. Called once thread is started.
 		*/
 	void runCoreThread();
 
@@ -161,20 +161,37 @@ private:
 	void commandCompletedNotify(UINT32 commandId);
 	};
 
+	/**
+	 * @brief	Returns the core thread manager used for dealing with the core thread from external threads.
+	 * 			
+	 * @see		CoreThread
+	 */
 	CM_EXPORT CoreThread& gCoreThread();
 
+	/**
+	 * @brief	Returns a core thread accessor for the current thread. Accessor is retrieved or created depending
+	 * 			if it previously existed. Each thread has its own accessor.
+	 * 	
+	 * @see		CoreThread
+	 */
 	CM_EXPORT CoreThreadAccessor<CommandQueueNoSync>& gCoreAccessor();
 
+	/**
+	 * @brief	Returns a synchronized core accessor you may call from any thread for working with the core thread.
+	 * 			Only one of these exists.
+	 * 			
+	 * @see		CoreThread
+	 */
 	CM_EXPORT CoreThreadAccessor<CommandQueueSync>& gSyncedCoreAccessor();
 
 	/**
-		* @brief	Throws an exception if current thread isn't the core thread;
-		*/
+	  * @brief	Throws an exception if current thread isn't the core thread;
+	  */
 	CM_EXPORT void throwIfNotCoreThread();
 
 	/**
-		* @brief	Throws an exception if current thread is the core thread;
-		*/
+	  * @brief	Throws an exception if current thread is the core thread;
+	  */
 	CM_EXPORT void throwIfCoreThread();
 
 #if CM_DEBUG_MODE

CamelotCore/Include/CmCoreThreadAccessor.h

@@ -14,9 +14,10 @@
 namespace BansheeEngine
 {
 	/**
-	 * @brief	Core thread accessor allows you to schedule core commands outside of the core thread.
+	 * @brief	Core thread accessor allows you to schedule core commands outside of the core thread. Provides a set of common
+	 * 			methods you may want to execute on the core thread, as well as a general command queuing methods.
 	 * 			
-	 * @note	All commands are queued and only executed after the call to submitToCoreThread, in the order they were called.
+	 * @note	Queued commands are only executed after the call to submitToCoreThread, in the order they were submitted.
 	 */
 	template <class CommandQueueSyncPolicy = CommandQueueNoSync>
 	class CM_EXPORT CoreThreadAccessor
@@ -227,21 +228,33 @@ namespace BansheeEngine
 				resource, subresourceIdx, data, std::placeholders::_1));
 		}
 
+		/**
+		 * @brief	Resize the provided window to specified width and height in pixels.
+		 */
 		void resizeWindow(RenderWindowPtr& renderWindow, UINT32 width, UINT32 height)
 		{
 			mCommandQueue->queue(std::bind(&RenderWindow::resize, renderWindow.get(), width, height));
 		}
 
+		/**
+		 * @brief	Move the provided window to specified screen coordinates.
+		 */
 		void moveWindow(RenderWindowPtr& renderWindow, INT32 left, INT32 top)
 		{
 			mCommandQueue->queue(std::bind(&RenderWindow::move, renderWindow.get(), left, top));
 		}
 
+		/**
+		 * @brief	Hide the provided window. (Does not destroy it, just hides it).
+		 */
 		void hideWindow(RenderWindowPtr& renderWindow)
 		{
 			mCommandQueue->queue(std::bind(&RenderWindow::setHidden, renderWindow.get(), true));
 		}
 
+		/**
+		 * @brief	Shows a previously hidden window.
+		 */
 		void showWindow(RenderWindowPtr& renderWindow)
 		{
 			mCommandQueue->queue(std::bind(&RenderWindow::setHidden, renderWindow.get(), false));
@@ -265,7 +278,7 @@ namespace BansheeEngine
 
 		/**
 		 * @brief	Makes all the currently queued commands available to the core thread. They will be executed
-		 * 			as soon as the core thread is ready.
+		 * 			as soon as the core thread is ready. All queued commands are removed from the accessor.
 		 */
 		void submitToCoreThread(bool blockUntilComplete = false)
 		{

CamelotCore/Include/CmGpuProgIncludeImporter.h

@@ -5,19 +5,23 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Importer using for importing GPU program (i.e. shader) include files.
+	 * 			Include files are just text files ending with ".gpuproginc" extension.
+	 */
 	class CM_EXPORT GpuProgIncludeImporter : public SpecificImporter
 	{
 	public:
 		GpuProgIncludeImporter();
 		virtual ~GpuProgIncludeImporter();
 
-		/** Inherited from SpecificImporter */
+		/** @copydoc SpecificImporter::isExtensionSupported */
 		virtual bool isExtensionSupported(const WString& ext) const;
 
-		/** Inherited from SpecificImporter */
+		/** @copydoc SpecificImporter::isMagicNumberSupported */
 		virtual bool isMagicNumberSupported(const UINT8* magicNumPtr, UINT32 numBytes) const; 
 
-		/** Inherited from SpecificImporter */
+		/** @copydoc SpecificImporter::import */
 		virtual ResourcePtr import(const WString& filePath, ConstImportOptionsPtr importOptions);
 	private:
 	};

CamelotCore/Include/CmGpuProgramImportOptions.h

@@ -6,21 +6,67 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Contains import options you may use to control how is a GPU program (i.e. shader)
+	 * 			file imported.
+	 */
 	class CM_EXPORT GpuProgramImportOptions : public ImportOptions
 	{
 	public:
 		GpuProgramImportOptions();
 
+		/**
+		 * @brief	Sets the name of the GPU program entry point method (e.g. "main").
+		 */
 		void setEntryPoint(const String& entryPoint) { mEntryPoint = entryPoint; }
+
+		/**
+		 * @brief	Sets the language the GPU program is written in (e.g. HLSL9, GLSL, HLSL11).
+		 */
 		void setLanguage(const String& language) { mLanguage = language; }
+
+		/**
+		 * @brief	Sets GPU program profile. Determines minimal feature-set the GPU program
+		 * 			requires in order to function.
+		 */
 		void setProfile(GpuProgramProfile profile) { mProfile = profile; }
+
+		/**
+		 * @brief	Sets GPU program type (e.g. vertex, pixel, etc.).
+		 */
 		void setType(GpuProgramType type) { mType = type; }
+
+		/**
+		 * @brief	Sets optional GPU program include files which may be used
+		 * 			for sharing code across multiple programs.
+		 */
 		void setIncludes(const Vector<HGpuProgInclude>::type& includes) { mIncludes = includes; }
 
+		/**
+		 * @brief	Gets the name of the GPU program entry point method (e.g. "main").
+		 */
 		const String& getEntryPoint() const { return mEntryPoint; }
+
+		/**
+		 * @brief	Gets the language the GPU program is written in (e.g. HLSL9, GLSL, HLSL11).
+		 */
 		const String& getLanguage() const { return mLanguage; }
+
+		/**
+		 * @brief	Gets GPU program profile. Determines minimal feature-set the GPU program
+		 * 			requires in order to function.
+		 */
 		GpuProgramProfile getProfile() const { return mProfile; }
+
+		/**
+		 * @brief	Gets GPU program type (e.g. vertex, pixel, etc.).
+		 */
 		GpuProgramType getType() const { return mType; }
+
+		/**
+		 * @brief	Gets optional GPU program include files which may be used
+		 * 			for sharing code across multiple programs.
+		 */
 		const Vector<HGpuProgInclude>::type& getIncludes() const { return mIncludes; }
 
 		/************************************************************************/

CamelotCore/Include/CmGpuProgramImporter.h

@@ -5,27 +5,23 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Importer for GPU programs (i.e. shaders). File must end with ".gpuprog" extension,
+	 * 			and actual type of the program is determined via import options.
+	 */
 	class CM_EXPORT GpuProgramImporter : public SpecificImporter
 	{
 	public:
-		/**
-		 * @copydoc SpecificImporter::isExtensionSupported().
-		 */
+		/** @copydoc SpecificImporter::isExtensionSupported */
 		virtual bool isExtensionSupported(const WString& ext) const;
 
-		/**
-		 * @copydoc SpecificImporter::isMagicNumberSupported().
-		 */
+		/** @copydoc SpecificImporter::isMagicNumberSupported */
 		virtual bool isMagicNumberSupported(const UINT8* magicNumPtr, UINT32 numBytes) const; 
 
-		/**
-		 * @copydoc SpecificImporter::import().
-		 */
+		/** @copydoc SpecificImporter::import */
 		virtual ResourcePtr import(const WString& filePath, ConstImportOptionsPtr importOptions);
 
-		/**
-		 * @copydoc SpecificImporter::createImportOptions().
-		 */
+		/** @copydoc SpecificImporter::createImportOptions */
 		virtual ImportOptionsPtr createImportOptions() const;
 	};
 }