More documentation

BansheeEngine.sln

@@ -1,14 +1,13 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
-# Visual Studio 2013
-VisualStudioVersion = 12.0.21005.1
-MinimumVisualStudioVersion = 10.0.40219.1
+# Visual Studio 2012
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "_Notes", "_Notes", "{1D081E5A-615A-4C06-B2DF-0D8D9390DE02}"
 	ProjectSection(SolutionItems) = preProject
 		CSharpWrap.txt = CSharpWrap.txt
 		Dependencies.txt = Dependencies.txt
 		DrawHelper.txt = DrawHelper.txt
 		EditorWindowDock.txt = EditorWindowDock.txt
+		GameGUI.txt = GameGUI.txt
 		GameObjectSerialization.txt = GameObjectSerialization.txt
 		Inspector.txt = Inspector.txt
 		MonoIntegrationGuide.txt = MonoIntegrationGuide.txt

BansheeEngine/Include/BsImageSprite.h

@@ -7,6 +7,9 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Image sprite description structure used for initializing or updating an image sprite.
+	 */
 	struct IMAGE_SPRITE_DESC
 	{
 		IMAGE_SPRITE_DESC()
@@ -14,22 +17,35 @@ namespace BansheeEngine
 			borderTop(0), borderBottom(0), uvScale(1.0f, 1.0f), uvOffset(0.0f, 0.0f)
 		{ }
 
-		UINT32 width;
-		UINT32 height;
-		SpriteAnchor anchor;
-		Vector2 uvScale;
-		Vector2 uvOffset;
+		UINT32 width; /**< Width of the image in pixels. */
+		UINT32 height; /**< Height of the image in pixels. */
+		SpriteAnchor anchor; /**< Determines where in the provided bounds will the sprite be placed. */
+		Vector2 uvScale; /**< Scale applied to UV width/height used for rendering the sprite. */
+		Vector2 uvOffset; /**< Offset applied to UV coordinates when rendering the sprite. */
 
-		SpriteTexturePtr texture;
-		Color color;
-		UINT32 borderLeft, borderRight, borderTop, borderBottom;
+		SpriteTexturePtr texture; /**< Texture to overlay on the sprite. */
+		Color color; /**< Color tint to apply to the sprite. */
+
+		/** Borders (in texels) that allow you to control how is the texture scaled. 
+		 * If borders are 0 the texture will be scaled uniformly. If they are not null
+		 * only the area inside the borders will be scaled and the outside are will remain
+		 * the original size as in the texture. This allows you to implement "Scale9Grid"
+		 * functionality.
+		 */
+		UINT32 borderLeft, borderRight, borderTop, borderBottom; 
 	};
 
+	/**
+	 * @brief	A sprite consisting of a single image represented by a sprite texture.
+	 */
 	class BS_EXPORT ImageSprite : public Sprite
 	{
 	public:
 		ImageSprite();
 
+		/**
+		 * @brief	Recreates internal sprite data according the specified description structure.
+		 */
 		void update(const IMAGE_SPRITE_DESC& desc);
 	};
 }

BansheeEngine/Include/BsOverlayManager.h

