More documentation

CamelotCore/Include/CmGpuProgInclude.h

@@ -5,12 +5,27 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Raw text resource that serves as an include file for GPU programs.
+	 */
 	class CM_EXPORT GpuProgInclude : public Resource
 	{
 	public:
+		/**
+		 * @brief	Text of the include file.
+		 */
 		const String& getString() const { return mString; }
 
+		/**
+		 * @brief	Creates a new include file resource with the specified include string.
+		 */
 		static HGpuProgInclude create(const String& includeString);
+
+		/**
+		 * @brief	Creates an include file resource with the specified include string.
+		 *
+		 * @note	Internal method. Use "create" for normal use.
+		 */
 		static GpuProgIncludePtr _createPtr(const String& includeString);
 	private:
 		GpuProgInclude(const String& includeString);

CamelotCore/Include/CmGpuResource.h

@@ -5,6 +5,12 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Represents a resource that in some way deals directly with the rendering
+	 *			API and the GPU.
+	 *
+	 * @note	e.g. texture, mesh, buffer, etc.
+	 */
 	class CM_EXPORT GpuResource : public Resource
 	{
 	public:

CamelotCore/Include/CmGpuResourceData.h

@@ -5,9 +5,17 @@
 namespace BansheeEngine
 {
 	/**
-	 * @brief	You can use this class to read and write to various GPU resources. 
+	 * @brief	You can use this class as a storage for reading and writing from/to various GPU resources. 
+	 *			It is meant to be created on sim thread and used on the core thread. This class is abstract
+	 *			and specific resource types need to implement their own type of GpuResourceData.
 	 * 			
-	 * @note	If you allocate an internal buffer to store the resource data, the ownership of the buffer
+	 * @note	Normal use of this class involves requesting an instance of GpuResourceData from a GpuResource,
+	 *			then scheduling a read or write on that resource using the provided instance.
+	 *			Instance will be locked while it is used by the core thread and sim thread will be allowed to
+	 *			access it when the operation ends. Caller can track AsyncOps regarding the read/write operation
+	 *			to be notified when it is complete.
+	 *
+	 *			If you allocate an internal buffer to store the resource data, the ownership of the buffer
 	 * 			will always remain with the initial instance of the class. If that initial instance
 	 * 			is deleted, any potential copies will point to garbage data.
 	 */
@@ -18,12 +26,15 @@ namespace BansheeEngine
 		GpuResourceData(const GpuResourceData& copy);
 		virtual ~GpuResourceData();
 
+		/**
+		 * @brief	Returns pointer to the internal buffer.
+		 */
 		UINT8* getData() const;
 
 		/**
 		 * @brief	Allocates an internal buffer of a certain size. If there is another
 		 * 			buffer already allocated, it will be freed and new one will be allocated.
-		 * 			Buffer size is determine based on parameters used for initializing the class.
+		 * 			Buffer size is determined based on parameters used for initializing the class.
 		 */
 		void allocateInternalBuffer();
 
@@ -51,16 +62,24 @@ namespace BansheeEngine
 		void setExternalBuffer(UINT8* data);
 
 		/**
-		 * @brief	Locks the data and makes it available only to the core thread. Don't call manually.
+		 * @brief	Locks the data and makes it available only to the core thread. 
+		 *
+		 * @note	Internal method.
 		 */
 		void lock() const;
 
 		/**
-		 * @brief	Unlocks the data and makes it available to all threads. Don't call manually.
+		 * @brief	Unlocks the data and makes it available to all threads. 
+		 *
+		 * @note	Internal method.
 		 */
 		void unlock() const;
 
 	protected:
+		/**
+		 * @brief	Returns the size of the internal buffer in bytes. This is calculated based
+		 *			on parameters provided upon construction and specific implementation details.
+		 */
 		virtual UINT32 getInternalBufferSize() = 0;
 
 	private:

CamelotCore/Include/CmMesh.h

@@ -10,6 +10,11 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Primary class for holding geometry. Stores data in the form of a vertex 
+	 *			buffers and optionally index buffer, which may be bound to the pipeline for drawing.
+	 *			May contain multiple sub-meshes.
+	 */
 	class CM_EXPORT Mesh : public MeshBase
 	{
 	public:
@@ -45,7 +50,14 @@ namespace BansheeEngine
 		 */
 		UINT32 mapToSubresourceIdx() const { return 0; }
 
+		/**
+		 * @brief	Returns an axis aligned bounding box of the geometry contained in the vertex buffers for all submeshes.
+		 */
 		const AABox& getBounds() const;
+
+		/**
+		 * @brief	Returns an axis aligned bounding box of the geometry contained in the specific sub-mesh.
+		 */
 		const AABox& getBounds(UINT32 submeshIdx) const;
 
 		/**
@@ -112,25 +124,84 @@ namespace BansheeEngine
 		/************************************************************************/
 		
 	public:
+		/**
+		 * @brief	Creates a new empty mesh.
+		 *
+		 * @param	numVertices		Number of vertices in the mesh.
+		 * @param	numIndices		Number of indices in the mesh. 
+		 * @param	vertexDesc		Vertex description structure that describes how are vertices organized in the
+		 *							vertex buffer. When binding a mesh to the pipeline you must ensure vertex description
+		 *							at least partially matches the input description of the currently bound vertex GPU program.
+		 * @param	bufferType		Specify static for buffers you don't plan on updating other reading from often. Otherwise specify
+		 *							dynamic. This parameter affects performance.
+		 * @param	drawOp			Determines how should the provided indices be interpreted by the pipeline. Default option is triangles,
+		 *							where three indices represent a single triangle.
+		 * @param	indexType		Size of indices, use smaller size for better performance, however be careful not to go over
+		 *							the number of vertices limited by the size.
+		 */
 		static HMesh create(UINT32 numVertices, UINT32 numIndices, 
 			const VertexDataDescPtr& vertexDesc, MeshBufferType bufferType = MeshBufferType::Static, 
 			DrawOperationType drawOp = DOT_TRIANGLE_LIST, IndexBuffer::IndexType indexType = IndexBuffer::IT_32BIT);
 
+		/**
+		 * @brief	Creates a new mesh and immediately writes some data to the mesh. This is faster than writing
+		 *			the data in a separate step after creation.
+		 *
+		 * @param	numVertices		Number of vertices in the mesh.
+		 * @param	numIndices		Number of indices in the mesh. 
+		 * @param	vertexDesc		Vertex description structure that describes how are vertices organized in the
+		 *							vertex buffer. When binding a mesh to the pipeline you must ensure vertex description
+		 *							at least partially matches the input description of the currently bound vertex GPU program.
+		 * @param	initialMeshData	Vertex and index data used for initializing the mesh. Caller must ensure the data vertex and index buffers
+		 *							match the ones in the mesh, however the data might only write to a certain subset of the mesh, it does not
+		 *							have to write to all of it.
+		 * @param	bufferType		Specify static for buffers you don't plan on updating other reading from often. Otherwise specify
+		 *							dynamic. This parameter affects performance.
+		 * @param	drawOp			Determines how should the provided indices be interpreted by the pipeline. Default option is triangles,
+		 *							where three indices represent a single triangle.
+		 * @param	indexType		Size of indices, use smaller size for better performance, however be careful not to go over
+		 *							the number of vertices limited by the size.
+		 */
 		static HMesh create(UINT32 numVertices, UINT32 numIndices, const VertexDataDescPtr& vertexDesc, const MeshDataPtr& initialMeshData, 
 			MeshBufferType bufferType = MeshBufferType::Static, DrawOperationType drawOp = DOT_TRIANGLE_LIST, 
 			IndexBuffer::IndexType indexType = IndexBuffer::IT_32BIT);
 
+		/**
+		 * @brief	Creates a new mesh from an existing mesh data. Created mesh will match the vertex and index buffers described
+		 *			by the mesh data exactly.
+		 *
+		 * @param	initialMeshData	Vertex and index data used for initializing the mesh. 
+		 * @param	bufferType		Specify static for buffers you don't plan on updating other reading from often. Otherwise specify
+		 *							dynamic. This parameter affects performance.
+		 * @param	drawOp			Determines how should the provided indices be interpreted by the pipeline. Default option is triangles,
+		 *							where three indices represent a single triangle.
+		 */
 		static HMesh create(const MeshDataPtr& initialMeshData, MeshBufferType bufferType = MeshBufferType::Static, 
 			DrawOperationType drawOp = DOT_TRIANGLE_LIST);
 
+		/**
+		 * @copydoc	create(UINT32, UINT32, const VertexDataDescPtr&, MeshBufferType, DrawOperationType, IndexBuffer::IndexType)
+		 *
+		 * @note	Internal method. Use "create" for normal use.
+		 */
 		static MeshPtr _createPtr(UINT32 numVertices, UINT32 numIndices, 
 			const VertexDataDescPtr& vertexDesc, MeshBufferType bufferType = MeshBufferType::Static, 
 			DrawOperationType drawOp = DOT_TRIANGLE_LIST, IndexBuffer::IndexType indexType = IndexBuffer::IT_32BIT);
 
+		/**
+		 * @copydoc	create(UINT32, UINT32, const VertexDataDescPtr&, const MeshDataPtr&, MeshBufferType, DrawOperationType, IndexBuffer::IndexType)
+		 *
+		 * @note	Internal method. Use "create" for normal use.
+		 */
 		static MeshPtr _createPtr(UINT32 numVertices, UINT32 numIndices, const VertexDataDescPtr& vertexDesc, const MeshDataPtr& initialMeshData, 
 			MeshBufferType bufferType = MeshBufferType::Static, DrawOperationType drawOp = DOT_TRIANGLE_LIST, 
 			IndexBuffer::IndexType indexType = IndexBuffer::IT_32BIT);
 
+		/**
+		 * @copydoc	create(const MeshDataPtr&, MeshBufferType, DrawOperationType)
+		 *
+		 * @note	Internal method. Use "create" for normal use.
+		 */
 		static MeshPtr _createPtr(const MeshDataPtr& initialMeshData, MeshBufferType bufferType = MeshBufferType::Static, 
 			DrawOperationType drawOp = DOT_TRIANGLE_LIST);
 	};

CamelotCore/Include/CmMeshBase.h

@@ -7,20 +7,48 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Type of buffers used by a mesh. These options usually affect performance and 
+	 *			you should specify static if you don't plan on modifying the mesh often,
+	 *			otherwise specify dynamic.
+	 */
 	enum class MeshBufferType
 	{
 		Static,
 		Dynamic
 	};
 
+	/**
+	 * @brief	Base class all mesh implementations derive from. Meshes hold geometry information,
+	 *			normally in the form of one or serveral index or vertex buffers. Different mesh implementations
+	 *			might choose to manage those buffers differently.
+	 */
 	class CM_EXPORT MeshBase : public GpuResource
 	{
 	public:
+		/**
+		 * @brief	Constructs a new instance.
+		 * @param	numVertices		Number of vertices in the mesh.
+		 * @param	numIndices		Number of indices in the mesh. 
+		 * @param	drawOp			Determines how should the provided indices be interpreted by the pipeline. Default option is triangles,
+		 *							where three indices represent a single triangle.
+		 */
 		MeshBase(UINT32 numVertices, UINT32 numIndices, DrawOperationType drawOp = DOT_TRIANGLE_LIST);
 		virtual ~MeshBase();
 
+		/**
+		 * @brief	Removes all sub-meshes in the mesh. All indices in the mesh will be assumed to
+		 *			belong to a single mesh.
+		 *
+		 * @note	Sim thread only.
+		 */
 		void clearSubMeshes();
 
+		/**
+		 * @brief	Allows you to mark a part of the mesh as a sub-mesh so you may draw that part separately.
+		 *
+		 * @note	Sim thread only.
+		 */
 		void addSubMesh(UINT32 indexOffset, UINT32 indexCount, DrawOperationType drawOp = DOT_TRIANGLE_LIST);
 
 		/**
@@ -33,7 +61,8 @@ namespace BansheeEngine
 
 		/**
 		 * @brief	Retrieves a sub-mesh containing data used for rendering a
-		 * 			certain portion of this mesh.
+		 * 			certain portion of this mesh. If no sub-meshes are specified manually
+		 *			a special sub-mesh containing all indices is returned.
 		 * 			
 		 * @note	Sim thread only.
 		 */

CamelotCore/Source/CmMeshBase.cpp

@@ -30,6 +30,8 @@ namespace BansheeEngine
 
 	void MeshBase::addSubMesh(UINT32 indexOffset, UINT32 indexCount, DrawOperationType drawOp)
 	{
+		THROW_IF_CORE_THREAD;
+
 		if((indexOffset + indexCount) > mNumIndices)
 		{
 			LOGWRN("Provided sub-mesh references indexes out of range. Sub-mesh range: "