More documentation

CamelotCore/Include/CmBindableGpuParamBlock.h

@@ -7,8 +7,13 @@
 namespace BansheeEngine
 {
 	/**
-	* @note	Due to the way allocation is handled, this class is not allowed to have a destructor.
-	*/
+	 * @brief	Specialized class for binding GPU parameters to the render system. Represents a single
+	 * 			parameter block buffer and is used for temporary storage of GPU parameters.
+	 * 
+	 * @note	Due to the way allocation is handled, this class is not allowed to have a destructor.
+	 * 			
+	 * @see		BindableGpuParams
+ 	 */
 	class CM_EXPORT BindableGpuParamBlock
 	{
 	public:
@@ -16,10 +21,17 @@ namespace BansheeEngine
 
 		/**
 		 * @brief	Uploads the current data to the specified buffer, and marks the block a non-dirty.
-		 * 			Should only be called from the core thread.
+		 * 			
+		 * @note	Core thread only.			
 		 */
 		void uploadToBuffer(GpuParamBlockBufferPtr buffer);
 
+		/**
+		 * @brief	Query if this object is dirty. If dirty the data of this block
+		 * 			will need to be uploaded to a GPU buffer.
+		 *
+		 * @note	Core thread only.
+		 */
 		bool isDirty() const { return mDirty; }
 	protected:
 		friend class GpuParams;

CamelotCore/Include/CmBindableGpuParams.h

@@ -5,16 +5,18 @@
 namespace BansheeEngine
 {
 	/**
-		* @brief	Specialized class for binding GPU parameters to the render system. This is a temporary class that
-		* 			is used for temporarily saving parameter data while parameters are scheduled to be bound to the GPU.
-		* 			This allows us to freely modify base GpuParams without worrying about changing scheduled by still 
-		* 			not executed parameter binds.
-		* 			
-		* @note		Upon assignment this class transfers ownership of its data. Internal data
-		* 			is destroyed when last assigned instance goes out of scope.
-		* 			(In short, you should never have more than one active copy of an instance of this class)
-		* 			
-		*			Created on the sim thread and used exclusively on the core thread.
+	 * @brief	Specialized class for binding GPU parameters to the render system. This is a temporary class that
+	 * 			is used for temporarily saving parameter data while parameters are scheduled to be bound to the GPU.
+	 * 			This allows us to freely modify base GpuParams without worrying about changing scheduled by still 
+	 * 			not executed parameter binds.
+	 * 			
+	 * @note	Upon assignment this class transfers ownership of its internal data. Internal data
+	 * 			is destroyed when last assigned instance goes out of scope.
+	 * 			(In short, you should never have more than one active copy of an instance of this class)
+	 * 			
+	 *			Created on the sim thread and used exclusively on the core thread.
+	 *			
+	 * @see		CoreThreadAccessorBase::bindGpuParams
 	**/
 	class CM_EXPORT BindableGpuParams
 	{
@@ -24,15 +26,33 @@ namespace BansheeEngine
 		~BindableGpuParams();
 
 		/**
-		 * @brief	Updates all used hardware parameter buffers. Should ONLY be called from core thread.
+		 * @brief	Uploads all CPU stored parameter buffer data to the GPU buffers.
 		 */
 		void updateHardwareBuffers();
 
+		/**
+		 * @brief	Gets a parameter block buffer from the specified slot.
+		 */
 		GpuParamBlockBufferPtr getParamBlockBuffer(UINT32 slot) const;
+
+		/**
+		 * @brief	Gets a parameter block buffer by name.
+		 */
 		GpuParamBlockBufferPtr getParamBlockBuffer(const String& name) const;
+
+		/**
+		 * @brief	Gets a texture bound to the specified slot.
+		 */
 		HTexture getTexture(UINT32 slot);
+
+		/**
+		 * @brief	Gets a sampler state bound to the specified slot.
+		 */
 		HSamplerState getSamplerState(UINT32 slot);
 
+		/**
+		 * @brief	Gets a description of all parameters stored in this class.
+		 */
 		const GpuParamDesc& getParamDesc() const { return mParamDesc; }
 
 	private:

CamelotCore/Include/CmBlendState.h

@@ -6,6 +6,13 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Structure that describes blend states for a single render
+	 * 			target. Used internally by BLEND_STATE_DESC for initializing a BlendState.
+	 * 			
+	 * @see		BLEND_STATE_DESC
+	 * @see		BlendState
+	 */
 	struct CM_EXPORT RENDER_TARGET_BLEND_STATE_DESC
 	{
 		RENDER_TARGET_BLEND_STATE_DESC()
@@ -30,6 +37,12 @@ namespace BansheeEngine
 		UINT8 renderTargetWriteMask;
 	};
 
+	/**
+	 * @brief	Structure that describes render pipeline blend states. Used for initializing
+	 * 			BlendState.
+	 * 			
+	 * @see		BlendState.
+	 */
 	struct CM_EXPORT BLEND_STATE_DESC
 	{
 		BLEND_STATE_DESC()
@@ -42,34 +55,106 @@ namespace BansheeEngine
 		RENDER_TARGET_BLEND_STATE_DESC renderTargetDesc[CM_MAX_MULTIPLE_RENDER_TARGETS];
 	};
 
-	// TODO Low priority - Write doc explaining various states
+	/**
+	 * @brief	Render system pipeline state that allows you how an object is renderer. 
+	 * 			More exactly this state allows to you to control how is a rendered
+	 * 			object blended with any previously renderer objects.
+	 * 			
+	 * @note	Blend states are immutable. Thread safe.
+	 */
 	class CM_EXPORT BlendState : public Resource
 	{
 	public:
 		virtual ~BlendState() {}
 
+		/**
+		 * @brief	Alpha to coverage allows you to perform blending without needing to worry about order of
+		 * 			rendering like regular blending does. It requires multi-sampling to be active in order to
+		 * 			work, and you need to supply an alpha texture that determines object transparency.
+		 *
+		 *			Blending is then performed by only using sub-samples covered by the alpha texture for the current
+		 *			pixel and combining them with sub-samples previously stored. 
+		 *			
+		 *			Be aware this is a limited technique only useful for certain situations. Unless you are having performance
+		 *			problems use regular blending.
+		 */
 		bool getAlphaToCoverageEnabled() const { return mData.alphaToCoverageEnable; }
+
+		/**
+		 * @brief	When not set, only the first render target blend descriptor will be used for all
+		 * 			render targets. If set each render target will use its own blend descriptor.
+		 */
 		bool getIndependantBlendEnable() const { return mData.independantBlendEnable; }
 
+		/**
+		 * @brief	Queries is blending enabled for the specified render target. Blending
+		 * 			allows you to combine the color from current and previous pixel based on
+		 * 			some value.
+		 */
 		bool getBlendEnabled(UINT32 renderTargetIdx) const;
+
+		/**
+		 * @brief	Determines what should the source blend factor be. This value determines
+		 * 			what will the color being generated currently be multiplied by.
+		 */
 		BlendFactor getSrcBlend(UINT32 renderTargetIdx) const;
+
+		/**
+		 * @brief	Determines what should the destination blend factor be. This value determines
+		 * 			what will the color already in render target be multiplied by.
+		 */
 		BlendFactor getDstBlend(UINT32 renderTargetIdx) const;
+
+		/**
+		 * @brief	Determines how are source and destination colors combined (after they are multiplied
+		 * 			by their respective blend factors).
+		 */
 		BlendOperation getBlendOperation(UINT32 renderTargetIdx) const;
+
+		/**
+		 * @brief	Determines what should the alpha source blend factor be. This value determines
+		 * 			what will the alpha value being generated currently be multiplied by.
+		 */
 		BlendFactor getAlphaSrcBlend(UINT32 renderTargetIdx) const;
+
+		/**
+		 * @brief	Determines what should the alpha destination blend factor be. This value determines
+		 * 			what will the alpha value already in render target be multiplied by.
+		 */
 		BlendFactor getAlphaDstBlend(UINT32 renderTargetIdx) const;
+
+		/**
+		 * @brief	Determines how are source and destination alpha values combined (after they are multiplied
+		 * 			by their respective blend factors).
+		 */
 		BlendOperation getAlphaBlendOperation(UINT32 renderTargetIdx) const;
+
+		/**
+		 * @brief	Render target write mask allows to choose which pixel components should the pixel shader
+		 * 			output.
+		 * 			
+		 *			Only the first four bits are used. First bit representing red, second green, third blue and
+		 *			fourth alpha value. Set bits means pixel shader will output those channels.
+		 */
 		UINT8 getRenderTargetWriteMask(UINT32 renderTargetIdx) const;
 
+		/**
+		 * @brief	Creates a new blend states using the specified blend state description structure.
+		 */
 		static HBlendState create(const BLEND_STATE_DESC& desc);
 
 		/**
-		 * @brief	Returns the default blend state;
+		 * @brief	Returns the default blend state that you may use
+		 * 			when no other is available.
 		 */
 		static const BlendStatePtr& getDefault();
 
 	protected:
 		friend class RenderStateManager;
 
+		/**
+		 * @brief	Initializes the blend state. Must be called right after construction.
+		 */
 		virtual void initialize(const BLEND_STATE_DESC& desc);
 
 		BLEND_STATE_DESC mData;