Merged revisions 2325:2332 from 1.5 branch. Only doc updates.

git-svn-id: svn://svn.code.sf.net/p/irrlicht/code/trunk@2333 dfc29bdd-3216-0410-991c-e03cc46cb475

include/EHardwareBufferFlags.h

@@ -12,24 +12,28 @@ namespace scene
 
 	enum E_HARDWARE_MAPPING
 	{
-		//! Don't load in hardware
+		//! Don't store on the hardware
 		EHM_NEVER=0,
 
-		//! Rarely changed
+		//! Rarely changed, usually stored completely on the hardware
 		EHM_STATIC,
 
-		//! Sometimes changed
+		//! Sometimes changed, driver optimized placement
 		EHM_DYNAMIC,
 
-		//! Always changed
+		//! Always changed, cache optimizing on the GPU
 		EHM_STREAM
 	};
 
 	enum E_BUFFER_TYPE
 	{
+		//! Does not change anything
 		EBT_NONE=0,
+		//! Change the vertex mapping
 		EBT_VERTEX,
+		//! Change the index mapping
 		EBT_INDEX,
+		//! Change both vertex and index mapping to the same value
 		EBT_VERTEX_AND_INDEX
 	};
 

include/IMesh.h

@@ -15,36 +15,37 @@ namespace scene
 {
 	class IMeshBuffer;
 
-	//! Class for accessing a mesh with multiple mesh buffers.
+	//! Class which holds the geometry of an object.
 	/** An IMesh is nothing more than a collection of some mesh buffers
 	(IMeshBuffer). SMesh is a simple implementation of an IMesh.
+	A mesh is usually added to an IMeshSceneNode in order to be rendered.
 	*/
 	class IMesh : public virtual IReferenceCounted
 	{
 	public:
 
-		//! Returns the amount of mesh buffers.
-		/** \return Returns the amount of mesh buffers (IMeshBuffer) in this mesh. */
+		//! Get the amount of mesh buffers.
+		/** \return Amount of mesh buffers (IMeshBuffer) in this mesh. */
 		virtual u32 getMeshBufferCount() const = 0;
 
-		//! Returns pointer to a mesh buffer.
+		//! Get pointer to a mesh buffer.
 		/** \param nr: Zero based index of the mesh buffer. The maximum value is
 		getMeshBufferCount() - 1;
-		\return Returns the pointer to the mesh buffer or
-		NULL if there is no such mesh buffer. */
+		\return Pointer to the mesh buffer or 0 if there is no such
+		mesh buffer. */
 		virtual IMeshBuffer* getMeshBuffer(u32 nr) const = 0;
 
-		//! Returns pointer to a mesh buffer which fits a material
+		//! Get pointer to a mesh buffer which fits a material
 		/** \param material: material to search for
-		\return Returns the pointer to the mesh buffer or
-		NULL if there is no such mesh buffer. */
+		\return Pointer to the mesh buffer or 0 if there is no such
+		mesh buffer. */
 		virtual IMeshBuffer* getMeshBuffer( const video::SMaterial &material) const = 0;
 
-		//! Returns an axis aligned bounding box of the mesh.
-		/** \return A bounding box of this mesh is returned. */
+		//! Get an axis aligned bounding box of the mesh.
+		/** \return Bounding box of this mesh. */
 		virtual const core::aabbox3d<f32>& getBoundingBox() const = 0;
 
-		//! set user axis aligned bounding box
+		//! Set user-defined axis aligned bounding box
 		/** \param box New bounding box to use for the mesh. */
 		virtual void setBoundingBox( const core::aabbox3df& box) = 0;
 
@@ -53,10 +54,17 @@ namespace scene
 		\param newvalue: New value to set in all materials. */
 		virtual void setMaterialFlag(video::E_MATERIAL_FLAG flag, bool newvalue) = 0;
 
-		//! set the hardware mapping hint, for driver
-		virtual void setHardwareMappingHint( E_HARDWARE_MAPPING newMappingHint, E_BUFFER_TYPE buffer=EBT_VERTEX_AND_INDEX ) = 0;
+		//! Set the hardware mapping hint
+		/** This methods allows to define optimization hints for the
+		hardware. This enables, e.g., the use of hardware buffers on
+		pltforms that support this feature. This can lead to noticeable
+		performance gains. */
+		virtual void setHardwareMappingHint(E_HARDWARE_MAPPING newMappingHint, E_BUFFER_TYPE buffer=EBT_VERTEX_AND_INDEX) = 0;
 
-		//! flags the meshbuffer as changed, reloads hardware buffers
+		//! Flag the meshbuffer as changed, reloads hardware buffers
+		/** This method has to be called every time the vertices or
+		indices have changed. Otherwise, changes won't be updated
+		on the GPU in the next render cycle. */
 		virtual void setDirty(E_BUFFER_TYPE buffer=EBT_VERTEX_AND_INDEX) = 0;
 	};
 

include/IMeshBuffer.h

@@ -56,13 +56,23 @@ namespace scene
 		EPT_POINT_SPRITES
 	};
 
