From 0408fc0667ed24379199be07a0316ca440fbcd52 Mon Sep 17 00:00:00 2001 From: minggo Date: Wed, 18 Mar 2015 15:02:03 +0800 Subject: [PATCH 01/10] update document for CCRef.h --- cocos/base/CCRef.h | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/cocos/base/CCRef.h b/cocos/base/CCRef.h index f0f2820ed9..bd6cacbd52 100644 --- a/cocos/base/CCRef.h +++ b/cocos/base/CCRef.h @@ -40,20 +40,25 @@ NS_CC_BEGIN class Ref; -/** Interface that defines how to clone an Ref */ +/** + * Interface that defines how to clone an Ref. + * @lua NA + * @js NA + */ class CC_DLL Clonable { public: - /** returns a copy of the Ref */ + /** Returns a copy of the Ref. */ virtual Clonable* clone() const = 0; + /** * @js NA * @lua NA */ virtual ~Clonable() {}; - /** returns a copy of the Ref. - * @deprecated Use clone() instead + /** Returns a copy of the Ref. + * @deprecated Use clone() instead. */ CC_DEPRECATED_ATTRIBUTE Ref* copy() const { @@ -63,6 +68,10 @@ public: } }; +/** + * Ref is used for reference count manangement. If a class inherits from Ref, + * then it is easy to be shared in different places. + */ class CC_DLL Ref { public: @@ -125,6 +134,8 @@ protected: public: /** + * Destructor + * * @js NA * @lua NA */ From f0a8fcd282bdfebd909fac4ea064b5a6f8d81b78 Mon Sep 17 00:00:00 2001 From: CocosRobot Date: Wed, 18 Mar 2015 10:28:24 +0000 Subject: [PATCH 02/10] [AUTO][ci skip]: updating cocos2dx_files.json --- templates/cocos2dx_files.json | 3 +++ 1 file changed, 3 insertions(+) diff --git a/templates/cocos2dx_files.json b/templates/cocos2dx_files.json index a4afdeeb84..62c604a01a 100644 --- a/templates/cocos2dx_files.json +++ b/templates/cocos2dx_files.json @@ -217,6 +217,7 @@ "cocos/2d/cocos2d.def", "cocos/2d/cocos2d_headers.props", "cocos/2d/cocos2dx.props", + "cocos/2d/doxygen_modules.h", "cocos/2d/libcocos2d.vcxproj", "cocos/2d/libcocos2d.vcxproj.filters", "cocos/2d/libcocos2d_8_1/libcocos2d_8_1.sln", @@ -494,6 +495,7 @@ "cocos/deprecated/CCString.cpp", "cocos/deprecated/CCString.h", "cocos/deprecated/CMakeLists.txt", + "cocos/doxygen_modules.h", "cocos/editor-support/cocosbuilder/Android.mk", "cocos/editor-support/cocosbuilder/CCBAnimationManager.cpp", "cocos/editor-support/cocosbuilder/CCBAnimationManager.h", @@ -1243,6 +1245,7 @@ "docs/RELEASE_NOTES.md", "docs/cocos2dx_portrait.png", "docs/doxygen.config", + "docs/doxygen_white_book.config", "download-deps.py", "extensions/Android.mk", "extensions/CMakeLists.txt", From a87c5755e9f77945fe7d90c47bd46ebb90a99710 Mon Sep 17 00:00:00 2001 From: "Huabing.Xu" Date: Wed, 18 Mar 2015 19:52:08 +0800 Subject: [PATCH 03/10] [ci skip] update comments CCTrianglesCommand.h --- cocos/renderer/CCTrianglesCommand.h | 46 +++++++++++++++++++++++++---- 1 file changed, 40 insertions(+), 6 deletions(-) diff --git a/cocos/renderer/CCTrianglesCommand.h b/cocos/renderer/CCTrianglesCommand.h index a7e1935108..5efb379716 100644 --- a/cocos/renderer/CCTrianglesCommand.h +++ b/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; }; From 431b3593a7271ac33a2d0808858b27a03fd0a410 Mon Sep 17 00:00:00 2001 From: "Huabing.Xu" Date: Wed, 18 Mar 2015 20:12:34 +0800 Subject: [PATCH 04/10] [ci skip] update comments CCQuadCommand.h --- cocos/renderer/CCQuadCommand.h | 41 ++++++++++++++++++++++++----- cocos/renderer/CCTrianglesCommand.h | 6 ++--- 2 files changed, 37 insertions(+), 10 deletions(-) diff --git a/cocos/renderer/CCQuadCommand.h b/cocos/renderer/CCQuadCommand.h index e8eab47ba3..5c17d50bc2 100644 --- a/cocos/renderer/CCQuadCommand.h +++ b/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; }; diff --git a/cocos/renderer/CCTrianglesCommand.h b/cocos/renderer/CCTrianglesCommand.h index 5efb379716..65fb2acd8e 100644 --- a/cocos/renderer/CCTrianglesCommand.h +++ b/cocos/renderer/CCTrianglesCommand.h @@ -30,9 +30,9 @@ 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. + 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 { From 0c8218581f33190728154ada2f283c61ea6acc70 Mon Sep 17 00:00:00 2001 From: "Huabing.Xu" Date: Wed, 18 Mar 2015 20:30:52 +0800 Subject: [PATCH 05/10] [ci skip] update comments CCRenderCommand.h --- cocos/renderer/CCRenderCommand.h | 56 +++++++++++++++++++++----------- 1 file changed, 37 insertions(+), 19 deletions(-) diff --git a/cocos/renderer/CCRenderCommand.h b/cocos/renderer/CCRenderCommand.h index 88d98c0ae7..811edeabff 100644 --- a/cocos/renderer/CCRenderCommand.h +++ b/cocos/renderer/CCRenderCommand.h @@ -40,68 +40,86 @@ NS_CC_BEGIN class CC_DLL RenderCommand { public: - + /**Enum the type of render command. */ enum class Type { + /** Reserved type.*/ UNKNOWN_COMMAND, + /** Quad command, used for draw quad.*/ QUAD_COMMAND, + /**Custom command, used for calling callback for rendering.*/ CUSTOM_COMMAND, + /**Batch command, used for draw batches in texture atlas.*/ BATCH_COMMAND, + /**Group command, which can group command in a tree hierarchy.*/ GROUP_COMMAND, + /**Mesh command, used to draw 3D meshes.*/ MESH_COMMAND, + /**Primitive command, used to draw primitives such as lines, points and triangles.*/ PRIMITIVE_COMMAND, + /**Triangles command, used to draw triangles.*/ TRIANGLES_COMMAND }; /** - * init function, will be called by all the render commands + Init function, will be called by all the render commands. + @param globalZOrder The global order of command, used for rendercommand sorting. + @param modelViewTransform Modelview matrix when submitting the render command. + @param flags Flag used to indicate whether the command should be draw at 3D mode or not. */ void init(float globalZOrder, const Mat4& modelViewTransform, uint32_t flags); - /** Get Render Command Id */ + /** Get global Z order. */ inline float getGlobalOrder() const { return _globalOrder; } - /** Returns the Command type */ + /** Returns the Command type. */ inline Type getType() const { return _type; } - /** Retruns whether is transparent */ + /** Retruns whether is transparent. */ inline bool isTransparent() const { return _isTransparent; } - /** set transparent flag */ + /** Set transparent flag. */ inline void setTransparent(bool isTransparent) { _isTransparent = isTransparent; } - + /** + Get skip batching status, if a rendering is skip batching, it will be forced to be rendering seperately. + */ inline bool isSkipBatching() const { return _skipBatching; } - + /**Set skip batching.*/ inline void setSkipBatching(bool value) { _skipBatching = value; } - + /**Whether the command should be rendered at 3D mode.*/ inline bool is3D() const { return _is3D; } - + /**Set the command rendered in 3D mode or not.*/ inline void set3D(bool value) { _is3D = value; } - + /**Get the depth by current model view matrix.*/ inline float getDepth() const { return _depth; } protected: + /**Constructor.*/ RenderCommand(); + /**Desctructor.*/ virtual ~RenderCommand(); - + //used for debug but it is not implemented. void printID(); - // Type used in order to avoid dynamic cast, faster + /**Type used in order to avoid dynamic cast, faster. */ Type _type; - // commands are sort by depth + /** Commands are sort by global Z order. */ float _globalOrder; - // transparent flag + /** Transparent flag. */ bool _isTransparent; - - // skip auto batching + + /** + QuadCommand and TrianglesCommand could be auto batched if there material ID is the same, however, if + a command is skip batching, it would be forced to draw in a seperate function call, and break the batch. + */ bool _skipBatching; - // is the command been rendered on 3D pass + /** Is the command been rendered on 3D pass. */ bool _is3D; - // depth + /** Depth from the model view matrix.*/ float _depth; }; From 19fc6a1495fb6b82d6102e4e0d2f0d0aa3476a83 Mon Sep 17 00:00:00 2001 From: minggo Date: Wed, 18 Mar 2015 20:37:43 +0800 Subject: [PATCH 06/10] update document for CCScheduler.h --- cocos/base/CCScheduler.h | 145 +++++++++++++++++++++++++++++---------- 1 file changed, 107 insertions(+), 38 deletions(-) diff --git a/cocos/base/CCScheduler.h b/cocos/base/CCScheduler.h index e18edef715..bb75be3e5f 100644 --- a/cocos/base/CCScheduler.h +++ b/cocos/base/CCScheduler.h @@ -46,11 +46,10 @@ NS_CC_BEGIN class Scheduler; typedef std::function ccSchedulerFunc; -// -// Timer -// -/** @brief Light-weight timer */ -// + +/** + * @cond + */ class CC_DLL Timer : public Ref { protected: @@ -106,13 +105,9 @@ class CC_DLL TimerTargetCallback : public Timer public: TimerTargetCallback(); - /** Initializes a timer with a target, a lambda and an interval in seconds, repeat in number of times to repeat, delay in seconds. */ + // Initializes a timer with a target, a lambda and an interval in seconds, repeat in number of times to repeat, delay in seconds. bool initWithCallback(Scheduler* scheduler, const ccSchedulerFunc& callback, void *target, const std::string& key, float seconds, unsigned int repeat, float delay); - /** - * @js NA - * @lua NA - */ inline const ccSchedulerFunc& getCallback() const { return _callback; }; inline const std::string& getKey() const { return _key; }; @@ -142,9 +137,11 @@ private: #endif -// -// Scheduler -// +/** + * @endcond + */ + + struct _listEntry; struct _hashSelectorEntry; struct _hashUpdateEntry; @@ -167,21 +164,39 @@ The 'custom selectors' should be avoided when possible. It is faster, and consum class CC_DLL Scheduler : public Ref { public: - // Priority level reserved for system services. + /** Priority level reserved for system services. + * @lua NA + * @js NA + */ static const int PRIORITY_SYSTEM; - // Minimum priority level for user scheduling. + /** Minimum priority level for user scheduling. + * Priority level of user scheduling should bigger then this value. + * + * @lua NA + * @js NA + */ static const int PRIORITY_NON_SYSTEM_MIN; + /** + * Constructor + * * @js ctor */ Scheduler(); + /** + * Destructor + * * @js NA * @lua NA */ virtual ~Scheduler(); + /** + * Gets the time scale of schedule callbacks. + * @see Scheduler::setTimeScale() + */ inline float getTimeScale() { return _timeScale; } /** Modifies the time of all scheduled callbacks. You can use this property to create a 'slow motion' or 'fast forward' effect. @@ -193,7 +208,7 @@ public: inline void setTimeScale(float timeScale) { _timeScale = timeScale; } /** 'update' the scheduler. - You should NEVER call this method, unless you know what you are doing. + * You should NEVER call this method, unless you know what you are doing. * @js NA * @lua NA */ @@ -208,30 +223,54 @@ public: If 'interval' is 0, it will be called every frame, but if so, it's recommended to use 'scheduleUpdate' instead. If the 'callback' is already scheduled, then only the interval parameter will be updated without re-scheduling it again. repeat let the action be repeated repeat + 1 times, use CC_REPEAT_FOREVER to let the action run continuously - delay is the amount of time the action will wait before it'll start - @param key The key to identify the callback + delay is the amount of time the action will wait before it'll start. + @param callback The callback function. + @param target The target of the callback function. + @param interval The interval to schedule the callback. If the value is 0, then the callback will be scheduled every frame. + @param repeat repeat+1 times to schedule the callback. + @param delay Schedule call back after `delay` seconds. If the value is not 0, the first schedule will happen after `delay` seconds. + But it will only affect first schedule. After first schedule, the delay time is determined by `interval`. + @param paused Whether or not to pause the schedule. + @param key The key to identify the callback function, because there is not way to identify a std::function<>. @since v3.0 */ void schedule(const ccSchedulerFunc& callback, void *target, float interval, unsigned int repeat, float delay, bool paused, const std::string& key); - /** Calls scheduleCallback with CC_REPEAT_FOREVER and a 0 delay + /** The scheduled method will be called every 'interval' seconds for ever. + @param callback The callback function. + @param target The target of the callback function. + @param interval The interval to schedule the callback. If the value is 0, then the callback will be scheduled every frame. + @param paused Whether or not to pause the schedule. + @param key The key to identify the callback function, because there is not way to identify a std::function<>. @since v3.0 */ void schedule(const ccSchedulerFunc& callback, void *target, float interval, bool paused, const std::string& key); - /** The scheduled method will be called every 'interval' seconds. + /** The scheduled method will be called every `interval` seconds. If paused is true, then it won't be called until it is resumed. If 'interval' is 0, it will be called every frame, but if so, it's recommended to use 'scheduleUpdate' instead. If the selector is already scheduled, then only the interval parameter will be updated without re-scheduling it again. repeat let the action be repeated repeat + 1 times, use CC_REPEAT_FOREVER to let the action run continuously delay is the amount of time the action will wait before it'll start - @since v3.0, repeat and delay added in v1.1 + @param selector The callback function. + @param target The target of the callback function. + @param interval The interval to schedule the callback. If the value is 0, then the callback will be scheduled every frame. + @param repeat repeat+1 times to schedule the callback. + @param delay Schedule call back after `delay` seconds. If the value is not 0, the first schedule will happen after `delay` seconds. + But it will only affect first schedule. After first schedule, the delay time is determined by `interval`. + @param paused Whether or not to pause the schedule. + @since v3.0 */ void schedule(SEL_SCHEDULE selector, Ref *target, float interval, unsigned int repeat, float delay, bool paused); - /** calls scheduleSelector with CC_REPEAT_FOREVER and a 0 delay */ + /** The scheduled method will be called every `interval` seconds for ever. + @param selector The callback function. + @param target The target of the callback function. + @param interval The interval to schedule the callback. If the value is 0, then the callback will be scheduled every frame. + @param paused Whether or not to pause the schedule. + */ void schedule(SEL_SCHEDULE selector, Ref *target, float interval, bool paused); /** Schedules the 'update' selector for a given target with a given priority. @@ -249,11 +288,15 @@ public: } #if CC_ENABLE_SCRIPT_BINDING - // schedule for script bindings + // Schedule for script bindings. /** The scheduled script callback will be called every 'interval' seconds. If paused is true, then it won't be called until it is resumed. If 'interval' is 0, it will be called every frame. return schedule script entry ID, used for unscheduleScriptFunc(). + + @warn Don't invoke this function unless you know what you are doing. + @js NA + @lua NA */ unsigned int scheduleScriptFunc(unsigned int handler, float interval, bool paused); #endif @@ -263,23 +306,29 @@ public: /** Unschedules a callback for a key and a given target. If you want to unschedule the 'callbackPerFrame', use unscheduleUpdate. + @param key The key to identify the callback function, because there is not way to identify a std::function<>. + @param target The target to be unscheduled. @since v3.0 */ void unschedule(const std::string& key, void *target); - /** Unschedule a selector for a given target. - If you want to unschedule the "update", use unscheudleUpdate. + /** Unschedules a selector for a given target. + If you want to unschedule the "update", use `unscheudleUpdate()`. + @param selector The selector that is unscheduled. + @param target The target of the unscheduled selector. @since v3.0 */ void unschedule(SEL_SCHEDULE selector, Ref *target); /** Unschedules the update selector for a given target + @param target The target to be unscheduled. @since v0.99.3 */ void unscheduleUpdate(void *target); /** Unschedules all selectors for a given target. This also includes the "update" selector. + @param target The target to be unscheduled. @since v0.99.3 @js unscheduleCallbackForTarget @lua NA @@ -290,16 +339,22 @@ public: You should NEVER call this method, unless you know what you are doing. @since v0.99.3 */ - void unscheduleAll(void); + void unscheduleAll(); /** Unschedules all selectors from all targets with a minimum priority. - You should only call this with kPriorityNonSystemMin or higher. + You should only call this with `PRIORITY_NON_SYSTEM_MIN` or higher. + @param minPriority The minimum priority of selector to be unscheduled. Which means, all selectors which + priority is higher than minPriority will be unscheduled. @since v2.0.0 */ void unscheduleAllWithMinPriority(int minPriority); #if CC_ENABLE_SCRIPT_BINDING - /** Unschedule a script entry. */ + /** Unschedule a script entry. + * @warn Don't invoke this function unless you know what you are doing. + * @js NA + * @lua NA + */ void unscheduleScriptEntry(unsigned int scheduleScriptEntryID); #endif @@ -308,11 +363,17 @@ public: // isScheduled /** Checks whether a callback associated with 'key' and 'target' is scheduled. + @param key The key to identify the callback function, because there is not way to identify a std::function<>. + @param target The target of the callback. + @return True if the specified callback is invoked, false if not. @since v3.0.0 */ bool isScheduled(const std::string& key, void *target); /** Checks whether a selector for a given taget is scheduled. + @param selector The selector to be checked. + @param target The target of the callback. + @return True if the specified selector is invoked, false if not. @since v3.0 */ bool isScheduled(SEL_SCHEDULE selector, Ref *target); @@ -322,6 +383,7 @@ public: /** Pauses the target. All scheduled selectors/update for a given target won't be 'ticked' until the target is resumed. If the target is not present, nothing happens. + @param target The target to be paused. @since v0.99.3 */ void pauseTarget(void *target); @@ -329,15 +391,18 @@ public: /** Resumes the target. The 'target' will be unpaused, so all schedule selectors/update will be 'ticked' again. If the target is not present, nothing happens. + @param target The target to be resumed. @since v0.99.3 */ void resumeTarget(void *target); - /** Returns whether or not the target is paused - @since v1.0.0 - * In js: var isTargetPaused(var jsObject) - * @lua NA - */ + /** Returns whether or not the target is paused. + * @param target The target to be checked. + * @return True if the target is paused, false if not. + * @since v1.0.0 + * @js isTargetPaused(var jsObject) + * @lua NA + */ bool isTargetPaused(void *target); /** Pause all selectors from all targets. @@ -347,19 +412,23 @@ public: std::set pauseAllTargets(); /** Pause all selectors from all targets with a minimum priority. - You should only call this with kPriorityNonSystemMin or higher. + You should only call this with PRIORITY_NON_SYSTEM_MIN or higher. + @param minPriority The minimum priority of selector to be paused. Which means, all selectors which + priority is higher than minPriority will be paused. @since v2.0.0 */ std::set pauseAllTargetsWithMinPriority(int minPriority); /** Resume selectors on a set of targets. This can be useful for undoing a call to pauseAllSelectors. + @param targetsToResume The set of targets to be resumed. @since v2.0.0 */ void resumeTargets(const std::set& targetsToResume); - /** calls a function on the cocos2d thread. Useful when you need to call a cocos2d function from another thread. + /** Calls a function on the cocos2d thread. Useful when you need to call a cocos2d function from another thread. This function is thread safe. + @param function The function to be run in cocos2d thread. @since v3.0 */ void performFunctionInCocosThread( const std::function &function); @@ -374,7 +443,7 @@ public: If the selector is already scheduled, then only the interval parameter will be updated without re-scheduling it again. repeat let the action be repeated repeat + 1 times, use CC_REPEAT_FOREVER to let the action run continuously delay is the amount of time the action will wait before it'll start - @deprecated Please use 'Scheduler::schedule' instead. + @deprecated Please use `Scheduler::schedule` instead. @since v0.99.3, repeat and delay added in v1.1 */ CC_DEPRECATED_ATTRIBUTE void scheduleSelector(SEL_SCHEDULE selector, Ref *target, float interval, unsigned int repeat, float delay, bool paused) @@ -382,8 +451,8 @@ public: schedule(selector, target, interval, repeat, delay, paused); }; - /** calls scheduleSelector with CC_REPEAT_FOREVER and a 0 delay - * @deprecated Please use 'Scheduler::schedule' instead. + /** Calls scheduleSelector with CC_REPEAT_FOREVER and a 0 delay. + * @deprecated Please use `Scheduler::schedule` instead. */ CC_DEPRECATED_ATTRIBUTE void scheduleSelector(SEL_SCHEDULE selector, Ref *target, float interval, bool paused) { From 2d5032732305e80ec075c8e4f21b6d8cee0e0bd1 Mon Sep 17 00:00:00 2001 From: Jacky Date: Wed, 18 Mar 2015 20:40:29 +0800 Subject: [PATCH 07/10] update CCActionManager & CCActionInstant & CCActionInterval & CCScene & CCSpriteFrame & CCSpriteFrameCache --- cocos/2d/CCActionInstant.h | 167 +++++++----- cocos/2d/CCActionInterval.h | 481 ++++++++++++++++++++++++---------- cocos/2d/CCActionManager.h | 61 ++++- cocos/2d/CCScene.h | 41 ++- cocos/2d/CCSpriteFrame.h | 97 ++++++- cocos/2d/CCSpriteFrameCache.h | 48 +++- 6 files changed, 657 insertions(+), 238 deletions(-) diff --git a/cocos/2d/CCActionInstant.h b/cocos/2d/CCActionInstant.h index 38047136a9..d0405aa426 100644 --- a/cocos/2d/CCActionInstant.h +++ b/cocos/2d/CCActionInstant.h @@ -38,10 +38,9 @@ NS_CC_BEGIN * @{ */ -/** -@brief Instant actions are immediate actions. They don't have a duration like -the IntervalAction actions. -*/ +/** @class ActionInstant +* @brief Instant actions are immediate actions. They don't have a duration like the IntervalAction actions. +**/ class CC_DLL ActionInstant : public FiniteTimeAction // { public: @@ -62,29 +61,32 @@ public: virtual bool isDone() const override; /** - * @param dt in seconds + * @param dt In seconds. */ virtual void step(float dt) override; /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; }; -/** @brief Show the node -*/ +/** @class Show +* @brief Show the node. +**/ class CC_DLL Show : public ActionInstant { public: - /** Allocates and initializes the action */ + /** Allocates and initializes the action. + * + * @return An autoreleased Show object. + */ static Show * create(); - // // Overrides // /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; virtual ActionInstant* reverse() const override; @@ -98,20 +100,23 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(Show); }; -/** -@brief Hide the node +/** @class Hide +* @brief Hide the node. */ class CC_DLL Hide : public ActionInstant { public: - /** Allocates and initializes the action */ + /** Allocates and initializes the action. + * + * @return An autoreleased Hide object. + */ static Hide * create(); // // Overrides // /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; virtual ActionInstant* reverse() const override; @@ -125,19 +130,23 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(Hide); }; -/** @brief Toggles the visibility of a node +/** @class ToggleVisibility +* @brief Toggles the visibility of a node. */ class CC_DLL ToggleVisibility : public ActionInstant { public: - /** Allocates and initializes the action */ + /** Allocates and initializes the action. + * + * @return An autoreleased ToggleVisibility object. + */ static ToggleVisibility * create(); // // Overrides // /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; virtual ToggleVisibility* reverse() const override; @@ -151,20 +160,24 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(ToggleVisibility); }; -/** -@brief Remove the node +/** @class RemoveSelf +* @brief Remove the node. */ class CC_DLL RemoveSelf : public ActionInstant { public: - /** create the action */ + /** Create the action. + * + * @param isNeedCleanUp Is need to clean up, the default value is true. + * @return An autoreleased RemoveSelf object. + */ static RemoveSelf * create(bool isNeedCleanUp = true); // // Override // /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; virtual RemoveSelf* clone() const override; @@ -184,21 +197,25 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(RemoveSelf); }; -/** -@brief Flips the sprite horizontally -@since v0.99.0 +/** @class FlipX +* @brief Flips the sprite horizontally. +* @since v0.99.0 */ class CC_DLL FlipX : public ActionInstant { public: - /** create the action */ + /** Create the action. + * + * @param x Flips the sprite horizontally if true. + * @return An autoreleased FlipX object. + */ static FlipX * create(bool x); // // Overrides // /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; virtual FlipX* reverse() const override; @@ -218,21 +235,25 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(FlipX); }; -/** -@brief Flips the sprite vertically -@since v0.99.0 +/** @class FlipY +* @brief Flips the sprite vertically. +* @since v0.99.0 */ class CC_DLL FlipY : public ActionInstant { public: - /** create the action */ + /** Create the action. + * + * @param y Flips the sprite vertically if true. + * @return An autoreleased FlipY object. + */ static FlipY * create(bool y); // // Overrides // /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; virtual FlipY* reverse() const override; @@ -252,20 +273,25 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(FlipY); }; -/** @brief Places the node in a certain position +/** @class Place +* @brief Places the node in a certain position. */ class CC_DLL Place : public ActionInstant // { public: - /** creates a Place action with a position */ + /** Creates a Place action with a position. + * + * @param pos A certain position. + * @return An autoreleased Place object. + */ static Place * create(const Vec2& pos); // // Overrides // /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; virtual Place* reverse() const override; @@ -286,20 +312,24 @@ private: }; -/** @brief Calls a 'callback' +/** @class CallFunc +* @brief Calls a 'callback'. */ class CC_DLL CallFunc : public ActionInstant // { public: - /** creates the action with the callback of type std::function. + /** Creates the action with the callback of type std::function. This is the preferred way to create the callback. - * When this funtion bound in js or lua ,the input param will be changed - * In js: var create(var func, var this, var [data]) or var create(var func) - * In lua:local create(local funcID) + * When this funtion bound in js or lua ,the input param will be changed. + * In js: var create(var func, var this, var [data]) or var create(var func). + * In lua:local create(local funcID). + * + * @param func A callback function need to be excuted. + * @return An autoreleased CallFunc object. */ static CallFunc * create(const std::function& func); - /** creates the action with the callback + /** Creates the action with the callback typedef void (Ref::*SEL_CallFunc)(); @deprecated Use the std::function API instead. @@ -309,14 +339,23 @@ public: CC_DEPRECATED_ATTRIBUTE static CallFunc * create(Ref* target, SEL_CallFunc selector); public: - /** executes the callback */ + /** Executes the callback. + */ virtual void execute(); + /** Get the selector target. + * + * @return The selector target. + */ inline Ref* getTargetCallback() { return _selectorTarget; } + /** Set the selector target. + * + * @param The selector target. + */ inline void setTargetCallback(Ref* sel) { if (sel != _selectorTarget) @@ -330,7 +369,7 @@ public: // Overrides // /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; virtual CallFunc* reverse() const override; @@ -374,19 +413,21 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(CallFunc); }; -/** -@brief Calls a 'callback' with the node as the first argument -N means Node +/** @class CallFuncN +* @brief Calls a 'callback' with the node as the first argument. N means Node. */ class CC_DLL CallFuncN : public CallFunc { public: - /** creates the action with the callback of type std::function. + /** Creates the action with the callback of type std::function. This is the preferred way to create the callback. + * + * @param func A callback function need to be excuted. + * @return An autoreleased CallFuncN object. */ static CallFuncN * create(const std::function& func); - /** creates the action with the callback + /** Creates the action with the callback. typedef void (Ref::*SEL_CallFuncN)(Node*); @deprecated Use the std::function API instead. @@ -421,16 +462,21 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(CallFuncN); }; -/** - @deprecated Please use CallFuncN instead. - @brief Calls a 'callback' with the node as the first argument and the 2nd argument is data +/** @class __CCCallFuncND + * @deprecated Please use CallFuncN instead. + * @brief Calls a 'callback' with the node as the first argument and the 2nd argument is data. * ND means: Node and Data. Data is void *, so it could be anything. */ - class CC_DLL __CCCallFuncND : public CallFunc { public: - /** creates the action with the callback and the data to pass as an argument */ + /** Creates the action with the callback and the data to pass as an argument. + * + * @param target A certain target. + * @param selector The callback need to be excuted. + * @param d Data, is void* type. + * @return An autoreleased __CCCallFuncND object. + */ CC_DEPRECATED_ATTRIBUTE static __CCCallFuncND * create(Ref* target, SEL_CallFuncND selector, void* d); // @@ -455,19 +501,22 @@ private: }; -/** +/** @class __CCCallFuncO @deprecated Please use CallFuncN instead. - @brief Calls a 'callback' with an object as the first argument. - O means Object. + @brief Calls a 'callback' with an object as the first argument. O means Object. @since v0.99.5 */ class CC_DLL __CCCallFuncO : public CallFunc { public: - /** creates the action with the callback - - typedef void (Ref::*SEL_CallFuncO)(Ref*); + /** Creates the action with the callback. + typedef void (Ref::*SEL_CallFuncO)(Ref*); + * + * @param target A certain target. + * @param selector The callback need to be excuted. + * @param object An object as the callback's first argument. + * @return An autoreleased __CCCallFuncO object. */ CC_DEPRECATED_ATTRIBUTE static __CCCallFuncO * create(Ref* target, SEL_CallFuncO selector, Ref* object); // diff --git a/cocos/2d/CCActionInterval.h b/cocos/2d/CCActionInterval.h index f3bf3121cf..730788e716 100644 --- a/cocos/2d/CCActionInterval.h +++ b/cocos/2d/CCActionInterval.h @@ -46,7 +46,7 @@ class EventCustom; * @{ */ -/** +/** @class ActionInterval @brief An interval action is an action that takes place within a certain period of time. It has an start time, and a finish time. The finish time is the parameter duration plus the start time. @@ -66,11 +66,22 @@ Action *pingPongAction = Sequence::actions(action, action->reverse(), nullptr); class CC_DLL ActionInterval : public FiniteTimeAction { public: - /** how many seconds had elapsed since the actions started to run. */ + /** How many seconds had elapsed since the actions started to run. + * + * @return The seconds had elapsed since the ations started to run. + */ inline float getElapsed(void) { return _elapsed; } - //extension in GridAction + /** Sets the ampliture rate, extension in GridAction + * + * @param amp The ampliture rate. + */ void setAmplitudeRate(float amp); + + /** Gets the ampliture rate, extension in GridAction + * + * @return The ampliture rate. + */ float getAmplitudeRate(void); // @@ -103,12 +114,16 @@ protected: bool _firstTick; }; -/** @brief Runs actions sequentially, one after another +/** @class Sequence + * @brief Runs actions sequentially, one after another. */ class CC_DLL Sequence : public ActionInterval { public: - /** helper constructor to create an array of sequenceable actions */ + /** Helper constructor to create an array of sequenceable actions. + * + * @return An autoreleased Sequence object. + */ #if (CC_TARGET_PLATFORM == CC_PLATFORM_WP8) || (CC_TARGET_PLATFORM == CC_PLATFORM_WINRT) // WP8 in VS2012 does not support nullptr in variable args lists and variadic templates are also not supported typedef FiniteTimeAction* M; @@ -129,17 +144,29 @@ public: static Sequence* create(FiniteTimeAction *action1, ...) CC_REQUIRES_NULL_TERMINATION; #endif - /** helper constructor to create an array of sequenceable actions given an array + /** Helper constructor to create an array of sequenceable actions given an array. * @code * When this funtion bound to the js or lua,the input params changed * in js :var create(var object1,var object2, ...) * in lua :local create(local object1,local object2, ...) * @endcode + * + * @param arrayOfActions An array of sequenceable actions. + * @return An autoreleased Sequence object. */ static Sequence* create(const Vector& arrayOfActions); - /** helper constructor to create an array of sequence-able actions */ + /** Helper constructor to create an array of sequence-able actions. + * + * @param action1 The first sequenceable action. + * @param args The va_list variable. + * @return An autoreleased Sequence object. + */ static Sequence* createWithVariableList(FiniteTimeAction *action1, va_list args); - /** creates the action */ + /** Creates the action. + * @param actionOne The first sequenceable action. + * @param actionTwo The second sequenceable action. + * @return An autoreleased Sequence object. + */ static Sequence* createWithTwoActions(FiniteTimeAction *actionOne, FiniteTimeAction *actionTwo); // @@ -150,7 +177,7 @@ public: virtual void startWithTarget(Node *target) override; virtual void stop(void) override; /** - * @param t in seconds + * @param t In seconds. */ virtual void update(float t) override; @@ -170,15 +197,25 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(Sequence); }; -/** @brief Repeats an action a number of times. +/** @class Repeat + * @brief Repeats an action a number of times. * To repeat an action forever use the RepeatForever action. */ class CC_DLL Repeat : public ActionInterval { public: - /** creates a Repeat action. Times is an unsigned integer between 1 and pow(2,30) */ + /** Creates a Repeat action. Times is an unsigned integer between 1 and pow(2,30). + * + * @param action The action needs to repeat. + * @param times The repeat times. + * @return An autoreleased Repeat object. + */ static Repeat* create(FiniteTimeAction *action, unsigned int times); + /** Sets the inner action. + * + * @param action The inner action. + */ inline void setInnerAction(FiniteTimeAction *action) { if (_innerAction != action) @@ -189,6 +226,10 @@ public: } } + /** Gets the inner action. + * + * @return The inner action. + */ inline FiniteTimeAction* getInnerAction() { return _innerAction; @@ -202,7 +243,7 @@ public: virtual void startWithTarget(Node *target) override; virtual void stop(void) override; /** - * @param dt in seconds + * @param dt In seconds. */ virtual void update(float dt) override; virtual bool isDone(void) const override; @@ -226,16 +267,25 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(Repeat); }; -/** @brief Repeats an action for ever. -To repeat the an action for a limited number of times use the Repeat action. -@warning This action can't be Sequenceable because it is not an IntervalAction -*/ +/** @class RepeatForever + * @brief Repeats an action for ever. + To repeat the an action for a limited number of times use the Repeat action. + * @warning This action can't be Sequenceable because it is not an IntervalAction. + */ class CC_DLL RepeatForever : public ActionInterval { public: - /** creates the action */ + /** Creates the action. + * + * @param action The action need to repeat forever. + * @return An autoreleased RepeatForever object. + */ static RepeatForever* create(ActionInterval *action); + /** Sets the inner action. + * + * @param action The inner action. + */ inline void setInnerAction(ActionInterval *action) { if (_innerAction != action) @@ -246,6 +296,10 @@ public: } } + /** Gets the inner action. + * + * @return The inner action. + */ inline ActionInterval* getInnerAction() { return _innerAction; @@ -258,7 +312,7 @@ public: virtual RepeatForever* reverse(void) const override; virtual void startWithTarget(Node* target) override; /** - * @param dt in seconds + * @param dt In seconds. */ virtual void step(float dt) override; virtual bool isDone(void) const override; @@ -280,20 +334,23 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(RepeatForever); }; -/** @brief Spawn a new action immediately +/** @class Spawn + * @brief Spawn a new action immediately */ class CC_DLL Spawn : public ActionInterval { public: - /** helper constructor to create an array of spawned actions + /** Helper constructor to create an array of spawned actions. * @code - * When this funtion bound to the js or lua,the input params changed + * When this funtion bound to the js or lua, the input params changed. * in js :var create(var object1,var object2, ...) * in lua :local create(local object1,local object2, ...) * @endcode + * + * @return An autoreleased Spawn object. */ #if (CC_TARGET_PLATFORM == CC_PLATFORM_WP8) || (CC_TARGET_PLATFORM == CC_PLATFORM_WINRT) - // WP8 in VS2012 does not support nullptr in variable args lists and variadic templates are also not supported + // WP8 in VS2012 does not support nullptr in variable args lists and variadic templates are also not supported. typedef FiniteTimeAction* M; static Spawn* create(M m1, std::nullptr_t listEnd) { return variadicCreate(m1, NULL); } static Spawn* create(M m1, M m2, std::nullptr_t listEnd) { return variadicCreate(m1, m2, NULL); } @@ -306,19 +363,33 @@ public: static Spawn* create(M m1, M m2, M m3, M m4, M m5, M m6, M m7, M m8, M m9, std::nullptr_t listEnd) { return variadicCreate(m1, m2, m3, m4, m5, m6, m7, m8, m9, NULL); } static Spawn* create(M m1, M m2, M m3, M m4, M m5, M m6, M m7, M m8, M m9, M m10, std::nullptr_t listEnd) { return variadicCreate(m1, m2, m3, m4, m5, m6, m7, m8, m9, m10, NULL); } - // On WP8 for variable argument lists longer than 10 items, use the other create functions or createSpawn with NULL as the last argument + // On WP8 for variable argument lists longer than 10 items, use the other create functions or createSpawn with NULL as the last argument. static Spawn* variadicCreate(FiniteTimeAction* item, ...); #else static Spawn* create(FiniteTimeAction *action1, ...) CC_REQUIRES_NULL_TERMINATION; #endif - /** helper constructor to create an array of spawned actions */ + /** Helper constructor to create an array of spawned actions. + * + * @param action1 The first sequenceable action. + * @param args The va_list variable. + * @return An autoreleased Spawn object. + */ static Spawn* createWithVariableList(FiniteTimeAction *action1, va_list args); - /** helper constructor to create an array of spawned actions given an array */ + /** Helper constructor to create an array of spawned actions given an array. + * + * @param arrayOfActions An array of spawned actions. + * @return An autoreleased Spawn object. + */ static Spawn* create(const Vector& arrayOfActions); - /** creates the Spawn action */ + /** Creates the Spawn action. + * + * @param action1 The first spawned action. + * @param action2 THe second spawned action. + * @return An autoreleased Spawn object. + */ static Spawn* createWithTwoActions(FiniteTimeAction *action1, FiniteTimeAction *action2); // @@ -329,7 +400,7 @@ public: virtual void startWithTarget(Node *target) override; virtual void stop(void) override; /** - * @param dt in seconds + * @param dt In seconds. */ virtual void update(float time) override; @@ -348,31 +419,37 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(Spawn); }; -/** @brief Rotates a Node object to a certain angle by modifying it's - rotation attribute. +/** @class RotateTo + * @brief Rotates a Node object to a certain angle by modifying it's rotation attribute. The direction will be decided by the shortest angle. */ class CC_DLL RotateTo : public ActionInterval { public: /** - * creates the action with separate rotation angles - * @param duration in seconds - * @param dstAngleX in degreesCW - * @param dstAngleY in degreesCW + * Creates the action with separate rotation angles. + * + * @param duration Duration time, in seconds. + * @param dstAngleX In degreesCW. + * @param dstAngleY In degreesCW. + * @return An autoreleased RotateTo object. */ static RotateTo* create(float duration, float dstAngleX, float dstAngleY); /** - * creates the action - * @param duration in seconds - * @param dstAngle in degreesCW + * Creates the action. + * + * @param duration Duration time, in seconds. + * @param dstAngle In degreesCW. + * @return An autoreleased RotateTo object. */ static RotateTo* create(float duration, float dstAngle); /** - * creates the action with 3D rotation angles - * @param duration in seconds + * Creates the action with 3D rotation angles. + * @param duration Duration time, in seconds. + * @param dstAngle3D A Vec3 angle. + * @return An autoreleased RotateTo object. */ static RotateTo* create(float duration, const Vec3& dstAngle3D); @@ -383,7 +460,7 @@ public: virtual RotateTo* reverse() const override; virtual void startWithTarget(Node *target) override; /** - * @param dt in seconds + * @param dt In seconds. */ virtual void update(float time) override; @@ -420,26 +497,35 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(RotateTo); }; -/** @brief Rotates a Node object clockwise a number of degrees by modifying it's rotation attribute. +/** @class RotateBy + * @brief Rotates a Node object clockwise a number of degrees by modifying it's rotation attribute. */ class CC_DLL RotateBy : public ActionInterval { public: /** - * creates the action - * @param duration in seconds - * @param deltaAngle in degreesCW + * Creates the action. + * + * @param duration Duration time, in seconds. + * @param deltaAngle In degreesCW. + * @return An autoreleased RotateBy object. */ static RotateBy* create(float duration, float deltaAngle); /** - * @param duration in seconds - * @param deltaAngleZ_X in degreesCW - * @param deltaAngleZ_Y in degreesCW + * Creates the action with separate rotation angles. + * + * @param duration Duration time, in seconds. + * @param deltaAngleZ_X In degreesCW. + * @param deltaAngleZ_Y In degreesCW. + * @return An autoreleased RotateBy object. * @warning The physics body contained in Node doesn't support rotate with different x and y angle. */ static RotateBy* create(float duration, float deltaAngleZ_X, float deltaAngleZ_Y); - /** - * @param duration in seconds + /** Creates the action with 3D rotation angles. + * + * @param duration Duration time, in seconds. + * @param deltaAngle3D A Vec3 angle. + * @return An autoreleased RotateBy object. */ static RotateBy* create(float duration, const Vec3& deltaAngle3D); @@ -450,7 +536,7 @@ public: virtual RotateBy* reverse(void) const override; virtual void startWithTarget(Node *target) override; /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; @@ -477,7 +563,8 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(RotateBy); }; -/** Moves a Node object x,y pixels by modifying it's position attribute. +/** @class MoveBy + * @brief Moves a Node object x,y pixels by modifying it's position attribute. x and y are relative to the position of the object. Several MoveBy actions can be concurrently called, and the resulting movement will be the sum of individual movements. @@ -487,13 +574,19 @@ class CC_DLL MoveBy : public ActionInterval { public: /** - * creates the action - * @param duration in seconds + * Creates the action. + * + * @param duration Duration time, in seconds. + * @param deltaPosition The delta distance in 2d, it's a Vec2 type. + * @return An autoreleased MoveBy object. */ static MoveBy* create(float duration, const Vec2& deltaPosition); /** - * creates the action - * @param duration in seconds + * Creates the action. + * + * @param duration Duration time, in seconds. + * @param deltaPosition The delta distance in 3d, it's a Vec3 type. + * @return An autoreleased MoveBy object. */ static MoveBy* create(float duration, const Vec3& deltaPosition); @@ -526,7 +619,8 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(MoveBy); }; -/** Moves a Node object to the position x,y. x and y are absolute coordinates by modifying it's position attribute. +/** @class MoveTo + * @brief Moves a Node object to the position x,y. x and y are absolute coordinates by modifying it's position attribute. Several MoveTo actions can be concurrently called, and the resulting movement will be the sum of individual movements. @since v2.1beta2-custom @@ -535,13 +629,17 @@ class CC_DLL MoveTo : public MoveBy { public: /** - * creates the action - * @param duration in seconds + * Creates the action. + * @param duration Duration time, in seconds. + * @param position The destination position in 2d. + * @return An autoreleased MoveTo object. */ static MoveTo* create(float duration, const Vec2& position); /** - * creates the action - * @param duration in seconds + * Creates the action. + * @param duration Duration time, in seconds. + * @param position The destination position in 3d. + * @return An autoreleased MoveTo object. */ static MoveTo* create(float duration, const Vec3& position); @@ -574,15 +672,19 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(MoveTo); }; -/** Skews a Node object to given angles by modifying it's skewX and skewY attributes +/** @class SkewTo + * @brief Skews a Node object to given angles by modifying it's skewX and skewY attributes @since v1.0 */ class CC_DLL SkewTo : public ActionInterval { public: /** - * creates the action - * @param t in seconds + * Creates the action. + * @param t Duration time, in seconds. + * @param sx Skew x angle. + * @param sy Skew y angle. + * @return An autoreleased SkewTo object. */ static SkewTo* create(float t, float sx, float sy); @@ -593,7 +695,7 @@ public: virtual SkewTo* reverse(void) const override; virtual void startWithTarget(Node *target) override; /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; @@ -601,7 +703,7 @@ CC_CONSTRUCTOR_ACCESS: SkewTo(); virtual ~SkewTo() {} /** - * @param t in seconds + * @param t In seconds. */ bool initWithDuration(float t, float sx, float sy); @@ -619,15 +721,19 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(SkewTo); }; -/** Skews a Node object by skewX and skewY degrees +/** @class SkewBy +* @brief Skews a Node object by skewX and skewY degrees. @since v1.0 */ class CC_DLL SkewBy : public SkewTo { public: /** - * creates the action - * @param t in seconds + * Creates the action. + * @param t Duration time, in seconds. + * @param deltaSkewX Skew x delta angle. + * @param deltaSkewY Skew y delta angle. + * @return An autoreleased SkewBy object. */ static SkewBy* create(float t, float deltaSkewX, float deltaSkewY); @@ -642,7 +748,7 @@ CC_CONSTRUCTOR_ACCESS: SkewBy() {} virtual ~SkewBy() {} /** - * @param t in seconds + * @param t In seconds. */ bool initWithDuration(float t, float sx, float sy); @@ -650,14 +756,19 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(SkewBy); }; -/** @brief Moves a Node object simulating a parabolic jump movement by modifying it's position attribute. +/** @class JumpBy + * @brief Moves a Node object simulating a parabolic jump movement by modifying it's position attribute. */ class CC_DLL JumpBy : public ActionInterval { public: /** - * creates the action - * @param duration in seconds + * Creates the action. + * @param duration Duration time, in seconds. + * @param position The jumping distance. + * @param height The jumping height. + * @param jumps The jumping times. + * @return An autoreleased JumpBy object. */ static JumpBy* create(float duration, const Vec2& position, float height, int jumps); @@ -668,7 +779,7 @@ public: virtual JumpBy* reverse(void) const override; virtual void startWithTarget(Node *target) override; /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; @@ -693,14 +804,19 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(JumpBy); }; -/** @brief Moves a Node object to a parabolic position simulating a jump movement by modifying it's position attribute. +/** @class JumpTo + * @brief Moves a Node object to a parabolic position simulating a jump movement by modifying it's position attribute. */ class CC_DLL JumpTo : public JumpBy { public: /** - * creates the action - * @param duration in seconds + * Creates the action. + * @param duration Duration time, in seconds. + * @param position The jumping destination position. + * @param height The jumping height. + * @param jumps The jumping times. + * @return An autoreleased JumpTo object. */ static JumpTo* create(float duration, const Vec2& position, float height, int jumps); @@ -717,7 +833,7 @@ CC_CONSTRUCTOR_ACCESS: /** * initializes the action - * @param duration in seconds + * @param duration In seconds. */ bool initWithDuration(float duration, const Vec2& position, float height, int jumps); @@ -728,7 +844,7 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(JumpTo); }; -/** Bezier configuration structure +/** @struct Bezier configuration structure */ typedef struct _ccBezierConfig { //! end position of the bezier @@ -739,15 +855,18 @@ typedef struct _ccBezierConfig { Vec2 controlPoint_2; } ccBezierConfig; -/** @brief An action that moves the target with a cubic Bezier curve by a certain distance. +/** @class BezierBy + * @brief An action that moves the target with a cubic Bezier curve by a certain distance. */ class CC_DLL BezierBy : public ActionInterval { public: - /** creates the action with a duration and a bezier configuration - * @param t in seconds + /** Creates the action with a duration and a bezier configuration. + * @param t Duration time, in seconds. + * @param c Bezier config. + * @return An autoreleased BezierBy object. * @code - * when this function bound to js or lua,the input params are changed + * When this function bound to js or lua,the input params are changed. * in js: var create(var t,var table) * in lua: lcaol create(local t, local table) * @endcode @@ -761,7 +880,7 @@ public: virtual BezierBy* reverse(void) const override; virtual void startWithTarget(Node *target) override; /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; @@ -784,14 +903,17 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(BezierBy); }; -/** @brief An action that moves the target with a cubic Bezier curve to a destination point. +/** @class BezierTo + * @brief An action that moves the target with a cubic Bezier curve to a destination point. @since v0.8.2 */ class CC_DLL BezierTo : public BezierBy { public: - /** creates the action with a duration and a bezier configuration - * @param t in seconds + /** Creates the action with a duration and a bezier configuration. + * @param t Duration time, in seconds. + * @param c Bezier config. + * @return An autoreleased BezierTo object. * @code * when this function bound to js or lua,the input params are changed * in js: var create(var t,var table) @@ -811,7 +933,7 @@ CC_CONSTRUCTOR_ACCESS: BezierTo() {} virtual ~BezierTo() {} /** - * @param t in seconds + * @param t In seconds. */ bool initWithDuration(float t, const ccBezierConfig &c); @@ -822,28 +944,38 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(BezierTo); }; -/** @brief Scales a Node object to a zoom factor by modifying it's scale attribute. - @warning This action doesn't support "reverse" +/** @class ScaleTo + @brief Scales a Node object to a zoom factor by modifying it's scale attribute. + @warning This action doesn't support "reverse". @warning The physics body contained in Node doesn't support this action. */ class CC_DLL ScaleTo : public ActionInterval { public: /** - * creates the action with the same scale factor for X and Y - * @param duration in seconds + * Creates the action with the same scale factor for X and Y. + * @param duration Duration time, in seconds. + * @param s Scale factor of x and y. + * @return An autoreleased ScaleTo object. */ static ScaleTo* create(float duration, float s); /** - * creates the action with and X factor and a Y factor - * @param duration in seconds + * Creates the action with and X factor and a Y factor. + * @param duration Duration time, in seconds. + * @param sx Scale factor of x. + * @param sy Scale factor of y. + * @return An autoreleased ScaleTo object. */ static ScaleTo* create(float duration, float sx, float sy); /** - * creates the action with X Y Z factor - * @param duration in seconds + * Creates the action with X Y Z factor. + * @param duration Duration time, in seconds. + * @param sx Scale factor of x. + * @param sy Scale factor of y. + * @param sz Scale factor of z. + * @return An autoreleased ScaleTo object. */ static ScaleTo* create(float duration, float sx, float sy, float sz); @@ -854,7 +986,7 @@ public: virtual ScaleTo* reverse(void) const override; virtual void startWithTarget(Node *target) override; /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; @@ -896,27 +1028,37 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(ScaleTo); }; -/** @brief Scales a Node object a zoom factor by modifying it's scale attribute. +/** @class ScaleBy + * @brief Scales a Node object a zoom factor by modifying it's scale attribute. @warning The physics body contained in Node doesn't support this action. */ class CC_DLL ScaleBy : public ScaleTo { public: /** - * creates the action with the same scale factor for X and Y - * @param duration in seconds + * Creates the action with the same scale factor for X and Y. + * @param duration Duration time, in seconds. + * @param s Scale factor of x and y. + * @return An autoreleased ScaleBy object. */ static ScaleBy* create(float duration, float s); /** - * creates the action with and X factor and a Y factor - * @param duration in seconds + * Creates the action with and X factor and a Y factor. + * @param duration Duration time, in seconds. + * @param sx Scale factor of x. + * @param sy Scale factor of y. + * @return An autoreleased ScaleBy object. */ static ScaleBy* create(float duration, float sx, float sy); /** - * creates the action with X Y Z factor - * @param duration in seconds + * Creates the action with X Y Z factor. + * @param duration Duration time, in seconds. + * @param sx Scale factor of x. + * @param sy Scale factor of y. + * @param sz Scale factor of z. + * @return An autoreleased ScaleBy object. */ static ScaleBy* create(float duration, float sx, float sy, float sz); @@ -935,14 +1077,17 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(ScaleBy); }; -/** @brief Blinks a Node object by modifying it's visible attribute +/** @class Blink + * @brief Blinks a Node object by modifying it's visible attribute. */ class CC_DLL Blink : public ActionInterval { public: /** - * creates the action - * @param duration in seconds + * Creates the action. + * @param duration Duration time, in seconds. + * @param blinks Blink times. + * @return An autoreleased Blink object. */ static Blink* create(float duration, int blinks); @@ -952,7 +1097,7 @@ public: virtual Blink* clone() const override; virtual Blink* reverse() const override; /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; virtual void startWithTarget(Node *target) override; @@ -977,15 +1122,18 @@ private: }; -/** @brief Fades an object that implements the RGBAProtocol protocol. It modifies the opacity from the current value to a custom one. +/** @class FadeTo + * @brief Fades an object that implements the RGBAProtocol protocol. It modifies the opacity from the current value to a custom one. @warning This action doesn't support "reverse" */ class CC_DLL FadeTo : public ActionInterval { public: /** - * creates an action with duration and opacity - * @param duration in seconds + * Creates an action with duration and opacity. + * @param duration Duration time, in seconds. + * @param opacity A certain opacity, the range is from 0 to 255. + * @return An autoreleased FadeTo object. */ static FadeTo* create(float duration, GLubyte opacity); @@ -996,7 +1144,7 @@ public: virtual FadeTo* reverse(void) const override; virtual void startWithTarget(Node *target) override; /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; @@ -1019,15 +1167,17 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(FadeTo); }; -/** @brief Fades In an object that implements the RGBAProtocol protocol. It modifies the opacity from 0 to 255. +/** @class FadeIn + * @brief Fades In an object that implements the RGBAProtocol protocol. It modifies the opacity from 0 to 255. The "reverse" of this action is FadeOut */ class CC_DLL FadeIn : public FadeTo { public: /** - * creates the action - * @param d in seconds + * Creates the action. + * @param d Duration time, in seconds. + * @return An autoreleased FadeIn object. */ static FadeIn* create(float d); @@ -1049,15 +1199,16 @@ private: FadeTo* _reverseAction; }; -/** @brief Fades Out an object that implements the RGBAProtocol protocol. It modifies the opacity from 255 to 0. +/** @class FadeOut + * @brief Fades Out an object that implements the RGBAProtocol protocol. It modifies the opacity from 255 to 0. The "reverse" of this action is FadeIn */ class CC_DLL FadeOut : public FadeTo { public: /** - * creates the action - * @param d in seconds + * Creates the action. + * @param d Duration time, in seconds. */ static FadeOut* create(float d); @@ -1077,7 +1228,9 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(FadeOut); FadeTo* _reverseAction; }; -/** @brief Tints a Node that implements the NodeRGB protocol from current tint to a custom one. + +/** @class TintTo + * @brief Tints a Node that implements the NodeRGB protocol from current tint to a custom one. @warning This action doesn't support "reverse" @since v0.7.2 */ @@ -1085,13 +1238,19 @@ class CC_DLL TintTo : public ActionInterval { public: /** - * creates an action with duration and color - * @param duration in seconds + * Creates an action with duration and color. + * @param duration Duration time, in seconds. + * @param red Red Color, from 0 to 255. + * @param green Green Color, from 0 to 255. + * @param blue Blue Color, from 0 to 255. + * @return An autoreleased TintTo object. */ static TintTo* create(float duration, GLubyte red, GLubyte green, GLubyte blue); /** - * creates an action with duration and color - * @param duration in seconds + * Creates an action with duration and color. + * @param duration Duration time, in seconds. + * @param color It's a Color3B type. + * @return An autoreleased TintTo object. */ static TintTo* create(float duration, const Color3B& color); @@ -1102,7 +1261,7 @@ public: virtual TintTo* reverse(void) const override; virtual void startWithTarget(Node *target) override; /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; @@ -1121,15 +1280,20 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(TintTo); }; -/** @brief Tints a Node that implements the NodeRGB protocol from current tint to a custom one. +/** @class TintBy + @brief Tints a Node that implements the NodeRGB protocol from current tint to a custom one. @since v0.7.2 */ class CC_DLL TintBy : public ActionInterval { public: /** - * creates an action with duration and color - * @param duration in seconds + * Creates an action with duration and color. + * @param duration Duration time, in seconds. + * @param deltaRed Delta red color. + * @param deltaGreen Delta green color. + * @param deltaBlue Delta blue color. + * @return An autoreleased TintBy object. */ static TintBy* create(float duration, GLshort deltaRed, GLshort deltaGreen, GLshort deltaBlue); @@ -1140,7 +1304,7 @@ public: virtual TintBy* reverse() const override; virtual void startWithTarget(Node *target) override; /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; @@ -1164,14 +1328,16 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(TintBy); }; -/** @brief Delays the action a certain amount of seconds +/** @class DelayTime + * @brief Delays the action a certain amount of seconds. */ class CC_DLL DelayTime : public ActionInterval { public: /** - * creates the action - * @param d in seconds + * Creates the action. + * @param d Duration time, in seconds. + * @return An autoreleased DelayTime object. */ static DelayTime* create(float d); @@ -1179,7 +1345,7 @@ public: // Overrides // /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; virtual DelayTime* reverse() const override; @@ -1193,7 +1359,8 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(DelayTime); }; -/** @brief Executes an action in reverse order, from time=duration to time=0 +/** @class ReverseTime + * @brief Executes an action in reverse order, from time=duration to time=0 @warning Use this action carefully. This action is not sequenceable. Use it as the default "reversed" method @@ -1203,7 +1370,11 @@ private: class CC_DLL ReverseTime : public ActionInterval { public: - /** creates the action */ + /** Creates the action. + * + * @param action a certain action. + * @return An autoreleased ReverseTime object. + */ static ReverseTime* create(FiniteTimeAction *action); // @@ -1214,7 +1385,7 @@ public: virtual void startWithTarget(Node *target) override; virtual void stop(void) override; /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; @@ -1233,16 +1404,28 @@ private: }; class Texture2D; -/** @brief Animates a sprite given the name of an Animation */ +/** @class Animate + * @brief Animates a sprite given the name of an Animation. + */ class CC_DLL Animate : public ActionInterval { public: - /** creates the action with an Animation and will restore the original frame when the animation is over */ + /** Creates the action with an Animation and will restore the original frame when the animation is over. + * + * @param animation A certain animation. + * @return An autoreleased Animate object. + */ static Animate* create(Animation *animation); - /** sets the Animation object to be animated */ + /** Sets the Animation object to be animated + * + * @param A certain animation. + */ void setAnimation( Animation* animation ); - /** returns the Animation object that is being animated */ + /** returns the Animation object that is being animated + * + * @return Gets the animation object that is being animated. + */ Animation* getAnimation() { return _animation; } const Animation* getAnimation() const { return _animation; } @@ -1254,7 +1437,7 @@ public: virtual void startWithTarget(Node *target) override; virtual void stop(void) override; /** - * @param t in seconds + * @param t In seconds. */ virtual void update(float t) override; @@ -1278,18 +1461,30 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(Animate); }; -/** Overrides the target of an action so that it always runs on the target +/** @class TargetedAction + * @brief Overrides the target of an action so that it always runs on the target * specified at action creation rather than the one specified by runAction. */ class CC_DLL TargetedAction : public ActionInterval { public: - /** Create an action with the specified action and forced target */ + /** Create an action with the specified action and forced target. + * + * @param target The target needs to override. + * @param action The action needs to override. + * @return An autoreleased TargetedAction object. + */ static TargetedAction* create(Node* target, FiniteTimeAction* action); - /** Sets the target that the action will be forced to run with */ + /** Sets the target that the action will be forced to run with. + * + * @param forcedTarget The target that the action will be forced to run with. + */ void setForcedTarget(Node* forcedTarget); - /** returns the target that the action is forced to run with */ + /** returns the target that the action is forced to run with. + * + * @return The target that the action is forced to run with. + */ Node* getForcedTarget() { return _forcedTarget; } const Node* getForcedTarget() const { return _forcedTarget; } @@ -1301,7 +1496,7 @@ public: virtual void startWithTarget(Node *target) override; virtual void stop(void) override; /** - * @param time in seconds + * @param time In seconds. */ virtual void update(float time) override; diff --git a/cocos/2d/CCActionManager.h b/cocos/2d/CCActionManager.h index 09566559de..cb7a4f9d55 100644 --- a/cocos/2d/CCActionManager.h +++ b/cocos/2d/CCActionManager.h @@ -44,14 +44,14 @@ struct _hashElement; * @{ */ -/** +/** @class ActionManager @brief ActionManager is a singleton that manages all the actions. Normally you won't need to use this singleton directly. 99% of the cases you will use the Node interface, which uses this singleton. But there are some cases where you might need to use this singleton. Examples: - When you want to run an action where the target is different from a Node. - - When you want to pause / resume the actions + - When you want to pause / resume the actions. @since v0.8 */ @@ -62,6 +62,7 @@ public: * @js ctor */ ActionManager(void); + /** * @js NA * @lua NA @@ -74,30 +75,49 @@ public: If the target is already present, then the action will be added to the existing target. If the target is not present, a new instance of this target will be created either paused or not, and the action will be added to the newly created target. When the target is paused, the queued actions won't be 'ticked'. + * + * @param action A certain action. + * @param target The target which need to be added an action. + * @param paused Is the target paused or not. */ void addAction(Action *action, Node *target, bool paused); /** Removes all actions from all the targets. - */ + */ void removeAllActions(); /** Removes all actions from a certain target. All the actions that belongs to the target will be removed. + * + * @param target A certain target. */ void removeAllActionsFromTarget(Node *target); /** Removes an action given an action reference. - */ + * + * @param action A certain target. + */ void removeAction(Action *action); - /** Removes an action given its tag and the target */ + /** Removes an action given its tag and the target. + * + * @param tag The action's tag. + * @param target A certain target. + */ void removeActionByTag(int tag, Node *target); - /** Removes all actions given its tag and the target */ + /** Removes all actions given its tag and the target. + * + * @param tag The actions' tag. + * @param target A certain target. + */ void removeAllActionsByTag(int tag, Node *target); - /** Gets an action given its tag an a target - @return the Action the with the given tag + /** Gets an action given its tag an a target. + * + * @param tag The action's tag. + * @param target A certain target. + * @return The Action the with the given tag. */ Action* getActionByTag(int tag, const Node *target) const; @@ -105,29 +125,42 @@ public: * Composable actions are counted as 1 action. Example: * - If you are running 1 Sequence of 7 actions, it will return 1. * - If you are running 7 Sequences of 2 actions, it will return 7. + * + * @param target A certain target. + * @return The numbers of actions that are running in a certain target. */ ssize_t getNumberOfRunningActionsInTarget(const Node *target) const; - /** @deprecated use getNumberOfRunningActionsInTarget() instead */ + /** @deprecated Use getNumberOfRunningActionsInTarget() instead. + */ CC_DEPRECATED_ATTRIBUTE inline ssize_t numberOfRunningActionsInTarget(Node *target) const { return getNumberOfRunningActionsInTarget(target); } /** Pauses the target: all running actions and newly added actions will be paused. - */ + * + * @param target A certain target. + */ void pauseTarget(Node *target); /** Resumes the target. All queued actions will be resumed. - */ + * + * @param target A certain target. + */ void resumeTarget(Node *target); /** Pauses all running actions, returning a list of targets whose actions were paused. + * + * @return A list of targets whose actions were paused. */ Vector pauseAllRunningActions(); - /** Resume a set of targets (convenience function to reverse a pauseAllRunningActions call) + /** Resume a set of targets (convenience function to reverse a pauseAllRunningActions call). + * + * @param targetsToResume A set of targets need to be resumed. */ void resumeTargets(const Vector& targetsToResume); - /** - * @param dt in seconds + + /** Main loop of ActionManager. + * @param dt In seconds. */ void update(float dt); diff --git a/cocos/2d/CCScene.h b/cocos/2d/CCScene.h index 313738828c..95fd68f0d7 100644 --- a/cocos/2d/CCScene.h +++ b/cocos/2d/CCScene.h @@ -46,7 +46,8 @@ class PhysicsWorld; * @{ */ -/** @brief Scene is a subclass of Node that is used only as an abstract concept. +/** @class Scene +* @brief Scene is a subclass of Node that is used only as an abstract concept. Scene and Node are almost identical with the difference that Scene has its anchor point (by default) at the center of the screen. @@ -61,23 +62,44 @@ Scene will create a default camera for you. class CC_DLL Scene : public Node { public: - /** creates a new Scene object */ + /** Creates a new Scene object. + * + * @return An autoreleased Scene object. + */ static Scene *create(); - /** creates a new Scene object with a predefined Size */ + /** Creates a new Scene object with a predefined Size. + * + * @param size The predefined size of scene. + * @return An autoreleased Scene object. + */ static Scene *createWithSize(const Size& size); using Node::addChild; virtual std::string getDescription() const override; - /** get all cameras */ + /** Get all cameras. + * + * @return The vector of all cameras. + */ const std::vector& getCameras() const { return _cameras; } + /** Get the default camera. + * + * @return The default camera of scene. + */ Camera* getDefaultCamera() const { return _defaultCamera; } + /** Get lights. + * + * @return The vector of lights. + */ const std::vector& getLights() const { return _lights; } - /** render the scene */ + /** Render the scene. + * + * @param renderer The renderer use to render the scene. + */ void render(Renderer* renderer); /** override function */ @@ -116,7 +138,16 @@ private: public: virtual void addChild(Node* child, int zOrder, int tag) override; virtual void addChild(Node* child, int zOrder, const std::string &name) override; + /** Get the physics world of the scene. + * + * @return The physics world of the scene. + */ inline PhysicsWorld* getPhysicsWorld() { return _physicsWorld; } + + /** Create a scene with physics. + * + * @return An autoreleased Scene object with physics. + */ static Scene *createWithPhysics(); CC_CONSTRUCTOR_ACCESS: diff --git a/cocos/2d/CCSpriteFrame.h b/cocos/2d/CCSpriteFrame.h index e104eb016d..e1ad24f0cc 100644 --- a/cocos/2d/CCSpriteFrame.h +++ b/cocos/2d/CCSpriteFrame.h @@ -41,7 +41,8 @@ class Texture2D; * @{ */ -/** @brief A SpriteFrame has: +/** @class SpriteFrame + * @brief A SpriteFrame has: - texture: A Texture2D that will be used by the Sprite - rectangle: A rectangle of the texture @@ -57,57 +58,131 @@ public: /** Create a SpriteFrame with a texture filename, rect in points. It is assumed that the frame was not trimmed. + * + * @param filename Texture file name. + * @param rect A specified rect. + * @return An autoreleased SpriteFrame object. */ static SpriteFrame* create(const std::string& filename, const Rect& rect); /** Create a SpriteFrame with a texture filename, rect, rotated, offset and originalSize in pixels. The originalSize is the size in pixels of the frame before being trimmed. + * + * @param filename Texture filename + * @param rect A specified rect. + * @param rotated Is rotated if true. + * @param offset A specified offset. + * @param originalSize A specified original size. + * @return An autoreleased SpriteFrame object. */ static SpriteFrame* create(const std::string& filename, const Rect& rect, bool rotated, const Vec2& offset, const Size& originalSize); /** Create a SpriteFrame with a texture, rect in points. It is assumed that the frame was not trimmed. + * @param pobTexture The texture pointer. + * @param rect A specified rect. + * @return An autoreleased SpriteFrame object. */ static SpriteFrame* createWithTexture(Texture2D* pobTexture, const Rect& rect); /** Create a SpriteFrame with a texture, rect, rotated, offset and originalSize in pixels. The originalSize is the size in points of the frame before being trimmed. + * @param pobTexture The texture pointer. + * @param rect A specified rect. + * @param rotated Is rotated if true. + * @param offset A specified offset. + * @param originalSize A specified original size. + * @return An autoreleased SpriteFrame object. */ static SpriteFrame* createWithTexture(Texture2D* pobTexture, const Rect& rect, bool rotated, const Vec2& offset, const Size& originalSize); // attributes + /** Get rect of the sprite frame. + * + * @return The rect of the sprite frame, in pixels. + */ inline const Rect& getRectInPixels() const { return _rectInPixels; } + /** Set rect of the sprite frame. + * + * @param rectInPixels The rect of the sprite frame, in pixels. + */ void setRectInPixels(const Rect& rectInPixels); + /**Is the sprite frame rotated or not. + * + * @return Is rotated if true. + */ inline bool isRotated() const { return _rotated; } + /** Set rotated of the sprite frame. + * + * @param rotated Rotated the sprite frame if true. + */ inline void setRotated(bool rotated) { _rotated = rotated; } - /** get rect of the frame */ + /** Get rect of the frame. + * + * @return The rect of the sprite frame. + */ inline const Rect& getRect() const { return _rect; } - /** set rect of the frame */ + /** Set rect of the frame. + * + * @param The rect of the sprite. + */ void setRect(const Rect& rect); - /** get offset of the frame */ + /** Get offset of the frame. + * + * @return The offset of the sprite frame, in pixels. + */ const Vec2& getOffsetInPixels() const; - /** set offset of the frame */ + /** Set offset of the frame. + * + * @param offsetInPixels The offset of the sprite frame, in pixels. + */ void setOffsetInPixels(const Vec2& offsetInPixels); - /** get original size of the trimmed image */ + /** Get original size of the trimmed image. + * + * @return The original size of the trimmed image, in pixels. + */ inline const Size& getOriginalSizeInPixels() const { return _originalSizeInPixels; } - /** set original size of the trimmed image */ + /** Set original size of the trimmed image. + * + * @param sizeInPixels The original size of the trimmed image, in pixels. + */ inline void setOriginalSizeInPixels(const Size& sizeInPixels) { _originalSizeInPixels = sizeInPixels; } - /** get original size of the trimmed image */ + /** Get original size of the trimmed image. + * + * @return The original size of the trimmed image. + */ inline const Size& getOriginalSize() const { return _originalSize; } - /** set original size of the trimmed image */ + /** Set original size of the trimmed image. + * + * @param sizeInPixels The original size of the trimmed image. + */ inline void setOriginalSize(const Size& sizeInPixels) { _originalSize = sizeInPixels; } - /** get texture of the frame */ + /** Get texture of the frame. + * + * @return The texture of the sprite frame. + */ Texture2D* getTexture(); - /** set texture of the frame, the texture is retained */ + /** Set texture of the frame, the texture is retained. + * + * @param pobTexture The texture of the sprite frame. + */ void setTexture(Texture2D* pobTexture); + /** Get offset of the frame. + * + * @return The offset of the sprite frame. + */ const Vec2& getOffset() const; + /** Set offset of the frame. + * + * @param offsets The offset of the sprite frame. + */ void setOffset(const Vec2& offsets); // Overrides diff --git a/cocos/2d/CCSpriteFrameCache.h b/cocos/2d/CCSpriteFrameCache.h index 0d843fa4f7..c5a0cfe880 100644 --- a/cocos/2d/CCSpriteFrameCache.h +++ b/cocos/2d/CCSpriteFrameCache.h @@ -51,37 +51,49 @@ class Texture2D; * @{ */ -/** @brief Singleton that handles the loading of the sprite frames. +/** @class SpriteFrameCache + * @brief Singleton that handles the loading of the sprite frames. It saves in a cache the sprite frames. @since v0.9 */ class CC_DLL SpriteFrameCache : public Ref { public: - /** Returns the shared instance of the Sprite Frame cache */ + /** Returns the shared instance of the Sprite Frame cache. + * + * @return The instance of the Sprite Frame Cache. + */ static SpriteFrameCache* getInstance(); /** @deprecated Use getInstance() instead */ CC_DEPRECATED_ATTRIBUTE static SpriteFrameCache* sharedSpriteFrameCache() { return SpriteFrameCache::getInstance(); } - /** Destroys the cache. It releases all the Sprite Frames and the retained instance. */ + /** Destroys the cache. It releases all the Sprite Frames and the retained instance. + */ static void destroyInstance(); /** @deprecated Use destroyInstance() instead */ CC_DEPRECATED_ATTRIBUTE static void purgeSharedSpriteFrameCache() { return SpriteFrameCache::destroyInstance(); } - /** + /** Destructor. * @js NA * @lua NA */ virtual ~SpriteFrameCache(); + + /** Initialize method. + * + * @return if success return true. + */ bool init(); /** Adds multiple Sprite Frames from a plist file. - * A texture will be loaded automatically. The texture name will composed by replacing the .plist suffix with .png + * A texture will be loaded automatically. The texture name will composed by replacing the .plist suffix with .png. * If you want to use another texture, you should use the addSpriteFramesWithFile(const std::string& plist, const std::string& textureFileName) method. * @js addSpriteFrames * @lua addSpriteFrames + * + * @param plist Plist file name. */ void addSpriteFramesWithFile(const std::string& plist); @@ -89,23 +101,35 @@ public: @since v0.99.5 * @js addSpriteFrames * @lua addSpriteFrames + * + * @param plist Plist file name. + * @param textureFileName Texture file name. */ void addSpriteFramesWithFile(const std::string& plist, const std::string& textureFileName); /** Adds multiple Sprite Frames from a plist file. The texture will be associated with the created sprite frames. * @js addSpriteFrames * @lua addSpriteFrames + * + * @param plist Plist file name. + * @param texture Texture pointer. */ void addSpriteFramesWithFile(const std::string&plist, Texture2D *texture); /** Adds multiple Sprite Frames from a plist file content. The texture will be associated with the created sprite frames. * @js addSpriteFrames * @lua addSpriteFrames + * + * @param plist_content Plist file content string. + * @param texture Texture pointer. */ void addSpriteFramesWithFileContent(const std::string& plist_content, Texture2D *texture); /** Adds an sprite frame with a given name. If the name already exists, then the contents of the old name will be replaced with the new one. + * + * @param frame A certain sprite frame. + * @param frameName The name of the sprite frame. */ void addSpriteFrame(SpriteFrame *frame, const std::string& frameName); @@ -123,25 +147,34 @@ public: */ void removeUnusedSpriteFrames(); - /** Deletes an sprite frame from the sprite frame cache. */ + /** Deletes an sprite frame from the sprite frame cache. + * + * @param name The name of the sprite frame that needs to removed. + */ void removeSpriteFrameByName(const std::string& name); /** Removes multiple Sprite Frames from a plist file. * Sprite Frames stored in this file will be removed. * It is convenient to call this method when a specific texture needs to be removed. * @since v0.99.5 + * + * @param plist The name of the plist that needs to removed. */ void removeSpriteFramesFromFile(const std::string& plist); /** Removes multiple Sprite Frames from a plist file content. * Sprite Frames stored in this file will be removed. * It is convenient to call this method when a specific texture needs to be removed. + * + * @param plist_content The string of the plist content that needs to removed. */ void removeSpriteFramesFromFileContent(const std::string& plist_content); /** Removes all Sprite Frames associated with the specified textures. * It is convenient to call this method when a specific texture needs to be removed. * @since v0.995. + * + * @param texture The texture that needs to removed. */ void removeSpriteFramesFromTexture(Texture2D* texture); @@ -150,6 +183,9 @@ public: You should retain the returned copy if you are going to use it. * @js getSpriteFrame * @lua getSpriteFrame + * + * @param name A certain sprite frame name. + * @return The sprite frame. */ SpriteFrame* getSpriteFrameByName(const std::string& name); From a5e148c829c8034e3b10accdd0bc54825b449d25 Mon Sep 17 00:00:00 2001 From: zhangbin Date: Wed, 18 Mar 2015 20:56:17 +0800 Subject: [PATCH 08/10] Update comments of some header files. --- cocos/2d/CCActionEase.h | 26 +-- cocos/2d/CCActionGrid.h | 4 +- cocos/2d/CCActionTiledGrid.h | 335 ++++++++++++++++++++++++--------- docs/doxygen_white_book.config | 4 +- 4 files changed, 263 insertions(+), 106 deletions(-) diff --git a/cocos/2d/CCActionEase.h b/cocos/2d/CCActionEase.h index 11b1b2a93f..81bd4c8099 100644 --- a/cocos/2d/CCActionEase.h +++ b/cocos/2d/CCActionEase.h @@ -144,7 +144,7 @@ private: @class EaseIn @brief EaseIn action with a rate. @detail The timeline of inner action will be changed by: - \f$time^rate\f$ + \f${ time }^{ rate }\f$. @ingroup Actions */ class CC_DLL EaseIn : public EaseRateAction @@ -175,7 +175,7 @@ private: @class EaseOut @brief EaseOut action with a rate. @detail The timeline of inner action will be changed by: - \f$time^(1/rate)\f$ + \f${ time }^ { (1/rate) }\f$. @ingroup Actions */ class CC_DLL EaseOut : public EaseRateAction @@ -206,9 +206,9 @@ private: @class EaseInOut @brief EaseInOut action with a rate @detail If time * 2 < 1, the timeline of inner action will be changed by: - \f$0.5*{ time }^{ rate }\f$ + \f$0.5*{ time }^{ rate }\f$. Else, the timeline of inner action will be changed by: - \f$1.0-0.5*{ 2-time }^{ rate }\f$ + \f$1.0-0.5*{ 2-time }^{ rate }\f$. @ingroup Actions */ class CC_DLL EaseInOut : public EaseRateAction @@ -239,7 +239,7 @@ private: @class EaseExponentialIn @brief Ease Exponential In action. @detail The timeline of inner action will be changed by: - \f${ 2 }^{ 10*(time-1) }-1*0.001\f$ + \f${ 2 }^{ 10*(time-1) }-1*0.001\f$. @ingroup Actions */ class CC_DLL EaseExponentialIn : public ActionEase @@ -269,7 +269,7 @@ private: @class EaseExponentialOut @brief Ease Exponential Out @detail The timeline of inner action will be changed by: - \f$1-{ 2 }^{ -10*(time-1) }\f$ + \f$1-{ 2 }^{ -10*(time-1) }\f$. @ingroup Actions */ class CC_DLL EaseExponentialOut : public ActionEase @@ -299,9 +299,9 @@ private: @class EaseExponentialInOut @brief Ease Exponential InOut @detail If time * 2 < 1, the timeline of inner action will be changed by: - \f$0.5*{ 2 }^{ 10*(time-1) }\f$ + \f$0.5*{ 2 }^{ 10*(time-1) }\f$. else, the timeline of inner action will be changed by: - \f$0.5*(2-{ 2 }^{ -10*(time-1) })\f$ + \f$0.5*(2-{ 2 }^{ -10*(time-1) })\f$. @ingroup Actions */ class CC_DLL EaseExponentialInOut : public ActionEase @@ -331,7 +331,7 @@ private: @class EaseSineIn @brief Ease Sine In @detail The timeline of inner action will be changed by: - \f$1-cos(time*\frac { \pi }{ 2 } )\f$ + \f$1-cos(time*\frac { \pi }{ 2 } )\f$. @ingroup Actions */ class CC_DLL EaseSineIn : public ActionEase @@ -361,7 +361,7 @@ private: @class EaseSineOut @brief Ease Sine Out @detail The timeline of inner action will be changed by: - \f$sin(time*\frac { \pi }{ 2 } )\f$ + \f$sin(time*\frac { \pi }{ 2 } )\f$. @ingroup Actions */ class CC_DLL EaseSineOut : public ActionEase @@ -391,7 +391,7 @@ private: @class EaseSineInOut @brief Ease Sine InOut @detail The timeline of inner action will be changed by: - \f$-0.5*(cos(\pi *time)-1)\f$ + \f$-0.5*(cos(\pi *time)-1)\f$. @ingroup Actions */ class CC_DLL EaseSineInOut : public ActionEase @@ -477,7 +477,7 @@ private: @brief Ease Elastic In action. @detail If time == 0 or time == 1, the timeline of inner action will not be changed. Else, the timeline of inner action will be changed by: - \f$-{ 2 }^{ 10*(time-1) }*sin((time-1-\frac { period }{ 4 } )*\pi *2/period)\f$ + \f$-{ 2 }^{ 10*(time-1) }*sin((time-1-\frac { period }{ 4 } )*\pi *2/period)\f$. @warning This action doesn't use a bijective function. Actions like Sequence might have an unexpected result when used with this action. @@ -520,7 +520,7 @@ private: @brief Ease Elastic Out action. @detail If time == 0 or time == 1, the timeline of inner action will not be changed. Else, the timeline of inner action will be changed by: - \f${ 2 }^{ -10*time }*sin((time-\frac { period }{ 4 } )*\pi *2/period)+1\f$ + \f${ 2 }^{ -10*time }*sin((time-\frac { period }{ 4 } )*\pi *2/period)+1\f$. @warning This action doesn't use a bijective function. Actions like Sequence might have an unexpected result when used with this action. @since v0.8.2 diff --git a/cocos/2d/CCActionGrid.h b/cocos/2d/CCActionGrid.h index e37f201ad0..8e4541e304 100644 --- a/cocos/2d/CCActionGrid.h +++ b/cocos/2d/CCActionGrid.h @@ -143,7 +143,7 @@ public: }; /** -@brief Base class for TiledGrid3D actions +@brief Base class for TiledGrid3D actions. */ class CC_DLL TiledGrid3DAction : public GridAction { @@ -305,7 +305,7 @@ private: }; /** -@brief DeccelAmplitude action +@brief DeccelAmplitude action. */ class CC_DLL DeccelAmplitude : public ActionInterval { diff --git a/cocos/2d/CCActionTiledGrid.h b/cocos/2d/CCActionTiledGrid.h index 914959bb39..c53826d44e 100644 --- a/cocos/2d/CCActionTiledGrid.h +++ b/cocos/2d/CCActionTiledGrid.h @@ -35,21 +35,27 @@ NS_CC_BEGIN * @{ */ -/** @brief ShakyTiles3D action */ +/** +@brief ShakyTiles3D action. +@detail This action is make the target node shake with many tiles. + You can create the action by these parameters: + duration, grid size, range, whether shake on the z axis. + */ class CC_DLL ShakyTiles3D : public TiledGrid3DAction { public: /** - * creates the action with a range, whether or not to shake Z vertices, a grid size, and duration - * @param duration in seconds - */ + @brief Create the action with a range, shake Z vertices, a grid and duration. + @param duration Specify the duration of the ShakyTiles3D action. It's a value in seconds. + @param gridSize Specify the size of the grid. + @param range Specify the range of the shaky effect. + @param shakeZ Specify whether shake on the z axis. + @return If the creation success, return a pointer of ShakyTiles3D action; otherwise, return nil. + */ static ShakyTiles3D* create(float duration, const Size& gridSize, int range, bool shakeZ); // Override virtual ShakyTiles3D* clone() const override; - /** - * @param time in seconds - */ virtual void update(float time) override; CC_CONSTRUCTOR_ACCESS: @@ -57,9 +63,13 @@ CC_CONSTRUCTOR_ACCESS: virtual ~ShakyTiles3D() {} /** - * initializes the action with a range, whether or not to shake Z vertices, a grid size, and duration - * @param duration in seconds - */ + @brief Initializes the action with a range, shake Z vertices, grid size and duration. + @param duration Specify the duration of the ShakyTiles3D action. It's a value in seconds. + @param gridSize Specify the size of the grid. + @param range Specify the range of the shaky effect. + @param shakeZ Specify whether shake on the z axis. + @return If the Initialization success, return true; otherwise, return false. + */ bool initWithDuration(float duration, const Size& gridSize, int range, bool shakeZ); protected: @@ -70,21 +80,27 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(ShakyTiles3D); }; -/** @brief ShatteredTiles3D action */ +/** +@brief ShatteredTiles3D action. +@detail This action make the target node shattered with many tiles. + You can create the action by these parameters: + duration, grid size, range, whether shatter on the z axis. +*/ class CC_DLL ShatteredTiles3D : public TiledGrid3DAction { public: /** - * creates the action with a range, whether of not to shatter Z vertices, a grid size and duration - * @param duration in seconds + * @brief Create the action with a range, whether of not to shatter Z vertices, grid size and duration. + * @param duration Specify the duration of the ShatteredTiles3D action. It's a value in seconds. + * @param gridSize Specify the size of the grid. + * @param range Specify the range of the shatter effect. + * @param shatterZ Specify whether shatter on the z axis. + * @return If the creation success, return a pointer of ShatteredTiles3D action; otherwise, return nil. */ static ShatteredTiles3D* create(float duration, const Size& gridSize, int range, bool shatterZ); // Override virtual ShatteredTiles3D* clone() const override; - /** - * @param time in seconds - */ virtual void update(float time) override; CC_CONSTRUCTOR_ACCESS: @@ -92,7 +108,13 @@ CC_CONSTRUCTOR_ACCESS: virtual ~ShatteredTiles3D() {} /** - * initializes the action with a range, whether or not to shatter Z vertices, a grid size and duration */ + @brief Initializes the action with a range, shatter Z vertices, grid size and duration. + @param duration Specify the duration of the ShatteredTiles3D action. It's a value in seconds. + @param gridSize Specify the size of the grid. + @param range Specify the range of the shatter effect. + @param shatterZ Specify whether shake on the z axis. + @return If the Initialization success, return true; otherwise, return false. + */ bool initWithDuration(float duration, const Size& gridSize, int range, bool shatterZ); protected: @@ -105,16 +127,22 @@ private: }; struct Tile; -/** @brief ShuffleTiles action - Shuffle the tiles in random order - */ +/** +@brief ShuffleTiles action. +@detail This action make the target node shuffle with many tiles in random order. + You can create the action by these parameters: + duration, grid size, the random seed. +*/ class CC_DLL ShuffleTiles : public TiledGrid3DAction { public: /** - * creates the action with a random seed, the grid size and the duration - * @param duration in seconds - */ + * @brief Create the action with grid size, random seed and duration. + * @param duration Specify the duration of the ShuffleTiles action. It's a value in seconds. + * @param gridSize Specify the size of the grid. + * @param seed Specify the random seed. + * @return If the creation success, return a pointer of ShuffleTiles action; otherwise, return nil. + */ static ShuffleTiles* create(float duration, const Size& gridSize, unsigned int seed); void shuffle(unsigned int *array, unsigned int len); @@ -123,9 +151,6 @@ public: // Overrides virtual void startWithTarget(Node *target) override; - /** - * @param time in seconds - */ virtual void update(float time) override; virtual ShuffleTiles* clone() const override; @@ -134,9 +159,12 @@ CC_CONSTRUCTOR_ACCESS: virtual ~ShuffleTiles(); /** - * initializes the action with a random seed, the grid size and the duration - * @param duration in seconds - */ + * @brief Initializes the action with grid size, random seed and duration. + * @param duration Specify the duration of the ShuffleTiles action. It's a value in seconds. + * @param gridSize Specify the size of the grid. + * @param seed Specify the random seed. + * @return If the Initialization success, return true; otherwise, return false. + */ bool initWithDuration(float duration, const Size& gridSize, unsigned int seed); protected: @@ -149,27 +177,49 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(ShuffleTiles); }; -/** @brief FadeOutTRTiles action - Fades out the tiles in a Top-Right direction +/** +@brief FadeOutTRTiles action. +@detail Fades out the target node with many tiles from Bottom-Left to Top-Right. */ class CC_DLL FadeOutTRTiles : public TiledGrid3DAction { public: /** - * creates the action with the grid size and the duration - * @param duration in seconds - */ + * @brief Create the action with the grid size and the duration. + * @param duration Specify the duration of the FadeOutTRTiles action. It's a value in seconds. + * @param gridSize Specify the size of the grid. + * @return If the creation success, return a pointer of FadeOutTRTiles action; otherwise, return nil. + */ static FadeOutTRTiles* create(float duration, const Size& gridSize); + /** + @brief Calculate the percentage a tile should be shown. + @param pos The position index of the tile. + @param time The current percentage of the action. + @return Return the percentage the tile should be shown. + */ virtual float testFunc(const Size& pos, float time); + + /** + @brief Show the tile at specified position. + @param pos The position index of the tile should be shown. + */ void turnOnTile(const Vec2& pos); + + /** + @brief Hide the tile at specified position. + @param pos The position index of the tile should be hide. + */ void turnOffTile(const Vec2& pos); + + /** + @brief Show part of the tile. + @param pos The position index of the tile should be shown. + @param distance The percentage that the tile should be shown. + */ virtual void transformTile(const Vec2& pos, float distance); // Overrides - /** - * @param time in seconds - */ virtual void update(float time) override; virtual FadeOutTRTiles* clone() const override; @@ -181,16 +231,19 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(FadeOutTRTiles); }; -/** @brief FadeOutBLTiles action. - Fades out the tiles in a Bottom-Left direction +/** +@brief FadeOutBLTiles action. +@detail Fades out the target node with many tiles from Top-Right to Bottom-Left. */ class CC_DLL FadeOutBLTiles : public FadeOutTRTiles { public: /** - * creates the action with the grid size and the duration - * @param duration in seconds - */ + * @brief Create the action with the grid size and the duration. + * @param duration Specify the duration of the FadeOutBLTiles action. It's a value in seconds. + * @param gridSize Specify the size of the grid. + * @return If the creation success, return a pointer of FadeOutBLTiles action; otherwise, return nil. + */ static FadeOutBLTiles* create(float duration, const Size& gridSize); // Overrides @@ -205,16 +258,19 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(FadeOutBLTiles); }; -/** @brief FadeOutUpTiles action. - Fades out the tiles in upwards direction +/** +@brief FadeOutUpTiles action. +@detail Fades out the target node with many tiles from bottom to top. */ class CC_DLL FadeOutUpTiles : public FadeOutTRTiles { public: /** - * creates the action with the grid size and the duration - * @param duration in seconds - */ + * @brief Create the action with the grid size and the duration. + * @param duration Specify the duration of the FadeOutUpTiles action. It's a value in seconds. + * @param gridSize Specify the size of the grid. + * @return If the creation success, return a pointer of FadeOutUpTiles action; otherwise, return nil. + */ static FadeOutUpTiles* create(float duration, const Size& gridSize); virtual void transformTile(const Vec2& pos, float distance) override; @@ -231,16 +287,19 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(FadeOutUpTiles); }; -/** @brief FadeOutDownTiles action. - Fades out the tiles in downwards direction +/** +@brief FadeOutDownTiles action. +@detail Fades out the target node with many tiles from top to bottom. */ class CC_DLL FadeOutDownTiles : public FadeOutUpTiles { public: /** - * creates the action with the grid size and the duration - * @param duration in seconds - */ + * @brief Create the action with the grid size and the duration. + * @param duration Specify the duration of the FadeOutDownTiles action. It's a value in seconds. + * @param gridSize Specify the size of the grid. + * @return If the creation success, return a pointer of FadeOutDownTiles action; otherwise, return nil. + */ static FadeOutDownTiles* create(float duration, const Size& gridSize); // Overrides @@ -255,25 +314,46 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(FadeOutDownTiles); }; -/** @brief TurnOffTiles action. - Turn off the files in random order +/** +@brief TurnOffTiles action. +@detail Turn off the target node with many tiles in random order. */ class CC_DLL TurnOffTiles : public TiledGrid3DAction { public: /** - * creates the action with the grid size and the duration - * @param duration in seconds - */ + * @brief Create the action with the grid size and the duration. + * @param duration Specify the duration of the TurnOffTiles action. It's a value in seconds. + * @param gridSize Specify the size of the grid. + * @return If the creation success, return a pointer of TurnOffTiles action; otherwise, return nil. + */ static TurnOffTiles* create(float duration, const Size& gridSize); /** - * creates the action with a random seed, the grid size and the duration - * @param duration in seconds - */ + * @brief Create the action with the grid size and the duration. + * @param duration Specify the duration of the TurnOffTiles action. It's a value in seconds. + * @param gridSize Specify the size of the grid. + * @param seed Specify the random seed. + * @return If the creation success, return a pointer of TurnOffTiles action; otherwise, return nil. + */ static TurnOffTiles* create(float duration, const Size& gridSize, unsigned int seed); + /** + @brief Shuffle the array specified. + @param array The array will be shuffled. + @param len The size of the array. + */ void shuffle(unsigned int *array, unsigned int len); + + /** + @brief Show the tile at specified position. + @param pos The position index of the tile should be shown. + */ void turnOnTile(const Vec2& pos); + + /** + @brief Hide the tile at specified position. + @param pos The position index of the tile should be hide. + */ void turnOffTile(const Vec2& pos); // Overrides @@ -285,7 +365,13 @@ CC_CONSTRUCTOR_ACCESS: TurnOffTiles() {} virtual ~TurnOffTiles(); - /** initializes the action with a random seed, the grid size and the duration */ + /** + * @brief Initializes the action with grid size, random seed and duration. + * @param duration Specify the duration of the TurnOffTiles action. It's a value in seconds. + * @param gridSize Specify the size of the grid. + * @param seed Specify the random seed. + * @return If the Initialization success, return true; otherwise, return false. + */ bool initWithDuration(float duration, const Size& gridSize, unsigned int seed); protected: @@ -297,36 +383,61 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(TurnOffTiles); }; -/** @brief WavesTiles3D action. */ +/** +@brief WavesTiles3D action. +@detail This action wave the target node with many tiles. +*/ class CC_DLL WavesTiles3D : public TiledGrid3DAction { public: /** - * creates the action with a number of waves, the waves amplitude, the grid size and the duration - * @param duration in seconds + * @brief Create the action with a number of waves, the waves amplitude, the grid size and the duration. + * @param duration Specify the duration of the WavesTiles3D action. It's a value in seconds. + * @param gridSize Specify the size of the grid. + * @param waves Specify the waves count of the WavesTiles3D action. + * @param amplitude Specify the amplitude of the WavesTiles3D action. + * @return If the creation success, return a pointer of WavesTiles3D action; otherwise, return nil. */ static WavesTiles3D* create(float duration, const Size& gridSize, unsigned int waves, float amplitude); - /** waves amplitude */ + /** + @brief Get the amplitude of the effect. + @return Return the amplitude of the effect. + */ inline float getAmplitude() const { return _amplitude; } + /** + @brief Set the amplitude to the effect. + @param amplitude The value of amplitude will be set. + */ inline void setAmplitude(float amplitude) { _amplitude = amplitude; } - /** waves amplitude rate */ + /** + @brief Get the amplitude rate of the effect. + @return Return the amplitude rate of the effect. + */ inline float getAmplitudeRate() const { return _amplitudeRate; } + /** + @brief Set the ampliture rate of the effect. + @param amplitudeRate The value of amplitude rate will be set. + */ inline void setAmplitudeRate(float amplitudeRate) { _amplitudeRate = amplitudeRate; } // Override virtual WavesTiles3D* clone() const override; - /** - * @param duration in seconds - */ virtual void update(float time) override; CC_CONSTRUCTOR_ACCESS: WavesTiles3D() {} virtual ~WavesTiles3D() {} - /** initializes the action with a number of waves, the waves amplitude, the grid size and the duration */ + /** + @brief Initializes an action with duration, grid size, waves count and amplitude. + @param duration Specify the duration of the WavesTiles3D action. It's a value in seconds. + @param gridSize Specify the size of the grid. + @param waves Specify the waves count of the WavesTiles3D action. + @param amplitude Specify the amplitude of the WavesTiles3D action. + @return If the initialization success, return true; otherwise, return false. + */ bool initWithDuration(float duration, const Size& gridSize, unsigned int waves, float amplitude); protected: @@ -338,38 +449,61 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(WavesTiles3D); }; -/** @brief JumpTiles3D action. - A sin function is executed to move the tiles across the Z axis - */ +/** +@brief JumpTiles3D action. +@detail Move the tiles of a target node across the Z axis. +*/ class CC_DLL JumpTiles3D : public TiledGrid3DAction { public: /** - * creates the action with the number of jumps, the sin amplitude, the grid size and the duration - * @param duration in seconds + * @brief Create the action with the number of jumps, the sin amplitude, the grid size and the duration. + * @param duration Specify the duration of the JumpTiles3D action. It's a value in seconds. + * @param gridSize Specify the size of the grid. + * @param numberOfJumps Specify the jump tiles count. + * @param amplitude Specify the amplitude of the JumpTiles3D action. + * @return If the creation success, return a pointer of JumpTiles3D action; otherwise, return nil. */ static JumpTiles3D* create(float duration, const Size& gridSize, unsigned int numberOfJumps, float amplitude); - /** amplitude of the sin*/ + /** + @brief Get the amplitude of the effect. + @return Return the amplitude of the effect. + */ inline float getAmplitude() const { return _amplitude; } + /** + @brief Set the amplitude to the effect. + @param amplitude The value of amplitude will be set. + */ inline void setAmplitude(float amplitude) { _amplitude = amplitude; } - /** amplitude rate */ + /** + @brief Get the amplitude rate of the effect. + @return Return the amplitude rate of the effect. + */ inline float getAmplitudeRate() const { return _amplitudeRate; } + /** + @brief Set the ampliture rate of the effect. + @param amplitudeRate The value of amplitude rate will be set. + */ inline void setAmplitudeRate(float amplitudeRate) { _amplitudeRate = amplitudeRate; } // Override virtual JumpTiles3D* clone() const override; - /** - * @param time in seconds - */ virtual void update(float time) override; CC_CONSTRUCTOR_ACCESS: JumpTiles3D() {} virtual ~JumpTiles3D() {} - /** initializes the action with the number of jumps, the sin amplitude, the grid size and the duration */ + /** + * @brief Initializes the action with the number of jumps, the sin amplitude, the grid size and the duration. + * @param duration Specify the duration of the JumpTiles3D action. It's a value in seconds. + * @param gridSize Specify the size of the grid. + * @param numberOfJumps Specify the jump tiles count. + * @param amplitude Specify the amplitude of the JumpTiles3D action. + * @return If the initialization success, return true; otherwise, return false. + */ bool initWithDuration(float duration, const Size& gridSize, unsigned int numberOfJumps, float amplitude); protected: @@ -381,13 +515,19 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(JumpTiles3D); }; -/** @brief SplitRows action */ +/** +@brief SplitRows action. +@detail Split the target node in many rows. + Then move out some rows from left, move out the other rows from right. +*/ class CC_DLL SplitRows : public TiledGrid3DAction { public : /** - * creates the action with the number of rows to split and the duration - * @param duration in seconds + * @brief Create the action with the number of rows and the duration. + * @param duration Specify the duration of the SplitRows action. It's a value in seconds. + * @param rows Specify the rows count should be splited. + * @return If the creation success, return a pointer of SplitRows action; otherwise, return nil. */ static SplitRows* create(float duration, unsigned int rows); @@ -400,7 +540,12 @@ CC_CONSTRUCTOR_ACCESS: SplitRows() {} virtual ~SplitRows() {} - /** initializes the action with the number of rows to split and the duration */ + /** + * @brief Initializes the action with the number rows and the duration. + * @param duration Specify the duration of the SplitRows action. It's a value in seconds. + * @param rows Specify the rows count should be splited. + * @return If the creation success, return true; otherwise, return false. + */ bool initWithDuration(float duration, unsigned int rows); protected: @@ -411,13 +556,20 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(SplitRows); }; -/** @brief SplitCols action */ +/** +@brief SplitCols action. +@detail Split the target node in many columns. + Then move out some columns from top, move out the other columns from bottom. +*/ class CC_DLL SplitCols : public TiledGrid3DAction { public: + /** - * creates the action with the number of columns to split and the duration - * @param duration in seconds + * @brief Create the action with the number of columns and the duration. + * @param duration Specify the duration of the SplitCols action. It's a value in seconds. + * @param cols Specify the columns count should be splited. + * @return If the creation success, return a pointer of SplitCols action; otherwise, return nil. */ static SplitCols* create(float duration, unsigned int cols); @@ -433,7 +585,12 @@ CC_CONSTRUCTOR_ACCESS: SplitCols() {} virtual ~SplitCols() {} - /** initializes the action with the number of columns to split and the duration */ + /** + * @brief Initializes the action with the number columns and the duration. + * @param duration Specify the duration of the SplitCols action. It's a value in seconds. + * @param cols Specify the columns count should be splited. + * @return If the creation success, return true; otherwise, return false. + */ bool initWithDuration(float duration, unsigned int cols); protected: diff --git a/docs/doxygen_white_book.config b/docs/doxygen_white_book.config index 53d778a30a..dd4a54bb17 100644 --- a/docs/doxygen_white_book.config +++ b/docs/doxygen_white_book.config @@ -1471,7 +1471,7 @@ FORMULA_TRANSPARENT = YES # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -USE_MATHJAX = NO +USE_MATHJAX = YES # When MathJax is enabled you can set the default output format to be used for # the MathJax output. See the MathJax site (see: @@ -1494,7 +1494,7 @@ MATHJAX_FORMAT = HTML-CSS # The default value is: http://cdn.mathjax.org/mathjax/latest. # This tag requires that the tag USE_MATHJAX is set to YES. -MATHJAX_RELPATH = http://www.mathjax.org/mathjax +# MATHJAX_RELPATH = http://www.mathjax.org/mathjax # The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax # extension names that should be enabled during MathJax rendering. For example From 85811bd710381afe196914c97a86eed496ec8cb7 Mon Sep 17 00:00:00 2001 From: minggo Date: Wed, 18 Mar 2015 21:24:31 +0800 Subject: [PATCH 09/10] update document for CCUserDefault.h --- cocos/base/CCUserDefault.h | 172 ++++++++++++++++++++++++------------- 1 file changed, 112 insertions(+), 60 deletions(-) diff --git a/cocos/base/CCUserDefault.h b/cocos/base/CCUserDefault.h index 858b60b18f..bc2f41516c 100644 --- a/cocos/base/CCUserDefault.h +++ b/cocos/base/CCUserDefault.h @@ -50,108 +50,159 @@ public: // get value methods /** - @brief Get bool value by key, if the key doesn't exist, a default value will return. - You can set the default value, or it is false. - * @js NA - */ - bool getBoolForKey(const char* pKey); - /** + * Get bool value by key, if the key doesn't exist, will return false. + * You can set the default value, or it is false. + * @param key The key to get value. + * @return Bool value by `key`. * @js NA */ - bool getBoolForKey(const char* pKey, bool defaultValue); - /** - @brief Get integer value by key, if the key doesn't exist, a default value will return. - You can set the default value, or it is 0. - * @js NA - */ - int getIntegerForKey(const char* pKey); + bool getBoolForKey(const char* key); + /** + * Get bool value by key, if the key doesn't exist, will return passed default value. + * @param key The key to get value. + * @param defaultValue The default value to return if the key doesn't exist. * @js NA */ - int getIntegerForKey(const char* pKey, int defaultValue); - /** - @brief Get float value by key, if the key doesn't exist, a default value will return. - You can set the default value, or it is 0.0f. - * @js NA - */ - float getFloatForKey(const char* pKey); + bool getBoolForKey(const char* key, bool defaultValue); + /** + * Get integer value by key, if the key doesn't exist, will return 0. + * You can set the default value, or it is 0. + * @param key The key to get value. + * @return Integer value of the key. * @js NA */ - float getFloatForKey(const char* pKey, float defaultValue); - /** - @brief Get double value by key, if the key doesn't exist, a default value will return. - You can set the default value, or it is 0.0. - * @js NA - */ - double getDoubleForKey(const char* pKey); + int getIntegerForKey(const char* key); + /** + * Get bool value by key, if the key doesn't exist, will return passed default value. + * @param key The key to get value. + * @param defaultValue The default value to return if the key doesn't exist. + * @return Integer value of the key. * @js NA */ - double getDoubleForKey(const char* pKey, double defaultValue); - /** - @brief Get string value by key, if the key doesn't exist, a default value will return. - You can set the default value, or it is "". - * @js NA - */ - std::string getStringForKey(const char* pKey); + int getIntegerForKey(const char* key, int defaultValue); + /** + * Get float value by key, if the key doesn't exist, will return 0.0. + * @param key The key to get value. + * @return Float value of the key. * @js NA */ - std::string getStringForKey(const char* pKey, const std::string & defaultValue); + float getFloatForKey(const char* key); + /** - @brief Get binary data value by key, if the key doesn't exist, a default value will return. - You can set the default value, or it is null. + * Get float value by key, if the key doesn't exist, will return passed default value. + * @param key The key to get value. + * @param defaultValue The default value to return if the key doesn't exist. + * @return Float value of the key. * @js NA - * @lua NA */ - Data getDataForKey(const char* pKey); + float getFloatForKey(const char* key, float defaultValue); + /** + * Get double value by key, if the key doesn't exist, will return 0.0. + * @param key The key to get value. + * @return Double value of the key. * @js NA - * @lua NA */ - Data getDataForKey(const char* pKey, const Data& defaultValue); + double getDoubleForKey(const char* key); + + /** + * Get double value by key, if the key doesn't exist, will return passed default value. + * @param key The key to get value. + * @param defaultValue The default value to return if the key doesn't exist. + * @return Double value of the key. + * @js NA + */ + double getDoubleForKey(const char* key, double defaultValue); + + /** + * Get string value by key, if the key doesn't exist, will return an empty string. + * @param key The key to get value. + * @return String value of the key. + * @js NA + */ + std::string getStringForKey(const char* key); + + /** + * Get string value by key, if the key doesn't exist, will return passed default value. + * @param key The key to get value. + * @param defaultValue The default value to return if the key doesn't exist. + * @return String value of the key. + * @js NA + */ + std::string getStringForKey(const char* key, const std::string & defaultValue); + + /** + * Get Data value by key, if the key doesn't exist, will return an empty Data. + * @param key The key to get value. + * @return Data value of the key. + * @js NA + */ + Data getDataForKey(const char* key); + + /** + * Get Data value by key, if the key doesn't exist, will return an empty Data. + * @param key The key to get value. + * @param defaultValue The default value to return if the key doesn't exist. + * @return Data value of the key. + * @js NA + */ + Data getDataForKey(const char* key, const Data& defaultValue); // set value methods /** - @brief Set bool value by key. + * Set bool value by key. + * @param key The key to set. + * @param value A bool value to set to the key. * @js NA */ - void setBoolForKey(const char* pKey, bool value); + void setBoolForKey(const char* key, bool value); /** - @brief Set integer value by key. + * Set integer value by key. + * @param key The key to set. + * @param value A integer value to set to the key. * @js NA */ - void setIntegerForKey(const char* pKey, int value); + void setIntegerForKey(const char* key, int value); /** - @brief Set float value by key. + * Set float value by key. + * @param key The key to set. + * @param value A float value to set to the key. * @js NA */ - void setFloatForKey(const char* pKey, float value); + void setFloatForKey(const char* key, float value); /** - @brief Set double value by key. + * Set double value by key. + * @param key The key to set. + * @param value A double value to set to the key. * @js NA */ - void setDoubleForKey(const char* pKey, double value); + void setDoubleForKey(const char* key, double value); /** - @brief Set string value by key. + * Set string value by key. + * @param key The key to set. + * @param value A string value to set to the key. * @js NA */ - void setStringForKey(const char* pKey, const std::string & value); + void setStringForKey(const char* key, const std::string & value); /** - @brief Set binary data value by key. + * Set Data value by key. + * @param key The key to set. + * @param value A Data value to set to the key. * @js NA - * @lua NA */ - void setDataForKey(const char* pKey, const Data& value); + void setDataForKey(const char* key, const Data& value); /** - @brief Save content to xml file + * You should invoke this function to save values set by setXXXForKey(). * @js NA */ void flush(); - /** returns the singleton + /** Returns the singleton. * @js NA * @lua NA */ @@ -161,20 +212,21 @@ public: */ static void destroyInstance(); - /** deprecated. Use getInstace() instead + /** @deprecated Use getInstace() instead. * @js NA * @lua NA */ CC_DEPRECATED_ATTRIBUTE static UserDefault* sharedUserDefault(); - /** + /**@deprecated Use destroyInstance() instead. * @js NA */ CC_DEPRECATED_ATTRIBUTE static void purgeSharedUserDefault(); - /** + /** All supported platforms other iOS & Android use xml file to save values. This function is return the file path of the xml path. * @js NA */ static const std::string& getXMLFilePath(); - /** + /** All supported platforms other iOS & Android use xml file to save values. This function checks whether the xml file exists or not. + * @return True if the xml file exists, flase if not. * @js NA */ static bool isXMLFileExist(); From 7f825d3dae55db40dc21c87a1228250c26e74769 Mon Sep 17 00:00:00 2001 From: minggo Date: Wed, 18 Mar 2015 21:45:00 +0800 Subject: [PATCH 10/10] update document for ccUtils.h --- cocos/base/ccUtils.h | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/cocos/base/ccUtils.h b/cocos/base/ccUtils.h index 9598a4e929..279c59c7e7 100644 --- a/cocos/base/ccUtils.h +++ b/cocos/base/ccUtils.h @@ -39,13 +39,14 @@ NS_CC_BEGIN ccNextPOT function is licensed under the same license that is used in Texture2D.m. */ -/** returns the Next Power of Two value. +/** Returns the Next Power of Two value. Examples: - If "value" is 15, it will return 16. - If "value" is 16, it will return 16. - If "value" is 17, it will return 32. - +@param value The value to get next power of two. +@return Returns the next power of two value. @since v0.99.5 */ @@ -53,12 +54,12 @@ int ccNextPOT(int value); namespace utils { - /** Capture the entire screen + /** Capture the entire screen. * To ensure the snapshot is applied after everything is updated and rendered in the current frame, * we need to wrap the operation with a custom command which is then inserted into the tail of the render queue. - * @param afterCaptured, specify the callback function which will be invoked after the snapshot is done. - * @param filename, specify a filename where the snapshot is stored. This parameter can be either an absolute path or a simple - * base filename ("hello.png" etc.), don't use a relative path containing directory names.("mydir/hello.png" etc.) + * @param afterCaptured specify the callback function which will be invoked after the snapshot is done. + * @param filename specify a filename where the snapshot is stored. This parameter can be either an absolute path or a simple + * base filename ("hello.png" etc.), don't use a relative path containing directory names.("mydir/hello.png" etc.). * @since v3.2 */ void CC_DLL captureScreen(const std::function& afterCaptured, const std::string& filename); @@ -75,16 +76,21 @@ namespace utils std::vector CC_DLL findChildren(const Node &node, const std::string &name); /** Same to ::atof, but strip the string, remain 7 numbers after '.' before call atof. - * Why we need this? Because in android c++_static, atof ( and std::atof ) is unsupported for numbers have long decimal part and contain several numbers can approximate to 1 ( like 90.099998474121094 ), it will return inf. this function is used to fix this bug. + * Why we need this? Because in android c++_static, atof ( and std::atof ) is unsupported for numbers have long decimal part and contain + * several numbers can approximate to 1 ( like 90.099998474121094 ), it will return inf. This function is used to fix this bug. + * @param str The string be to converted to double. + * @return Returns converted value of a string. */ double CC_DLL atof(const char* str); /** Get current exact time, accurate to nanoseconds. - */ + * @return Returns the time in seconds since the Epoch. + */ double CC_DLL gettime(); /** - * calculate all children's boundingBox + * Calculate unionof bounding box of a node and its children. + * @return Returns unionof bounding box of a node and its children. */ Rect CC_DLL getCascadeBoundingBox(Node *node); }