More documentation

CamelotCore/Include/CmBlendState.h

@@ -56,7 +56,7 @@ namespace BansheeEngine
 	};
 
 	/**
-	 * @brief	Render system pipeline state that allows you how an object is renderer. 
+	 * @brief	Render system pipeline state that allows you to modify how an object is rendered. 
 	 * 			More exactly this state allows to you to control how is a rendered
 	 * 			object blended with any previously renderer objects.
 	 * 			
@@ -139,7 +139,7 @@ namespace BansheeEngine
 		UINT8 getRenderTargetWriteMask(UINT32 renderTargetIdx) const;
 
 		/**
-		 * @brief	Creates a new blend states using the specified blend state description structure.
+		 * @brief	Creates a new blend state using the specified blend state description structure.
 		 */
 		static HBlendState create(const BLEND_STATE_DESC& desc);
 

CamelotCore/Include/CmDepthStencilState.h

@@ -6,6 +6,11 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Descriptor structured used for initializing DepthStencilState.
+	 *
+	 * @see		DepthStencilState
+	 */
 	struct CM_EXPORT DEPTH_STENCIL_STATE_DESC
 	{
 		DEPTH_STENCIL_STATE_DESC()
@@ -46,34 +51,106 @@ namespace BansheeEngine
 
 	CM_ALLOW_MEMCPY_SERIALIZATION(DEPTH_STENCIL_STATE_DESC);
 
-	// TODO Low priority - Write doc explaining various states
+	/**
+	* @brief	Render system pipeline state that allows you to modify how an object is rendered.
+	* 			More exactly this state allows to you to control how are depth and stencil buffers
+	*			modified upon rendering.
+	*
+	* @note		Depth stencil states are immutable. Thread safe.
+	*/
 	class CM_EXPORT DepthStencilState : public Resource
 	{
 	public:
 		virtual ~DepthStencilState() {}
 
+		/**
+		 * @brief	If enabled, any pixel about to be written will be tested against the depth value
+		 *			currently in the buffer. If the depth test passes (depending on the set value
+		 *			and chosen depth comparison function), that pixel is written and depth is
+		 *			updated (if depth write is enabled).
+		 */
 		bool getDepthReadEnable() const { return mData.depthReadEnable; }
+
+		/**
+		 * @brief	If enabled rendering pixels will update the depth buffer value. 
+		 */
 		bool getDepthWriteEnable() const { return mData.depthWriteEnable; }
+
+		/**
+		 * @brief	Determines what operation should the renderer use when comparing previous and 
+		 *			current depth value. If the operation passes, pixel with the current depth
+		 *			value will be considered visible.
+		 */
 		CompareFunction getDepthComparisonFunc() const { return mData.depthComparisonFunc; }
 
+		/**
+		 * @brief	If true then stencil buffer will also be updated when a pixel is written, and
+		 *			pixels will be tested against the stencil buffer before rendering.
+		 */
 		bool getStencilEnable() const { return mData.stencilEnable; }
+
+		/**
+		 * @brief	Mask to apply to any value read from the stencil buffer, before applying the
+		 *			stencil comparison function.
+		 */
 		UINT8 getStencilReadMask() const { return mData.stencilReadMask; }
+
+		/**
+		 * @brief	Mask to apply to any value about to be written in the stencil buffer.
+		 */
 		UINT8 getStencilWriteMask() const { return mData.stencilWriteMask; }
 
+		/**
+		 * @brief	Operation that happens when stencil comparison function fails on a front facing polygon.
+		 */
 		StencilOperation getStencilFrontFailOp() const { return mData.frontStencilFailOp; }
+
+		/**
+		* @brief	Operation that happens when stencil comparison function passes but depth test fails
+		*			on a front facing polygon.
+		*/
 		StencilOperation getStencilFrontZFailOp() const { return mData.frontStencilZFailOp; }
+
+		/**
+		* @brief	Operation that happens when stencil comparison function passes on a front facing polygon.
+		*/
 		StencilOperation getStencilFrontPassOp() const { return mData.frontStencilPassOp; }
+
+		/**
+		 * @brief	Stencil comparison function used for front facing polygons. Stencil buffer will be modified according
+		 *			to previously set stencil operations depending whether this comparison passes or fails.
+		 */
 		CompareFunction getStencilFrontCompFunc() const { return mData.frontStencilComparisonFunc; }
 
+		/**
+		* @brief	Operation that happens when stencil comparison function fails on a back facing polygon.
+		*/
 		StencilOperation getStencilBackFailOp() const { return mData.backStencilFailOp; }
+
+		/**
+		* @brief	Operation that happens when stencil comparison function passes but depth test fails
+		*			on a back facing polygon.
+		*/
 		StencilOperation getStencilBackZFailOp() const { return mData.backStencilZFailOp; }
+
+		/**
+		* @brief	Operation that happens when stencil comparison function passes on a back facing polygon.
+		*/
 		StencilOperation getStencilBackPassOp() const { return mData.backStencilPassOp; }
+
+		/**
+		* @brief	Stencil comparison function used for back facing polygons. Stencil buffer will be modified according
+		*			to previously set stencil operations depending whether this comparison passes or fails.
+		*/
 		CompareFunction getStencilBackCompFunc() const { return mData.backStencilComparisonFunc; }
 
+		/**
+		 * @brief	Creates a new depth stencil state using the specified depth stencil state description structure.
+		 */
 		static HDepthStencilState create(const DEPTH_STENCIL_STATE_DESC& desc);
 
 		/**
-		 * @brief	Returns the default depth stencil state;
+		 * @brief	Returns the default depth stencil state that you may use when no other is available.
 		 */
 		static const DepthStencilStatePtr& getDefault();
 	protected:

CamelotCore/Include/CmDrawOps.h

@@ -4,6 +4,10 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Describes operation that will be used for rendering a certain
+	 *			set of vertices.
+	 */
 	enum DrawOperationType 
 	{
 		DOT_POINT_LIST = 1,

CamelotCore/Include/CmEventQuery.h

@@ -33,13 +33,22 @@ namespace BansheeEngine
 		 */
 		virtual bool isReady() const = 0;
 
+		/**
+		 * @brief	Triggered when GPU starts processing the query.
+		 */
 		boost::signal<void()> onTriggered;
 
+		/**
+		 * @brief	Creates a new query, but does not schedule it on GPU.
+		 */
 		static EventQueryPtr create();
 
 	protected:
 		friend class QueryManager;
 
+		/**
+		 * @brief	Returns true if the query is still waiting for its "ready" callback to be triggered.
+		 */
 		bool isActive() const { return mActive; }
 		void setActive(bool active) { mActive = active; }
 

CamelotCore/Include/CmGpuBuffer.h

@@ -7,42 +7,151 @@
 
 namespace BansheeEngine 
 {
+	/**
+	 * @brief	Handles a generic GPU buffer that you may use for storing any kind of data you wish to be accessible
+	 *			to the GPU. These buffers may be bounds to GPU program binding slots and accessed from a GPU program,
+	 *			or may be used by fixed pipeline in some way.
+	 *
+	 * @note	Core thread only.
+	 */
 	class CM_EXPORT GpuBuffer : public CoreObject
     {
     public:
         virtual ~GpuBuffer();
 
+		/**
+		 * @brief	Locks the buffer returning a pointer to the internal buffer data that you may then
+		 *			read or write to. Caller must ensure it will only perform actions promised in the
+		 *			provided GPU lock options parameter.
+		 *
+		 * @param	offset	Number of bytes at which to lock the buffer. Returned pointer points to this location.
+		 * @param	length	Number of bytes to lock.
+		 * @param	options How to lock the buffer. Certain options offer better performance than others.
+		 */
 		virtual void* lock(UINT32 offset, UINT32 length, GpuLockOptions options) = 0;
+
+		/**
+		 * @brief	Unlocks a previously locked buffer. Any pointers to internal buffers returned when
+		 *			it was locked will become invalid.
+		 */
 		virtual void unlock() = 0;
 
+		/**
+		 * @brief	Reads buffer data into the previously allocated buffer.
+		 *
+		 * @param	offset	Number of bytes at which to start reading the buffer.
+		 * @param	length	Number of bytes to read.
+		 * @param	pDest	Previously allocated buffer of "length" bytes size.
+		 */
         virtual void readData(UINT32 offset, UINT32 length, void* pDest) = 0;
+
+		/**
+		* @brief	Writes data into the buffer.
+		*
+		* @param	offset		Number of bytes at which to start writing to the buffer.
+		* @param	length		Number of bytes to write.
+		* @param	pDest		Previously allocated buffer used to retrieve the data from.
+		* @param	writeFlags  Flags that may be used to improve performance for specific use cases.
+		*/
         virtual void writeData(UINT32 offset, UINT32 length, const void* pSource, BufferWriteType writeFlags = BufferWriteType::Normal) = 0;
 
+		/**
+		 * @brief	Copies data from another buffer into this buffer.
+		 *
+		 * @param	srcBuffer			Buffer to copy the data from.
+		 * @param	srcOffset			Offset in bytes into the source buffer - this is where reading starts from.
+		 * @param	dstOffset			Offset in bytes into the destination buffer - this is where writing starts from.
+		 * @param	length				Number of bytes to copy from source to destination.
+		 * @param	discardWholeBuffer	If true, the contents of the current buffer will be entirely discarded. This can improve
+		 *								performance if you know you wont be needing that data any more.
+		 */
 		virtual void copyData(GpuBuffer& srcBuffer, UINT32 srcOffset, 
 			UINT32 dstOffset, UINT32 length, bool discardWholeBuffer = false) = 0;
 
+		/**
+		 * @brief	Creates a buffer view that may be used for binding a buffer to a slot in the pipeline. Views allow you to specify
+		 *			how is data in the buffer organized to make it easier for the pipeline to interpret.
+		 *
+		 * @param	buffer			Buffer to create the view for.
+		 * @param	firstElement	Position of the first element visible by the view.
+		 * @param	elementWidth	Width of one element in bytes.
+		 * @param	numElements		Number of elements in the buffer.
+		 * @param	useCounter		Should the buffer allow use of a counter. This is only relevant for random read write buffers.
+		 * @param	usage			Determines type of the view we are creating, and which slots in the pipeline will the view be bindable to.
+		 *
+		 * @note	If a view with this exact parameters already exists, it will be returned and new one will not be created.
+		 *
+		 *			Only Default and RandomWrite views are supported for this type of buffer. 
+		 *			TODO Low Priority: Perhaps reflect this limitation by having an enum with only
+		 *			those two options?
+		 */
 		static GpuBufferView* requestView(GpuBufferPtr buffer, UINT32 firstElement, UINT32 elementWidth, UINT32 numElements, bool useCounter, GpuViewUsage usage);
+
+		/**
+		 * @brief	Releases a view created with requestView. 
+		 *
+		 * @note	View will only truly get released once all references to it are released.
+		 */
 		static void releaseView(GpuBufferView* view);
 
+		/**
+		 * @brief	Returns the type of the GPU buffer. Type determines which kind of views (if any) can be created
+		 *			for the buffer, and how is data read or modified in it.
+		 */
 		GpuBufferType getType() const { return mType; }
+
+		/**
+		 * @brief	Returns buffer usage which determines how are planning on updating the buffer contents.
+		 */
 		GpuBufferUsage getUsage() const { return mUsage; }
+
+		/**
+		 * @brief	Return whether the buffer supports random reads and writes within the GPU programs.
+		 */
 		bool getRandomGpuWrite() const { return mRandomGpuWrite; }
+
+		/**
+		 * @brief	Returns whether the buffer supports counter use within GPU programs.
+		 */
 		bool getUseCounter() const { return mUseCounter; }
+
+		/**
+		 * @brief	Returns number of elements in the buffer.
+		 */
 		UINT32 getElementCount() const { return mElementCount; }
+
+		/**
+		 * @brief	Returns size of a single element in the buffer in bytes.
+		 */
 		UINT32 getElementSize() const { return mElementSize; }
 
 	protected:
 		GpuBuffer(UINT32 elementCount, UINT32 elementSize, GpuBufferType type, GpuBufferUsage usage, bool randomGpuWrite = false, bool useCounter = false);
 
+		/**
+		 * @brief	Creates an empty view for the current buffer.
+		 */
 		virtual GpuBufferView* createView() = 0;
+
+		/**
+		 * @brief	Destroys a view previously created for this buffer.
+		 */
 		virtual void destroyView(GpuBufferView* view) = 0;
+
+		/**
+		 * @brief	Destroys all buffer views regardless if their reference count is
+		 *			zero or not.
+		 */
 		void clearBufferViews();
 
 		/**
-		 * @copydoc CoreGpuObject::destroy_internal()
+		 * @copydoc CoreObject::destroy_internal()
 		 */
 		virtual void destroy_internal();
 
+		/**
+		 * @brief	Helper class to help with reference counting for GPU buffer views.
+		 */
 		struct GpuBufferReference
 		{
 			GpuBufferReference(GpuBufferView* _view)

CamelotCore/Include/CmGpuBufferView.h

@@ -5,6 +5,12 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Descriptor structure used for initializing a GPU buffer view.
+	 *
+	 * @see		GpuBufferView
+	 * @see		GpuBuffer
+	 */
 	struct CM_EXPORT GPU_BUFFER_DESC
 	{
 		UINT32 firstElement;
@@ -14,6 +20,10 @@ namespace BansheeEngine
 		GpuViewUsage usage;
 	};
 
+	/**
+	 * @brief	Holds information about a GPU buffer view. Views allow you to specify
+	 *			how is data in a buffer organized to make it easier for the pipeline to interpret.
+	 */
 	class CM_EXPORT GpuBufferView
 	{
 	public:
@@ -32,15 +42,49 @@ namespace BansheeEngine
 		GpuBufferView();
 		virtual ~GpuBufferView();
 
+		/**
+		 * @brief	Initializes the GPU buffer view. Must be called right after
+		 *			construction.
+		 */
 		virtual void initialize(GpuBufferPtr buffer, GPU_BUFFER_DESC& desc);
 
+		/**
+		 * @brief	Returns a descriptor structure used for creating the view.
+		 */
 		const GPU_BUFFER_DESC& getDesc() const { return mDesc; }
+
+		/**
+		 * @brief	Returns the buffer this view was created for.
+		 */
 		GpuBufferPtr getBuffer() const { return mBuffer; }
 
+		/**
+		 * @brief	Returns index of first element in the buffer that this view
+		 *			provides access to.
+		 */
 		UINT32 getFirstElement() const { return mDesc.firstElement; }
+
+		/**
+		 * @brief	Returns width of an element in the buffer, in bytes.
+		 */
 		UINT32 getElementWidth() const { return mDesc.elementWidth; }
+
+		/**
+		 * @brief	Returns the total number of elements this buffer provides
+		 *			access to.
+		 */
 		UINT32 getNumElements() const { return mDesc.numElements; }
+
+		/**
+		 * @brief	Returns true if this view allows a GPU program to use counters on
+		 *			the bound buffer.
+		 */
 		bool getUseCounter() const { return mDesc.useCounter; }
+
+		/**
+		 * @brief	Returns view usage which determines where in the pipeline 
+		 *			can the view be bound.
+		 */
 		GpuViewUsage getUsage() const { return mDesc.usage; }
 
 	protected: