Merge pull request #10950 from dabingnn/v3_comments

[ci skip] update comments CCTrianglesCommand.h

cocos/renderer/CCQuadCommand.h

@@ -30,41 +30,68 @@
 
 NS_CC_BEGIN
 
-/** Command used to render one or more Quads */
+/** 
+ Command used to render one or more Quads, similar to TrianglesCommand.
+ Every QuadCommand will have generate material ID by give textureID, glProgramState, Blend function
+ if the material id is the same, these QuadCommands could be batched to save draw call.
+ */
 class CC_DLL QuadCommand : public RenderCommand
 {
 public:
-    
+    /**Constructor.*/
     QuadCommand();
+    /**Destructor.*/
     ~QuadCommand();
     
-    /** Initializes the command with a globalZOrder, a texture ID, a `GLProgram`, a blending function, a pointer to quads,
-     * quantity of quads, and the Model View transform to be used for the quads */
+    /** Initializes the command.
+     @param globalOrder GlobalZOrder of the command.
+     @param textureID The openGL handle of the used texture.
+     @param glProgramState The specified glProgram and its uniform.
+     @param blendType Blend function for the command.
+     @param quads Rendered quads for the command.
+     @param quadCount The number of quads when rendering.
+     @param mv ModelView matrix for the command.
+     @param flags to indicate that the command is using 3D rendering or not.
+     */
     void init(float globalOrder, GLuint textureID, GLProgramState* shader, const BlendFunc& blendType, V3F_C4B_T2F_Quad* quads, ssize_t quadCount,
               const Mat4& mv, uint32_t flags);
-    
+    /**Deprecated function, the params is similar as the upper init function, with flags equals 0.*/
     CC_DEPRECATED_ATTRIBUTE void init(float globalOrder, GLuint textureID, GLProgramState* shader, const BlendFunc& blendType, V3F_C4B_T2F_Quad* quads, ssize_t quadCount,
               const Mat4& mv);
-    
+    /**Apply the texture, shaders, programs, blend functions to GPU pipeline.*/
     void useMaterial() const;
-    
+    /**Get the material id of command.*/
     inline uint32_t getMaterialID() const { return _materialID; }
+    /**Get the openGL texture handle.*/
     inline GLuint getTextureID() const { return _textureID; }
+    /**Get the pointer of the rendered quads.*/
     inline V3F_C4B_T2F_Quad* getQuads() const { return _quads; }
+    /**Get the number of quads for rendering.*/
     inline ssize_t getQuadCount() const { return _quadsCount; }
+    /**Get the glprogramstate.*/
     inline GLProgramState* getGLProgramState() const { return _glProgramState; }
+    /**Get the blend function.*/
     inline BlendFunc getBlendType() const { return _blendType; }
+    /**Get the model view matrix.*/
     inline const Mat4& getModelView() const { return _mv; }
     
 protected:
+    /**Generate the material ID by textureID, glProgramState, and blend function.*/
     void generateMaterialID();
     
+    /**Generated material id.*/
     uint32_t _materialID;
+    /**OpenGL handle for texture.*/
     GLuint _textureID;
+    /**GLprogramstate for the commmand. encapsulate shaders and uniforms.*/
     GLProgramState* _glProgramState;
+    /**Blend function when rendering the triangles.*/
     BlendFunc _blendType;
+    /**The pointer to the rendered quads.*/
     V3F_C4B_T2F_Quad* _quads;
+    /**The number of quads for rendering.*/
     ssize_t _quadsCount;
+    /**Model view matrix when rendering the triangles.*/
     Mat4 _mv;
 };
 

cocos/renderer/CCTrianglesCommand.h

@@ -29,47 +29,81 @@
 #include "renderer/CCGLProgramState.h"
 
 NS_CC_BEGIN
+/** 
+ Command used to render one or more Triangles, which is similar to QuadCommand.
+ Every TrianglesCommand will have generate material ID by give textureID, glProgramState, Blend function
+ if the material id is the same, these TrianglesCommands could be batched to save draw call.
+*/
 class CC_DLL TrianglesCommand : public RenderCommand
 {
 public:
+    /**The structure of Triangles. */
     struct Triangles
     {
+        /**Vertex data pointer.*/
         V3F_C4B_T2F* verts;
+        /**Index data pointer.*/
         unsigned short* indices;
+        /**The number of vertices.*/
         ssize_t vertCount;
+        /**The number of indices.*/
         ssize_t indexCount;
     };
-    
+    /**Construtor.*/
     TrianglesCommand();
+    /**Destructor.*/
     ~TrianglesCommand();
     
-    /** Initializes the command with a globalZOrder, a texture ID, a `GLProgram`, a blending function, a pointer to triangles,
-     * quantity of quads, and the Model View transform to be used for the quads */
+    /** Initializes the command.
+     @param globalOrder GlobalZOrder of the command.
+     @param textureID The openGL handle of the used texture.
+     @param glProgramState The specified glProgram and its uniform.
+     @param blendType Blend function for the command.
+     @param triangles Rendered triangles for the command.
+     @param mv ModelView matrix for the command.
+     @param flags to indicate that the command is using 3D rendering or not.
+     */
     void init(float globalOrder, GLuint textureID, GLProgramState* glProgramState, BlendFunc blendType, const Triangles& triangles,const Mat4& mv, uint32_t flags);
-    
+    /**Deprecated function, the params is similar as the upper init function, with flags equals 0.*/
     CC_DEPRECATED_ATTRIBUTE void init(float globalOrder, GLuint textureID, GLProgramState* glProgramState, BlendFunc blendType, const Triangles& triangles,const Mat4& mv);
-    
+    /**Apply the texture, shaders, programs, blend functions to GPU pipeline.*/
     void useMaterial() const;
-    
+    /**Get the material id of command.*/
     inline uint32_t getMaterialID() const { return _materialID; }
+    /**Get the openGL texture handle.*/
     inline GLuint getTextureID() const { return _textureID; }
+    /**Get a const reference of triangles.*/
     inline const Triangles& getTriangles() const { return _triangles; }
+    /**Get the vertex count in the triangles.*/
     inline ssize_t getVertexCount() const { return _triangles.vertCount; }
+    /**Get the index count of the triangles.*/
     inline ssize_t getIndexCount() const { return _triangles.indexCount; }
+    /**Get the vertex data pointer.*/
     inline const V3F_C4B_T2F* getVertices() const { return _triangles.verts; }
+    /**Get the index data pointer.*/
     inline const unsigned short* getIndices() const { return _triangles.indices; }
+    /**Get the glprogramstate.*/
     inline GLProgramState* getGLProgramState() const { return _glProgramState; }
+    /**Get the blend function.*/
     inline BlendFunc getBlendType() const { return _blendType; }
+    /**Get the model view matrix.*/
     inline const Mat4& getModelView() const { return _mv; }
     
 protected:
+    /**Generate the material ID by textureID, glProgramState, and blend function.*/
     void generateMaterialID();
     
+    /**Generated material id.*/
     uint32_t _materialID;
+    /**OpenGL handle for texture.*/
     GLuint _textureID;
+    /**GLprogramstate for the commmand. encapsulate shaders and uniforms.*/
     GLProgramState* _glProgramState;
+    /**Blend function when rendering the triangles.*/
     BlendFunc _blendType;
+    /**Rendered triangles.*/
     Triangles _triangles;
+    /**Model view matrix when rendering the triangles.*/
     Mat4 _mv;
 };