*注释

8 files changed, 275 insertions, 38 deletions

diff --git a/src/libjin/Graphics/Bitmap.h b/src/libjin/Graphics/Bitmap.h
index 9277cc8..c983676 100644
--- a/src/libjin/Graphics/Bitmap.h
+++ b/src/libjin/Graphics/Bitmap.h
@@ -11,15 +11,55 @@ namespace jin
 {
 	namespace graphics
 	{
-
+        /// 
+        /// A RGBA32 bitmap.
+        /// 
+        /// A bitmap keeps pixels and can't render directly onto screen. To render bitmap, 
+        /// a texture is required. A texture is create from specific bitmap.
+        /// 
 		class Bitmap
 		{
 		public:
-			static Bitmap* createBitmap(const void* pixel, unsigned width, unsigned height);
+            /// 
+            /// Create bitmap by pixels data.
+            /// 
+            /// @param pixels Pixels data.
+            /// @param width Width of bitmap.
+            /// @param height Height of bitmap.
+            /// @return Return bitmap pointer if created, otherwise return null.
+            /// 
+			static Bitmap* createBitmap(const void* pixels, unsigned width, unsigned height);
+
+            /// 
+            /// Create bitmap from compressed image data.
+            /// 
+            /// @param imgData Compressed image data. 
+            /// @param size Size of image data.
+            /// @return Return bitmap pointer if created, otherwise return null.
+            /// 
 			static Bitmap* createBitmap(const void* imgData, size_t size);
-			static Bitmap* createBitmap(int w, int h, Color color = Color::BLACK);
+
+            /// 
+            /// Create bitmap with specific color and size.
+            /// 
+            /// @param width Width of bitmap. 
+            /// @param height Height of bitmap. 
+            /// @param color Color of bitmap.
+            /// @return Return bitmap pointer if created, otherwise return null.
+            /// 
+			static Bitmap* createBitmap(int width, int height, Color color = Color::BLACK);
+
+            /// 
+            /// Create bitmap with another one. 
+            /// 
+            /// @param bitmap Bitmap be cloned.
+            /// @return Return bitmap pointer if created, otherwise return null.
+            /// 
 			static Bitmap* clone(const Bitmap* bitmap);
 
+            /// 
+            /// Destructor of bitmap
+            /// 
 			virtual ~Bitmap();
 			/* init pixels */
 			void bind(Color* pixels, int w, int h);
diff --git a/src/libjin/Graphics/Drawable.cpp b/src/libjin/Graphics/Drawable.cpp
index aa17f1a..947bb99 100644
--- a/src/libjin/Graphics/Drawable.cpp
+++ b/src/libjin/Graphics/Drawable.cpp
@@ -79,7 +79,7 @@ namespace jin
             gl.drawArrays(GL_QUADS, 0, 4);
             gl.bindTexture(0);
         }
-
+		
         void Drawable::draw(const math::Quad& slice, int x, int y, float sx, float sy, float r, float ax, float ay)
         {
             float vertCoords[8] = {
diff --git a/src/libjin/Graphics/Drawable.h b/src/libjin/Graphics/Drawable.h
index 29f1946..31ee3c5 100644
--- a/src/libjin/Graphics/Drawable.h
+++ b/src/libjin/Graphics/Drawable.h
@@ -12,19 +12,55 @@ namespace jin
 {
     namespace graphics
     {
-
+		/// 
+		/// 
+		///
         class Drawable
         {
         public:
+			/// 
+			/// 
+			///
             Drawable(int w = 0, int h = 0);
+
+			///
+			/// 
+			/// 
             Drawable(const Bitmap* bitmap);
+
+			/// 
+			/// 
+			///
             virtual ~Drawable();
 
+			/// 
+			/// 
+			/// 
             void setAnchor(int x, int y); 
+
+			/// 
+			/// 
+			/// 
             void draw(int x, int y, float sx = 1, float sy = 1, float r = 0);
+
+			/// 
+			/// 
+			/// 
             void draw(const math::Quad& slice, int x, int y, float sx = 1, float sy = 1, float r = 0, float ax = 0, float ay = 0);
+
+			/// 
+			/// 
+			/// 
             inline int getWidth() const { return size.w; }
+
+			/// 
+			/// 
+			/// 
             inline int getHeight() const { return size.h; }
+
+			/// 
+			/// 
+			///
             inline GLuint getTexture() const { return texture; }
 
         protected:
diff --git a/src/libjin/Graphics/Font/Font.h b/src/libjin/Graphics/Font/Font.h
index 14211e1..1d09cfc 100644
--- a/src/libjin/Graphics/Font/Font.h
+++ b/src/libjin/Graphics/Font/Font.h
@@ -13,23 +13,79 @@ namespace jin
 		class Font
 		{
 		public:
+            /// 
+            /// Font constructor.
+            /// 
 			Font(unsigned fontsize)
-				: fontSize(fontsize)
+				: mFontSize(fontsize)
 			{
 			}
+
+            /// 
+            /// Font destructor.
+            /// 
 			virtual ~Font() {};
 
+            /// 
+            /// Create page with given text.
+            /// 
+            /// @param text Text to be typesetted.
+            /// @param lineheight Line height of text. 
+            /// @param spacing Spacing between characters. 0 by default.
+            /// @return Page if created successfully, otherwise return null.
+            /// 
 			virtual Page* typeset(const Text& text, int lineheight, int spacing = 0) = 0;
-			virtual Page* typeset(const Content& text, int lineheight, int spacing = 0) = 0;
 
+            /// 
+            /// Create page with given unicode codepoints.
+            /// 
+            /// @param content Unicode codepoints to be typesetted.
+            /// @param lineheight Line height of text. 
+            /// @param spacing Spacing between characters. 0 by default.
+            /// @return Page if created successfully, otherwise return null.
+            /// 
+			virtual Page* typeset(const Content& content, int lineheight, int spacing = 0) = 0;
+
+            /// 
+            /// Render page to given position.
+            /// 
+            /// @param page Page to be rendered.
+            /// @param x X value of the position. 
+            /// @param y Y value of the position.
+            /// 
 			virtual void print(const Page* page, int x, int y) = 0;
-			virtual void print(const Content& text, int x, int y, int lineheight, int spacing = 0) = 0;
+
+            /// 
+            /// Render unicode codepoints to given position.
+            /// 
+            /// @param content Unicode codepoints to be typesetted.
+            /// @param x X value of the position.
+            /// @param y Y value of the position. 
+            /// @param lineheight Line height of the content. 
+            /// @param spacing Spacing between characters.
+            /// 
+			virtual void print(const Content& content, int x, int y, int lineheight, int spacing = 0) = 0;
+
+            /// 
+            /// Render text to given position.
+            /// 
+            /// @param text Text to be rendered. 
+            /// @param x X value of the position. 
+            /// @param y Y value of the position.
+            /// @param lineheight Line height of the text. 
+            /// @param spacing Spacing between characters.
+            ///
 			virtual void print(const Text& text, int x, int y, int lineheight, int spacing = 0) = 0;
 
-			inline unsigned getFontSize() { return fontSize; };
+            /// 
+            /// Get font size.
+            /// 
+            /// @return Font size.
+            /// 
+			inline unsigned getFontSize() { return mFontSize; };
     
 		protected:
-			unsigned fontSize;
+			unsigned mFontSize;
 
 		};
 
diff --git a/src/libjin/Graphics/Font/TTF.cpp b/src/libjin/Graphics/Font/TTF.cpp
index 4c3648a..b90bbba 100644
--- a/src/libjin/Graphics/Font/TTF.cpp
+++ b/src/libjin/Graphics/Font/TTF.cpp
@@ -317,7 +317,7 @@ namespace jin
 		int TTF::getCharWidth(int c)
 		{
 			int adw, lsb;
-			ttf->pushTTFsize(fontSize);
+			ttf->pushTTFsize(mFontSize);
 			ttf->getHMetrics(c, &adw, &lsb);
 			ttf->popTTFsize();
 			return adw;
@@ -330,7 +330,7 @@ namespace jin
 
 		int TTF::getTextWidth(const Content& t, int spacing)
 		{
-			ttf->pushTTFsize(fontSize);
+			ttf->pushTTFsize(mFontSize);
 			int res = 0;
 			int tmp = 0;
 			for (Codepoint c : t)
@@ -352,7 +352,7 @@ namespace jin
 
 		int TTF::getTextHeight(const Content& t, int lineheight)
 		{
-			ttf->pushTTFsize(fontSize);
+			ttf->pushTTFsize(mFontSize);
 			int res = 0;
 			bool newline = true;
 			for (Codepoint c : t)
@@ -372,7 +372,7 @@ namespace jin
 
 		void TTF::getTextBox(const Content& text, int* w, int* h, int lineheight, int spacing)
 		{
-			ttf->pushTTFsize(fontSize);
+			ttf->pushTTFsize(mFontSize);
 			*w = 0;
 			*h = 0;
 			int tmp = 0;
@@ -402,7 +402,7 @@ namespace jin
 		TTF::TTFGlyph& TTF::bakeGlyph(unsigned int character)
 		{
 			int w, h, xoff, yoff;
-			ttf->pushTTFsize(fontSize);
+			ttf->pushTTFsize(mFontSize);
 			GLuint atlas = atlases.back();
 			const Color* bitmap = ttf->getCodepointBitmap(character, &w, &h, &xoff, &yoff);
 			int adw, lsb;
diff --git a/src/libjin/Graphics/Image.h b/src/libjin/Graphics/Image.h
index bed1986..53eb0d7 100644
--- a/src/libjin/Graphics/Image.h
+++ b/src/libjin/Graphics/Image.h
@@ -8,18 +8,44 @@ namespace jin
     namespace graphics
     {
 
-	    /* just like bitmap but only from image file*/
-	    /* readonly bitmap */
+        /// 
+        /// A readonly bitmap.
+        /// 
+        /// Just like bitmap but only from image file. The pixels data
+        /// is readonly.
+        ///
 	    class Image : public Bitmap
 	    {
 	    public:
+            /// 
+            /// Create image from image file.
+            /// 
+            /// @param path Image path.
+            /// @return Image if created successfully, otherwise return null.
+            ///
             static Image* createImage(const char* path);
+
+            /// 
+            /// Create image from image data.
+            /// 
+            /// @param imgData Image data to create image.
+            /// @param size Size of image data.
+            /// @return Image if created successfully, otherwise return null.
+            /// 
 		    static Image* createImage(const void* imgData, size_t size);
+
+            /// 
+            /// Image destructor.
+            ///
 		    ~Image();
 
 	    private:
+            /// 
+            /// Image constructor.
+            /// 
 		    Image();
 
+            // Disable setters inherited from Bitmap.
 		    void bind(Color* pixels, int w, int h);
 		    void resetPixels(const Color* pixels, int w, int h);
 		    void resetPixels(const Color& pixels, int w, int h);
@@ -29,7 +55,7 @@ namespace jin
 
 	    };
 
-    }
-}
+    } // namespace graphics
+} // namespace jin
 
 #endif
\ No newline at end of file
diff --git a/src/libjin/Graphics/Shader/Shader.h b/src/libjin/Graphics/Shader/Shader.h
index b9f83e7..d1d843a 100644
--- a/src/libjin/Graphics/Shader/Shader.h
+++ b/src/libjin/Graphics/Shader/Shader.h
@@ -1,10 +1,12 @@
 #ifndef __LIBJIN_SHADER_H
 #define __LIBJIN_SHADER_H
+
 #include "../../jin_configuration.h"
-#if LIBJIN_MODULES_RENDER
+#if defined(jin_graphics) && defined(jin_graphics_shader)
 
 #include <string>
 #include <map>
+
 #include "../../3rdparty/GLee/GLee.h"
 #include "../color.h"
 #include "../texture.h"
@@ -16,98 +18,169 @@ namespace jin
 	namespace graphics
 	{
 		/// 
-		/// @details Built in shader program.
+		/// Built in shader program.
+		/// 
+		/// Built in shader program written with custom shading language called JSL
+        /// (jin shading language). A JSL program is compiled into glsl, so most glsl 
+        /// built in functions and structs are available in JSL.
 		/// 
 		class Shader
 		{
 		public:
 			/// 
-			/// @brief Create shader program from source code.
+			/// Create shader program from source code.
 			/// 
 			/// @param source The shader source code.
 			/// 
 			static Shader* createShader(const std::string& source);
 
 			/// 
-			/// @brief Get current shader.
+			/// Get current shader.
+			/// 
+			/// @return Current used shader program.
 			///
 			static inline Shader* getCurrentShader() { return CurrentShader; }
 
 			/// 
-			/// @brief Unuse current shader 
+			/// Unuse current shader.
 			///
 			static void unuse();
 
 			/// 
-			/// 
+			/// Destructor of shader.
 			/// 
 			virtual ~Shader();
 			
 			/// 
-			/// 
+			/// Use specific shader.
 			/// 
 			void use(); 
 
 			/// 
+			/// Send float value to shader.
 			/// 
+			/// @param name Name of the uniform variable to be assigned. 
+			/// @param number Value of uniform variable to be sent.
 			/// 
 			void sendFloat(const char* name, float number);
 
 			/// 
+			/// Send texture to shader.
+			///
+			/// @param name Name of the uniform variable to be assigned.
+			/// @param texture Texture to be sent.
 			/// 
-			/// 
-			void sendTexture(const char*  name, const Texture* image);
+			void sendTexture(const char*  name, const Texture* texture);
 
 			/// 
+			/// Send integer value to shader 
 			/// 
+			/// @param name Name of the uniform variable to be assigned. 
+			/// @param value Value to be sent.
 			///
 			void sendInt(const char* name, int value);
 
 			/// 
+			/// Send 2D vector to shader.
 			/// 
+			/// @param name Name of the uniform variable to be assigned.
+			/// @param x X value of the vector to be sent.
+			/// @param y Y value of the vector to be sent.
 			///
 			void sendVec2(const char* name, float x, float y);
 
-			///
 			/// 
+			/// Send 3D vector to shader.
 			/// 
+			/// @param name Name of the uniform variable to be assigned.
+			/// @param x X value of the vector to be sent.
+			/// @param y Y value of the vector to be sent.
+			/// @param z Z value of the vector to be sent.
+			///
 			void sendVec3(const char* name, float x, float y, float z);
 
 			/// 
+			/// Send 4D vector to shader.
 			/// 
-			/// 
+			/// @param name Name of the uniform variable to be assigned.
+			/// @param x X value of the vector to be sent.
+			/// @param y Y value of the vector to be sent.
+			/// @param z Z value of the vector to be sent.
+			/// @param w W value of the vector to be sent.
+			///
 			void sendVec4(const char* name, float x, float y, float z, float w);
 
 			///
-			///
+			/// Send canvas to shader. 
+			/// 
+			/// @param name Name of the uniform variable to be assigned. 
+			/// @param canvas Canvas to be sent.
 			///
 			void sendCanvas(const char* name, const Canvas* canvas);
 
 			///
+			/// Send color to shader.
+			/// 
+			/// @param name Name of the uniform variable to be assigned.
+			/// @param color Color to be sent.
 			///
-			///
-			void sendColor(const char* name, const Color* col);
+			void sendColor(const char* name, const Color* color);
 
 			///
-			///
-			///
+			/// Send 4 by 4 matrix to shader.
+			/// 
+			/// @param name Name of the uniform variable to be assigned.
+			/// @param mat4 Matrix to be sent.
+ 			///
 			void sendMatrix4(const char* name, const math::Matrix* mat4);
 
 			///
-			///
+			/// Set vertices value.
+			/// 
+			/// @param n Number of vertices. 
+			/// @param type Data type of each component in the array.
+			/// @param stride Byte offset between consecutive generic vertex attributes.
+			/// @param pointers Pointer to the first component of the first generic vertex 
+			///	    attribute in the array. 
 			///
 			void bindVertexPointer(int n, GLenum type, GLsizei stride, const GLvoid * pointers);
 
 			///
-			///
+			/// Set texture UV coordinates.
+			/// 
+			/// @param n Number of vertices. 
+			/// @param type Data type of each component in the array.
+			/// @param stride Byte offset between consecutive generic vertex attributes.
+			/// @param pointers Pointer to the first component of the first generic vertex 
+			///     attribute in the array. 
 			///
 			void bindUVPointer(int n, GLenum type, GLsizei stride, const GLvoid * pointers);
 
 		protected:
+			/// 
+			/// Reference of current used shader.
+			/// 
 			static Shader* CurrentShader;
 
+			/// 
+			/// Get texture unit of the uniform texture. If not, assign one.
+			/// 
+			/// @param name Name of the texture uniform variable.
+			/// @return Texture unit which texture variable be assigned.
+			/// 
 			GLint claimTextureUnit(const std::string& name);
+
+			/// 
+			/// Shader constructor.
+			/// 
 			Shader(const std::string& program);
+
+			/// 
+			/// Compile JSL program into GLSL source. 
+			/// 
+			/// @param program JSL source code. 
+			/// @return Return true if compile successed, otherwise return false.
+			/// 
 			bool compile(const std::string& program);
 
 			GLuint mPID; 
@@ -119,5 +192,6 @@ namespace jin
 	} // namespace graphics
 } // namespace jin
 
-#endif // LIBJIN_MODULES_RENDER
+#endif // jin_graphics && jin_graphics_shader
+
 #endif // __LIBJIN_SHADER_H
\ No newline at end of file
diff --git a/src/libjin/jin_configuration.h b/src/libjin/jin_configuration.h
index 83eb90b..55633a1 100644
--- a/src/libjin/jin_configuration.h
+++ b/src/libjin/jin_configuration.h
@@ -61,4 +61,9 @@
 
 #define LIBJIN_OS LIBJIN_WINDOWS
 
+/// ģ��������
+#define jin_graphics
+#define jin_graphics_font
+#define jin_graphics_shader
+
 #endif
\ No newline at end of file