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/IGUIEnvironment.h

@@ -153,8 +153,8 @@ public:
 	\return Pointer to the font. Returns 0 if the font could not be loaded.
 	This pointer should not be dropped. See IReferenceCounted::drop() for
 	more information. */
-	virtual IGUIImageList* createImageList( video::ITexture* texture, 
-					core::dimension2d<s32>	imageSize, bool useAlphaChannel ) = 0;
+	virtual IGUIImageList* createImageList( video::ITexture* texture,
+					core::dimension2d<s32>	imageSize, bool useAlphaChannel ) = 0;
 
 	//! Returns pointer to the font with the specified filename.
 	/** Loads the font if it was not loaded before.
@@ -194,7 +194,7 @@ public:
 	virtual IGUIElement* getRootGUIElement() = 0;
 
 	//! Adds a button element.
-	/** \param rectangle Position and dimension of the button.
+	/** \param rectangle Rectangle specifying the borders of the button.
 	\param parent Parent gui element of the button.
 	\param id Id with which the gui element can be identified.
 	\param text Text displayed on the button.
@@ -206,7 +206,7 @@ public:
 		IGUIElement* parent=0, s32 id=-1, const wchar_t* text=0, const wchar_t* tooltiptext = 0) = 0;
 
 	//! Adds an empty window element.
-	/** \param rectangle Position and dimension of the window.
+	/** \param rectangle Rectangle specifying the borders of the window.
 	\param modal Defines if the dialog is modal. This means, that all other
 	gui elements which were created before the window cannot be used until
 	it is removed.
@@ -248,7 +248,7 @@ public:
 	//! Adds a scrollbar.
 	/** \param horizontal Specifies if the scroll bar is drawn horizontal
 	or vertical.
-	\param rectangle Position and dimension of the scroll bar.
+	\param rectangle Rectangle specifying the borders of the scrollbar.
 	\param parent Parent gui element of the scroll bar.
 	\param id Id to identify the gui element.
 	\return Pointer to the created scrollbar. Returns 0 if an error
@@ -274,7 +274,7 @@ public:
 
 	//! Adds an image element.
 	/** Use IGUIImage::setImage later to set the image to be displayed.
-	\param rectangle Position and dimension of the image.
+	\param rectangle Rectangle specifying the borders of the image.
 	\param parent Parent gui element of the image.
 	\param id Id to identify the gui element.
 	\param text Title text of the image.
@@ -286,7 +286,7 @@ public:
 
 	//! Adds a checkbox element.
 	/** \param checked Define the initial state of the check box.
-	\param rectangle Position and dimension of check box.
+	\param rectangle Rectangle specifying the borders of the check box.
 	\param parent Parent gui element of the check box.
 	\param id Id to identify the gui element.
 	\param text Title text of the check box.
@@ -297,7 +297,7 @@ public:
 		IGUIElement* parent=0, s32 id=-1, const wchar_t* text=0) = 0;
 
 	//! Adds a list box element.
-	/** \param rectangle Position and dimension of list box.
+	/** \param rectangle Rectangle specifying the borders of the list box.
 	\param parent Parent gui element of the list box.
 	\param id Id to identify the gui element.
 	\param drawBackground Flag whether the background should be drawn.
@@ -320,7 +320,7 @@ public:
 		bool scrollBarVertical = true, bool scrollBarHorizontal = false) = 0;
 
 	//! Adds a mesh viewer. Not 100% implemented yet.
-	/** \param rectangle Position and dimension of mesh viewer.
+	/** \param rectangle Rectangle specifying the borders of the mesh viewer.
 	\param parent Parent gui element of the mesh viewer.
 	\param id Id to identify the gui element.
 	\param text Title text of the mesh viewer.
@@ -358,7 +358,7 @@ public:
 
 	//! Adds a static text.
 	/** \param text Text to be displayed. Can be altered after creation by SetText().
-	\param rectangle Position and dimension of the static text.
+	\param rectangle Rectangle specifying the borders of the static text
 	\param border Set to true if the static text should have a 3d border.
 	\param wordWrap Enable if the text should wrap into multiple lines.
 	\param parent Parent item of the element, e.g. a window.
@@ -379,7 +379,7 @@ public:
 	ctrl+X, ctrl+V, ctrl+C, shift+Left, shift+Right, Home, End, and so on.
 	\param text Text to be displayed. Can be altered after creation
 	by setText().
-	\param rectangle Position and dimension of the edit box.
+	\param rectangle Rectangle specifying the borders of the edit box.
 	\param border Set to true if the edit box should have a 3d border.
 	\param parent Parent item of the element, e.g. a window.
 	Set it to 0 to place the edit box directly in the environment.
@@ -393,7 +393,7 @@ public:
 	//! Adds a spin box.
 	/** An edit box with up and down buttons
 	\param text Text to be displayed. Can be altered after creation by setText().
-	\param rectangle Position and dimension of the spin box.
+	\param rectangle Rectangle specifying the borders of the spin box.
 	\param parent Parent item of the element, e.g. a window.
 	Set it to 0 to place the spin box directly in the environment.
 	\param id The ID of the element.
@@ -404,7 +404,7 @@ public:
 		bool border=true,IGUIElement* parent=0, s32 id=-1) = 0;
 
 	//! Adds an element for fading in or out.
-	/* \param rectangle Rectangle specifying the borders of the element.
+	/** \param rectangle Rectangle specifying the borders of the fader.
 	If the pointer is NULL, the whole screen is used.
 	\param parent Parent item of the element, e.g. a window.
 	\param id An identifier for the fader.
@@ -414,7 +414,7 @@ public:
 	virtual IGUIInOutFader* addInOutFader(const core::rect<s32>* rectangle=0, IGUIElement* parent=0, s32 id=-1) = 0;
 
 	//! Adds a tab control to the environment.
-	/** \param rectangle Position and dimension of the tab control.
+	/** \param rectangle Rectangle specifying the borders of the tab control.
 	\param parent Parent item of the element, e.g. a window.
 	Set it to 0 to place the tab control directly in the environment.
 	\param fillbackground Specifies if the background of the tab control
@@ -434,7 +434,7 @@ public:
 	/** You can use this element to group other elements. This is not used
 	for creating tabs on tab controls, please use IGUITabControl::addTab()
 	for this instead.
-	\param rectangle Position and dimension of the tab.
+	\param rectangle Rectangle specifying the borders of the tab.
 	\param parent Parent item of the element, e.g. a window.
 	Set it to 0 to place the tab directly in the environment.
 	\param id An identifier for the tab.
@@ -445,8 +445,8 @@ public:
 		IGUIElement* parent=0, s32 id=-1) = 0;
 
 	//! Adds a context menu to the environment.
-	/** \param rectangle Position and dimension of the menu. Note that the
-	menu is resizing itself based on what items you add.
+	/** \param rectangle Rectangle specifying the borders of the menu.
+	Note that the menu is resizing itself based on what items you add.
 	\param parent Parent item of the element, e.g. a window.
 	Set it to 0 to place the menu directly in the environment.
 	\param id An identifier for the menu.
@@ -479,7 +479,7 @@ public:
 	virtual IGUIToolBar* addToolBar(IGUIElement* parent=0, s32 id=-1) = 0;
 
 	//! Adds a combo box to the environment.
-	/** \param rectangle Position and dimension of the combo box.
+	/** \param rectangle Rectangle specifying the borders of the combo box.
 	\param parent Parent item of the element, e.g. a window.
 	Set it to 0 to place the combo box directly in the environment.
 	\param id An identifier for the combo box.
@@ -490,7 +490,7 @@ public:
 		IGUIElement* parent=0, s32 id=-1) = 0;
 
 	//! Adds a table to the environment
-	/** \param rectangle Position and dimension of the table.
+	/** \param rectangle Rectangle specifying the borders of the table.
 	\param parent Parent item of the element, e.g. a window. Set it to 0
 	to place the element directly in the environment.
 	\param id An identifier for the table.
@@ -499,9 +499,9 @@ public:
 	This pointer should not be dropped. See IReferenceCounted::drop() for
 	more information. */
 	virtual IGUITable* addTable(const core::rect<s32>& rectangle,
-		IGUIElement* parent=0, s32 id=-1, bool drawBackground = false) = 0;
+		IGUIElement* parent=0, s32 id=-1, bool drawBackground=false) =0;
 
