More documentation

CamelotCore/Include/CmPixelBuffer.h

@@ -1,117 +1,93 @@
-/*
------------------------------------------------------------------------------
-This source file is part of OGRE
-    (Object-oriented Graphics Rendering Engine)
-For the latest info, see http://www.ogre3d.org/
+#pragma once
 
-Copyright (c) 2000-2011 Torus Knot Software Ltd
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
------------------------------------------------------------------------------
-*/
-#ifndef __HardwarePixelBuffer__
-#define __HardwarePixelBuffer__
-
-// Precompiler options
 #include "CmPrerequisites.h"
 #include "CmHardwareBuffer.h"
 #include "CmPixelUtil.h"
 
-namespace BansheeEngine {
-
-	/** \addtogroup Core
-	*  @{
-	*/
-	/** \addtogroup RenderSystem
-	*  @{
-	*/
-	/** Specialisation of HardwareBuffer for a pixel buffer. The
-    	HardwarePixelbuffer abstracts an 1D, 2D or 3D quantity of pixels
-    	stored by the rendering API. The buffer can be located on the card
-    	or in main memory depending on its usage. One mipmap level of a
-    	texture is an example of a HardwarePixelBuffer.
-    */
+namespace BansheeEngine 
+{
+	/**
+	 * @brief	Represents a hardware buffer that stores a single pixel surface.
+	 *			This may be a 1D, 2D or 3D surface, but unlike a texture it consists
+	 *			only of a single surface (no mip maps, cube map faces or similar).
+	 *
+	 * @note	Core thread only
+	 */
     class CM_EXPORT PixelBuffer : public HardwareBuffer
     {
-    protected: 
-        // Extents
-        UINT32 mWidth, mHeight, mDepth;
-        // Pitches (offsets between rows and slices)
-        UINT32 mRowPitch, mSlicePitch;
-        // Internal format
-        PixelFormat mFormat;
-        // Currently locked region (local coords)
-        PixelData mCurrentLock;
-		// The current locked box of this surface (entire surface coords)
-		PixelVolume mLockedBox;
-        
-        /// Internal implementation of lock(), must be overridden in subclasses
-        virtual PixelData lockImpl(const PixelVolume lockBox,  GpuLockOptions options) = 0;
-
-        /// Internal implementation of lock(), do not OVERRIDE or CALL this
-        /// for HardwarePixelBuffer implementations, but override the previous method
-        virtual void* lockImpl(UINT32 offset, UINT32 length, GpuLockOptions options);
-
-		friend class RenderTexture;
     public:
-        /// Should be called by HardwareBufferManager
-        PixelBuffer(UINT32 mWidth, UINT32 mHeight, UINT32 mDepth,
-                PixelFormat mFormat, GpuBufferUsage usage, bool useSystemMemory);
+        PixelBuffer(UINT32 mWidth, UINT32 mHeight, UINT32 mDepth, PixelFormat mFormat, 
+			GpuBufferUsage usage, bool useSystemMemory);
         ~PixelBuffer();
 
-        /** make every lock method from HardwareBuffer available.
-        See http://www.research.att.com/~bs/bs_faq2.html#overloadderived
-        */
+		// Make the other lock overloads visible.
         using HardwareBuffer::lock;	
 
-        /** Lock the buffer for (potentially) reading / writing.
-		    @param lockBox Region of the buffer to lock
-		    @param options Locking options
-		    @returns PixelBox containing the locked region, the pitches and
-		    	the pixel format
-		*/
+		/**
+		 * @brief	Locks a certain region of the pixel buffer for reading and returns a pointer
+		 *			to the locked region.
+		 *
+		 * @param	lockBox		Region of the surface to lock.
+		 * @param	options		Lock options that hint the hardware on what you intend to do with the locked data.
+		 *
+		 * @note	Returned object is only valid while the lock is active.
+		 */
 		virtual const PixelData& lock(const PixelVolume& lockBox, GpuLockOptions options);
-		/// @copydoc HardwareBuffer::lock
+		
+		/**
+		 * @copydoc	HardwareBuffer::lock
+		 */
         virtual void* lock(UINT32 offset, UINT32 length, GpuLockOptions options);
-
-		/** Get the current locked region. This is the same value as returned
-		    by lock(const Image::Box, LockOptions)
-		    @returns PixelBox containing the locked region
-		*/        
-        const PixelData& getCurrentLock();
 		
-		/// @copydoc HardwareBuffer::readData
+		/**
+		 * @copydoc	HardwareBuffer::readData
+		 */
 		virtual void readData(UINT32 offset, UINT32 length, void* pDest);
-		/// @copydoc HardwareBuffer::writeData
+
+		/**
+		 * @copydoc	HardwareBuffer::writeData
+		 */
 		virtual void writeData(UINT32 offset, UINT32 length, const void* pSource, BufferWriteType writeFlags = BufferWriteType::Normal);
 
-        /// Gets the width of this buffer
+		/**
+		 * @brief	Returns width of the surface in pixels.
+		 */
         UINT32 getWidth() const { return mWidth; }
-        /// Gets the height of this buffer
+
+		/**
+		 * @brief	Returns height of the surface in pixels.
+		 */
         UINT32 getHeight() const { return mHeight; }
-        /// Gets the depth of this buffer
+
+		/**
+		 * @brief	Returns depth of the surface in pixels.
+		 */
         UINT32 getDepth() const { return mDepth; }
-        /// Gets the native pixel format of this buffer
+
+		/**
+		 * @brief	Returns format of the pixels in the surface.
+		 */
         PixelFormat getFormat() const { return mFormat; }
-    };
 
-	/** @} */
-}
-#endif
+	protected:
+		friend class RenderTexture;
 
+		/**
+		 * @brief	Internal implementation of the "lock" method.
+		 */
+		virtual PixelData lockImpl(const PixelVolume lockBox, GpuLockOptions options) = 0;
+
+		/**
+		 * @copydoc	HardwareBuffer::lockImpl
+		 */
+		virtual void* lockImpl(UINT32 offset, UINT32 length, GpuLockOptions options);
+
+	protected:
+		UINT32 mWidth, mHeight, mDepth;
+		UINT32 mRowPitch, mSlicePitch;
+		PixelFormat mFormat;
+
+		PixelData mCurrentLock;
+		PixelVolume mLockedBox;
+    };
+}