-	//! Struct for holding a mesh with a single material
-	/** SMeshBuffer is a simple implementation of a MeshBuffer.
+	//! Struct for holding a mesh with a single material.
+	/** A part of an IMesh which has the same material on each face of that
+	group. Logical groups of an IMesh need not be put into separate mesh
+	buffers, but can be. Separately animated parts of the mesh must be put
+	into separate mesh buffers.
+	Some mesh buffer implementations have limitations on the number of
+	vertices the buffer can hold. In that case, logical grouping can help.
+	Moreover, the number of vertices should be optimized for the GPU upload,
+	which often depends on the type of gfx card. Typial figures are
+	1000-10000 vertices per buffer.
+	SMeshBuffer is a simple implementation of a MeshBuffer, which supports
+	up to 65535 vertices.
 
 	Since meshbuffers are used for drawing, and hence will be exposed
 	to the driver, chances are high that they are grab()'ed from somewhere.
 	It's therefore required to dynamically allocate meshbuffers which are
-	passed to a video driver and only drop hte buffer once it's not used in
+	passed to a video driver and only drop the buffer once it's not used in
 	the current code block anymore.
 	*/
 	class IMeshBuffer : public virtual IReferenceCounted

include/rect.h

@@ -27,25 +27,30 @@ namespace core
 	{
 	public:
 
+		//! Default constructor creating empty rectangle at (0,0)
 		rect() : UpperLeftCorner(0,0), LowerRightCorner(0,0) {}
 
+		//! Constructor with two corners
 		rect(T x, T y, T x2, T y2)
 			: UpperLeftCorner(x,y), LowerRightCorner(x2,y2) {}
 
+		//! Constructor with two corners
 		rect(const position2d<T>& upperLeft, const position2d<T>& lowerRight)
 			: UpperLeftCorner(upperLeft), LowerRightCorner(lowerRight) {}
 
+		//! Constructor with upper left corner and dimension
 		template <class U>
 		rect(const position2d<T>& pos, const dimension2d<U>& size)
 			: UpperLeftCorner(pos), LowerRightCorner(pos.X + size.Width, pos.Y + size.Height) {}
 
-
+		//! move right by given numbers
 		rect<T> operator+(const position2d<T>& pos) const
 		{
 			rect<T> ret(*this);
 			return ret+=pos;
 		}
 
+		//! move right by given numbers
 		rect<T>& operator+=(const position2d<T>& pos)
 		{
 			UpperLeftCorner += pos;
@@ -53,12 +58,14 @@ namespace core
 			return *this;
 		}
 
+		//! move left by given numbers
 		rect<T> operator-(const position2d<T>& pos) const
 		{
 			rect<T> ret(*this);
 			return ret-=pos;
 		}
 
+		//! move left by given numbers
 		rect<T>& operator-=(const position2d<T>& pos)
 		{
 			UpperLeftCorner -= pos;
@@ -66,20 +73,21 @@ namespace core
 			return *this;
 		}
 
+		//! equality operator
 		bool operator==(const rect<T>& other) const
 		{
 			return (UpperLeftCorner == other.UpperLeftCorner &&
 				LowerRightCorner == other.LowerRightCorner);
 		}
 
-
+		//! inequality operator
 		bool operator!=(const rect<T>& other) const
 		{
 			return (UpperLeftCorner != other.UpperLeftCorner ||
 				LowerRightCorner != other.LowerRightCorner);
 		}
 
-		// compares size of rectangles
+		//! compares size of rectangles
 		bool operator<(const rect<T>& other) const
 		{
 			return getArea() < other.getArea();
@@ -102,7 +110,9 @@ namespace core
 				LowerRightCorner.Y >= pos.Y);
 		}
 