-	//! Returns the default element factory which can create all built in elements
+	//! Get the default element factory which can create all built-in elements
 	/** \return Pointer to the factory.
 	This pointer should not be dropped. See IReferenceCounted::drop() for
 	more information. */
@@ -514,34 +514,45 @@ public:
 	\param factoryToAdd Pointer to new factory. */
 	virtual void registerGUIElementFactory(IGUIElementFactory* factoryToAdd) = 0;
 
-	//! Returns amount of registered gui element factories.
+	//! Get amount of registered gui element factories.
 	/** \return Amount of registered gui element factories. */
 	virtual u32 getRegisteredGUIElementFactoryCount() const = 0;
 
-	//! Returns a gui element factory by index
+	//! Get a gui element factory by index
+	/** \param index Index of the factory.
+	\return Factory at given index, or 0 if no such factory exists. */
 	virtual IGUIElementFactory* getGUIElementFactory(u32 index) const = 0;
 
-	//! Adds a GUI Element by its name
+	//! Adds a GUI element by its name
+	/** Each factory is checked if it can create an element of the given
+	name. The first match will be created.
+	\param elementName Name of the element to be created.
+	\param parent Parent of the new element, if not 0.
+	\return New GUI element, or 0 if no such element exists. */
 	virtual IGUIElement* addGUIElement(const c8* elementName, IGUIElement* parent=0) = 0;
 
 	//! Saves the current gui into a file.
 	/** \param filename Name of the file.
-	\param start The GUIElement to start with. Root if 0. */
+	\param start The GUIElement to start with. Root if 0.
+	\return True if saving succeeded, else false. */
 	virtual bool saveGUI(const core::string<c16>& filename, IGUIElement* start=0) = 0;
 
 	//! Saves the current gui into a file.
 	/** \param file The file to write to.
-	\param start The GUIElement to start with. Root if 0. */
+	\param start The GUIElement to start with. Root if 0.
+	\return True if saving succeeded, else false. */
 	virtual bool saveGUI(io::IWriteFile* file, IGUIElement* start=0) = 0;
 
 	//! Loads the gui. Note that the current gui is not cleared before.
 	/** \param filename Name of the file.
-	\param parent Parent for the loaded GUI, root if 0. */
+	\param parent Parent for the loaded GUI, root if 0.
+	\return True if loading succeeded, else false. */
 	virtual bool loadGUI(const c16* filename, IGUIElement* parent=0) = 0;
 
 	//! Loads the gui. Note that the current gui is not cleared before.
 	/** \param file The file to load from.
-	\param parent Parent for the loaded GUI, root if 0. */
+	\param parent Parent for the loaded GUI, root if 0.
+	\return True if loading succeeded, else false. */
 	virtual bool loadGUI(io::IReadFile* file, IGUIElement* parent=0) = 0;
 
 	//! Writes attributes of the gui environment

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