CamelotCore/Include/CmRasterizerState.h

@@ -6,6 +6,12 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Structure that describes pipeline rasterizer state. Used for initializing
+	 *			a RasterizerState.
+	 *
+	 * @see		RasterizerState
+	 */
 	struct CM_EXPORT RASTERIZER_STATE_DESC
 	{
 		RASTERIZER_STATE_DESC()
@@ -33,34 +39,101 @@ namespace BansheeEngine
 		bool antialiasedLineEnable;
 	};
 
-	// TODO Low priority - Write doc explaining various states
+	/**
+	 * @brief	Render system pipeline state that allows you to modify how an object is rasterized.
+	 *			i.e. how are polygons converted to pixels.
+	 *
+	 * @note	Rasterizer states are immutable. Thread safe.
+	 */
 	class CM_EXPORT RasterizerState : public Resource
 	{
 	public:
 		virtual ~RasterizerState() {}
 
+		/**
+		 * @brief	Polygon mode allows you to draw polygons as solid objects or as wireframe by
+		 *			just drawing their edges.
+		 */
 		PolygonMode getPolygonMode() const { return mData.polygonMode; }
+
+		/**
+		 * @brief	Sets vertex winding order. Faces that contain vertices with this order will 
+		 *			be culled and not rasterized. Used primarily for saving cycles by not rendering
+		 *			backfacing faces.
+		 */
 		CullingMode getCullMode() const { return mData.cullMode; }
 
+		/**
+		* @brief	Represents a constant depth bias that will offset the depth values of new pixels 
+		*			by the specified amount.
+		*
+		* @note		This is useful if you want to avoid z fighting for objects at the same or similar depth.
+		*/
 		int getDepthBias() const { return mData.depthBias; }
+
+		/**
+		 * @brief	Maximum depth bias value.
+		 */
 		float getDepthBiasClamp() const { return mData.depthBiasClamp; }
+
+		/**
+		 * @brief	Represents a dynamic depth bias that increases as the slope of the rendered polygons 
+		 *			surface increases. Resulting value offsets depth values of new pixels. This offset will 
+		 *			be added on top of the constant depth bias.
+		 *
+		 * @note	This is useful if you want to avoid z fighting for objects at the same or similar depth.
+		 */
 		float getSlopeScaledDepthBias() const { return mData.slopeScaledDepthBias; }
 
+		/**
+		 * @brief	If true, clipping of polygons past the far Z plane is enabled. This ensures proper
+		 *			Z ordering for polygons outside of valid depth range (otherwise they all have the same
+		 *			depth). It can be useful to disable if you are performing stencil operations that count on
+		 *			objects having a front and a back (like stencil shadow) and don't want to clip the back.
+		 */
 		bool getDepthClipEnable() const { return mData.depthClipEnable; }
+
+		/**
+		 * @brief	Scissor rectangle allows you to cull all pixels outside of the scissor rectangle.
+		 *			
+		 * @see		RenderSystem::setScissorRect
+		 */
 		bool getScissorEnable() const { return mData.scissorEnable; }
+
+		/**
+		 * @brief	Determines how are samples in multi-sample render targets handled.
+		 *			If disabled all samples in the render target will be written the same value, 
+		 *			and if enabled each sample will be generated separately.
+		 *			
+		 * @note	In order to get an antialiased image you need to both enable this option and use
+		 *			a MSAA render target.
+		 */
 		bool getMultisampleEnable() const { return mData.multisampleEnable; }
+
+		/**
+		 * @brief	Determines should the lines be antialiased. This is separate from multi-sample
+		 *			antialiasing setting as lines can be antialiased without multi-sampling.
+		 *
+		 * @note	This setting is usually ignored if MSAA is used, as that provides sufficient antialiasing.
+		 */
 		bool getAntialiasedLineEnable() const { return mData.antialiasedLineEnable; }
 
+		/**
+		 * @brief	Creates a new rasterizer state using the specified rasterizer state descriptor structure.
+		 */
 		static HRasterizerState create(const RASTERIZER_STATE_DESC& desc);
 
 		/**
-		 * @brief	Returns the default rasterizer state;
+		 * @brief	Returns the default rasterizer state.
 		 */
 		static const RasterizerStatePtr& getDefault();
 
 	protected:
 		friend class RenderStateManager;
 
+		/**
+		* @brief	Initializes the rasterizer state. Must be called right after construction.
+		*/
 		virtual void initialize(const RASTERIZER_STATE_DESC& desc);
 		RASTERIZER_STATE_DESC mData;
 

CamelotCore/Source/CmPixelBuffer.cpp

@@ -1,30 +1,3 @@
-/*
------------------------------------------------------------------------------
-This source file is part of OGRE
-    (Object-oriented Graphics Rendering Engine)
-For the latest info, see http://www.ogre3d.org
-
-Copyright (c) 2000-2011 Torus Knot Software Ltd
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
------------------------------------------------------------------------------
-*/
 #include "CmPixelBuffer.h"
 #include "CmException.h"
 
@@ -37,7 +10,6 @@ namespace BansheeEngine
         mWidth(width), mHeight(height), mDepth(depth),
         mFormat(format)
     {
-        // Default
         mRowPitch = mWidth;
         mSlicePitch = mHeight*mWidth;
 		mSizeInBytes = mHeight*mWidth*PixelUtil::getNumElemBytes(mFormat);
@@ -66,13 +38,6 @@ namespace BansheeEngine
         return mCurrentLock;
     }
     
-    const PixelData& PixelBuffer::getCurrentLock() 
-	{ 
-        assert(isLocked() && "Cannot get current lock: buffer not locked");
-        
-        return mCurrentLock; 
-    }
-
     void* PixelBuffer::lockImpl(UINT32 offset, UINT32 length, GpuLockOptions options)
     {
 		CM_EXCEPT(InternalErrorException, "lockImpl(offset,length) is not valid for PixelBuffers and should never be called");
@@ -81,14 +46,12 @@ namespace BansheeEngine
 	void PixelBuffer::readData(UINT32 offset, UINT32 length, void* pDest)
 	{
 		// TODO
-		CM_EXCEPT(NotImplementedException,
-				"Reading a byte range is not implemented. Use blitToMemory.");
+		CM_EXCEPT(NotImplementedException, "Reading a byte range is not implemented. Use blitToMemory.");
 	}
 
 	void PixelBuffer::writeData(UINT32 offset, UINT32 length, const void* pSource, BufferWriteType writeFlags)
 	{
 		// TODO
-		CM_EXCEPT(NotImplementedException,
-				"Writing a byte range is not implemented. Use blitFromMemory.");
+		CM_EXCEPT(NotImplementedException, "Writing a byte range is not implemented. Use blitFromMemory.");
 	}
 }

CamelotD3D9Renderer/Source/CmD3D9PixelBuffer.cpp

@@ -303,7 +303,7 @@ namespace BansheeEngine
 	}
 
 	//-----------------------------------------------------------------------------  
-	BansheeEngine::PixelData D3D9PixelBuffer::lockBuffer(BufferResources* bufferResources, 
+	PixelData D3D9PixelBuffer::lockBuffer(BufferResources* bufferResources, 
 													   const PixelVolume &lockBox, 
 													   DWORD flags)
 	{