@@ -7,7 +7,8 @@
 namespace BansheeEngine
 {
 	/**
-	 * @brief	Takes care which overlay gets rendered on which render target.
+	 * @brief	Handles overlay rendering by determining which overlay gets rendered 
+	 *			on which render target. Overlays are always rendered on top of any geometry.
 	 * 			
 	 * @note	Overlays could have been stored directly on a RenderTarget but this class
 	 * 			was created to decouple the connection.
@@ -16,19 +17,37 @@ namespace BansheeEngine
 	 */
 	class BS_EXPORT OverlayManager : public Module<OverlayManager>
 	{
+		/**
+		 * @brief	Used for comparing overlays in order to determine their rendering order.
+		 */
 		struct OverlayComparer
 		{
 			bool operator() (const Overlay* const& a, const Overlay* const& b);
 		};
 
 	public:
+		/**
+		 * @brief	Schedules any overlays for the specified viewport to be rendered.
+		 *			(adds them to the render queue).
+		 */
 		void render(ViewportPtr& target, RenderQueue& renderQueue) const;
 
 	private:
 		friend class Overlay;
 
+		/**
+		 * @brief	Attaches the specified overlay to the viewport.
+		 */
 		void attachOverlay(const Viewport* target, const Overlay* overlay);
+
+		/**
+		 * @brief	Detaches the specified overlay from the viewport.
+		 */
 		void detachOverlay(const Viewport* target, const Overlay* overlay);
+
+		/**
+		 * @brief	Detaches the specified overlay from all viewports.
+		 */
 		void detachOverlayFromAll(const Overlay* overlay);
 
 		UnorderedMap<const Viewport*, Set<const Overlay*, OverlayComparer>> mOverlaysPerTarget;

BansheeEngine/Include/BsSprite.h

@@ -7,6 +7,9 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Determines position of the sprite in its bounds.
+	 */
 	enum SpriteAnchor
 	{
 		SA_TopLeft,
@@ -20,6 +23,10 @@ namespace BansheeEngine
 		SA_BottomRight
 	};
 
+	/**
+	 * @brief	Contains information about a single sprite render element,
+	 *			including its geometry and material.
+	 */
 	struct SpriteRenderElement
 	{
 		SpriteRenderElement()
@@ -33,17 +40,31 @@ namespace BansheeEngine
 		GUIMaterialInfo matInfo;
 	};
 
+	/**
+	 * @brief	Generates geometry and contains information needed for rendering
+	 *			a two dimensional element.
+	 */
 	class BS_EXPORT Sprite
 	{
 	public:
 		Sprite();
 		virtual ~Sprite();
 
+		/**
+		 * @brief	Returns clipped bounds of the sprite.
+		 *
+		 * @param	offset		Offset that will be added to the returned bounds.
+		 * @param	clipRect	Local clip rect that is used for clipping the sprite bounds.
+		 *						(Clipping is done before the offset is applied). If clip rect
+		 *						width or height is zero, no clipping is done.
+		 *
+		 * @returns	Clipped sprite bounds.
+		 */
 		RectI getBounds(const Vector2I& offset, const RectI& clipRect) const;
 
 		/**
-		 * @brief	Returns the number of separate render elements in the sprite. Normally this is one, but some sprites
-		 * 			may consist of multiple materials, in which case each will require it's own mesh (render element)
+		 * @brief	Returns the number of separate render elements in the sprite. Normally this is 1, but some sprites
+		 * 			may consist of multiple materials, in which case each will require its own mesh (render element)
 		 * 			
 		 * @return	The number render elements.
 		 */
@@ -51,10 +72,10 @@ namespace BansheeEngine
 
 		/**
 		 * @brief	Gets a material for the specified render element index.
-		 * 			
-		 * @see getNumRenderElements()
 		 * 		
-		 * @return	Handle to the material.
+		 * @return	Structure describing the material.
+		 *
+		 * @see		getNumRenderElements()
 		 */
 		const GUIMaterialInfo& getMaterial(UINT32 renderElementIdx) const;
 
@@ -62,22 +83,19 @@ namespace BansheeEngine
 		 * @brief	Returns the number of quads that the specified render element will use. You will need this
 		 * 			value when creating the buffers before calling "fillBuffer".
 		 * 			
-		 * @see getNumRenderElements()
-		 * @see fillBuffer()
-		 * 		
+		 * @return	Number of quads for the specified render element. 
+		 *	
 		 * @note	Number of vertices = Number of quads * 4
 		 *			Number of indices = Number of quads * 6
 		 *			
-		 * @return	Number of quads for the specified render element. 
+		 * @see		getNumRenderElements()
+		 * @see		fillBuffer()
 		 */
 		UINT32 getNumQuads(UINT32 renderElementIdx) const;
 
 		/**
 		 * @brief	Fill the pre-allocated vertex, uv and index buffers with the mesh data for the
 		 * 			specified render element.
-		 * 			
-		 * @see getNumRenderElements()
-		 * @see	getNumQuads()
 		 *
 		 * @param	vertices			Previously allocated buffer where to store the vertices.
 		 * @param	uv					Previously allocated buffer where to store the uv coordinates.
@@ -88,17 +106,42 @@ namespace BansheeEngine
 		 * @param	vertexStride		Number of bytes between of vertices in the provided vertex and uv data.
 		 * @param	indexStride			Number of bytes between two indexes in the provided index data.
 		 * @param	renderElementIdx	Zero-based index of the render element.
+		 *
+		 * @see		getNumRenderElements()
+		 * @see		getNumQuads()
 		 */
 		UINT32 fillBuffer(UINT8* vertices, UINT8* uv, UINT32* indices, UINT32 startingQuad, UINT32 maxNumQuads, 
 			UINT32 vertexStride, UINT32 indexStride, UINT32 renderElementIdx, const Vector2I& offset, const RectI& clipRect, bool clip = true) const;
 
+	protected:
+		/**
+		 * @brief	Clips the provided vertices to the provided clip rectangle.
+		 *
+		 * @param	vertices	Pointer to the start of the buffer containing vertex positions.
+		 * @param	uv			Pointer to the start of the buffer containing UV coordinates.
+		 * @param	numQuads	Number of quads in the provided buffer pointers.
+		 * @param	vertStride	Number of bytes to skip when going to the next vertex. This assumes both position
+		 *						and uv coordinates have the same stride (as they are likely pointing to the same buffer).
+		 * @param	clipRect	Rectangle to clip the geometry to.
+		 */
 		static void clipToRect(UINT8* vertices, UINT8* uv, UINT32 numQuads, UINT32 vertStride, const RectI& clipRect);
+
+		/**
+		 * @brief	Returns the offset needed to move the sprite in order for it to respect the provided anchor.
+		 */
 		static Vector2I getAnchorOffset(SpriteAnchor anchor, UINT32 width, UINT32 height);
-	protected:
-		mutable RectI mBounds;
-		mutable Vector<SpriteRenderElement> mCachedRenderElements;
 
+		/**
+		 * @brief	Calculates the bounds of all sprite vertices.
+		 */
 		void updateBounds() const;
+
+		/**
+		 * @brief	Clears internal geometry buffers.
+		 */
 		void clearMesh() const;
+
+		mutable RectI mBounds;
+		mutable Vector<SpriteRenderElement> mCachedRenderElements;
 	};
 }

BansheeEngine/Include/BsSpriteTexture.h

@@ -7,24 +7,51 @@
 namespace BansheeEngine
 {
 	/**
-	 * @brief	Texture interface that attempts to hide the underlying texture. This primarily allows us
-	 * 			to create a sprite texture atlas, without requiring any of the sprite classes to directly
-	 * 			know about it.
+	 * @brief	Texture interface that encapsulates underlying texture which allows us
+	 * 			to create a sprite texture atlas (e.g. multiple SpriteTextures referencing
+	 *			different parts of a single Texture).
 	 */
 	class BS_EXPORT SpriteTexture : public Resource
 	{
 	public:
+		/**
+		 * @brief	Returns internal Texture that the sprite texture references.
+		 */
 		const HTexture& getTexture() const;
+
+		/**
+		 * @brief	Transforms wanted UV coordinates into coordinates you
+		 *			can use for sampling the internal texture.
+		 */
 		Vector2 transformUV(const Vector2& uv) const;
 
+		/**
+		 * @brief	Returns a dummy sprite texture.
+		 */
 		static const HSpriteTexture& dummy();
+
+		/**
+		 * @brief	Creates a new sprite texture that references the entire area of the provided
+		 *			texture.
+		 */
 		static HSpriteTexture create(const HTexture& texture);
+
+		/**
+		 * @brief	Creates a new sprite texture that references a sub-area of the provided
+		 *			texture.
+		 */
 		static HSpriteTexture create(const Vector2& uvOffset, const Vector2& uvScale, const HTexture& texture);
 
+		/**
+		 * @brief	Checks if the sprite texture and its internal texture have been loaded.
+		 */
 		static bool checkIsLoaded(const HSpriteTexture& tex);
 	private:
 		friend class SpriteTextureRTTI;
 
+		/**
+		 * @copydoc	create(const Vector2&, const Vector2&, const HTexture&)
+		 */
 		SpriteTexture(const Vector2& uvOffset, const Vector2& uvScale, const HTexture& texture);
 
 		HTexture mAtlasTexture;
@@ -35,6 +62,9 @@ namespace BansheeEngine
 		/* 								RTTI		                     		*/
 		/************************************************************************/
 
+		/**
+		 * @brief	Creates a new empty and uninitialized sprite texture. To be used by factory methods.
+		 */
 		static SpriteTexturePtr createEmpty();
 	public:
 		friend class SpriteTextureRTTI;

BansheeEngine/Include/BsTextSprite.h

@@ -7,16 +7,25 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Specifies how is text horizontally aligned within its bounds.
+	 */
 	enum TextHorzAlign
 	{
 		THA_Left, THA_Center, THA_Right
 	};
 
+	/**
+	 * @brief	Specifies how is text vertically aligned within its bounds.
+	 */
 	enum TextVertAlign
 	{
 		TVA_Top, TVA_Center, TVA_Bottom
 	};
 
+	/**
+	 * @brief	Text sprite description structure used for initializing or updating a text sprite.
+	 */
 	struct TEXT_SPRITE_DESC
 	{
 		TEXT_SPRITE_DESC()
@@ -24,39 +33,62 @@ namespace BansheeEngine
 			horzAlign(THA_Left), vertAlign(TVA_Top), wordWrap(false)
 		{ }
 
-		UINT32 width;
-		UINT32 height;
-		SpriteAnchor anchor;
+		UINT32 width; /**< Width of the bounds to render the text within, in pixels. */
+		UINT32 height; /**< Height of the bounds to render the text within, in pixels. */
+		SpriteAnchor anchor; /**< Determines how to anchor the text within the bounds. */
 
-		WString text;
-		HFont font;
-		UINT32 fontSize;
-		Color color;
-		TextHorzAlign horzAlign;
-		TextVertAlign vertAlign;
-		bool wordWrap;
+		WString text; /**< Text to generate geometry for. */
+		HFont font; /**< Font containing the data about character glyphs. */
+		UINT32 fontSize; /**< Size of the font to use when displaying the text. */
+		Color color; /**< Color tint of the text. */
+		TextHorzAlign horzAlign; /**< Specifies how is text horizontally aligned within its bounds. */
+		TextVertAlign vertAlign; /**< Specifies how is text vertically aligned within its bounds. */
+		bool wordWrap; /**< If true the text will word wrap when it doesn't fit, otherwise it will overflow. */
 	};
 
+	/**
+	 * @brief	A sprite consisting of a quads representing a text string.
+	 */
 	class BS_EXPORT TextSprite : public Sprite
 	{
 	public:
 		TextSprite();
 
+		/**
+		 * @brief	Recreates internal sprite data according the specified description structure.
+		 */
 		void update(const TEXT_SPRITE_DESC& desc);
 
+		/**
+		 * @brief	Calculates and returns offset for each individual text line. The offsets provide
+		 *			information on how much to offset the lines within provided bounds.
+		 *
+		 * @param	textData	Text data to generate offsets for.
+		 * @param	width		Width of the text bounds into which to constrain the text, in pixels.
+		 * @param	height		Height of the text bounds into which to constrain the text, in pixels.
+		 * @param	horzAlign	Specifies how is text horizontally aligned within its bounds.
+		 * @param	vertAlign	Specifies how is text vertically aligned within its bounds.
+		 */
 		static Vector<Vector2I> getAlignmentOffsets(const TextData& textData, 
 			UINT32 width, UINT32 height, TextHorzAlign horzAlign, TextVertAlign vertAlign);
 
 		/**
 		 * @brief	Calculates text quads you may use for text rendering, based on the specified text
 		 * 			data. Only generates quads for the specified page.
-		 * 			
-		 * 			You must provide pre-allocated vertex/uv/index buffers of adequate size to hold all
-		 * 			quads for the specified page.
-		 * 			
-		 * @note	uv and/or index array may be null.
 		 *
-		 * @return	Number of generated quads.
+		 * @param	page			Font page to generate the data for.
+		 * @param	textData		Text data to generate offsets for.
+		 * @param	width			Width of the text bounds into which to constrain the text, in pixels.
+		 * @param	height			Height of the text bounds into which to constrain the text, in pixels.
+		 * @param	horzAlign		Specifies how is text horizontally aligned within its bounds.
+		 * @param	vertAlign		Specifies how is text vertically aligned within its bounds.
+		 * @param	anchor			Determines how to anchor the text within the bounds.
+		 * @param	vertices		Output buffer containing quad positions. Must be allocated and of adequate size.
+		 * @param	uv				Output buffer containing quad UV coordinates. Must be allocated and of adequate size. Can be null.
+		 * @param	indices			Output buffer containing quad indices. Must be allocated and of adequate size. Can be null.
+		 * @param	bufferSizeQuads	Size of the output buffers, in number of quads.
+		 *
+		 * @returns	Number of generated quads.
 		 */
 		static UINT32 genTextQuads(UINT32 page, const TextData& textData, UINT32 width, UINT32 height, 
 			TextHorzAlign horzAlign, TextVertAlign vertAlign, SpriteAnchor anchor, Vector2* vertices, Vector2* uv, UINT32* indices, 
@@ -65,12 +97,18 @@ namespace BansheeEngine
 		/**
 		 * @brief	Calculates text quads you may use for text rendering, based on the specified text data. Generates quads for all pages.
 		 * 			
-		 *			You must provide pre-allocated vertex/uv/index buffers of adequate size to hold all quads for all characters
-		 *			on all pages.
-		 *			
-		 * @note	uv and/or index array may be null.
+		 * @param	textData		Text data to generate offsets for.
+		 * @param	width			Width of the text bounds into which to constrain the text, in pixels.
+		 * @param	height			Height of the text bounds into which to constrain the text, in pixels.
+		 * @param	horzAlign		Specifies how is text horizontally aligned within its bounds.
+		 * @param	vertAlign		Specifies how is text vertically aligned within its bounds.
+		 * @param	anchor			Determines how to anchor the text within the bounds.
+		 * @param	vertices		Output buffer containing quad positions. Must be allocated and of adequate size.
+		 * @param	uv				Output buffer containing quad UV coordinates. Must be allocated and of adequate size. Can be null.
+		 * @param	indices			Output buffer containing quad indices. Must be allocated and of adequate size. Can be null.
+		 * @param	bufferSizeQuads	Size of the output buffers, in number of quads.
 		 *
-		 * @return	Number of generated quads.
+		 * @returns	Number of generated quads.
 		 */
 		static UINT32 genTextQuads(const TextData& textData, UINT32 width, UINT32 height, 
 			TextHorzAlign horzAlign, TextVertAlign vertAlign, SpriteAnchor anchor, Vector2* vertices, Vector2* uv, UINT32* indices, 

GameGUI.txt

@@ -0,0 +1,8 @@
+  - Move Scale9Grid stuff from ImageSprite to SpriteTexture
+
+  Moved all GUI rendering outside of GUIManager and into SpriteManager
+   - Make it generic for 2D game purposes
+
+  See SpriteTexture.txt for needed sprite texture updated.
+
+  Check Unity 2D tools for editor functionality: https://www.youtube.com/watch?v=EOX6itCuKOc&feature=youtu.be