-		//! Returns if the rectangle collides with another rectangle.
+		//! Check if the rectangle collides with another rectangle.
+		/** \param other Rectangle to test collision with
+		\return True if the rectangles collide. */
 		bool isRectCollided(const rect<T>& other) const
 		{
 			return (LowerRightCorner.Y > other.UpperLeftCorner.Y &&
@@ -112,6 +122,7 @@ namespace core
 		}
 
 		//! Clips this rectangle with another one.
+		/** \param other Rectangle to clip with */
 		void clipAgainst(const rect<T>& other)
 		{
 			if (other.LowerRightCorner.X < LowerRightCorner.X)
@@ -169,13 +180,13 @@ namespace core
 			return true;
 		}
 
-		//! Returns width of rectangle.
+		//! Get width of rectangle.
 		T getWidth() const
 		{
 			return LowerRightCorner.X - UpperLeftCorner.X;
 		}
 
-		//! Returns height of rectangle.
+		//! Get height of rectangle.
 		T getHeight() const
 		{
 			return LowerRightCorner.Y - UpperLeftCorner.Y;
@@ -208,7 +219,7 @@ namespace core
 				(LowerRightCorner.Y >= UpperLeftCorner.Y));
 		}
 
-		//! Returns the center of the rectangle
+		//! Get the center of the rectangle
 		position2d<T> getCenter() const
 		{
 			return position2d<T>(
@@ -216,7 +227,7 @@ namespace core
 					(UpperLeftCorner.Y + LowerRightCorner.Y) / 2);
 		}
 
-		//! Returns the dimensions of the rectangle
+		//! Get the dimensions of the rectangle
 		dimension2d<T> getSize() const
 		{
 			return dimension2d<T>(getWidth(), getHeight());
@@ -224,18 +235,19 @@ namespace core
 
 
 		//! Adds a point to the rectangle
-		/** Cause the rectangle to grow bigger, if point is outside of
+		/** Causes the rectangle to grow bigger if point is outside of
 		the box
-		\param p Point to add into the box. */
+		\param p Point to add to the box. */
 		void addInternalPoint(const position2d<T>& p)
 		{
 			addInternalPoint(p.X, p.Y);
 		}
 
 		//! Adds a point to the bounding rectangle
-		/** Cause the rectangle to grow bigger, if point is outside of
-		\param x X Coordinate of the point to add to this box.
-		\param y Y Coordinate of the point to add to this box. */
+		/** Causes the rectangle to grow bigger if point is outside of
+		the box
+		\param x X-Coordinate of the point to add to this box.
+		\param y Y-Coordinate of the point to add to this box. */
 		void addInternalPoint(T x, T y)
 		{
 			if (x>LowerRightCorner.X)
@@ -249,11 +261,15 @@ namespace core
 				UpperLeftCorner.Y = y;
 		}
 
+		//! Upper left corner
 		position2d<T> UpperLeftCorner;
+		//! Lower right corner
 		position2d<T> LowerRightCorner;
 	};
 
+	//! Rectangle with float values
 	typedef rect<f32> rectf;
+	//! Rectangle with int values
 	typedef rect<s32> recti;
 
 } // end namespace core